PVCS
®
Dimensions
™Data Migration Guide
Manager, PVCS Dimensions, PVCS Content Manager, PVCS Metrics, PVCS Pulse, PVCS Replicator, PVCS TeamLink, PVCS Tracker, PVCS TrackerLink, PVCS Version Manager, PVCS VM Server and WishLink are trademarks of MERANT. All other trademarks are the property of their respective owners.
ACKNOWLEDGEMENT. PVCS® Dimensions™ is implemented using the ORACLE® relational database management system. ORACLE is a registered trademark of Oracle Corporation, Redwood City, California.
No part of this publication, with the exception of the software product user documentation contained on a CD-ROM, may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to any electronic medium or machine-readable form without prior written consent of MERANT. Licensees may duplicate the software product user documentation contained on a CD-ROM, but only to the extent necessary to support the users authorized access to the software under the license agreement. Any reproduction of the documentation, regardless of whether the
documentation is reproduced in whole or in part, must be accompanied by this copyright statement in its entirety, without modification.
U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and the Documentation were developed at private expense, that no part is in the public domain, and that the Software and Documentation are Commercial Computer Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication or disclosure by the U.S. Government is subject to
restrictions as set forth in, among other sources, DFARS 252.227-7015 and 227.7202, or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at FAR 52.227-19, as applicable. Contractor is MERANT, 3445 NW 211th Terrace, Hillsboro Oregon 97124. Rights are reserved under copyright laws of the United States with respect to unpublished portions of the Software.
MERANT
3445 NW 211th Terrace Hillsboro, Oregon 97124
3
Table of Contents
Welcome to Dimensions . . . .
7
Typographical Conventions. . . 8
Ordering Hard-Copy Manuals . . . 9
Contacting Technical Support . . . 9
1
Introduction . . . 11
Disable CM Rules while Migrating Data . . . 12
Migrating Third-Party Configuration Management System Data into Dimensions . . . 12
Forms-Based Data Migration Utility . . . 12
Standalone Utilities . . . 13
PVCS Dimensions Data Interchange File Format (PDIFF ) Import/Export Utility . . . 14
Moving Version Manager and Tracker Data into Dimensions . . . 14
2
Data Migration Utility . . . 17
When to Use the Data Migration Utility? . . . 18
Prerequisites for Using the Data Migration Utility . . . 18
Starting the Data Migration Utility . . . 20
Invoking . . . 20
Logging In . . . 21
Initial Screen . . . 22
Specifying Upload Details . . . 23
Specifying PVCS Dimensions Item Types and Design Parts . . . 25
Generating Upload Script . . . 28
Running Upload Script . . . 30
Logging the Running of the Upload Script . . . 32
Restrictions . . . 33
3
Dimensions Migration Standalone Utilities. . . 35
Foreword. . . 36
General Information . . . 36
Case Translation . . . 37
Wild Card Characters . . . 37
Execution Authority: Change-Manager or Tool-Manager . . . 37
Dimensions Download . . . 38
Dimensions Upload . . . 40
RCS-Like Front End to Dimensions: prcs . . . 44
SCCS-Like Front End to Dimensions: psccs . . . 45
4
Data Interchange File Format (PDIFF). . . 47
Foreword. . . 48
PDIFF Specification . . . 48
Change Document POID . . . 50
System Change Document Attributes . . . 51
User Attribute – (Optional) . . . 53
Action - (Optional) . . . 53
Update – (Optional) . . . 54
Relate – (Mandatory: at least one design part relate required) . . . 55
Delegate – (Optional). . . 56
Attribute History – (Optional) . . . 56
Table of Contents
5
Design Part POID . . . 57
System Design Part Attributes . . . 58
User Attribute – (Optional) . . . 60
Relate – (Optional). . . 60
Relate History – (Optional) . . . 61
Control Plan POIDs . . . 61
Process Model Attribute Valid Sets. . . 61
Process Model Delegatees. . . 62
Process Model Change Document/Item Browse Templates . . . 63
Example PDIFF Files . . . 64
Change Document Example . . . 64
Design Part Example . . . 67
Process Model Example . . . 71
5
Using the pdiff Tool to Import/Export Data . . . 75
General Description . . . 76
Process Model Export . . . 77
Process Model Import . . . 78
Design Part Export . . . 79
Design Part Import . . . 79
Change Document Export . . . 80
Change Document Import . . . 82
Transferring a Dimensions Product. . . 84
Export Data via PDIFF . . . 84
Create a Base Database . . . 86
Import Data via PDIFF . . . 87
Limitations . . . 89
7
Welcome to Dimensions
Thank you for choosing MERANT™ PVCS® Dimensions™, a powerful process management and change control system that will revolutionize the way you develop software. Dimensions helps you organize, manage, and protect your software
development projects on every level—from storing and tracking changes to individual files, to managing and monitoring an entire development cycle.
Purpose of this manual
As of Dimensions release 7.1, Dimensions now addresses the issue of moving Version Manager and Tracker data into
Dimensions by providing a MERANT Consulting-led service that utilizes a newly developed XML-based PVCS Dimensions
Migration Utility. This utility moves Version Manager and Tracker data into Dimensions products, allowing the customer - with MERANT Consulting assistance - to define how the data is mapped into Dimensions. For further information please contact MERANT Consulting.
For more information
Refer to the PVCS® Dimensions™ Getting Started Guide for a
description of the Dimensions Documentation Set, a summary of the ways to work with Dimensions, and instructions for accessing the Online Help.
Edition status This is Edition 3.1 of the PVCS® Dimensions™ Data Migration Guide. The information in this edition applies to Release 7.1 of PVCS® Dimensions™ or later.
NOTE The prcs and psccs standalone tools described in this
document are not supported on the Windows NT/2000 version of Dimensions.
Typographical Conventions
The following typographical conventions are used in the online manuals and online help. These typographical conventions are used to assist you when using the documentation; they are not meant to contradict or change any standard use of typographical conventions in the various Dimensions components or the host operating system.
Convention Explanation
italics Introduces new terms that you may not be familiar with and occasionally indicates emphasis.
bold Emphasizes important information and field names. UPPERCASE Indicates keys or key combinations that you can use.
For example, press the ENTER key.
monospace Indicates syntax examples, values that you specify, or results that you receive.
monospaced italics
Indicates names that are placeholders for values you specify; for example, filename.
monospace bold
Indicates the results of an executed command.
vertical rule | Separates menus and their associated commands. For example, select File | Copy means to select Copy from the File menu.
Also, indicates mutually exclusive choices in a command syntax line.
brackets [] Indicates optional items. For example, in the following statement: SELECT [DISTINCT],
DISTINCT is an optional keyword.
. . . Indicates command arguments that can have more than one value.
Ordering Hard-Copy Manuals 9
Ordering Hard-Copy Manuals
As part of your Dimensions license agreement, you may print and distribute as many copies of the PVCS Dimensions manuals as needed.
If you do not want to print each of these online manuals, you can order hard-copy versions from MERANT. To order, please contact your sales representative for assistance.
Contacting Technical Support
MERANT provides technical support for all registered users of this product, including limited installation support for the first 30 days. If you need support after that time, contact MERANT using one of the methods listed in the installation guides, the
Getting Started Guide, or the Online Help.
Technical support is available 24 hours a day, 7 days a week, with language-specific support available during local business hours. For all other hours, technical support is provided in English. Support via the
web, E-mail, and telephone
SupportNet Customers can report problems and ask questions on the SupportNet web page: http://support.merant.com/
To submit an issue, click on the Report a Problem link and follow the instructions. You can also submit issues via E-mail or phone. Refer to the installation guides, Getting Started Guide, or Online help for a list of contact numbers, including numbers to call for local language support.
The SupportNet Web site contains up-to-date technical support information. Our SupportNet Community shares information via the Web, automatic E-mail notification, newsgroups, and
SupportNet Online is our global service network that provides access to valuable tools and information for an online community for users. SupportNet Online also includes a KnowledgeBase, which contains how-to information and allows you to search on keywords for technical bulletins. You can also download fix releases for your PVCS products.
11
1
Introduction
In this Chapter
For this section… See page…
Disable CM Rules while Migrating Data
12 Migrating Third-Party
Configuration Management System Data into Dimensions
12 Moving Version Manager and
Tracker Data into Dimensions
Disable CM Rules while Migrating Data
WARNING! If you have enabled Dimensions Change
Management Rules (CM Rules), then this option must be disabled while performing any of the data migration discussed in this manual, otherwise errors will occur. See the related manual
Process Modeling User’s Guide for details of CM Rules and how to
enable or disable them.
Migrating Third-Party Configuration
Management System Data into Dimensions
Dimensions addresses the issue of migrating data from existing third-party Configuration Management systems that are no longer adequate to fulfill your present or envisaged needs by providing various end-user tools, as described below.
Forms-Based Data Migration Utility
For a one-time or incremental migration (upload) of a list of specified files in a specified operating system directory structure into revisioned files (items) under Dimensions control (see
Chapter 2, “Data Migration Utility”). This facility is available to all users who have the roles to create new items or revise existing item revisions in Dimensions.
NOTE Downloading of data from Dimensions to an
operating-system directory structure of files is only available via the standalone download utility described below.
Migrating Third-Party Configuration Management System Data into Dimensions 13
Standalone Utilities
The standalone utilities (see Chapter 3, “Dimensions Migration Standalone Utilities”) comprise:
■ Download (see “Dimensions Download” on page 38) A one-time or incremental download of revisioned items from Dimensions control to a target operating system directory. This is equivalent to a Dimensions get operation with no item header substitution. This facility is available to all users who have the roles to get items from Dimensions. ■ Upload (see “Dimensions Upload” on page 40)
A one-time or incremental upload of a list of specified files in a specified operating system directory structure into
revisioned files (items) under Dimensions control.
■ PRCS (see “RCS-Like Front End to Dimensions: prcs” on page 44)
A RCS-like front end to the version control commands of Dimensions.
■ PSCCS (see “SCCS-Like Front End to Dimensions: psccs” on page 45)
A SCCS-like front end to the version control commands of Dimensions.
NOTE The standalone functions are all available on the UNIX or
Windows NT/2000 versions of Dimensions, with the exception of
PVCS Dimensions Data Interchange File
Format (PDIFF ) Import/Export Utility
The PDIFF format and pdiff Tool (see Chapter 4, “Data
Interchange File Format (PDIFF)” and Chapter 5, “Using the pdiff Tool to Import/Export Data”) are used to import/export the following Dimensions data to and from Dimensions:
■ Change Documents
■ Design Parts
■ Certain process model data, namely:
•
Valid sets.•
Delegation candidates.•
User role assignments.•
Change Document browse templates.Moving Version Manager and Tracker Data
into Dimensions
As of Dimensions release 7.1, Dimensions now addresses the issue of moving Version Manager and Tracker data into Dimensions by providing a MERANT Consulting-led service that utilizes a newly developed XML-based PVCS Dimensions Migration Utility. This utility moves Version Manager and Tracker data into Dimensions products, allowing the customer - with MERANT Consulting assistance - to define how the data is mapped into Dimensions. For Version Manager, the utility migrates users/groups, project databases, subprojects, archives, revisions, and specified version labels. The Version Manager mappings are as follows:
Moving Version Manager and Tracker Data into Dimensions 15
■ Archives and revisions are mapped to Dimensions items.
■ Version labels are mapped to Dimensions baselines, worksets, and attributes.
For Tracker, the utility migrates projects and software change requests (SCRs), transforming them into Dimensions change documents. The change document mappings can be:
■ to a generic type or
■ to specific types of change documents, such as
enhancements, defects, and issues, depending on the values of Tracker fields.
17
2
Data Migration Utility
In this Chapter
For this section… See page…
When to Use the Data Migration Utility?
18 Prerequisites for Using the Data
Migration Utility
18 Starting the Data Migration
Utility
20 Initial Screen 22 Specifying Upload Details 23 Specifying PVCS Dimensions Item
Types and Design Parts
25 Identifying Files that are NOT to
be Transferred
27 Generating Upload Script 28 Running Upload Script 30 Logging the Running of the
Upload Script
32 Restrictions 33
When to Use the Data Migration Utility?
The Data Migration Utility should be used when you wish to perform a one-time or incremental migration of files from an operating system directory into Dimensions items.
Using your answers to its guided questions, the Data Migration Utility creates a script of Dimensions commands to upload the nominated files into Dimensions.
Prerequisites for Using the Data Migration
Utility
NOTE For installation information, please refer, as appropriate,
to the Installation Guide for Windows Servers or the Installation
Guide for UNIX Systems plus the top-level README file.
Before running the Data Migration Utility to perform a data migration to Dimensions, you should ensure that:
■ You have the WORKSET-MANAGER role for the recipient Dimensions workset.
■ You have available the name of the operating system
directory from which files are to be migrated into Dimensions. ■ You have already created a Dimensions product (see Process
Modeling User’s Guide) for owning the files, and have the
name of that product available. When creating the product you need to:
•
Define item libraries.Prerequisites for Using the Data Migration Utility 19
•
Create an empty workset for the product.TIP Base your product on an existing product whose user
roles and lifecycles you have already defined. The installation-default demo product PAYROLL is a good example.
When creating your product from an existing product, if you wish to inherit the existing product’s design parts and item types ensure that you check the Copy design part structure
from the base product check box (plus the Copy the Item Process Definitions (IPDs) check box if you plan to use
Dimensions Build).
■ You have already created Dimensions item types and design parts for the files which are to be migrated into Dimensions. Furthermore, that you have decided on the item type and design part to be used for each set of files with the same filename extension. The Data Migration Utility initially generates filename pattern matching strings from the unique filename extensions found in the nominated source operating system directory, but you can customize these rules to suit your particular needs e.g. you might decide that all files with extension ".c”, with the single exception of
"foo.c”, should be migrated as item types "SRC” and be owned by design part "SRC MODULE”. Optionally, you can specify Dimensions item formats which are to be used for specific types of files so that their MIME type (used by I-Net) and storage semantics (text/binary) can be explicitly
specified.
■ You have created the Dimensions workset into which data will be migrated, thus making it available for selection by the Data Migration Utility. If a workset-id is not specified when requested in the Data Migration Utility, then the migrated data will appear in your default workset.
NOTE If you are working on a Windows NT/2000 system with a
Dimensions server installation, and you want to connect to a remote Dimensions server for a plain file upload, you must set
the MCX_SLAVE environment variable to mcxrelay.exe. If you
do not do this, the upload utility invoked by the Data Migration Utility connects to the local server and an incorrect Dimensions command script is generated.
Starting the Data Migration Utility
Invoking
Invoke the Data Migration Utility as follows: ■ Windows
Start | Programs | PVCS Dimensions | Data Migration Utility
■ UNIX
•
From Motif Client’s Control Panel, Products Tool, Design Tool, Version Tool and Change Tool:Utilities | Data Migration
NOTE The “Utilities” menu is only present in the Dimensions
Version and Dimensions Change tools if the menu sets “All Options” has been selected.
•
From the UNIX Dimensions server operating system prompt:Starting the Data Migration Utility 21
Logging In
The Data Migration Utility requests the following login information:
■ Windows NT/2000 Dimensions server and Windows NT/2000 and Windows 98 clients
The login information requested is the same as that requested for PC Client. Briefly this is:
•
If you are using a Windows NT/2000 node hosting a Dimensions server:On first use, a “Local” login dialog will be displayed that requests:
•
the Database login ID•
and the Database Password.The values for these fields were assigned to you when you were first registered to use Dimensions locally. The values for these fields and others, shown when More >> is selected, will usually have been given to you by the System Administrator.
•
If you are using a Windows NT/2000 or Windows 98 node hosting Dimensions clients:A “Remote” login dialog will be displayed that requests:
•
the User Id and Password for the remote operating system user account•
and the Database login ID and Database Password. The values for these fields were assigned to you when you were first registered to use Dimensions remotely. The values for these fields and others, shown whenMore >> is selected, will usually have been given to you by
Once the relevant fields in the “local” or “Remote” login dialog have been entered, connection to the Dimensions database will follow.
Please refer to the PC Client User’s Guide for more detailed information.
■ UNIX
None. All login information is inherited from the Motif Client itself.
Specifying Upload Details 23
The Data Migration Utility screens described in the following sections will walk you through the process of migrating (uploading) data from a specified operating-system directory structure into Dimensions. Use the Next > and < Back buttons to step forward and backward between screens respectively.
The steps to be completed are:
1 Specifying details required by the Dimensions upload function (see page 23).
2 Specifying the Dimensions item types and design parts to receive the migrated files (see page 25).
3 Identifying files that are to be excluded from the migration (see page 27).
4 Generating the Dimensions upload script (see page 28).
5 Running the upload script (see page 30).
6 Logging the running of the upload script (see page 32).
NOTE On entering the Data Migration Utility, the screen’s
banner will identify your current Dimensions username and the base database to which you are connected.
Specifying Upload Details
The Data Migration Utility generates a Dimensions command script to create a Dimensions item for each operating system file to be uploaded. For this script to be meaningful, the
prerequisites described in “Prerequisites for Using the Data Migration Utility” on page 18 need to have been performed. This screen enables you to:
■ Specify the operating-system directory from which files are to be uploaded, either by directly typing it or by selecting it via the Browse for Folder dialog accessed via the ... button. ■ Specify the Dimensions product to own the uploaded files by
selecting an existing value from the associated combo box. ■ Optionally specify the Dimensions workset to contain the
uploaded files by selecting an existing value from the
associated combo box. Remember that if this is left blank the files will appear in your default workset.
Press Next> when all the relevant details have been entered to progress to the next screen.
Specifying PVCS Dimensions Item Types and Design Parts 25
The Data Migration Utility will examine the content of the specified upload directory to determine all the unique filename extensions.
Specifying PVCS Dimensions Item Types and
Design Parts
This screen enables you to define transfer rules based upon pattern matching for the file name. Typically most of these rule details will be generated automatically by the Data Migration Utility from the unique filename extensions of the files to be
uploaded, but this screen enables you to complete any missing fields or, if desired, override fields in the automatically generated rules. A "catch all" rule with pattern "%" occurs first in the list. The displayed upload rules comprise:
■ A filename pattern match (text-entry field).
■ The Dimensions item format (combo box).
■ The Dimensions item type (combo box).
■ The design part to own the Dimensions item (combo box).
Instructions appear on the screen detailing how to fill in the filename pattern matching rules. More general rules must appear in the list before more specific rules to ensure that the more specific rules are attempted first.
The choice of format is dictated by the data type of the files concerned. The format specifies whether the file is manipulated as text or binary. These settings can be determined from the Dimensions Process Modeler. The owning design part will default to the top part of the product into which the migration is being performed.
To add a rule, select the entry after which you wish the rule to be added and press the Add Entry button.
To delete a rule, select the entry to be removed and press the
Delete Entry button.
Press Next > when all relevant details have been entered. The Data Migration Utility will check that all pattern matches have an associated item type and that the item formats are all registered. An error will be raised if any of these checks fail. The errors can be resolved by the use of the Process Modeler.
Identifying Files that are NOT to be Transferred 27
NOTE The rules you enter will be saved for future invocations of
the Data Migration Utility by the same user (provided you do not change the directory specification, etc at that future invocation). Files in the upload directory that match the specified rules but which you wish to be excluded from to the upload are specified in the next screen.
The Data Migration Utility will use this information together with the exclusion list supplied in the next step to generate a script of Dimensions Create Item/Update Item (CI/UI) commands to perform the upload.
Identifying Files that are NOT to be
Transferred
Having used the previous screen to specify filename pattern matching rules for the upload, the following screen enables you to specify certain filenames matching those rules to be excluded from the upload. These filenames, which must be relative to the top-level upload directory (i.e. they must not be absolute paths), may include the wildcard character % e.g. if in the previous screen you specified that files with pattern match %.c should be uploaded, here you can exclude say any .c file with a name beginning with the letter z by simply adding the entry z%.c to the exclusion list.
The Add Entry and Delete Entry buttons function as described for the previous screen.
Generating Upload Script
For upload from a specified directory structure, you first have to decide whether the upload is to be Unrestricted (default) or
Restricted. In an unrestricted upload, all files in the upload
directory are considered for uploading regardless of whether or not they have already been registered with Dimensions; whereas, in a restricted upload, only those files in the upload directory that have already been registered with Dimensions and which have changed are uploaded. Select the appropriate radio button.
Generating Upload Script 29
Next either accept the default names for the files into which the Data Migration Utility will place its generated data or specify your own, namely:
■ Dimensions script file (default upload.pcs)
■ Log file (default upload.log).
■ Configuration file (default upload.cfg)
In pressing the Next > button, the input gathered in this and previous screens is used to generate an upload configuration file which is then fed to the Dimensions upload program to
■ Dimensions UI (Update Item) commands (restricted mode), or
■ Dimensions CI (Create Item) and UI commands (unrestricted
mode).
A message box is displayed to inform you that the upload operation may take a while to complete. A further message box will be displayed when the Data Migration Utility has completed generating the command script.
At the next screen you are advised to browse the log file for any errors or warning messages that might have occurred.
IMPORTANT! Client versions of the Data Migration Utility will
additionally generate a Login dialog. Fill this in as described in
“Logging In” on page 21.
Running Upload Script
On the following screen, you are firstly advised to use the
integral browser (accessed by the Browse button) to examine the log file to check for any error or warning messages that may have been generated by the Data Migration Utility.
If the log file is satisfactory, you may wish to browse the script file (again using the integral browser) and configuration file (using an operating-system editor). With respect to the command script, it should be noted that Dimensions item creation is performed by matched Dimensions CI commands (with /NOKEEP parameter) and Fetch (get) Item (FI) commands (with /NOEXPAND
Running Upload Script 31
Once you are satisfied with the command script, press the Run button to execute the Dimensions commands. If no validation errors are detected, you will be presented with a confirmation box before execution can actually begin. Following that, you will automatically progress to the Running Upload Script dialog. If the Dimensions workset filename to be created contain sub-directories, then you must have a "WORKSET-MANAGER" role to perform the migration for the workset specified.
Logging the Running of the Upload Script
The Running Upload Script dialog logs progress of the
Dimensions commands. The current command being executed is displayed in the Current Command display area; any failures being reported in Failures scrolling window; and the total number of commands executed together with the number of successes and failures are reported in the No. of commands
executed so far, Success and Failure display areas. Additionally,
you can browse the script file being run and the logfile generated by pressing the appropriate Browse button.
Restrictions 33
Press the Close button to return to the Run Upload Script dialog. There, press the Close or Finish button to complete the
migration process, or press the < Back button to step back in the Data Migration Utility.
Restrictions
Multiple invocations of the Data Migration Utility by the same user connecting to the same Dimensions base database are not supported i.e. only one session per user per base database is supported.
If two or more users attempt to upload files at the same time, Ids generated in scripts may conflict, causing Oracle errors to occur.
35
3
Dimensions Migration
Standalone Utilities
In this Chapter
For this section… See page…
Foreword 36 General Information 36 Dimensions Download 38 Dimensions Upload 40 RCS-Like Front End to Dimensions:
prcs
44 SCCS-Like Front End to
Dimensions: psccs
Foreword
This chapter describes the four Dimensions standalone utilities listed below that are used for the migration of data. Some of these utilities are intended for use by change-managers, product-managers or part-managers only – these will be
identified as such when discussed. Also, some of the utilities are only available for certain operating systems – these too will be identified where appropriate.
■ download This utility performs a download of a list of
specified files under Dimensions into a target directory. ■ upload This utility performs an upload of a list of specified
files in a user directory into Dimensions.
■ prcs [Not Windows NT/2000] This utility provides a RCS-like front end to the version control commands of Dimensions.
■ psccs [Not Windows NT/2000] This utility provides an
SCCS-like front end to the version control commands of Dimensions.
The standalone utility pdiff is discussed in Chapter 5, “Using the pdiff Tool to Import/Export Data” following an introduction to its format in Chapter 4, “Data Interchange File Format (PDIFF)”.
General Information
All these utilities are run as independent programs from the operating system prompt (or from a command script file). They require the user to have performed a standard Dimensions user’s login, which sets up the environment required for all Dimensions processing. The utilities all reside in the directory specified by the environment variable PCMS_PROG – which the standard login will include in the directory search path.
General Information 37
The syntax of each utility is explained under separate headings below, but the following general points are best explained in detail now.
Case Translation
Lowercase letters can be included in the values of parameters, and will automatically be interpreted as the equivalent in uppercase. This applies to all parameters, except those which are
specifically stated to be case-sensitive.
Wild Card Characters
In several parameters a range of possible values can be indicated by including a % (percent) character, which is interpreted as matching any zero or more characters. This applies only to
parameters for which it is stated that wild card % may be used.
In other parameters a null string can be used to imply all possible values; a null string is specified as "" (two consecutive
double-quote characters). This applies only to parameters for
which it is stated that a null string may be used.
Execution Authority: Change-Manager
or Tool-Manager
If the parameters are specified so that a utility is required to process the change documents of several different products in the same execution, then the user must either have the
change-manager role for every product concerned, or else have the tool-manager role for the database.
Dimensions Download
This utility is available to all users who have the roles to get items from Dimensions. It performs a download of a list of specified files under Dimensions into a user directory. A download of a Dimensions file is equivalent to a get operation with no item header substitution i.e.FI /NOEXPAND.
Syntax download [ --version ] [ -n [ -s script-file ] ] [ -r ] [ -C start-dir ] [ -W workset-spec | -B baseline-spec ] [ -D root-dir ] [ -f rule-file ] [ -p database-specifier] [-l log-file] [ -N ] [ -E ] [ input-file ]
<input-file>, -, -r download performs a download of the list of files held in Dimensions specified in <input-file>. If no <input-file> is specified, download searches the workset default directory unless “–” is specified, in which case it reads a list of filenames from the standard input. If the -r option is specified, download
will perform a recursive search of the workset directory corresponding to the current working directory for items to download.
IMPORTANT! To ensure correct operation of download , files specified in <input-file> must be separated with
<line-feed><carriage-return>, this includes the last file in list. If this is not done, you may under certain circumstances get a Path
too long error message.
Pcmsfile, -f If no <rule-file> is specified, download will look for
Pcmsfile in the current working directory and the workset
default directory. download restricts searches to the specified workset. It does not preserve anything (as the whole point is to export items from Dimensions). As a result, the only sensible rule directive to put in a download rule file is nofetch. This directive instructs download to ignore the matching files. The syntax for these directives is exactly the same as that used for Dimensions
Dimensions Download 39
Make – please refer to the Dimensions Make chapter in
Dimensions Build User’s Guide for details.
Example If you want to download the entire contents of a workset except the '.doc' file and the contents of the directory 'test_data', then you would use the command:
download -W "PROD:WORKSET" -D /your/root -r -f your-rules
The file 'your-rules' would contain:
test_data/% %.doc: nofetch
-W, -D The -W option specifies the workset from which to download the files, 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 downloaded. The name of the script can be specified using the -s option. If no name is specified, the name download.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 from which the files are to be downloaded. 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
download will be written.
-B Specifies that downloads should be made from a specified baseline rather than a workset.
-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.
-E Causes files to be expanded when they are downloaded. The default is to download files in unexpanded form.
-C Create the file in the start (output) directory specified by
-C start-dir
Dimensions Upload
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 example: Example %: $FORMAT = TEXT %.c %.h: $FORMAT = C %.cpp CC/include/%.h: $FORMAT = C++
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:
%:
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
-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).
RCS-Like Front End to Dimensions: prcs
This utility [Not available for Windows NT/2000] is available to all users who have the roles to do the associated Dimensions
operations. It provides an RCS-like front end to the version control commands of Dimensions.
Syntax prcs subcommand [ option ... ] [ filename ... ] [Dimensions option ... ]
filename prcs applies an RCS-like subcommand to the Dimensions item associated with each specified filename. Additionally,
SCCS-Like Front End to Dimensions: psccs 45
filename, PCMS, PCMS/<wildcard>
The mapping between the filenames specified to the prcs
command and the associated Dimensions item is derived from
the filename by searching for a matching workset filename in
the current workset. The prcs command expects these items to reside in a workset directory that, when appended to the current workset root directory, equates to the current working directory. If the filename is given as PCMS or PCMS/<wildcard> then the
command is applied to all Dimensions items which are in the same relative sub-directory of the workset and which match the wildcard. The wildcard is in standard Dimensions format.
prcs uses the same mechanism as Dimensions Make to determine the correct workset for operation. If it is unable to determine a workset, then a diagnostic message is issued. Please refer to the Command-Line Reference Guide for full details on
prcs.
SCCS-Like Front End to Dimensions: psccs
This utility [Not available for Windows NT/2000] is available to all users who have the roles to do the associated Dimensions operations. It provides an SCCS-like front end to the version control commands of Dimensions.
Syntax psccs subcommand [ option ... ] [ filename ... ] [Dimensions option ... ]
filename psccs applies an SCCS-like subcommand to the Dimensions item associated with each specified filename. Additionally,
Dimensions-specific options may be specified.
filename, PCMS, PCMS/<wildcard>
The mapping between the filenames specified to the psccs
command and the associated Dimensions item is derived from
the filename by searching for a matching workset filename in
the current workset. The psccs command expects these items to reside in a workset directory that, when appended to the current workset root directory, equates to the current working directory.
If the filename is given as PCMS or PCMS/<wildcard> then the
command is applied to all Dimensions items which are in the same relative sub-directory of the workset and which match the wildcard. The wildcard is in standard Dimensions format.
psccs uses the same mechanism as Dimensions Make to
determine the correct workset for operation. If it is unable to determine a workset, then a diagnostic message is issued. Please refer to the Command-Line Reference Guide for full details on
47
4
Data Interchange File Format
(PDIFF)
In this Chapter
For this section… See page…
Foreword 48 PDIFF Specification 48 Change Document POID 50 Design Part POID 57 Control Plan POIDs 61 Example PDIFF Files 64
Foreword
This chapter describes PDIFF, the PVCS® Dimensions™ Data Interchange File Format, that is used to import/export data to and from Dimensions. Chapter 5 describes the associated tool
pdiff.
NOTE In this chapter of the manual PDIFF will be used when
referring to the PVCS® Dimensions™ Data Interchange File Format itself and pdiff will be used when referring to the associated tool.
PDIFF supports the following Dimensions data: ■ Change Documents
■ Design Parts
■ Process Model (Control Plan)
•
Valid Sets•
Delegation Candidates•
User Role Assignments•
Change Document Browse Templates.PDIFF Specification
PDIFF is a text file format composed of lines no longer than 255 characters. PDIFF files may only contain blank lines, comments and PVCS® Dimensions™ Object Instance Definitions (POIDs):
PDIFF Specification 49
A PDIFF file begins with a 10-line header followed by one or more POIDs. The PDIFF header contains the PDIFF version, the creation date and time as well as the name of the creator of the file. The rest of the lines in the header are reserved for future use.
PDIFF :==
<PDIFF Header> <POIDS>
The following rules apply to the PDIFF contents:
7 The number of characters in each line of the file must not exceed 255.
8 KEYWORD may either be a keyword specially recognized by
Dimensions (see below) or refer to a non-system change document field.
9 <string> is normally a maximum 1978-character value either on the same line or spanning several lines with each line terminated with the back-slash character ( \ ). Note that when determining a value spanning several lines, the character \ at the end of each line and the subsequent new line character will be ignored. For the change document descriptions, ( $DETAILED_DESC, $ACTION_DESC,
$AD_HISTORY), values may be longer than 1978 characters.
10 Any "\n" found within <text-value> will be interpreted as a new line character and, consequently, a new line will be inserted at that point within the text.
Comments These start with a # character and are terminated by an end-of-line character.
POIDs Dimensions deals with a number of object types i.e. ITEM, PART, CHDOC, CONTROL PLAN, etc., but
the scope of this manual only covers CHDOC, PART, and some CONTROL PLAN POIDs.
11 A "\F" found for the first two characters of values detailed in (3) will indicate that the following string is to be interpreted as a filename from which to get the attribute or description value.
The PDIFF header has the following format:
<PDIFF Header> :==
#PDIFF<version number>
#DATE <DD-MMM-YYYY> <HH:MM:SS> #CREATED BY <name>
#RESERVED
Change Document POID
A change document definition begins with the OBJECT CHDOC
statement on a single line and ends with a END_OBJECT
statement. The body of the CHDOC POID consists of system attributes, user attributes, actions, updates and relations.
<CHDOC POID> :== OBJECT CHDOC
<attributes>
<composite chdoc attributes> END_OBJECT
<attributes> :==
<system chdoc attribute> | <user attribute> | <attributes>
<composite chdoc attributes> :==
<action> |
<update> |
<relation> |
<delegate> |
<attribute history> |
<attribute update history> | <composite chdoc attributes>
Change Document POID 51
<system chdoc attributes> :== $DOC_SEQ <number>| $IDENTIFIER <string> | $ARCHIVED {Y|N} | $TYPE <string> | $CREATE_DATE <date> | $TIMEZONE <timezone> | $CURRENT_STATUS <string> | $ORIGINATOR <string> | $LIFECYLE_ID <string> | $LC_SEQ <number> |
$DETAILED_DESC <long string> |
$ACTION_DESC
.CURRENT <long string>
.ALL_PREV <long string> |
$AD_HISTORY
.ACTION_NO <number>
.FILE \F<filename>
System Change Document Attributes
System attributes for a Dimensions change document can be one of:
■ Change Document Sequence – (mandatory)
This is a unique sequence number given to each change document within a product.
■ Change Document Identifier – (optional)
The change document identifier is composed of the product identifier, the change document type and the Change Document Sequence number:
<product id>_<type>_<doc_seq> ■ Archive flag – (optional)
A flag to indicate if the change document is to be archived or not, the default is not to archive the change document.
■ Type of the Change Document – (mandatory)
■ Date the Change Document was Created – (mandatory)
■ Timezone – (optional)
This indicates the timezone in which the PDIFF file was generated. Currently, this field is for information purposes only, and is ignored on load.
■ Current Status of the Change Document – (mandatory)
■ The Originator of the Change Document – (mandatory)
■ Lifecycle Id – (optional)
The lifecycle used by the change document. ■ Lifecycle Sequence – (optional)
The lifecycle sequence is a number indicating the sequence of the current status within the lifecycle. The lifecycle and the lifecycle sequence must be both specified together or not at all for a given change document.
■ The Detailed Description of the Change Document – (optional)
■ Action Description (this has two parts) – (optional) The current action description and concatenation of all previous action descriptions.
■ Action Description History (this has two parts) – (optional) The action description in a file together with an action number. There may be many of these statements, each for a different action number.
Change Document POID 53
User Attribute – (Optional)
Dimensions user attributes are defined by the product manager as part of the process model (control plan) definition for the Dimensions product. Each user-defined attribute will have a variable name and this is used in the PDIFF to refer to this attribute. In PDIFF, user attributes are specified as:
<user attribute> :==
<attribute variable name> <attribute value> <attribute variable name> :==
<string>
<attribute value> :== <string>
NOTE <attribute variable name> cannot contain white
space characters. When importing a change document the loader will not validate the values of the change document attributes against their associated valid sets, if any.
Action - (Optional)
An action (i.e. a state transition such as a sign-off or rejection) performed by a user. There may be several of these for the different change document action numbers.
NOTE Each state transition performed by a user on a change
document is represented in Dimensions as a separate action number. The action number starts from 0 when the change document is created in the user's held list (i.e. private area). When the change document is entered (saved) into the system it is given the action number 1. The action number is then
incremented each time the change document is actioned to a new state.
<action> :== $ACTION .ACTION_NO <number> .DATE <date> .USER <string> .STATE <string> .PHASE <string> .TYPE A
.COMMENT <max 80 string>
NOTE The .COMMENT value must be one of the following:
"Document created" or "Actioned document from <STATE1> to <STATE2>".
Only the first 80 characters of the .COMMENT value are read; the
rest are ignored. The .TYPE specifier is optional.
Update – (Optional)
This is a record of the update history for the change document at specific action numbers. There is an optional .TYPE specifier to
indicate Update (U) or Delegate (D) history – there may be several such entries. The update statement consists of the action number at which the update was performed, user who performed the update, the state in which the update was made, date of update and an update comment if any.
<update> :== $UPDATE .ACTION_NO <number> .DATE <date> .USER <string> .STATE <string> .PHASE <string> .TYPE {U|D}
Change Document POID 55
NOTE The .COMMENT value must be one of the following:
"Change document attribute(s) updated", "Added Delegation for...", "Related Design Part..." or
"Added action description".
Only the first 80 characters of the .COMMENT value are read; the
rest are ignored. The .TYPE specifier is optional.
Relate – (Mandatory: at least one
design part relate required)
This statement defines a single relationship which the change document has with the specified affected object. The relation statement consists of the action number at which the
relationship was created, type of the relationship (e.g.
DEPENDENT, AFFECTED, INFO, IN RESPONSE TO or "user defined type"), the class of the related object (e.g. CHDOC,
ITEM or PART), the date the relationship was created and the user who created the relationship.
NOTE A user defined relationship type must be defined using
the Process Modeler Object Type Definitions | (Change Doc) | Rel Types function
For change documents, the destination object may be a child or a parent. In the .OBJECT part of the $RELATE statement a
CHDOC: implies a child and a PARENT_CHDOC: implies a parent.
<relation> :== $RELATE
.ACTION_NO <number> .TYPE <string>
.OBJECT CHDOC:<chdoc id> | PARENT_CHDOC:<chdoc id> | PART:<part spec> |
ITEM:<item spec> .DATE <date>
.USER <string>
Delegate – (Optional)
This statement allows the delegation of the change document to a specified user having the specified role. There are two optional specifiers: .CAPABILITY and .OPERATION. The .CAPABILITY
specifier may be one of Secondary (S), Primary (P) or Leader (L) with the default being Primary (P) and .OPERATION may be one
of ADD or REPLACE.
The delegate statement has the following syntax:
<delegate> :== $DELEGATE
.USER <string> .ROLE <string> .CAPABILITY { S | P | L } .OPERATION { ADD | REPLACE }
Attribute History – (Optional)
This statement allows attribute history to be added for each action number of a change document. The specifiers are
.ACTION_NO for the action number of the history and
.ATTRIBUTE consisting of the attribute number, the sequence
and the attribute value. The sequence starts at 1 and indicates if the attribute had multi values. All single valued attributes must have a sequence number of 1. The attribute number is in the range 1 to 240. The .ATTRIBUTE specifier is repeated for each
Design Part POID 57
<attribute history> :== $ATTRIBUTE_HISTORY
.ACTION_NO <number> <attribute info list> <attribute info list> :==
<attribute info> [<attribute info list>] <attribute info> :==
.ATTRIBUTE <attr_no>:<attr seq>:<string>
Attribute Update History – (Optional)
This statement allows attribute update history to be added for each update to an attribute. The specifiers .ACTION_NO, .DATE,
.USER, .STATUS must correspond to a $UPDATE statement in
the change document POID.
<attribute update history> :== $ATTRIBUTE_UPDATE_HISTORY .ACTION_NO <number> .ATTR_NO <number> .SEQ_NO <number> .DATE <date> .USER <string> .STATUS <string> .PREV_VALUE <string> .NEW_VALUE <string>
Design Part POID
A design part definition begins with the OBJECT PART
statement on a single line and ends with a END_OBJECT
statement. The body of the PART POID consists of system
<PART POID> :== OBJECT PART <attributes> <relate_history> END_OBJECT <attributes> :==
<system part attribute> | <user attribute> | <attributes>
<composite part attributes> :== <part relate> | <part relate history> | <composite part attributes> <system part attributes> :==
$PRODUCT_ID <string> | $PART_ID <string> | $VARIANT <string> | $CURRENT_PCS <string> | $PCS <string> | $STATUS <string> | $DESCRIPTION <string> | $CREATE_DATE <string> | $CATEGORY <string> | $USER <string> | $PREV_PART <part spec>
System Design Part Attributes
System Attributes for a Dimensions Design Parts can be one of: ■ Product Identifier – (mandatory)
This is the owning Dimensions Product of the PART POID. ■ Design Part Identifier – (mandatory)
Design Part POID 59
■ Design Part Variant – (mandatory) This is the Variant of the PART POID.
■ Part Control Status (PCS or CURRENT_PCS) – (mandatory) This is the revision of the PART POID. $PCS or
$CURRENT_PCS may be used as the specifier. $CURRENT_PCS
is used for design parts that are the most current revisions and that are OPEN. $PCS is used for DESIGN PARTS that are
CLOSED or REJECTED. ■ Status – (mandatory)
This is the lifecycle status of the PART POID and has one of
the following values: OPEN, CLOSED or SUSPENDED.
■ Description – (optional)
This is the description of the PART POID. ■ Create Date – (mandatory)
This is the creation date of the PART POID. ■ Category – (mandatory)
This is the design part type category of the PART POID. ■ User – (mandatory)
This is the owning user of the PART POID. ■ Previous Design Part – (optional)
This is a reference to a design part specification from which this PART POID was derived when the design part revision
User Attribute – (Optional)
Dimensions user attributes are defined by the product manager as part of the control plan definition for the Dimensions product. Each user-defined attribute will have a variable name and this is used in the PDIFF to refer to this attribute. In PDIFF user
attributes are specified as:
<user attribute> :==
<attribute variable name> <attribute value> <attribute variable name> :==
<string>
<attribute value> :== <string>
NOTE <attribute variable name> cannot contain white
space characters. When importing a change document the loader will not validate the values of the change document attributes against their associated valid sets, if any.
Relate – (Optional)
This statement defines a single breakdown or usage relationship to another design part. PARENT_PART in the .OBJECT specifier
indicates the relationship is to be reversed. All design parts other than the root ones must have parent BREAKDOWN relationships.
<part relate> :== $RELATE
.TYPE {BREAKDOWN|USAGE}
.OBJECT PARENT_PART:<part spec> |
PART:<part spec>
.DATE <date>
Control Plan POIDs 61
Relate History – (Optional)
This statement defines the history for the changes made to the design part BREAKDOWN and USAGE relationships.
<part relate history> :== $RELATE_HISTORY
.TYPE {BREAKDOWN|USAGE}
.OBJECT <part spec>
.DATE <date>
[.USER <string>]
Control Plan POIDs
There are three process model (control plan) POIDs currently supported by PDIFF:
1 VALID_SET, DELEGATEES
2 CHDOC_BROWSE_TEMPLATES
3 ITEM_BROWSE_TEMPLATES
Process Model Attribute Valid Sets
The valid set POID defines multiple choice for attribute values for the given Dimensions product process model (control plan). The valid set POID is defined as follows:
<VALID SET POID> :== OBJECT VALID_SET $PRODUCT_ID <string> $VALID_SET_NAME <string> $NO_COLUMNS <number> $ERROR_MESSAGE <string> $DESCRIPTION <string>
END_OBJECT
<valid set values> :==
<value set value> [<valid set values>] <valid set value> :==
$VALUE .DISP_ORDER <number> .COL1 <string> .COL2 <string> .COL3 <string> .COL4 <string> .COL5 <string> .COL6 <string> .COL7 <string> .COL8 <string>
Process Model Delegatees
The delegatee POID defines user role assignments and delegation candidates for a given Dimensions product process model
(control plan).
<VALID SET POID> :== OBJECT DELEGATEE
$PRODUCT_ID <string>
<delegatees user_role_assignments> END_OBJECT
<delegatees user_role_assignments> :== <delegatee user_role assignment>
[<delegatees user_role_assignments>] <delegatee user_role_assignment> :== <delegatee> | <user_role_assignment> <delegatee> :== $DELEGATEE .ROLE <string> .USER <string> .CAPABILITY [P|S|L] .PART_ID <string> .PART_VARIANT <string>
