Manage Learn to apply best practices and optimize your operations.

Five special characters in DXL

In XML, there are five predefined entity references used in place of specific characters that would otherwise be interpreted as part of the XML itself.

View member feedback to this tip.

In Bryce Berry's recent tip Creating hotspot buttons on the fly using DXL, there are some in-line comments/documentation that read as follows:

It's necessary to replace any ampersands in the Database Title with its' HTML equivalent as DXL can't convert special characters such as &, <, and >
< less than = <
> greater than = >
& ampersand = &

In fact, it's not that DXL can't convert these special characters, it's just that they ARE special characters. In XML, there are five predefined entity references used in place of specific characters that would otherwise be interpreted as part of the XML itself. These five characters and their entity references are as follows:

  1. Ampersand {&} = &amp;
  2. Less than {<} = &lt;
  3. Greater than {>} = &gt;
  4. Double quotes {"} = &quot;
  5. Apostrophe {'} = '
So, text can be safely converted to well-formed XML. Example (the code below is a private method in a class):
Private Function convertEntityRef
(pstrValu As String) As Boolean 
        On Error Goto errorThrower 
        Const AMPERSAND = "&ampamp;" 
        Const APOSTROPHE = "&ampapos;" 
        Const DBL_QUOTES = "&ampquot;" 
        Const GT = "&ampgt;" 
        Const LT = "&amplt;" 
        convertEntityRef = False 
        pstrValu$ = Replace(pstrValu$, 
        pstrValu$ = Replace(pstrValu$, 
        pstrValu$ = Replace(pstrValu$, 
{<}, LT) 
        pstrValu$ = Replace(pstrValu$, 
{>}, GT) 
        pstrValu$ = Replace(pstrValu$, 
        convertEntityRef = True 
        Exit Function 
        Call Me.buildStackTrace(Erl, 
        Error Err, Error$ 
End Function


This is a good tip. But, what I especially liked is the error handling. Dallas uses a technique that is both simple and powerful -- the best kind of technique.

Powerful: By passing the error up the call stack, he is building a Java-like stack trace, capturing in order each subroutine/function/method/property that is involved and the offending a line number in each of those procedures.

Simple: The code is the same in every procedure's error handler. Only the main subroutine needs to report the error text.

—Grant L.

Do you have comments on this tip? Let us know.

This tip was submitted to the tip exchange by member Dallas Gimpel. Please let others know how useful it is via the rating scale below. Do you have a useful Notes/Domino tip or code to share? Submit it to our monthly tip contest and you could win a prize and a spot in our Hall of Fame.

Dig Deeper on XML and Web Services for Lotus Notes Domino



  • iSeries tutorials's tutorials provide in-depth information on the iSeries. Our iSeries tutorials address areas you need to know about...

  • V6R1 upgrade planning checklist

    When upgrading to V6R1, make sure your software will be supported, your programs will function and the correct PTFs have been ...

  • Connecting multiple iSeries systems through DDM

    Working with databases over multiple iSeries systems can be simple when remotely connecting logical partitions with distributed ...