Database Modifications

Overview

The following modifications are allowed:

• Set attribute

• 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 - that means, if a text attribute then the new value must be text. for example, 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

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. for example,

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

The method to delete an element is Delete(). For example:

MyEle.Delete();

All descendants in the primary hierarchy will be deleted. It will not delete elements in any secondary hierarchies.

There is a boolean method IsHierarchyDeleteable to test if an element can be deleted.

Copy

As with Delete, the standard COPY method copies the primary hierarchy. The following points are relevant when copying:

• Certain attributes are not copied. for example, NAME.

• For Name attributes, automatic renaming is possible.

• The element may be copied to an existing element, or as a new element.

• Cross references within the copied hierarchy are automatically updated to the copied element. References external to the copied hierarchy are left unchanged.

There are further details in the reference manuals.

An example of the DbElement method is:

myEle1.Copy(myEle2);

myEle1.CreateCopyHierarchyAfter(myEle2,copyoption);

The first example copies 'myEle2' on top of myEle1. The second example copies myEle2 and all its descendants to a new element after myEle1.

There are methods to:

• Copy a single element to an existing element.

• Copy an element and all its descendants to an existing element.

• Copy an element and all its descendants to a new element.

• Copy common attributes ('CopyLike') between existing elements.

There is a separate class DbCopyOption to hold the options when doing a copy. These options are only available when copying an element and all its descendants.

The element types must match if copying to an existing element.

There is a boolean method IsCopyable to test if an element can be copied.

Moving Element

An element can be moved to a different location in the primary hierarchy. There are methods to:

• Inset before a given element.

• Insert after a given element.

• Insert into members list at the last position.

Currently an element may only be moved within the same database.

An error will be raised if the element is not allowed at the new location.

There is a boolean method IsInsertable to test if an element can be moved.

Currently there is not an exposed C# method for moving elements between DBs. This will be exposed shortly.

Changing Type

It is possible to change the type of certain elements.

When a type is changed, the attributes are copied from the old to the new value. Any attributes not valid for the new type are lost. Thus a round trip of changing back to the original type may represent a loss of data.

Pseudo Attributes Relating to Modifications