More content coming soon…

I just want to ask you all for your patience.The end of the year really got me good. I got sick and swamped at work at the same time!I also needed to take some time off for the holidays, so I’m slowly getting back into the groove of things.It shouldn’t be long before more updates are up. I wish all of you a healthy, happy 2008! 

White Papers Galore

For those of you who couldn’t attend the US 2007 UGC conference, I thought I would pass along some information that was provided to those who did.

Telelogic has posted the white papers from this year’s conference here:

http://www.telelogic.com/campaigns/2007/ugc/agenda_postevent.cfm?region=us

Not all white papers will be posted due to some companies not giving Telelogic permission to share. And according to the email, not all white papers have been posted yet, so you have to keep checking back

It’d be nice to have all those white papers in one place instead of having to poke and prod around. But if you’re willing to do that poking and prodding, I’m sure you’ll find some useful information.

Live from Atlanta

I am writing this from Atlanta, GA, site of 2007’s Telelogic User Group Conference. If any of you see me, please don’t hesitate to come up to me and say hi.

Also, I will be presenting my white paper, “Using DOORS to Update and Configure DOORS Clients” on Tuesday afternoon. I hope to see you there!

Site Redesign

I’m sure you can see by now that I have redesigned the site. It’s a lot more legible than the old site, in my opinion. I hope you all like it!

Introducing…

I know updates have been sparse for the past few weeks. That’s because I’ve been working on a redesign for the site and a new feature. A feature that I hope will be highly utilized.

You can find snippets of DXL all over the place, but you can’t just go to one place and find lots of DXL. You can visit Tony Goodman’s smart DXL, or Michael Sutherland’s Galactic Solutions, and find some interesting DXL along with some great information on the inner workings of DOORS, but you cannot find a lot of different DXL in one place.

I’m hoping to change that with a DXL file repository I’ve programmed into this site. I’ve found that I am much better at DXL than I am at Web Development, and I’ve been working on this for quite a while, just about as long as this site has been launched!Not all features have been implemented yet, but the important ones have. The DXL Repository allows:

  • registered users to upload files
  • anyone to download files
  • registered users can make comments
  • anyone can read comments
  • categories to be assigned to files
  • descriptions to be added to files
  • a download counter

Eventually, you’ll be able to browse DXL by category and do a search. As I said, I’m not the greatest Web Developer in the world, so if you run into a bug, please let me know. There is a limit on the filesize you can post, so if you try posting a large file and get an error, it may be due to that. If there is a category you think I should add, let me know. In the meantime, if a category doesn’t fit, just put it in the “Uncategorized” category.

The very first DXL I’ve posted is a script that allows users to save views without DOORS’ horrible Save View dialog box. This makes view management an absolute breeze for administrators, and saving views simple for users. The name of the script is Simple Save View, and you can download it here.

For this file repository to be successful, you have to contribute to it. Contribute snippets, examples, full-fledged scripts, or even zipped powerpoint presentations.

This can be one of the most valuable resources for DOORS users everywhere. We don’t have to worry about the Telelogic Forums losing posts or someone’s personal Web site going down. This site will be up and running for quite a while, and will be cached by Google and other major search sites, so for goodness sake, share your most useful DXL and let’s have a library the DOORS community can use.

DOORS Link Modules – Explained!

One thing that really confuses new DOORS adminisrators is link modules. When I say that DOORS is not Access, one thing that makes DOORS different than other databases is link modules.

I think Telelogic, both in their documentation and in the DOORS UI, makes way too big a deal out of link modules. Link modules are just a container, yet going through the documentation it’s not clear exactly what that container holds.

Link modules are like airports, and linksets and link mappings are like flight paths. Source formal modules objects are passengers, and target formal modules and objects are destinations.

Is everyone with me so far?

Let’s say we have DOORS modules representing Customer Requirements, System Requirements, and Software Requirements. Let’s say no link module exists, and no link mappings yet exist. Someone creates a link from Software to System. DOORS will ask if a link module should be created, and if the user says yes, DOORS will ask if a linkset should be made. If the user says yes to that, the link gets made.

The created link module, named DOORS Links, will be created in the same folder as the Software module. DOORS will have created a linkset for the relationship Software to System requirements. This linkset will be contained in the link module. At this point we should rename DOORS Links to something a little cleaner, like “Links to System.”

This linkset is like a flight path. A passenger just took a flight from Software through the DOORS Links airport, arriving at target destination System.

Let’s say another airport is created. We want to use this airport to link Software Requirements to a new module, SSDD. Let’s call this airport “Links to SSDD”. (In other words, in the same folder, create a link module called “Links to SSDD.”) In the Software Module, I can go to File>Module Properties and choose the “Linksets” tab. The name of this tab is misleading. What you are doing here is defining link mappings. Linksets are defined in Link Modules.

Link mappings are flight paths too. But unlike linksets, they can be mandatory flight paths.

In the “Linksets” tab, click the “Add…” button. As the target module choose SSDD, and then set “Links to SSDD” for the link module. Check the Mandatory checkbox and make sure Overridable is unchecked. Click ok. Finally, check the “Only allow outgoing links as specified in the above list” checkbox. Click OK.

When a user creates a link from a SW requirement to the SSDD requirement, DOORS will now use the “Links to SSDD” as the link module. When the first link is created, DOORS will ask to create a linkset for SW to SSDD links. When the user agrees to have DOORS create the linkset, the link is made.

In other words, SW passengers traveling to destination SSDD will be required to use the “Links to SSDD” airport and the SW to SSDD flightpath. Yes, there’s the “Links to System” airport as well, but that airport doesn’t feature the same flight path, and even if it did (and it can, in case you were wondering), we’ve mandated that our SW passengers traveling to SSDD have to use the Links to SSDD airport. They don’t have a choice, similar to many passengers who use the airport in real life.

What if we didn’t make that airport mandatory, or we made the airport overridable. Well, in DOORS you can do that, and in my opinion it’s a horrible idea. As Administrators, we’re like the FAA. We control the flight paths. Letting commercial pilots fly freely without using flight paths is a recipe for a crash, or at the very least, some near-misses.

This all sounds really complicated, I bet. To me, there is too much thought invovled for my end users, and I like to make things really easy for my users. The easier things are for them, the easier my job is.

 Once the above has been set up to be mandatory, DOORS does the work for the users automatically when it comes to creating links. Users don’t have to worry about link modules and mappings and linksets when it comes to creating links through the interface. But as soon as they use Link By Attribute, Delete Links, or the Analysis Wizard, they have to start worrying about link modules. And when you have multiple link modules, the user has be savvy enough to realize what they’re doing.

My rule of thumb is unless there is a very good reason to do otherwise, every folder should have a link module within it in DOORS, and every module within said folder should use the same link module.

So if I have a folder for Use Cases, with 10 Use Case modules inside, I set up my databases to have just one link module for Use Case Links. Now the target module (ie., destination) for each and every Use Case may be different.

So if Use Case 3 links to System Requirement modules A and B, and SSDD Modules 1 and 2, when I run the Analysis Wizard for all modules and choose the Use Case Links link module, I’m going to get all outgoing links. Whereas if I had set up a separate link module for System requirements versus for SSDD requirements, then using the analysis wizard, it would be much easier for me to see just the SSDD links, not bothering with the System links.

Why, then, would I put all outgoing links in one module? It’s simple–I can always edit the DXL that shows traceability to exclude certain target modules!

Therefore it’s a trade-off. I make my life a little harder because I have to create custom trace reports from time to time, to make everyone else’s life easier with not having to worry about which links go in which link module. There is nothing to worry about, as there is only one link module in each folder!

My personal opinion is that this is bad design in DOORS. An end user should never, ever have to worry about link modules. And most of the time they don’t. But if they ever do, you can make it easier on them by letting the answer be obvious.

And that can be done using multiple link modules or just one. The choice is up to you. The important thing for admins to realize is that link modules are containers for linksets, and a link “travels” along a linkset, thus you really want to define your flight paths, so that when it comes time to do traceability, your traceability matrix is easy to understand.

Each module that gets created needs to be maintained. This includes link modules. So my last piece of advice is to make link module maintenance easy. Since links can only be created from a user who has edit access on the source module, make the link module have permissions for group “Everyone else” to “RMC”. This way, you don’t have to manage group permissions for link modules. If I don’t have edit access to a module, then I can’t create a link. But once I do have rights to that module, you as the Admin won’t have to go in and grant me rights to the link module. I’ll be able to create links instantly, and thus don’t run the risk of creating another link module called “DOORS Links”.

 Once you make the choice on how to set up your link modules, be sure you know why and be sure it’s documented. Maybe you want a separate link module just for internal links rather than external links. Maybe you want to control traceability via DXL, like I tend to do. Just know why you’re doing what you’re doing and then be consistent. Easier said than done most of the time, but not with link modules.

DXL Tutorial – Part I

I’ve seen a few DXL guides in my day, and I’ve seen a lot of DXL snippets, but I’ve never seen an in-depth DXL tutorial. I’m writing this to help plug a gap in the world of DOORS and DXL.

DXL coding is like coding in any other type of language, you have to practice it and do it over and over and over again until you learn its intricacies. The problem that DXL has, unlike many languages, is that it only has a reference guide, and not a full API manual. The reference guide assumes that the programmer is only using the guide as a reference, so explanations are generally on the shorter side, and details are generally not always given where they ought to be.

Telelogic wants to sell training, and that’s fine, but in my opinion, they cripple their user guides as a result. I think they could put every ounce of information about DOORS and DXL in their documentation and they would still sell training, as most projects have managers that understand the importance of getting requirements right the first time.

There I go, digressing again.

The reason I bring it up in the first place is that there are just many different places to go to find critical information. Why isn’t the DXL I wrote showing up in my user menu? Why am I getting an error on a print statement? Finding the answers to these questions takes a lot of time, as you may find them on the Telelogic forums, in the reference guide, via a Google search or by studying code yourself, but there isn’t just one or two single places to go.

The purpose of this series is to take a relatively simple script and add on to it and make it robust, providing a great DXL tutorial in the process. I shall do my best to document the reason for every single line of code.

I was recently tasked with finding out which modules in our database have incoming links. So I wrote a simple function to accomplish the task. This series will take that function and expand upon it incrementally, giving it more features.

Please leave me comments and ask as many questions as possible. Also, make some requests for features. We can all try to build this together. Remember, the goal here is to document as much as possible in an easy tutorial—so people can look at this example and see all the basics to lookout for in one place.

I do assume that you have a basic understanding of programming. This isn’t about teaching programming. You should know the difference between an int and a string. You should know the difference between a for loop and a while loop. If you know the basics–if statements, Boolean logic, etc, you will likely be able to learn some DXL from this tutorial.

So without further ado, let’s begin.

For now, I am setting our goal to be finding out if the current module has any objects that contain incoming links. This seems pretty easy overall. We will eventually expand upon it and include every module in a folder, but for right now, we’re going to concentrate on just the current module.

Thus, step one is to open a module.

The first thing to get out of the way is how to format the comments at the beginning of the file. This header information is important in case someone else has to maintain our DXL and/or we ever want to put it in a DOORS menu.

If we want to use this in a DOORS DXL menu, our code must begin with each of the comment styles, in this order.

//

/*
*/

You can run any DXL you want without this at the beginning, but it will never show up in a DOORS menu.

So I’m going to populate this code.

//Module has incoming links.dxl

/*
$FILENAME: Module has incoming links.dxl
$VERSION: 0.1
$DATE_MODIFIED: 2007-09-23
$DESCRIPTION:
The purpose of this DXL is to report whether the current module has any objects with incoming links.
$CHANGE_HISTORY:
2007-09-23: Initial Release
*/

DXL, like C and C++, uses // and /* */ for comments. You can put anything you like in here and you’ll never get errors. The // is for a single line and /* */denotes multi-line comments.

So we’ve got our description. We should save the file as “Module has incoming links.dxl”.

Now let’s actually start some coding.

For now, the requirement is only to determine whether or not any objects have incoming links. We don’t need to count the number of objects, nor do we need any additional link information.

We have two methods of accomplishing this. We can look at every single object in the module one-by-one, or we can apply a filter. The better way to accomplish this is to apply a filter. Before we apply it, we have to define it.

//Declare filter integers for accepted and rejected objects
int iAcc = 0
int iRej = 0

//Turn off current filter
filtering off

//Define the filter
Filter f = hasLinks( linkFilterIncoming, "*" )

The above code will not give any errors in DOORS, but it won’t give any output either. However, I want to discuss what has already been done.

I declared integer variables for the number of objects accepted and rejected by the filter. This is necessary because if 0 objects are accepted, then our module has no objects with incoming links, and we need to know that. We likely won’t use the iRej variable, but we need it because the function that sets the filter requires it. I also initialize the variable because it’s just good practice. Without initializing it first, if I were to say, print iAcc, and it didn’t have a value, the user would get a DXL error.

Notice, also, how DOORS does not end statements with a semicolon. This makes it different than many other languages. If you don’t like this, you may put a semicolon at the end of every statement. DOORS will ignore it, but will still run DXL.

I did turn filtering off in case there is a filter applied. I do this because DOORS can be quirky sometimes and it’s best to be as explicit as possible. I believe you may omit this statement and the code will still work flawlessly, but I prefer to be safe when it comes to DXL.

Finally, notice where we define the actual filter. Notice that Filter is capitalized. When we declared integers, int was not capitalized. The reason for this is that DXL custom types are capitalized. In C, there are strings, reals, ints, bools, etc. If it exists in standard C, then it is not capitalized in DXL. The filter type is not found in C, so Filter must be capitalized, as must other DXL types, such as Module, Link, Object, and so forth.

There is a function for a filter called hasLinks. If you reference the DXL manual, you’ll see that you can filter on linkFilterIncoming, linkFilterOutgoing, or linkFilterBoth. These values correspond to the values in the links tab of the define filter dialog in DOORS.

The “*” means that we are ignoring specific link modules. Instead, we just want to know if there are any incoming links, regardless of which link module those links may be going through. If we wanted to look at a specific link module, the line would change to:

Filter f = hasLinks( linkFilterIncoming, “/path/to/link module/actual link module name” )

Is everyone with me so far? Now we just need to set the filter and turn filtering on and see what we get.

//set filter
set( current Module, f, iAcc, iRej)

The above code sets the filter f in the current Module. It passes the variables iAcc and iRej by reference, so that both iAcc and iRej are updated with the results. (The & symbol in front of iAcc and iRej in the DXL reference manual for this function means that these variables will get updated by the function).

At this point, we could turn filtering on with a line that said, “filtering on,” but there is no need to do so. We have the information we need. You can turn filtering on if you want to do a quick check, as every object should have at least one incoming link.

If any objects were accepted, we know we have incoming links. So we just need to print out whether we do.

( iAcc > 0 ) ? print "true" : print "false"

This is a unary if statement. Since we’re just wanting to do something simple, we can use this method. It is equivalent to the following code.

if ( iAcc > 0 ) {
print "true"
} else {
print "false"
}//end if

The above code, whichever if statement method is used, will print out true or false in the DXL Interaction window, even if the DXL Interaction window is not being displayed. Calling print will always display it.

Since this may be a menu option one day, we shouldn’t use the print statement. So I’m going to change the code.

( iAcc > 0 ) ? ack "true" : ack "false"

Ack is equivalent to msgBox for you VB programmers out there. It displays a dialog box with an OK button. It’s more interactive and user friendly. (I apologize for using buzzwords from the 1990s, but in this case, it’s true. An ack box is generally better to use than a print statement in DXL.)

So for now, we’re done. I’ve included the entire code below. We’re going to add on to it. My plans eventually are to choose an individual module to run this on via a dialog box. Then maybe to choose a folder to run this on. Finally we may output a report to Microsoft Excel. And we’ll do it from scratch.

Next time we’re going to talk about making the above code into a function. This will let us reuse the code in other scripts very easily.

If anyone has any ideas on how to enhance this, or what tutorial features you’d like to see, feel free to comment below.

//Module has incoming links.dxl

/*

$FILENAME: Module has incoming links.dxl
$VERSION: 0.1
$DATE_MODIFIED: 2007-09-24
$DESCRIPTION:
The purpose of this DXL is to report whether the current module has any objects with incoming links.

$CHANGE_HISTORY:
2007-09-24: Initial Release

*/

//Declare filter integers for accepted and rejected objects
int iAcc = 0
int iRej = 0

//Turn off current filter, in case there is one already applied
filtering off

//Define the filter
Filter f = hasLinks( linkFilterIncoming, "*" )

//set filter
set( current Module, f, iAcc, iRej)

( iAcc > 0 ) ? ack "true" : ack "false"

To run this, in the module you’ve opened, choose Tools>DXL Interaction, paste the code, and click Run.

DOORS Is Not Access — Part II

In my last entry I explained the concept of a public database. DOORS is a public database. Access is semi-public, as an Access developer can take steps to expose or hide the database from the users, where Oracle is usually intended to completely backend all data. Users don’t really go into an Oracle database and poke around.

This isn’t true for DOORS. When DOORS is used as anything other than a repository, users can usually see more than they absolutely need to. This makes DOORS different from other databases.

Let me illustrate my point with a story.

Read More “DOORS Is Not Access — Part II”

DOORS Is Not Access – Part I

It is my sincere hope that one day, someone who has just been tasked to administer DOORS for their company and who knows nothing about DOORS will come across this entry and think a little bit before jumping in head first.

Merriam-Webster defines a database as “a usually large collection of data organized especially for rapid search and retrieval.” In this sense, DOORS is a database. There is a DOORS server, with organized data that can be accessed by clients.

But just because DOORS is a database, that does not mean that it’s just like every other database. And I’m not talking about the difference between, say, MySQL and PostgreSQL. Or even Access and Oracle. Yes, Access and Oracle are vastly different, but all of the database servers/tools listed above have one thing in common: most of the time, the customers of the data they house never see the structure of the database.

Read More “DOORS Is Not Access – Part I”