BizzyBee’s BizzyThoughts

Step-by-step DXL debugging

When I started developing Viewnify, I stumbled upon all kind of problems and at first it was really hard to discover where the troubles were located.

Viewnify extensively uses DXL to alter the design of all views of a database. For those who don’t know what DXL is yet, it’s an XML representation of Domino data or design elements. In other words, such file can contain all info stored in a document or all design properties from a design element, or even a whole database. This gives you all kinds of powerful possibilities. But with great power comes great responsibility (sorry, I just had to use this quote here, couldn’t resist ;-))

The first aid I found was the NotesDXLImporter.Log property. I thought. Then. But what I got was very cryptical messages.

What I really needed was a dxl file, so I could take a look in it. And a tool to investigate the DXL file.

Creating the DXL file

Most of the times DXL is used to transform data or design elements. In my example code I use pipelining to achieve this:

'Pipeline creation
Set exporter = s.CreateDXLExporter
Set parser = s.CreateDOMParser
Set importer = s.CreateDXLImporter
Call exporter.SetInput(nc)
Call exporter.SetOutput(parser)
Call parser.SetOutput(importer)
Call importer.SetOutput(db)

Basically, you export the data or design elements, you parse (change) it and you import it again. More about pipelining is well explained in Designer Help, so I won’t cover this here.

To create a debug file we need to “bypass the pipe”, so I add a conditional piece of code below the pipeline creation part:

If DebugMode=True Then
	debugDir="c:\dxl" 'Or whatever directory you want it to be
	debugFile="dxlfile.xml" 'The name of your DXL file
	'First see if debugdir exists
	If Dir$(debugDir,16)<>“” Then
	Else
		Mkdir debugDir
	End If
	‘Define stream
	Set stream = s.CreateStream
	filename$ = debugDir & “\” & debugFile
	If Not stream.Open(filename$,”UTF-8″) Then
		Messagebox “Cannot open ” & filename$,, “Error”
		Exit Sub
	End If
	Call stream.Truncate
	Call parser.SetOutput(stream)
End If

Some remarks here:

• I give the file an xml extension, so it can be recognized by external programs as being an xml file. Extension dxl is too Domino specific for this.
• In stream.Open I also specify “UTF-8″. When I tested without this parameter, Domino seems to use “UTF-16″ and this confuses Internet Explorer and other external tools.

At this point, after running your agent you should find an xml-file in the specified directory when DebugMode=True.

Preparing your gears

There are 2 conditions that need to be fulfilled in order to succeed in importing a DXL file in Domino. The DXL file needs to be:

1. well-formed, meaning that the structure follows the rules on how an xml file should be built. F.e. every opening tag needs a closing tag. A bit like the XML grammar being followed.
2. valid, meaning a specific syntax is used. This syntax is dictated in Domino by a DTD-file. It tells us how the xml tags should be named, what attributes and values can be used, etc.

Although you can investigate some things in the browser (especially well-formedness) I suggest you look after an external tool to peek into the xml file. The one I use is XML Copy Editor: it’s opensource, it has enough whistles and bells for this purpose, is easy to use and quite fast (important, because a DXL file can become large, especially when exporting big collections).

Here’s a screenshot of an opened DXL file:

After opening the xml file you generated, you can see the DTD used at the top. In the first line there is: 'xmlschemas/domino_6_5_6.dtd'

This means that the xml file is validated against the file domino_6_5_6.dtd in the subdirectory xmlschemas. The DTD used depends on the version of Notes used.

IMPORTANT: if you want to validate your xml file, first copy the directory xmlschemas (containing all DTD from your current Notesversion + the previous ones) in your notesdirectory to your debugdirectory.

Now we’re ready to role! Checking the DXL file is a 2-step process I will demonstrate in XML COPY Editor

Is it valid?

In XML Copy Editor you choose XML - Check Well-formedness.

At the bottom you’ll see error messages like this one if your grammar sucks:

Is it well-formed?

Validation is done with the menu XML - Validate - DTD

If there are validation errors, you will now see at what line and what kind of error.

Where to go from here?

Well-formedness should be easy to tackle. Creating valid DXL is often more difficult to achieve. My main source of information is Designer Help (starting at the document “The Domino DTD”). Also, it doesn’t hurt to look at the DTD-file itself, it seems pretty readable to me after a while.

If you found this interesting, in a future article I may also cover some specific errors and traps I encountered during my DXL journey.

(No Ratings Yet)

 Loading ...

4 Responses to “Step-by-step DXL debugging”

1. Stephan H. Wissel says:
   December 29th, 2007 at 2:39 pm

   DXL can be pretty challenging. While Views are relatively straight forward, forms are not. The XML follows the internal structure more than the idea of an XML file. E.g. a “run” element influences all following text instead of enclosing the text that is defined by a run. Also inside a run line breaks are actually line breaks, there is no “br” element.
   stw

2. Martin Vereecken says:
   December 29th, 2007 at 5:14 pm

   Agree! Forms are worse than views. Only a lot of trial and error can help

3. Ken Haggman says:
   January 16th, 2008 at 9:19 am

   DXL has more (lots more) problems than just the occasional export error that may be due to poorly formed XML. NotesHound was from the start completely based around DXL but we have now abandoned DXL and are using other means to get the job done.

   The worst problem, in my mind, is the instability of DXL. A piece of code may run 26 times against the same design element or document and work absolutely fine, and then - totally inexplainable - it will generate a DXL eporter error on the 27th run. The one gusess I can come up with for such behaviour is memory leaks.

4. Martin Vereecken says:
   January 16th, 2008 at 8:44 pm

   I encountered some problems too, and for most of them I found a solution or workaround. I didn’t receive many real problem records with Viewnify yet, so I hope that means it runs rather stable (not that users are so frustrated that they even won’t consider posting comments)

Leave a Reply