XML Entity Declaration

The DOCTYPE may specify a DTD that contains entity declarations that make it possible to reuse XML data in multiple places. An entity represents a value, which can then be referenced by the entity name within the XML document or DTD. XML entities are often used to make XML documents more readable, or to modularize DTDs be defining reusable groups ot attributes and elements. This is the only functionality provided by DTDs and not by schemas, and is the reason DTDs are still used in combination with XML Schemas.

A general entity declaration has the format:

<!ENTITYName"Value">

A parameter entity declaration has the format:

<!ENTITY%Name"Value">

General Entities

References in the XML document to &Name; are replaced by Value. When parsed, this data no longer contains the original reference sequence, so on a round trip conversion, the entity references are lost and replaced by the substituted values.

Uniface supports the five predefined XML entities for XML Structs and for Uniface XML streams:

Predefined XML Character Entity References
Character Name Unicode Description
" quot U+0022 (34) Double quotation mark
& amp U+0026 (38) Ampersand
' apos U+0027 (39) Apostrophe
< lt U+003C (60) Less-than sign
> gt U+003E (62) Greater-than sign

Parameter Entities

Parameter entities have the format %Name; and can only be used in external DTDs. Like normal XML entities, parameter entity references are replaced by the substituted values when parsed.

XML Structs

In an XML-based Struct, entity and parameter entity declarations are represented by name Structs with annotations, as summarized in the following table:

XML to Struct Mapping

XML Document

XML Struct

Annotations

Internal entity declaration

Named Struct with XML entity name, and one nameless scalar member with the value.

xmlClass = "entity-declaration"

External entity declaration

Named Struct with the XML entity name and no value

xmlClass = "entity-declaration"

xmlPublicID = Value and/or xmlSystemID = Value

xmlExternalDoctype= "yes"

Unparsed external entity declaration, such as

<!ENTITY logo SYSTEM "http://www.xmlwriter.net/logo.gif" NDATA gif >

Named Struct with the XML entity name and no value

xmlClass = "entity-declaration"

xmlPublicID = Value and/or xmlSystemID = Value

xmlNotation = Value

xmlExternalDoctype= "yes"

Parameter entity declaration

Named Struct with the parameter entity name

xmlClass = "param-entity-declaration"

xmlPublicID = Value and/or xmlSystemID = Value

xmlExternalDoctype= "yes"

When converting from Structs to XML, the predefined XML character entity references are applied.

External DTD

An external DTD contains the following entity declarations:

<!ENTITY % s "salt">
<!ENTITY % p "pepper">
<!ENTITY % sp "%s; and %p;">

The corresponding Struct contains the following:

[s] = "salt"
  $tags
    [xmlClass] = "param-entity-declaration"
[p] = "pepper"
  $tags
    [xmlClass] = "param-entity-declaration"
[sp] = "salt and pepper"
   $tags
    [xmlClass] = "entity-declaration"

Related Topics