Database Modifications

Check that the attribute value is the right type - i.e. 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 make sure 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 element
CLMNUM	int	User or extract number claiming element. Extract numbers are negative
CLMTIE	DbElement[]	Reference to elements that are automatically claimed along with this element
NPDESC	DbElement[]	List of non primary offspring
OKCLA	bool	True if element may be claimed
OKCLH	Bool	True if element and hierarchy may be claimed
OKREL	bool	True if element may be released
OKRLH	Bool	True if element and hierarchy may be released
PRIMTY	Bool	True if element is primary
PRMMEM	bool	True if there are any primary elements amongst descendants
PRMOWN	DbElement	Primary owning element (will be itself if primary)
USCLHI	DbElement[]	Elements in descendant hierarchy claimed to this user
USERC	String	User name of user claiming element
USNCLH	DbElement[]	Elements in descendant hierarchy not claimed to this user

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.

Create 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.

Delete 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 Element

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.

Move 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.

Change 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


Attribute Name	Data Type	Qualifier	Description
DACCLA	bool		True if DAC allows element to be claimed
DACCOH	bool		True if DAC allows element hierarchy to be copied to another DB
DACCOP	bool		True if DAC allows element to be copied to another DB
DACCRE	bool	DbElementType	True if DAC allows element to be created
DACDEL	bool		True if DAC allows element to be deleted
DACERR	String	DbAttribute	Returns the DAC error
DACEXH	Bool		True if DAC allows element hierarchy to be exported
DACEXP	Bool		True if DAC allows element to be exported
DACISS	Bool		True if DAC allows element to be issued
DACMOD	bool	DbAttribute	True if DAC allows attribute of element to be modified
MODATT	Bool	DbAttribute	True if attribute of element can be modified
MODDEL	Bool	DbAttribute	True if element can be deleted
MODERR	string	DbAttribute	Returns the error text that would occur if attribute was modified