• Create element • Delete element • Copy element • Change type • Move element
•
The Modification Pipeline
When an element is modified, it is not simply the case of directly updating the database. For example, when setting an attribute the following sequence takes place:
1. Check that the attribute value is the right type 2. Check against any valid values or ranges
3. If the new value is the same as before, then return.
4. Check against the user access control defined in the system DB. 5. Check that the DB is open in write
6. Check LOCK flag
7. Do claim check, and claim if needed if DB is 'implicit claim' 8. Make attribute specific checks.
9. Make the actual database change. 10. Add to change list
11. Invoke attribute specific follow up code. 12. Update any dynamic rules affected
It can be seen that making what appears to be a simple modification is actually quite complicated.
In particularly a lot of errors are possible. Errors may be generated by any of the steps 1-2 plus steps 4-8.
If an error occurs the code will raise a PdmsException. The calling code needs to allow for this.
Clarification of some of these errors is as follows:
Check that the attribute value is the right type - i.e. if a text attribute then the new value
must be text. E.g. setting DESC to 99 will raise an error.
Check against any valid values or ranges - This will check the value against any user
provided criteria stored in the dictionary DBs.
Check access control - An error will be raised if the modification is not allowed. An error
will also be raised at this point if the attribute is not valid for the given element.
Check that the DB is open in write - An error will be raised if 'read only'. Check LOCK flag - An error will be raised if the LOCK flag is true.
Do claim check, and claim if needed (and implicit claim is allowed) - An error will be
raised if:
• The DB uses explicit claims and the primary element has not been claimed. • The primary element is claimed by another user or extract.
Call the legality checking routines to ensure that the modification is valid - These
checks are made by the plugged in application specific code. Thus potentially any error could be raised.
•
Claiming Elements
If a DB has been set up to be 'implicit' the user will claim elements as needed without having to do explicit claims.
There are some methods on DbElement to claim/release individual elements or a hierarchy of elements. If working on a hierarchy of elements, and errors occur, then the system will still do what it can.
There are also methods on the MDB class to claim/release a list of elements. Performance is improved by claiming or releasing elements in bulk, thus in general the MDB methods should be used rather than the ones on DbElement.
The granularity of claim is at the level of primary element. This is described in the data management reference manual.
•
Pseudo Attributes Relating to Claims
Attribute Name C# Data Type Description
CLMID
String
Unique system ID of user claiming elementCLMNUM
int
User or extract number claiming element.Extract numbers are negative
CLMTIE
DbElement[]
Reference to elements that areautomatically claimed along with this element
NPDESC
DbElement[]
List of non primary offspringOKCLA
bool
True if element may be claimedOKCLH
Bool
True if element and hierarchy may beclaimed
OKREL
bool
True if element may be releasedOKRLH
Bool
True if element and hierarchy may bereleased
PRIMTY
Bool
True if element is primaryPRMMEM
bool
True if there are any primary elementsamongst descendants
PRMOWN
DbElement
Primary owning element (will be itself if primary)USCLHI
DbElement[]
Elements in descendant hierarchy claimed to this userUSERC
String
User name of user claiming elementUSNCLH
DbElement[]
Elements in descendant hierarchy notDatabase Interface
•
Set Attribute
As for getting attributes, there is a family of methods for setting attributes depending on the attribute type.
ele.SetAttribute(ATT.DESC, "Example description");
There are no methods that take a qualifier.
The code should always be prepared to handle any exceptions raised.
There is a boolean method IsAttributeSetable to test if a given attribute may be set. This does not take the new value, so it is possible that the actual setting will still fail if the new value is invalid.
•
Creating Element
Creation is relatively straightforward. Elements can be created: • Below a given element
• After a given element • Before a given element
If creating an element below a given element then the position in the list must be given. E.g.
DbElement myNewPipe=myZoneElement.Create(1,NOUN.PIPE);
This creates a new PIPE below 'myZoneElement' as the first member. If the position is beyond the end of the current members list, it will create it at the end.
An exception will be raised if the required type of element cannot be created at the required point.
There is a boolean method IsCreatable to test if an element of a given type could be created at the required location.
Deleting element