PDMS 12.0 to 12.1 Upgrade

15.01.2013 13:49

1 Introduction

To prepare a 12.0 project for 12.1 use, a database upgrade is required. To perform the upgrade the user must do the following:

  • Start ADMIN.
  • Lock the project.
  • Invoke the upgrade process. Refer to Upgrade Commands.
  • Unlock the project.

Note: It is not a requirement that Catalogue Projects need to be upgraded. These can remain at version 12.0.

1.1 Part Upgrades

A number of changes made in 12.1 require an upgrade to parts of the data model and the database. Each individual change is referred to here as a Part Upgrade. In general these Part Upgrades have been designed to be 'optional' from a user perspective, in that the 12.1 software can work with a database that has not been upgraded and the software will degrade gracefully - that is, the software will continue to work, although new functionality may not be fully present. This means that it is possible for users to continue to work with Foreign DBs, which may be shared with 12.0 or earlier projects and which have not been upgraded, included in their projects. An example would be a Corporate Catalogue DB used for 12.0 and multiple projects.

A framework is provided to run all the part upgrades. Thus the user is provided with a single upgrade to execute - all or nothing.

  • As a consequence of the 'all or nothing' approach, the project must remain it its original state if any part of the upgrade fails.

1.2 Upgrade Framework

1.2.1 Framework Functionality

The upgrade will be invoked from Admin and will control the upgrade process, and run each Part Upgrade in the appropriate order.

The upgrade process will put an upgrade number in databases, indicating the level to which they have been upgraded. This will make it easy to detect on opening whether a database has or has not been upgraded. This upgrade number will also be used by the Reconfigure.

Part upgrades outside the Framework

  • Are independent of all other non-framework upgrades (i.e. non-framework upgrades can be applied in any order
  • Have a method of determining whether or not they have been applied, not relying on the upgrade number
    • This to be available to the user

It will not be possible to backtrack to pre-upgrade sessions.

1.2.2 Global

Each DB must be entirely in either an upgraded or non-upgraded state for PDMS software to operate. Therefore it is necessary that all extracts of a DB are processed during an upgrade.

The granularity of an upgrade will be a Project, excluding Foreign DBs.

1.2.3 Upgrade Commands

There is a single upgrade command which will work on a DB or the whole project. If successful, the upgrade number for the DB will be updated.

The suggested syntax is:

DBUP DB team/dbname TO LATEST

The user can replace LATEST with a known upgrade number which can be found using the Q UPGRADE LIST command.


Internally the code will invoke all upgrades to get to the required upgrade number. If the upgrade number is omitted, then it will be upgraded to the latest.

Any extracts will be refreshed as part of an upgrade when their Master database is upgraded.


This command lists the current upgrade version of all databases in the project and the upgrade version that the software works on. If databases are on a lower upgrade version than the software, then the "upgrade required" text accompanies the database.


This command lists all the part upgrades ("item:" in the response) organized per upgrade version. I.e. a part upgrade belongs to a particular upgrade version. An upgrade version is the increment we do database upgrades in. The upgrade version is a 8-digit number. So to upgrade a database to a specific upgrade version, the user can give the command


This command will upgrade the database MYTEAM/MYDB to upgrade version 12010103 including the versions 12010100, 12010101, 12010102. I.e. upgrades versions are applied sequentially, and it is not possible to skip any intermediate versions.

Global Projects

In Global projects, databases must be upgraded at their primary location. The upgrade must be run separately at each project location, since any secondary databases will be ignored.

All descendant extracts must be primary at the same location as their master database, otherwise the database hierarchy will not be upgraded. Such databases can be identified using the ISEXCP attribute. If a database is primary (ISPRIM TRUE), but not all its extracts are primary (ISEXCP FALSE), then it will be omitted from a project upgrade.

Additional syntax is available in Global projects to allow for centrally administered system databases. These cannot be upgraded at the administered location, but must be upgraded at their primary location:


Where locnam defines the LOCID, name or reference (gid) of a Location element in a Global project. This syntax will be available in ADMIN.

The ALLSYSTEM option in a Global project allows all primary system databases to be upgraded.
Individual satellite system databases may be upgraded using the 'SYSTEM FOR locnam' syntax provided they are primary. If the Global daemon is running, the upgrade will issue Global commands to send such administered system databases back to the administered locations.

It is the responsibility of the System administrator to make sure that updates are run to send all modified databases to satellites; and to relocate extract databases as required back to their original primary locations.

In a Global project, the UPGRADE STATUS query (see below) will also show the status of secondary databases and extract hierarchies. This will help administrators to identify which extracts will need relocating.

Note: Extract hierarchies which contain secondary extracts cannot be upgraded.

1.2.4 The Upgrade Process

The upgrade process will be undertaken by System Administrators responsible for the project at all locations. It is feasible that system administration may be taken at a remote location for some locations. When upgrading multiple projects then many System
Administrators will need to co-ordinate. The upgrade process may become complicated if running through different time zones. The upgrade process will upgrade one project at a time. Consideration to the order of projects to be upgraded will need to be undertaken by the user.

The projects will need to be locked for the duration of the upgrade, with all Users out of the system.

The following upgrade steps must be performed by an administrator:

  1. Make sure all users have exited from project
  2. Lock project at all locations (upgrade will check for this. (see below)
  3. Disable Automatic update events
  4. Expunge all users in the system at the local location
  5. Flush data from Working extracts - these will not be considered
  6. Check for No Transient Databases
  7. DICE project
  8. If DICE reveals issues, address them, then re-run DICE
    Administrator may want to unlock project while DICE issues are being addressed, but
    will need to exclude all users and Lock project again before final DICE]
  9. [After clean DICE]
  10. Back-up project at all locations

The following upgrade steps will performed by the upgrade:

  1. At each location, run Update
  2. Deep Refresh with Propagation on all DBs
  3. Temporarily relocate all non-Foreign DBs, to make appear Primary at Hub
  4. Loop over all non-Foreign DBs in project at Hub and Upgrade (i.e. run each framework part-upgrade on that DB)
  5. Do NOT perform Savework during this process
  6. Update at all locations
  7. Refresh
  8. Post-process at all locations
  9. Optionally Merge Sessions
  10. Optionally Reconfigure for Unicode
  11. Update at all locations
  12. Relocate DBs back to original locations
  13. DICE check project
  14. Perform non-framework upgrades if applicable

The mechanism by which the Administrator will tell the upgrade whether to Merge Sessions, and whether to Reconfigure for Unicode, are design details which will be described in the design documentation.

Locking the Project

The project as a whole cannot be locked, only individual locations; however, it is possible to lock all online locations from the HUB through Global. To do this run the following command from the HUB:


The HUB can be locked without the need for a daemon command by just typing:


It is possible to confirm whether locations are locked by evaluating the return result from:


1.2.5 Extract Hierarchies

It should not be necessary to change the extract hierarchy, or to consolidate data within extract hierarchies. Therefore the System Administrator should not need to FLUSH, ISSUE, DROP data between extracts (working extracts are an exception to this - see below). Nor should they need to delete any extract families to leave only Masters. However all extracts will need to be relocated to a single location, although this does not need to be the HUB.

1.2.6 Working Extracts

The upgrade process will need to make sure that all data is up to date at the HUB where pre-scan data checks will need to be made. Working Extracts cannot be propagated as they are specific to a single location. As a result all data MUST be flushed, and claims released from the Working Extract into its parent. This is only true for working extracts, all other extracts do not need to be flushed, or have its claims released, as all non working extracts will be available at the HUB.

1.2.7 Offline Locations

Global supports Offline locations; therefore we cannot assume that the Hub has a Global connection to that location. Where as Offline locations do not support distributed Extracts it can support stand-alone extract families.

It will not be possible to co-ordinate the upgrade from another location if Offline locations are used. Offline locations are relatively independent, and can be treated as such.

1.3 Upgrade Requirements

The necessary database upgrades for use of 12.1 will be implemented as part upgrades. Other internal changes may be handled differently.

1.3.1 Part Upgrades Included in the Framework

The following requirements for a Part Upgrade are included in the 12.1 upgrade framework:

  • UKEYs (avoid duplicates)
  • Performance of 'finding' Database Elements
  • Module Definitions
  • Character Handling (Unicode Representation)
  • Line Widths in DRAFT
1.3.2 Other Changes

The following requirements for other changes are related to moving from 12.0 to 12.1

  • Units in Schematic Model Manager
  • Move CYMWRL to new REFDESI db
  • Shape Upgrades in Diagrams
  • Unicode
  • Units (PDMS)
1.3.3 Users Customisation

Users will have to review all their customisation, to check that assumptions are not invalidated by 12.1 changes. For example:

  • If Engineering applications require write access to existing SYSTEMs they will need to be moved to a RefDESI DB
  • PML may need to be edited because of the new PDMS Unit handling.

1.4 Part Upgrade Details

1.4.1 Performance of 'finding' Database Elements

A change has been made to significantly improve performance of finding database elements when Type is one of the criteria in the selection. This requires an Index on Type. Invisible attributes are added to all elements of relevant element types by the upgrade script and an Index is added by the upgrade script. This needs to be performed on the entire extract hierarchy.

1.4.2 Module Definitions

At 12.1 there are some changes to Module Definitions in the AVEVA Plant product.

  • A new module, Tags, has been added. This is part of the Engineering Product, but will be added for all projects to enable them to adopt use of the Engineering product if and when they decide to do so.

These module changes are made by the upgrade script

1.4.3 UKEYs (avoid duplicates)

At 12.1 the 'Database Number' is part of the UKEY when it is created. This prevents UKEY clash of any UKEYs created at 12.1.

PDMS 12.1 continues to be able to use UKEY references in 12.0 format (created at 12.0 or earlier), even when the UKEY definition has been upgraded. Thus users can 'mix' 12.0 format UKEYs and those created at 12.1. Therefore only 'UKEY' clash will be both 12.0 format. It is possible to convert UKEYs in 12.0 format to 12.1 format.

Need to change DICT DB (UKEY definition) first, then all DBs referencing it. The DICT DB change is performed by the upgrade. AVEVA recommend performing the change on UKEY references on an 'as need' basis (i.e. if a UKEY clash is encountered). This is because of the time which could be required to update all UKEY references in a project.

1.4.4 Line Widths in DRAFT

A 12.0.SP6 fix addresses a Line width problem in DRAFT, where 'thin', 'medium' and 'thick' lines were not the exact width expected, leading to lines which were expected to have different thicknesses having the same width. A macro was provided with fix to add necessary attributes. This is incorporated in 12.0 to 12.1 upgrade. It will do nothing where 12.0 fix macro has already been applied and will add necessary attribute in other cases.

1.4.5 Character Handling (Unicode Representation)

See Unicode.

This is an optional part of the 12.0 to 12.1 upgrade. Users can continue to operate in a 12.0 character set at 12.1, providing Language environment variables are set appropriately; but 12.0 limitations on characters allowed will then remain. This upgrade is a Reconfigure. It is an optional step in upgrade. Alternatively it can be undertaken on a separate occasion.

  • PDMS 12.1 can open and read databases created prior to 12.1
    • The project setting must be correct
    • So only 1 character set in a project
  • PDMS 12.1 can write to databases created prior to 12.1
    • The project setting must be correct
    • The character must be in the character set
    • An attempt to write an invalid character will result in an error

1.5 Other Changes

1.5.1 Units in Schematic Model Manager

Schematic data imported into Schematic Model Manager prior to 12.1 must be upgraded to use new Units functionality, but this process will be handled separately to the main upgrade process. A check is performed automatically on entry to Schematic Model Manager and the user will be warned if an upgrade is required. The upgrade process must be carefully considered by project administrators as it can affect multiple projects and locations. Firstly, schematic data is scanned to identify changes required. Secondly, UDA definitions are updated for the appropriate units. Thirdly, the changes identified are applied to the schematic data.
Refer to Schematic Model Manager User Guide for details of the upgrade process.

1.5.2 Shape Upgrades in Diagrams

The shape upgrades for Diagrams are changes to Visio shapes. These changes are to Visio files and not the Dabacon database. They will be actioned by the Diagrams Application when the diagram is opened in write mode by the Diagrams 12.1 application.

Users will be able to choose to:

  • Execute a batch job function available from within Diagrams
  • Set an 'automatic upgrade' flag, so that each Diagram is upgraded when it is first opened in 12.1 
  • Manually call the upgrade option from the Tools menu when a non-upgraded Diagram is open. If the setting says that no automatic upgrade should be performed on open, then a warning will appear in message log, saying that the diagram needs updating.

Non-upgraded Visio shapes will still work in Diagrams 12.1, although they will not have any extended functionality, such as new context menu options etc. So Foreign 12.0 DBs can be used at 12.1

In Global/Extract scenarios the upgrade will work as any other change; the diagram will be saved in a new version after upgrade. If the upgrade is performed on an extract, it will be updated on the Main DB after flushing the extract.

1.5.3 Unicode

At 12.1 new Dabacon databases will, by default, store text in a Unicode encoding; these may be termed Unicode encoded Databases.

Databases created prior to Unicode enabled PDMS 12.1 to store names, text attributes and other text strings using an encoding determined by the project settings, which determines the range of characters that may be present. These may be termed Locally encoded or Legacy databases since the project settings are set to match a specific locale (Russian, Chinese etc). By default, the encoding is Ascii ISO8859-1 ("Latin 1").

Such locally encoded databases do not need to be modified or upgraded to be used in 12.1. They may be opened and read from (for example as Foreign Databases) without restriction, since the Unicode standard encompasses all existing local encodings. They may also be written to, with the restriction that character data may only contain characters in the projectdefined encoding. An attempt to write an invalid character (for example a name containing a Chinese character into a Russian database) will be rejected with an error.

It is important that any project containing locally encoded databases (either directly or as foreign dbs) has its project settings set explicitly and correctly to make sure that character data is interpreted correctly.

Unicode encoded databases cannot be opened (for reading or writing) with pre-Unicode versions of PDMS. However, it is possible to specifically create locally encoded databases if it is required that they should be accessible by previous versions of PDMS.

In cases where it is required to extend the range of characters that may be used in existing locally encoded databases, RECONFIGURE may be used to convert it to a Unicode encoded database.

In the following example legacy DICT dbs (used to hold UDA and UDET names) are reconfigured to be Unicode encoded. Using a Unicode Executable (12.1) for db MASTER/DICT (In ADMIN):


Doing it this way means that no deletion and recreation (or copy) is required for the DB, and therefore no re-adding to the MDB structures is required either. Using RECONFIG SESSIONS in the FROM phase of the reconfigure operation will preserve both the sessions and references.

In Summary:

Locally Encoded (Legacy) Databases:

  • can be opened for read access in both Unicode and non-Unicode versions of PDMS
  • can be opened for write access in both Unicode and non-Unicode versions of PDMS, but the range of characters which may be used is restricted to the set defined by the project settings
  • require that the project settings are correct so that characters can be interpreted correctly
  • can be reconfigured to a Unicode encoded database

Unicode Encoded Databases:

  • cannot be opened for read or write access in pre-Unicode versions of PDMS
  • can store the full range of Unicode characters available in Unicode versions of PDMS

Unicode in Plant

All Plant and Schematics code will handle Unicode strings. Administrators may have chosen to convert all DBs to Unicode as part of their upgrade process, or may decide for each DB whether and when to upgrade manually, and perform this upgrade using Reconfigure as in the example above.

1.5.4 Units (PDMS)

At 12.0 and earlier versions the only physical quantity which was formally recognised in PDMS was length, used for DISTance and BORE, and the derived %SQDI (squared length) and %CUDI (cubic length) set via the UNIT field of an Attribute.

Most other Dabacon products had similar restrictions, except for:

  • Schematic data imported via Schematic Model Manager (refer to Units in Schematic Model Manager)
1.5.5 Systems and CYMWRL in RefDESI DBs

Neither Systems nor CYMWRLs will be put in RefDESI DBs by the 12.1 upgrade script, although AVEVA would encourage Administrators to move them to RefDESI DBs to enable users to make maximum advantage of new features in 12.1.

Systems can still be placed in DESI DBs at 12.1 - and users without any of the Engineering or Diagrams products may choose to do this. Where Systems are in DESI DBs, Diagrams and Engineering products can still assign elements to them. If Users want to move Systems to a RefDESI DB they should be able to do this with normal copy/move commands. Any problems encountered doing this should be regarded as Defect Fixing. Therefore it was not necessary to include move Systems to RefDESI in the upgrade.

There will be no automatic move of CYMWRLs into Design Reference databases, and Integrator no longer automatically creates a Link World. Project administrators are recommended to create a separate Design Reference database to hold links, and then use
the new Manage Links dialogue, available from the Integrator > Settings menu or the Compare/Update > Options dialogue. This can be used to create and manage Link Worlds in the appropriate database, including consolidating links from separate databases.

1.6 Global Considerations

The following considerations must be made when applying upgrade parts to a Global project.

  • The user must run an upgrade for all primary DBs at a location.
  • For extracts, the entire extract family must be made primary at the same location
  • System DBs should be upgraded at all locations.

2 Units

In earlier versions of PDMS and other Dabacon-based AVEVA products the only physical dimension which was recognised in the storage of quantities was Length. Length is used for attributes of type DISTance and BORE, and the derived SQDI (squared length) and CUDI (cubic length) set via the UNIT field of an Attribute.

Most other Dabacon products had similar restrictions, except for Schematic data imported via Schematic Model Manager (refer to Units in Schematic Model Manager).

For lengths the values are stored in the database in millimetres. Users can choose which length units are used in the GUI, from a predetermined set.

Overview of Units at 12.1

At 12.1 PDMS and other Dabacon-based AVEVA products have been enhanced to recognise other dimensions which are relevant to attributes Engineers and Designers may want to use. How to create attributes with specific a specific dimension is described in 12.1 User Documentation.

The extra dimensions which have been introduced at 12.1 are managed in a similar manner to Lengths. There is a 'Database-Unit' for each dimension, in which the quantities will be stored, and a set of 'Display-Units' which the users can choose for their GUI. The dimensions and their Database Units are listed in 0.

Dimensions are now checked in calculations, so it is not possible to add a length quantity to a mass quantity.

Derived quantities are also recognised, so if a length (in millimetres) is divided by a time (in seconds) this is now recognised as a speed (in millimetres per second). These are also subject to dimension checking.

Prior to 12.1 users used standard attributes with dimensions, and may have created their own UDAs and catalogue properties which represent dimensioned quantities. It is expected that all of these will be attributes of type 'Real'.

Summary of Action to be Taken

To take advantage of the new functionality, attributes need to be set to the correct dimension. This has been done for the standard attributes. Users will need it to do it for their UDAs and catalogue and design parameters and properties. Any data imported to a Schematic database using Schematic Model Manager will need to have the 12.1 upgrade applied.

Users do not need to change all dimensions at the same time. For example Lengths are already handled correctly. It is expected that users will have stored angles in Degrees, so they will also be handled correctly. It just required the administrator to identify which UDAs are angles and set their UUNIT to ANGL.

Separately for each of the dimensions listed in Angles: - Unit Weights (per distance) (UMAS) the administrator needs to determine

If all quantities have been stored in the new Database Units

  • Set the UUNIT for any UDAs
  • Any UDAs used to store the Unit values are no longer required and can be deleted
  • Any user appware managing unit conversion or display can be removed or replaced by standard functions.

If all quantities have been stored in the same unit (which is not the new Database Unit)

  • Set the UUNIT for any UDAs
  • Output a datal file with the dimensions being set to numeric


  • Read the datal file back in with the current units set appropriately so that unqualified values are assumed to be in those units:


  • Any UDAs used to store the Unit values are no longer required and can be deleted
  • Any user appware managing unit conversion or display can be removed or replaced by standard functions

If quantities have been stored in mixed units with a UDA recording the unit for each

  • Set the UUNIT for any UDAs
  • Set the dimensions to numeric


  • Output a file with the attribute values, with the value from the unit UDA appended
  • Check the format of the value plus unit conforms to new input format rules
  • If necessary edit the file with a text editor or script to achieve this
  • Read the file back in
  • Set current units as preferred


  • Any UDAs used to store the Unit values are no longer required and can be deleted
  • Any user appware managing unit conversion or display can be removed or replaced by standard functions

If quantities have been stored in mixed units with 'custom and practice' being the only record of the unit

  • It is hoped very few users are in this situation
  • For the short-term set the dimensions to numeric
  • Plan to move to more rigorous use of units, probably employing a combination of the techniques above.

2.1 Core Units (PDMS)

At 12.1, Dabacon attributes will formally recognise all the dimensions listed in the table in Dimensions and their Database Units. The table also indicates the database unit which Dabacon will use from 12.1 onwards. Database units have been chosen to be that thought to be the most commonly used unit. Where all quantities of a dimension are stored in the database unit, the new functionality can be used without any upgrade. All attributes that have the UNIT field set for the first time, were until now stored as values with no specified unit. The units that were associated with their values in the past were determined by use and convention; and these could change from application to application, and project to project. This flexibility cannot be supported henceforth and a 'unit of storage' must be defined. AVEVA are setting the database units to those thought to be most
commonly used in practice, but this will not be universally compatible. Hence the UNITS NUMERIC command is introduced to disable dimension conversion for selected dimensions.

If the 12.1 database unit does not agree with values stored in existing project databases, such data must be converted, or the units of measure of that physical dimension must be set to NUMERIC to disable dimension conversion for this dimension. Disabling a specific dimension in this way means that no advantages will be gained from the introduction of that dimension when working on the projects.


is used to suspend all default unit conversions on input and output for attributes of the nominated dimension.

  • no conversion from the stored value will be made on output
  • no unit qualifying strings will be appended to output values
  • Input values with no qualifying unit strings will be stored without conversion in the database
  • If input values have a unit qualifying string, then a conversion factor will be applied.

This is of particular value to users who wish to continue storing and using attribute values as now, and especially when the values stored are assumed by their system to be in units that are DIFFERENT to those now being assumed by the PDMS or Dabacon system.

For the upgrade to 12.1 users will need to:

Review all use of dimensions from the table below other than length

  • In particular they will need to review their use of density and mass

For each dimension which has been used

  • Are all stored quantities in the database unit?
  • If not
    • Either set UNITS NUMERIC
    • Or write a script to convert from their stored unit to database units and apply to all extracts of each DB used by the project. This will need to include Foreign DBs.
2.1.1 Dimensions of Standard Stored and Derived Attributes


These attributes are assumed to stored be in Degrees


Bores (BORE)

These attributes are assumed to stored be in mm. As in 12.0


Volumes (CUDI)

These attributes are assumed to stored be in mm3. As in 12.0 most of these are derived attributes


Currents (CURR)

These attributes are assumed to stored be in Amps


Densities (DENS)

These attributes are assumed to stored be in kg/m3


Densities in Manufacturing Database (MAND)

These attributes are assumed to stored be in kg/mm3


Lengths and Distances (DIST)

These attributes are assumed to stored be in mm