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.
stream.OpenI 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
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:
- 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.
- 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:
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.