clearimport

Reads data files created by clearexport tools and import elements into a VOB

APPLICABILITY

ClearCase (administrative command)

SYNOPSIS

clearimport [ -v·erbose] [ -i·dentical] [ -n·setevent ] [ -master ] [ -pcase ]

[ -d·irectory destination-dir] [ -c·omment comment] datafile

DESCRIPTION

During the import stage, you invoke clearimport within an existing VOB on the datafile created by clearexport_*. For each object processed by clearexport_* and entered in datafile, clearimport does one of the following things:

• Creates a new element with the same versions as the original.

  The user who invokes clearimport becomes the owner of the elements that clearimport creates. clearexport_* and clearimport use ClearCase magic files to determine which element type to use for each element clearimport creates. For more information on magic files and file-typing, see the cc.magic reference page.

• Checks out an existing element (optionally, on a branch) and checks in a new version for each original version that has not already been imported

If any of the original files were located in subdirectories, clearimport creates corresponding directory elements.

clearimport uses your view context to select the directory version into which it imports elements. However, when clearimport creates directory versions, it creates them on the main branch. The exceptions are as follows:

• If a directory already exists in the target VOB, you can check it out on a branch, and clearimport uses that version
• If you are exporting with clearexport_ffile and you use the -b option, clearimport imports to the specified branch

Requirements and Restrictions

You must observe the following requirements and restrictions:

• If you are importing ClearCase files, use the same config spec (the same view) for the export phase (invocation of clearexport_ccase) and the import phase (invocation of clearimport).
• Do not run clearimport in a view that has file elements checked out from the target VOB. If clearimport is importing to a checked-out element in the target VOB, it cancels the checkout (uncheckout) of that element and deletes the view-private file from the view storage directory. Any changes that you made to the file are lost.
• Do not run clearimport in a UCM view. If you do, clearimport fails with an error message.
• When you import PVCS, RCS, SourceSafe, or SCCS files, clearimport uses an extraction command specific to the version-control product. You must have this extraction command in your path during import:

  Product	Extraction Command
  PVCS	get
  RCS	co
  SourceSafe	ss.exe
  SCCS	get

  PVCS and SCCS use the same command; make sure the correct one is in your path.

• Do not run clearexport_* on UNIX and then run clearimport on Windows to import the data, or vice-versa. However, you can transfer data in either direction between UNIX and Windows by mounting the UNIX VOB or file-system on your Windows machine and running both clearexport_* and clearimport on the Windows machine.

Creation of Event Records During the Import Phase

clearimport documents changes to the VOB by creating event records:

• Each time clearimport creates a new file element, it stores an import file element event record, along with the standard create element event record, in the VOB database. The import file element event record is associated with the parent directory element, not with the new file element itself. clearimport creates the import event record only if the object is more than 24 hours old.
• Each time clearimport creates a new version, it annotates the standard create version event record with the comment from the original version.
• Each time clearimport creates a new VOB symbolic link, it creates a standard create symbolic link event record.
• clearimport always stamps the import file element event record with the current time. It stamps the create version and create element event records according to the original data unless you use the -nsetevent option.
• clearimport stamps the event record for the creation of a branch with the same time stamp as the version at which it was created.

  NOTE: When clearimport creates a branch, the branch and version 0 of the element inherit the history information (user, group, and time stamp) of the version from which the branch sprouts.

• clearimport stamps the event record for attachment of an attribute, label, or merge arrow with the same time stamp as the associated version.
• clearimport stamps event records for the creation of directory elements and type objects with the current time, and attaches the comment created by importer or the comment given with the -comment option.

Incremental Import and Restartability

clearimport can skip certain versions or entire elements, which gives you some flexibility:

• You can import an element in several passes. You may use incremental import for time-budgeting reasons (when there are too many versions to import at once), or because the original element is still being developed.
• You can restart clearimport if it terminates prematurely for any reason. clearimport quickly updates versions it has already imported, effectively resuming where it left off.

CAUTION: If you invoke clearimport with the -nsetevent option, it creates ClearCase versions that are newer than all the original files to be imported; thus, it is not restartable.

For each source version, clearimport does not create a corresponding version if it already exists on the target branch-that is, if it has the same time stamp (or a more recent one). However, even when clearimport bypasses version creation, it still updates the new version's metadata, such as version labels, using information from the source version.

Preserving the Case of Files

By default, clearimport converts all file names to lower case. This is generally the simplest and most efficient way to import files when you use the MVFS option of case insensitive mode (the default). Converting file names on import mirrors the behavior of new files created in case-insensitive mode. For more information, see Administering ClearCase.

Use the -pcase option when you need to preserve the case of files being imported; for example, when you import files whose names differ only in case (for example, Makefile and makefile) and you have disabled case-insensitive mode.

Handling of Unreadable or Troublesome Elements

clearimport prints an error when it cannot read an element version specified in the export data file. It creates version 0 of the unreadable element and continues to process the export datafile. Additionally, if clearimport has any difficulty importing any elements, it prints a list of such elements after it finishes.

PERMISSIONS AND LOCKS

Permissions Checking: To invoke clearimport, you must be the VOB owner or a member of the ClearCase group, unless you use the -nsetevent option. Locks: An error occurs if the target VOB is locked.

OPTIONS AND ARGUMENTS

VERBOSITY OF OUTPUT.  Default: clearimport prints a header for each kind of type creation (label, branch, attribute, and so on). When it creates directory elements, file elements, and VOB symbolic links, it prints a header as well as element names and version-IDs. When the import is completed, clearimport prints a message indicating that it has closed the directories.

-v·erbose

clearimport prints messages when it performs these operations: creates types, branches, directories, VOB symbolic links, attributes, or version labels; draws merge arrows; makes branches or elements obsolete; checks in or cancels checkouts of directories; and checks out onto a branch (when using a datafile created by clearexport_ffile -b).

CREATION OF IDENTICAL SUCCESSOR VERSIONS.  Default: When you invoke clearimport on a datafile created by clearexport_ffile, it does not create a new version that is identical to its predecessor.

-i·dentical

Creates a new version even if it is identical to its predecessor, but only if the file has a more recent date than the date on the version in the VOB.

TRANSCRIPTION OF HISTORY INFORMATION.  Default: The exporters extract historical information from each object and place it in the object's description in the datafile. The create version and create element event records created for the object by clearimport have the same information-user, group, and time stamp-as the original object.

NOTE: When clearimport creates a branch, the branch and version 0 of the element inherit the history information of the version from which the branch sprouts.

-n·setevent

Event records and historical information for new elements and versions reflect who ran the execution of clearimport and when, not the original data. You cannot use this option when you import a datafile created with clearexport_ccase.

CAUTION: If you invoke clearimport with the -nsetevent option, it is not restartable.

MASTERSHIP OF THE MAIN BRANCH. Default: Assigns mastership of the element's main branch to the VOB replica that masters the main branch.

-master

Assigns mastership of the main branch of the element to the VOB replica in which you execute the clearimport command.

PRESERVE CASE OF FILES. Default: clearimport converts all file names to lower case.

-pcase

Preserves the case of files being imported.

SPECIFYING A DESTINATION DIRECTORY.  Default: clearimport imports elements into the current directory.

-d·irectory destination-dir

clearimport imports elements into the specified VOB directory.

EVENT RECORDS AND COMMENTS.  Default: clearimport attaches the comment "created by importer" to any directories created during the import process.

-c·omment comment

clearimport attaches the specified comment instead of the default comment.

SPECIFYING THE DATA FILE.  Default: None. You must specify the datafile on which you want to invoke clearimport.

datafile

File created by clearexport_* command (by default, named cvt_data).

EXAMPLES

• Invoke clearimport on cvt_data, forcing creation of identical versions and attaching a comment to new directories.

c:\> net use * \\view\newview (set a view context)

Drive F: is now connected to \\view\newview.
The command completed successfully.

c:\> f:

f:\> cd newvob (go to VOB directory where data is to be imported)

f:\newvob> clearimport -identical -c "rick's import" c:\src\cvt_data (invoke clearimport)

• Invoke clearimport on cvt_data, enabling verbose output and importing elements into the \newvob directory.

c:\> net use y: \\view\view1

Drive Y: is now connected to \\view\view1.
The command completed successfully.

c:\> y:

y:\> clearimport -verbose -directory \newvob cvt_data

SEE ALSO

chtype, clearexport_ccase, clearexport_ffile, clearexport_pvcs, clearexport_rcs, clearexport_sccs, clearexport_ssafe, events_ccase, protect, rename