DOORS DXL Object Operation

This article describes the functions and example programs about creating and managing DOORS DXL object operation.

Create Object in DXL

In IBM Rational DOORS, an Object refers to a discrete unit of information that is stored in a module. An Object can represent a requirement, a test case, a use case, a design element, or any other type of information that needs to be tracked and managed.

In DOORS DXL (DOORS Extension Language), an Object is represented by the Object data type. The Object data type provides access to the various properties and attributes of an Object, such as its Object Text, Object ID, and module location.

Here is an example of how to create and manipulate an Object in DOORS DXL:

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o0.dxl
* $DESCRIPTION: DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/
// Open the module
Module m = read("/path/to/module", false)

// Create a new Object
Object o = create(m, "My Object", "This is the Object Text")

// Print the Object ID and Object Text
print "Object ID: " o."Object ID" "\n"
print "Object Text: " o."Object Text" "\n"

// Update the Object Text
o."Object Text" = "This is the updated Object Text"

save(m)

In this example, the read function is used to open a module, and the create function is used to create a new DOORS DXL Object in the module. The create function takes as arguments the module in which to create the Object, the name of the Object, and the initial Object Text.

The Object ID and Object Text are then printed to the console using the print statement and the Object Text is updated using the bracket notation. Finally, the update function is used to save the changes to the Object.

Note that this is a simplified example and there are many more advanced things you can do with DOORS DXL to manipulate Objects, such as iterating over all Objects in a module, accessing Object attributes, and creating complex data structures to manage Objects. The Object data type provides a rich set of functions and properties for working with Objects in DOORS.

Now, let’s look at another example of creating objects using DXL. Here is the module before creating the object –

Now, run the following program on the above module to create objects –

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o1.dxl
* $DESCRIPTION: DOORS DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/

// Example of Object
Module m = current
Object obj1, obj2, obj3, obj4

obj1 = create(m)
obj2 = create below (obj1)
obj3 = create last (obj1)
obj4 = create after (obj1)
print "Done!"

Here is the DXL output window –

All the three objects are now created in the module –

Here is the different ways you can use the create function –

Object create(Module m)
Object create(Object o)
Object create(after(Object o))
Object create(before(Object o))
Object create(below(Object o))
object create(first(below(Object o)))
Object create(last(below(Object o)))

Delete Object in DXL

You can delete a DOORS DXL Object from a module using the softDelete() function. An object can be recovered (by using undelete() function) after it has been deleted with softDelete() function. But, hardDelete() function is used with an intention to delete the object permanently.

Here is an example module in DOORS –

Here is an example of deleting an object in DXL –

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o3.dxl
* $DESCRIPTION: DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/

// Example of Object deleting
Module m = current
Object obj = current

if (null canDelete(obj)) {	// check if user has write permission for this object
	softDelete(obj)			// no incoming links should be present for current object
}

// You can unDelete an object 
// if (isDeleted (obj)) { 
	// undelete (obj)
// }

print "Done!"

Here is the output –

Move Object in DXL

You can move a DOORS DXL object using the move() function. You can move function in the following ways –

void move(Object o1, Object o2)
void move(Object o1, below(Object o2))
void move(Object o1, last(below(Object o2)))

These functions move an object to a position, which is controlled by the second argument passed to the function, as follows:

Argument Syntax	Moves
Object o2	object o1 and its descendants to be immediately after object o2
below(Object o2)	object o1 and its descendants to be immediately after object o2
last(below(Object o2))	object o1 and its descendants to be the last child below o2

Let’s now look at an example program to understand the move() function in DXL. In this example, we will move the last object in the module and its descendants under the first object. Here is the object structure before we move an object –

Now, run the following program –

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o2.dxl
* $DESCRIPTION: DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/

// Example of Object moving
Module m = current
Object currObj = null
Object desObj = null

desObj = first (m)
currObj = last (m)

move (currObj, below desObj)

print "Done!"

The module is now updated after executing this code –

Object Navigation in DXL

Vertical Object Navigation

The following functions can be used for vertical navigation in DOORS module –

Object first(Object o)
Object last(Object o)
Object next(Object o)
Object parent(Object o)
Object previous(Object o)
Object first(Module m)
Object last(Module m)

The last two functions return the first and last objects of module m in a depth first tree search, that is the first and last objects as they appear in a displayed module

Here is an example of navigating the first and last object in the DOORS module –

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o4.dxl
* $DESCRIPTION: DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/

// Example of Object Navigation
Module m = current
Object o1 = first (m)	// get the first object in the module
Object o2 = last (m)	// get the last object in the module

print (module o2)."Name" ""	//prints the name of the module

print "Done!"

Now, if the last object has children, it count the last children as last object –

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o5.dxl
* $DESCRIPTION: DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/

// Example of Object Navigation
Module m = current
Object o1 = first (m)	// get the first object in the module
Object o2 = last (m)	// get the last object in the module

print "Last Object text = " o2."Object Text" "\n"

The last() function also respects the display set in DOORS module. In the following example, we will set a filter to make sure only a handful objects are visible in the module and then apply last() function on the module.

Here is the module before applying the filter –

Now, apply the following filter –

DOORS module after applying the filter –

Now, run the following DXL code –

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o6.dxl
* $DESCRIPTION: DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/

// Example of Object Navigation
Module m = current

// Manually apply filter such that the child object of last objects are not visible.
// This example is to show that the last() function respect the display set
Object o1 = first (m)	// get the first object in the module
Object o2 = last (m)	// get the last object in the module

print "Last Object text = " o2."Object Text" "\n"

Here is the output window –

The last object is printed here as ‘LastObject’ and not ‘LastChild-1’.

Horizontal Object Navigation

These functions are similar to the vertical navigation functions, but take as an argument a call to the function sibling, which returns a handle to allow navigation between sibling objects (children of the same parent).

The following functions can be used to navigate in DOORS DXL object horizontally –

Object first(sibling(Object o))
Object last(sibling(Object o))
Object next(sibling(Object o))
Object previous(sibling(Object o))

Now, let’s look at an example module before we execute the dxl code for horizontal naviagtion –

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o7.dxl
* $DESCRIPTION: DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/

// Example of Object Navigation
Module m = current
Object o = current

Object firstSib = first sibling (o)
Object nextSib = next sibling (o)
Object lastSib = last sibling (o)


print "Current Object = " o."Object Text" "\n"
print "First Sibling Object = " firstSib."Object Text" "\n"
print "Next Sibling Object = " nextSib."Object Text" "\n"
print "Last Sibling Object = " lastSib."Object Text" "\n"

Get Specific Object

The index notation, [ ], can be used to find an specific object in DOOSR module. Here is the syntax –

Object o [ int n ]
Module m [ int n ]

This returns the nth child of object o counting from 1, or the nth top-level child of module m, counting from 1.

Access Objects using for loop

We can use the for loop to access all the objects in the DOORS module. Here is an example –

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o10.dxl
* $DESCRIPTION: DOORS DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/

// Example of Object navigation within the module
Module m = current
Object o = current

for o in current Module do { 
	print identifier(o) " = " o."Object Text" "\n"
}

Object Data Access

The following functions can be used to access object data –

Object current
string identifier (Object o)
string number (Object o)
int level (Object o)
bool leaf (Object o)

Here is an example code –

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o8.dxl
* $DESCRIPTION: DOORS DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/

// Example of Object Data Access
Module m = current
Object o = current

string objIdentifier = identifier (o)
string objNumber = number (o)
int objLevel = level (o)

print "Current Object = " o."Object Text" "\n"
print "objIdentifier = " objIdentifier "\n"
print "objNumber = " objNumber "\n"
print "objLevel = " objLevel "\n"

Object Attribute Access

IBM DOORS provides a way to access DOORS DXL object attribute as well. Here is the syntax on how to access object attribute –

int <Object o>.<string AttributeName>
real <Object o>.<string AttributeName>
string <Object o>.<string AttributeName>

Here is an example program –

// www.TheCloudStrap.Com 

/************************************************************************
* $FILENAME: o9.dxl
* $DESCRIPTION: DXL Object example
*
* NOTICE: Copyright www.TheCloudStrap.Com. All rights reserved.
* Software comes without any warranties and guarantees, is provided 
* as is and is not supported. Use this software at your own risk. 
* Authors resume no liabilities.
* 
* Contact: admin {at} TheCloudStrap.com
************************************************************************/

// Example of Object Attribute Access
Module m = current
Object o = current

string absNumer = o."Absolute Number"
string txt = o."Object Text"
string prefix = m."Prefix"

print "Current Object = " txt "\n"
print "Absolute Number = " absNumer "\n"
print "Prefix = " prefix "\n"

Object Enumeration Access

Enumerated attributes are a special case and we can access both option name and option value of enumerated attributes. Here is an example code snippet –

Object o = current
string status = o."Status"    // Option Names are = Pending, Open, Close
int option_val = o."Status"  // value of options = 0, 1, 2
print "Status for current test is " status "(" option_val ")"

Here, the variable type in the 2nd and 3rd line determines whether option name or option value is being accessed.

You can also check if a string is a member of an enumerated value. For example –

Object o = current
string t_status = o."Status"   // option names are = pending, open, close
if(!isMember(o."Status", "Hold")) {
      print "'Hold' is not included in the enumeration"
      o."Status" += "Hold"    // add 'Hold' in the enumeration
}

Object Attribute setting

You can set the value of an DOORS DXL object attribute using the following syntax –

<Object o>.<string AttributeName> = int
<Object o>.<string AttributeName> = real
<Object o>.<string AttributeName> = string
<Object o>.<string AttributeName> = bool

Here is an example code snippet that explains this –

Object o = current 
o."Object Text" = "This is new object test adding from an dxl file"
o."Status" = "Hold"

Conclusion

In this article we have discussed DOORS DXL Object navigation i.e – how to create an object, delete an object and handle different ways of navigation using DXL.