Skip to main content

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
FeedbackOpens in a new tab