Message Sets: TDS Null handling options

TDS supports the handling of null values within messages, provided that the logical Nillable property of the element is set.

You can use the message set property Boolean Null Representation to specify the value to be used for Boolean Null representation. You can use the object properties Encoding Null and Encoding Null Value to control how null handling is represented for individual objects.

You can select the Encoding Null property from the enumerated values NULLPadFill, NULLLogicalValue, NULLLiteralValue, and NULLLiteralFill:

  • Only use the NULLPadFill option for fixed length objects. If you select this option for an object of simple type dateTime, a null dateTime is written out, which is an empty tag with a delimiter. (This is equivalent to selecting NullLiteralValue, with the Encoding Null Value property set to the empty string "".) If you select this option for an object of another simple type, the object is filled with the value specified by the Padding Character property. If you select this option, the Encoding Null Value property is disabled.
  • If you select the NULLLogicalValue option, the value entered for the Encoding Null Value property is converted to its logical value. For writing, the logical value is written in the same way as any other value. For parsing, the converted logical value is compared against the converted message data.
  • If you select the NULLLiteralValue option, the value entered for the Encoding Null Value property is directly substituted as if it were a string value. The value is not case sensitive. For fixed length objects, the literal value must be no longer than the length of the object.

    If the literal value is shorter, the Encoding Null Value is padded (using Padding Character) on output. On input, if the NULLLiteralValue's length does not match the Length field, set the message set level Trim Fix Len String property so that padded nulls are correctly parsed.

  • If you select the NULLLiteralFill option, the value entered for the Encoding Null Value property is interpreted as a single character string value. Therefore, each character of the value of the element in the bit stream must match exactly the character value specified, to be interpreted as a null value.

The use of the Encoding Null Value property is dependent on the value that you select for the Encoding Null property described above. Null values are not defined for binary types. The properties Encoding Null and Encoding Null Value are therefore not set for binary types.

Handling missing fields in a delimited format

When dealing with delimited message formats, it is common for fields to be empty. For example, in a line-oriented format, blank lines might be inserted to separate lines of data.
This is Line 1<CR><LF>
<CR><LF>
This is Line 3<CR><LF>
This is Line 4
If the TDS property Suppress Absent Element Delimiters of the parent complex type is set to Never, such a message is successfully parsed, but the blank line does not appear in the message tree: 
MRM
   - line1 = 'This is Line 1'
   - line3 = 'This is Line 3'
   - line4 = 'This is Line 4'
If you need to preserve the blank lines in the message tree, you can use TDS null handling to treat the blank line as NULL. Configure the following properties on the element:
  • Select Nillable .
  • Set TDS Encoding Null to NullLiteralValue.
  • Leave TDS Encoding Null Value empty.
The message tree then looks like:
MRM
   - line1 = 'This is Line 1'
   - line2 = NULL
   - line3 = 'This is Line 3'
   - line4 = 'This is Line 4'

The example above assumes that each line is modeled as an element of simple type string. If each line is modeled as an element of complex type, with each line consisting of a repeating number of word elements, set the three null handling properties on the word element instead, because an element of complex type cannot have a null value.

The message tree then looks like: 
MRM
   - line1
        - word = 'This'
        - word = 'is'
        - word = 'Line'
        - word = '1'
   - line2
        - word = NULL
   - line3
        - word = 'This'
        - word = 'is'
        - word = 'Line'
        - word = '3'
   - line4
        - word = 'This'
        - word = 'is'
        - word = 'Line'
        - word = '4'