This utility is available to all users who have the roles to create new items or revise existing item revisions in Dimensions. It performs an upload of a list of specified files from a user directory into the Dimensions repository.
Syntax upload [ --version ] [ -n [ -s script-file ] ] [ -r ] [-C start-dir ] [ -W workset-spec ] [ -D workset-dir ] [ -U ] [ -R ] [ -f rule-file ] [ -p database-specifier ] [ -l log-file ] [ -N ] [ -E ] [ -k | -z ] [ input-file ]
<input-file>, -r upload performs an upload of the list of files specified in
<input-file>. If no <input-file> is specified, upload will attempt to upload every file in the current working directory. If the -r option is specified, upload will attempt to upload every
Dimensions Upload 41
file found recursively below the current working directory.
Symbolic links are ignored.
-U Specifies that an unrestricted upload should be performed. In this mode, upload will revise items for files it finds in the target workset and additionally create items for any files it cannot find there. In the default restricted mode, upload simply revises items if the corresponding file both exist and has changed.
-f, <rule-file>, Pcmsfile
If no <rule-file> is specified, upload will look for Pcmsfile in the current working directory and the workset default directory. The Pcmsfile contains filename pattern matching rules that tell the upload program which files are to be to considered for uploading and which should be excluded from consideration. The preserve and nopreserve directives are respectively used in these rules to nominate files for, or exclude files from, consideration when performing an upload; they are also used to name design parts to own the Dimensions items, types for the items and various other properties. The syntax for these directives is exactly the same as that used for Dimensions Make – please refer to the Dimensions Make chapter of
Dimensions Build User’s Guide for details.
NOTE The nopreserve directive overrides the preserve directive if there is a filename pattern match, and that the order is important – more general pattern matches should be specified before more restrictive ones.
Because upload has to map files to Dimensions items, it needs more complicated rules than download. The minimum
requirement is a rule-file that specifies an item type to use, for example:
Example %:
preserve $TYPE = SRC
The upload facility can work out defaults for just about
everything else, except for the format to use for files without a suffix. You can use two approaches to resolve this. One is to
provide a default format and override it where appropriate, for
This example gives all files the format TEXT, except for ’.c’ and
’.h’ files which use format C, unless it is a ’.h’ file in the directory ‘CC/include’ (or a descendent), in which case format C++ is used. Files with a ‘.cpp’ suffix use format C++ too.
The other approach is to explicitly specify the format for each file without a suffix, for example:
Example scripts/%:
$FORMAT = SH README:
$FORMAT = TEXT
In this example, all files in scripts get the format SH, while all files called README use the format TEXT.
Configuration search paths can be used to allow the files on disk to be compared against the contents of more than one workset.
This is most useful when using upload to merge several projects with some common code into a single Dimensions product.
Example For example, say you have PROJECT1, PROJECT2 and PROJECT3.
First, PROJECT1 is loaded into PROD:WORKSET1. Then, when you load PROJECT2, you could use the same rule-file but with the following additional directive:
%:
configuration PROD:WORKSET1
Dimensions Upload 43
Files that exist in both PROJECT1 and PROJECT2 will not be loaded from PROJECT2 (unless, of course, the version in PROJECT2 is different). This works best if you use item types with edit at initial lifecycle state disabled and make the worksets for the second and subsequent projects branch worksets. You can then use the workset merge facilities to resolve any conflicts between the projects.
-W, -D The -W option specifies the workset to upload into and the -D option specifies the directory to treat as the workset default directory.
If no -W option is specified, the current workset is used, as determined from the current working directory. If no -D option is specified, the current working directory is used as the workset default directory.
NOTE The current working directory must be the specified workset default directory or a descendent thereof.
-n, -s Specifying -n causes a command file to be generated, rather than the file being directly uploaded. The name of the script can be specified using the -s option. If no name is specified, the name upload.cmd will be used and the file will be placed in the current working directory.
CAUTION! In Windows NT/2000, “.cmd” is reserved as the filename extension for an executable. You must make sure that the specified filename does not end in “.cmd”.
-p Enables you to specify the database into which the files are to be uploaded. If not specified, the current database is used.
--version Enables you to check the version of the download you are running. It merely displays the version number and then exits.
-l Enables you to specify a file where error messages from the upload will be written.
-N Causes dual-mode length and checksum matching to be disabled.
The dual-mode feature matches files using the length and checksum of both the binary and text interpretation of a file where the native text file format is not the same as UNIX text file format.
Gotten Files By default (unless -z is specified as described below), files will be gotten back to disk after they are uploaded. These gotten files will also by default be unexpanded unless the addition -E option is specified to cause them to be expanded.
-R Causes upload to check in locally checked out files in addition to unchecked out files that have been modified locally.
-k Causes user files to be retained when they are uploaded.
-z Stops files being gotten back to disk after they have been
uploaded i.e. it will override the normal default action which is to get these files.
-C Create the file in the start (output) directory specified by -C start-dir
-E Expand gotten files (default is unexpanded).