Database Interface
4.2.1 DbElement Basics
•
Overview
This section describes the DbElement class. The DbElement class is the most widely used class and it covers a large proportion of the database functionality that will be used in practise.
The methods fall into the following groups: • Navigation
• Querying of attributes • Database modifications
• Storage of rules and expressions • Comparison across sessions
DbElement is a generic object that represents all database elements regardless of their type.
•
Constructors
An instance of a DbElement may be obtained as follows:
• There is a static GetElement() method with no arguments to return a 'null' DbElement.
• There is a static GetElement() method which returns a DbElement given a name. This name should include the '/'.
• There is a static GetElement() method which returns a DbElement given a ref(two long int array) and type. This is only needed where a reference has been stored externally to PDMS.
• There are many methods on various classes which return DbElements e.g.
DbElement vess1 = DbElement.GetElement("/VESS1");
•
Identity
The DbElement object encapsulates the identity of the database object. Any comparison of database objects must be done using DbElements. The DbElement has 'value' semantics for comparison purposes. i.e. comparing of two DbElements will always return true if they refer to the same element, even if they are different objects. DbElement instances should be used in all cases where the identity of an element is being passed or stored.
A DbElement can be identified externally to PDMS by a combination of the ref number AND type. The ref number is a two long integer, for example: =123/4567.
Database Interface
•
Element Validity
A DbElement need not represent a 'valid' element. There are a number of reasons why a DbElement might be invalid:
• The element is in a DB not opened. • The element has been deleted.
There is a IsValid()method to test if a DbElement is valid.
If the DbElement is invalid then all attribute access and database navigation will fail for that DbElement.
•
Error Handling
The error handling techniques used are: 1. Some methods raise a PdmsException
2. Some methods return false if the operation can not be done.
3. For navigation operations, if the navigation does not succeed then a 'null' element is returned. A null element can be tested using the 'IsNull' method. It will have a reference of =0/0.
Note: The error handling philosophy is likely to change at PDMS 12.1.
•
Basic Properties
DbElement has the following basic methods:
ToString()- Returns the Name of the element. If unnamed, it returns the constructed name.
GetElementType()- Returns the DbElementType.
There are a number of pseudo attributes that return slight variations on name and type, as below.
Type related:
Name Related:
Attribute Name C# Data Type Qualifier Description
ACTTYPE
DbElementType
Type of elementAHLIS
DbElementType
(200)
List of actual types in owning hierarchy
OSTYPE
DbElementType
Shortcut for "Type of owner" TYPEDbElementType
Type of the element, ignoringUDET
TYSEQU
int
Type Sequence NumberAttribute Name C# Data Type Qualifier Description
CUTNAM String int Full name of element, truncated
to n characters
CUTNMN String int Full name of element (without
leading slash) truncated to n characters
4.2.2
Navigation
•
Basic Navigation
There are basic methods to navigate the primary hierarchy. e.g. consider the following hierarchy:
If we are sitting at Zone2, we can navigate as follows:
using NOUN=Aveva.Pdms.Database.DbElementTypeInstance; DbElement zone = DbElement.GetElement("/Zone1") DbElement temp=zone2.Next(); // temp is now Zone3 temp=zone2->Previous(); // temp is now Zone1 temp=zone2->Owner(); // temp is now Site1 temp=zone2->FirstMember(); // temp is now Pipe1 DbElement pipe1=temp;
temp=zone2->LastMember(); // temp is now Equi1
DbElement temp=pipe1.Next(NOUN.EQUIPMENT); // temp is Equi1
FLNM String Full name of the element
FLNN String Full name of the element (without
leading slash)
ISNAMED Bool True if element is named
NAMESQ String Type. sequence number and
name of element
NAMETY String Type and name of the element
NAMN String Name of the element (without
leading slash)
NAMTYP String Type and full name of element
Database Interface
DbElement temp=pipe1.Previous(); // temp is ‘null’ as there is no previous element. This can only be tested using the ‘IsNull’ method
Scanning the database is a very common operation. For this reasons there are additional iterator and filter classes that ease this task. These are described in the section on Filters/Iterators.
•
Pseudo Attributes Relating to Element Navigation
'*'- qualifier is optional
•
Secondary Hierarchies
Standard navigation methods do not work for descending a secondary hierarchy. Pseudo attribute SMEMB must be used. E.g. to get the design elements below a GPSET, you must query the SMEMB attribute on the GPSET.
Pseudo attributes relating to secondary hierarchies are:
Attribute Name Data Type Qualifier Description
ALLELE DbElement[]
)
DbElementType All elements in the MDB of a particular type
CONNECTIONS DbElement[] Connections
CONNECTIONS H
DbElement[] Connections for all descendants
CONNER String Int Connection error message
DDEP Int Database depth within
hierarchy (World is 0)
FRSTW DbElement String Reference of first world of given
DB type in current MDB
MAXD Int DB hierarchy depth of lowest
level item beneath element MBACK DbElement[] *DbElementType Members in reverse order
MCOU Int *DbElementType Number of Element Members of
Given type
MEMB DbElement[] *DbElementType All members, or members of
specific type
OWNLST DbElement[] Owning hierarchy
PARENT DbElement *DbElementType Reference of ascendant
element of specified type
SEQU Int Sequence Position in Member
List
TYSEQU Int Type Sequence Number
Attribute Name Data Type Description
GPPRXS
DbElement[]
Group proxy items referring to elementGROUPS
DbElement[]
GPSETs in which element occursThe difference between SMEMB and SEXPND is that SEXPND allows for recursive secondary hierarchies. Where there are no recursive possibilities, SMEMB and SEXPND will be the same. The following example illustrates the difference between SMEMB and SEXPND:
In the example there are two secondary nodes S1, S2. S1 holds element A, C, and S2 holds S1,D,G.
For S1,
SMEMB returns A,C SEXPND returns A,C For S2,
SMEMB returns S1,D, G SEXPND returns A,C, D, G