Handling Empty Strings and Null Values

This topic discusses how to handle empty strings and null values.

The XML examples in this topic are in literal format.

Class and Property Parameters Discussed on This Page
XMLUSEEMPTYELEMENT XMLIGNORENULL XMLNILNOOBJECT XMLNIL

Default Projections of Empty Strings and Null Values

The following table summarizes the default XML projections of empty strings and null values. Note that the XML projections are analogous to the SQL projections, which are also shown here for comparison.

Default SQL and XML Projections of Empty Strings and Null Values

InterSystems IRIS Value	Default Projection to XML	Projection to SQL
$char(0)	Empty element or attribute	SQL empty string
""	No projection	SQL NULL value

The following sections describe how these projections work upon export and import, and provide details on your options for controlling these projections.

Exporting Values

The following table lists the ways in which empty strings and null values can be exported from XML-enabled objects to XML documents, for a property that is projected to XML as an element:

Exporting Empty Strings and Null Values for a Property Projected to XML as an Element

Details of XML-Enabled Class	Property equals ""	Property equals $char(0)
Class specifies default values for XMLIGNORENULL and XMLNIL	Exported XML document does not contain an element that corresponds to this property	Exported document contains an empty element that corresponds to this property; see the subsection
Class specifies XMLIGNORENULL=1	Exported document contains an empty element that corresponds to this property; see the subsection
Class specifies XMLNIL=1 (and XMLIGNORENULL is not 1)	Exported document contains an empty element that corresponds to this property and this empty element specifies xsi:nil="true"

The details are similar for a property projected as an attribute:

Exporting Empty Strings and Null Values for a Property Projected to XML as an Attribute

Details of XML-Enabled Class	Property equals ""	Property equals $char(0)
Class specifies default values for the parameters described in this table	Exported XML document does not contain an attribute that corresponds to this property	Exported document contains an empty attribute that corresponds to this property
XMLIGNORENULL=1	Exported document contains an empty attribute that corresponds to this property. For example: PropName=""
XMLNIL=1 (and XMLIGNORENULL is not 1)	Exported XML document does not contain an attribute that corresponds to this property (same as the default scenario)

Controlling the Form of an Empty Element

By default, InterSystems IRIS® data platform writes an empty element with an opening tag and a closing tag. For example:

<PropName></PropName>

You can instead cause InterSystems IRIS to write a self-closing empty element (which is equivalent). For example:

<PropName />

To do so, specify the XMLUSEEMPTYELEMENT class parameter as 1. The default for this parameter is 0.

Details for XMLIGNORENULL, XMLNIL, and XMLUSEEMPTYELEMENT

XMLIGNORENULL

Used during export to XML (and when writing SOAP messages), this parameter controls whether to ignore null strings (rather than exporting them).

This parameter is a class parameter in all XML-enabled classes. XMLIGNORENULL can equal 0 (the default), 1, "INPUTONLY", or "RUNTIME" (not case-sensitive).

The XMLIGNORENULL class parameter is inherited by subclasses.

XMLNIL

Used during export to XML (and when writing SOAP messages), this parameter controls the use of the xsi:nil attribute for null strings.

This parameter is a class parameter and a property parameter in all XML-enabled classes; the property parameter takes precedence. XMLNIL can equal 0 (the default) or 1.

The XMLNIL class parameter is not inherited by subclasses. The XMLNIL property parameter is inherited.

XMLUSEEMPTYELEMENT

Used during export to XML (and when writing SOAP messages), this parameter controls whether InterSystems IRIS writes self-closing empty tags. This parameter applies in two scenarios:

If XMLUSEEMPTYELEMENT is 1 for a class, the parameter affects any string-valued properties that equal "" and that are projected as elements. Any such property is exported as a self-closing empty element.
If XMLUSEEMPTYELEMENT is 1 for a class, and none of the properties appear as elements in the XML export, then the parameter affects the form of the empty element corresponding to the class instance. This element is exported as a self-closing empty element.

If XMLUSEEMPTYELEMENT is 1 in a class, the system generates slightly more code for that class. Also the XML processing for that class is slightly less efficient.

Importing Values

The following table lists the ways in which InterSystems IRIS handles empty, null, or missing elements and attributes when it imports from XML into an XML-enabled object:

Importing XML Documents with Empty, Null, or Missing Elements and Attributes

Details of XML-Enabled Class	Imported document does not contain the element or attribute	In the imported document, the element or attribute is empty	In the imported document, the element is empty and specifies xsi:nil="true"
Class specifies default value for XMLNILNOOBJECT parameter	The property is not set	The property is set equal to $char(0)	If the property is a literal-valued property, the property is not set If the property is an object-valued property, the property is set to a new instance of the referenced class; no properties are set in this instance
Class specifies XMLNILNOOBJECT=1	The property is not set	The property is set equal to $char(0)	The property is not set

Controlling the XML Element and Attribute Names

Controlling Transformations of Values