RADE

Synopsis

adl_site_transfer [-h|-help|-?]
  -rhost RemoteHost -rport RemotePort
  -rsite Site -rw Ws -rtree ws_tree -rtmp TmpDirectory [-rimage image | -rno_image] 
  [-r_sync] [-r_collect] [-r_publish] [-r_promote [WS... ] ]
  -lw Ws -ltree ws_tree [-ltmp TmpDir] [-limage image | -lno_image] 
  [-l_collect] [-l_sync]
  [-lwd WorkingDirectory]
  [-all_fw | -fw fw... | -fw_file fw_file]
  [-simul] [-import_only | -export_only] [-keep_trace n] [-no_compress] [-force_start]

Options starting by '-r' concern the 'r'emote hosts while options starting by '-l' concern the 'l'ocal workspace.

Other options concern the whole transfer operation.

Usage

The adl_site_transfer command is a user command and can work between any workspaces of two different sites. It is possible to use workspaces without images, especially on the remote site where it is advised to have a workspace dedicated to each transfer and this may require a lot of disk space if all of them own one image.

To start a transfer

• A distant host must be specified using the -rhost and -rport options: the host is the one where the SCM Multi-site Transfer Manager [2] is running and the port is the port on which it is listening for clients' requests. Note that this remote host may not be reachable from any local host since special privileges may be required for accessing the distant site (ask your system engineers).
• A string must be given to identify the distant site. That this is not necessarily the string returned the adl_ls_site command but rather a string that is different for each transfer that is started from the same local workspace and targeting different sites. This string is used for computing the name of a directory where various data will be stored.
• The remote transfer workspace must be specified using its name. This workspace must exists. 
  It is possible to specify a working image or to let SCM chooses the default one. it is also possible to specify that no image is to be used for either saving disk space of because the SCM Multi-site Transfer Manager's account does not grant privileges for writing in all workspace's images.
• The remote workspace tree must be specified. It is not mandatory to give this information if the remote workspace exists in only one tree but this avoids the adl_site_transfer command to retrieve these information by itself.
• A remote temporary directory must be specified using the -rtmp option. It must be a valid directory on the host specified by the -rhost option and it must have enough free space for being able to contain (temporarily) a large amount of data because source files to receive or to send will be copied in it.
• Remote actions must be specified for managing the remote workspace. Indeed if the remote workspace exists only for sharing components, no one is working in it and it is needed to make changes happen in it:
  • the -r_collect and -r_sync options specify the actions to be performed before computing the changes to be transferred;
  • the -r_publish and -r_promote options specify the actions to be performed after receiving changes from the local site.
• The local workspace must be specified using its name. This workspace must exists.
  It is possible to specify a working image or to let SCM chooses the default one. it is also possible to specify that no image is to be used because either no one exists or the current user has no right for working in one image. Not however that special transfer data have to be stored and retrieved for each transfer: those information are stored by default under the local workspace's image. If there is no local image, then another storage directory must be specified using the -lwd option.
• A local workspace tree must be specified. It is not mandatory to give this information if the local workspace exists in only one tree but this avoids the adl_site_transfer command to retrieve these information by itself.

The purpose of the command is to share frameworks between sites and thus allowing concurrent developments on the same items. However it is possible than only one site is allowed to modify the shared frameworks, in that case it is not needed to import changes from it and the -export_only or -import_only options can be used to restrict the transfer to one direction and also reducing the time spent by the command.

[Top]

Necessary Context

The adl_site_transfer command works with two workspaces: a local one and a remote one. The local workspace becomes the current working workspace and then the current user must have enough rights to work in it. Secondly the remote workspace is managed by the SCM Multi-site Transfer Manager process; this process is managed by the SCM administrator of the distant site and must be started using an account that has rights for managing remote workspaces. 

Before starting a transfer, it is required to attach in both workspaces the frameworks that are to be shared. Note that if you chose a root workspace as a transfer workspace, it will be never possible to detach any framework from it.

[Top]

Prerequisites Commands

The command calls other SCM commands to perform operations on local and remote workspaces: synchronization, promotion, collect, publishing, ... 
These commands are batch commands and does not need user's help for their execution. The only command that requires user's help is the adl_solve_merge [1] command. It is run automatically when changes coming from the distant site are in conflict with local changes.
As the transfer manages frameworks that are visible in both workspaces, it is needed to attach all the frameworks that are to be shared: use the adl_attach command for that purpose. Note that this step may require help from users of the distant site if users from the local site have no way to access it and to run SCM commands.

[Top]

Data Directory

This directory is used to store data during transfer execution: intermediate files, temporary files, trace files, etc 
It contains also data files that are used for computing delta of changes between successive transfers. 

When no specific directory is specified when running a transfer, the default directory is taken in the local transfer workspace's image:

<path to the local transfer workspace's image>/ToolsData/MultiSite

A specific directory can be specified by the -lwd ('l'ocal 'w'orking 'd'irectory) option. Note that like for the default directory, this directory must be writable for the user who runs adl_site_transfer. When such a specific directory is specified, additional directories are created regarding the associated transfer:

• for a transfer starting from the local workspace <WS> and the associated image <IMAGE>, the path to the data directory is
  <path specified by the -lwd option>/MultiSite/<WS>/<IMAGE>
• for a transfer starting from the local workspace <WS> and without image, the path to the data directory is
  <path specified by the -lwd option>/MultiSite/<WS>/_NO_IMAGE_

It is interesting to use a specific directory for gathering information for all transfers of a site because this can facilitate the management of transfers:

• it is easier to monitor the amount of data taken by transfer files when they are located on the same file system
• it is easier to manage several transfers if all information are gathered under the same directory rather than scattered over transfer workspaces' images.

Transfer Specific Sub-directory

Information are not found directly under the "data directory" but under sub-directories whose names are computed regarding the adl_site_transfer starting parameters. These sub-directories allow to use the same location for storing information for different transfers. Even when the local workspace is the origin of several different transfers, it is possible to use its image for storing information.

The name of a sub-directory is the concatenation of the following strings:

• local workspace tree name (see -ltree option)
• local workspace name (see -lw option)
• remote site name (see -rsite option)
• remote workspace name (see -rw option)
• remote workspace tree name (see -rtree option)

[Top]

Understanding a Transfer

This section describes the different steps composing a transfer between workspaces. The adl_site_transfer command prints a message at the beginning of each step and all traces are available through a html report that can be found under the following path:

<path to the data directory>/<transfer specific directory>/follow_up.htm

A transfer falls down in several main steps:

1. Initialisation of local and remote environments: adl_site_transfer checks that the remote SCM Multi-site Transfer Manager is reachable and that the local and remote workspaces exist.
2. Local and remote environment analysis: the command checks that the two SCM installations share the same data exchange formats (SCM data and source files) and looks for the availability of tar and compression tools:
   • The ADL_TAR_DIR environment variable is checked in both local and remote environments to know whether a "tar" tool is available.
   • The "gzip" tool is searched in both local and remote environments to known whether data can be compressed before their sending.
     Note that those tools are not brought with SCM but can be used as soon as they are available in both environments.
3. Previous transfer's recovery.
   The program goes through this step only if the previous transfer failed while importing data from one site to the other one. In that case the previous transfer is finished before starting the new one.
4. Importing changes from remote site.
   This step consists in computing what changed in remote workspace since the last transfer and getting those changes into the local workspace.
5. Solving conflicting changes.
   These conflicts happen because the local workspace contains some changes that are conflicting with some of those coming from the distant site. Like the adl_sync command, the adl_site_transfer command calls the adl_solve_merge command [1] in order to solve all conflicting changes.
6. Exporting changes to remote site.
   This steps is the reverse step of the fourth one but is started only if there is no more merge to be solved in the local workspace.

Figure 1: follow_up.htm

There are more steps and sub-steps than those described above: all of them can be found in the follow_up.htm file. The figure 1 shows the structure of this file: There is one column per site: the left one gives information about tasks performed on the local site and the right one gives information about remote operations. Each column contains cells that represent a sub-task the text in the cell explains its purpose this text is a hyper text link when traces are available for this step the colour of a cell gives its status: green for OK, grey if not executed or useless, yellow if it is under way and red if it failed The global status of the transfer is given at the top of the page and using the same colour as for the cells. The page is updated each time a step starts or finishes, so a running transfer can be followed by using the current browser "refresh" button or using the one given at the top of the page ().

[Top]

Packaging and Compressing Files Using External Tools

Compression

On Unix platform

The command looks first for the "gzip" program and, if not found, it looks for the "compress" program. If one program is found and is available on both sites, it will be used for compressing files. Note however that if the SCM Multi-site Transfer Manager is running on Windows-NT platform, the "compress" program will never be chosen whatever the local platform is.

On Windows-NT platform

The command looks for the "gzip" program and if it is available on both sites, it will be used for compressing files.

Packaging

The command looks for the environment variable ADL_TAR_DIR and its value must be the path to a directory where a "adl_tar" program must be found. This variable must be set also in the working environment of the SCM Multi-site Transfer Manager, it can point to a different path than on the local host but must also contain a "adl_tar" program.

If the "adl_tar" program is found on both sites, it will be used for packaging user files and transfer specific files before sending them from one site to the other. Note that those 'tar' files will be also compressed if a compression tool is available on both sites.

adl_tar's interface

Here are the parameters of each call to the adl_tar program:

• when creating a tar
  • -cvf <filename>
    <filename> is the path to the 'tar' file
  • -T <filename>
    <filename> is the path to a file containing the list of files to be copied in the 'tar' file
  • <nothing> or -z or -Z
    -z means that a compression is expected using the "gzip" program
    -Z means that a compression is expected using the "compress" program 
• when extracting data from a tar
  • -xvf <filename>
    <filename> is the path to the 'tar' file containing the data to extract
  • <nothing> or -z or -Z
    -z means that the 'tar' file is supposed to have been compressed using the "gzip" program
    -Z means that the 'tar' file is supposed to have been compressed using the "compress" program

[Top]

Options

adl_site_transfer accepts the following options:  

Global parameters
-h|-help|-?	Help of the command
-keep_trace n	Number of trace directories to keep. Traces are located under the Data Directory.
-simul	Simulate import specific operations.  Note that other actions will be done (adl_sync, adl_photo, etc) and also that data will be imported at database level (not workspace level)
-import_only	Only get what changed on remote site
-export_only	Only send what changed on local site
-no_compress	Transfer data without compressing them even some compression tool are detected as available by the command.
-force_start	If the previous transfer crashed without being unregistered by the transfer manager the new transfer won't be allowed to start. This option can be used to force the new transfer to start by un-registering the previous one. To use with care because having two instances of the same transfer running at the same time may cause unpredictable results.
-lwd	A directory in which the program will stored persistent data. If not set, data will be stored in the current working image of the local workspace. See the Data Directory section for more information.
Remote site parameters
-rhost RemoteHost	Remote host name or IP address
-rport number	Port on which the transfer manager is listening on remote host
-rsite Site	A string identifying uniquely the remote SCM installation
-rw Ws	Name of remote transfer workspace
-rimage image	Remote workspace's image to be used for the transfer
-rno_image	To specify that no image is to be used when working in the remote workspace
-rtree ws_tree	Remote workspace tree to consider (only one tree can be treated in one transfer)
-rtmp TmpDir	Temporary directory for remote operations
-r_collect	To collect remote workspace's child workspace(s) BEFORE computing remote changes
-r_sync	To synchronize the remote workspace BEFORE computing remote changes
-r_publish	To publish the remote workspace AFTER the transfer
-r_promote [WS]	To promote the remote workspace AFTER the transfer.  One or several target workspaces can be specified for the promotion: they will be used as arguments for the -to option of the adl_promote command.
Local site parameters
-lw Ws	Workspace name
-limage image	Image of the local workspace to be used for the current transfer
-lno_image	To specify that the local workspace has no image on the current host.
-ltree ws_tree	Workspace tree to consider (only one tree can be treated in one transfer)
-ltmp TmpDir	Temporary directory for local operations
-l_collect	To collect local workspace's child workspace(s) BEFORE starting the transfer
-l_sync	To synchronize the local workspace BEFORE starting the transfer
Filtering frameworks(*)
-all_fw	Consider all the attached frameworks. It is the default
-fw fw...	Consider the frameworks whose names or Id (prefixed by \"soid:\") are given
-fw_file fw_file	Consider the frameworks whose names or Id are read in the file fw_file

^(*) Normally these options are not very useful since a filter is already active by attaching or detaching frameworks in both local and remote workspaces. They can serve punctually to transfer changes concerning a subset of frameworks.
If framework names are given and if the option -export_only is specified, the frameworks are found in the local workspace. Otherwise the frameworks are found in the remote workspace.

[Top]

Examples

Start a transfer between local workspace "localws" and remote workspace "remotews" and let adl_site_transfer uses the default image for both workspaces. The SCM Multi-site Transfer Manager is running on host "lebadsy" and is listening on port 23452, "/tmp" is chosen as the remote temporary directory since "lebadsy" is a UNIX workstation. The transfer is performed between the local tree "V5R8" and the remote tree "V5R8". The -l_sync and -l_promote options are used to respectively synchronize the remote workspace before computing changes and promoting its contents after importing in it what changed on local workspace. 

Start the previous transfer but restrict it to importing changes from the remote site.

Start a transfer between local workspace "localws" and remote workspace "remotews" and do not use any image for both workspaces. The SCM Multi-site Transfer Manager is running on host "lebadsy" and is listening on port 23452, "/tmp" is chosen as the remote temporary directory since "lebadsy" is a UNIX workstation. The transfer is performed between the local tree "V5R8" and the remote tree "V5R8". As no image is used, a data directory is specified using the -lwd option.

[Top]

References

[Top]

History

[Top]

Copyright © 2001, Dassault Systèmes. All rights reserved.