Working with Optional Elements

LightWave Server has several mechanisms to indicate the presence of optional elements. These mechanisms use a schema attribute to indicate the presence or absence of the element.

Using the hideIfEmpty Attribute

The hideIfEmpty="1" attribute may be set on any element to indicate that if the source element is empty, it should not be included in the response payload. An element is considered empty when it is completely filled with the element's string padding character. Note that the string padding may be explicitly set on the element using the stringPadding attribute, or inherited from its parent. In the following example, if element optionalIfSpaces is filled with spaces, or optionalIfZeros is filled with zeros, the elements will not be included in the response payload.

<type name="SampleType">
	<element name="optionalIfSpaces" type="string" size="32" hideIfEmpty="1" stringPadding="spaces" />
	<element name="optionalIfZeroes" type="aStructureType" hideIfEmpty="1" stringPadding="zeros" />
</type>

Using the isSet Attribute

The isSet attribute may be set on any element, and references a target integer element which is used to indicate the presence or absence of the source element. In the following example, if the value of the element isAddressSet is non-zero, then the theAddress is included in the response. In this example, the hide attribute is set on the isAddressSet element to indicate that it is never included in the response payload. Note that when a response is received, the isSet target element will be set to zero if the source element is not present in the response, or non-zero if it is present.

<type name="SampleType">
    <element name="isAddressSet" type="int" size="4" hide="1" />
    <element name="theAddress" type="AddressType" isSet="isAddressSet" />
</type>

Using the minOccurs Attribute

The minOccurs attribute has two distinct uses:

1. On variable-length array fields: minOccurs specifies the minimum number of array elements to serialize. This is its primary use and is documented in Annotating DDL Elements. It applies to fields using OCCURS x TO y TIMES DEPENDING ON or annotated with dependsOn.

2. On string elements (deprecated): minOccurs="0" may be set on elements with type="string" to indicate that if the source element is filled with the string padding character, it should not be included in the response payload. This use is deprecated. New definitions should use hideIfEmpty instead.

If you are working with a fixed-size PIC X(n) field and want to omit it when empty, use hideIfEmpty as described above — not minOccurs.

The following example shows the deprecated string-element usage:

<type name="SampleType">
	<element name="optionalIfSpaces" type="string" size="32" minOccurs="0" stringPadding="spaces" />
	<element name="optionalIfZeros" type="string" size="32" minOccurs="0" stringPadding="zeros" />
</type>