Annotating DDL Elements

The LightWave Server™ Dictionary Manager translates your DDL 'definitions' to <type> and <element> elements in your Dictionary File. However, the <element> element supports features not available in DDL. Though you could modify the generated <element> elements to take advantage of these features, you'd have to repeat the modifications if you refresh your Dictionary. Instead, you can create 'annotations' on DDL definition elements that Dictionary Manager will recognize and incorporate into your Dictionary automatically.

A LightWave annotation is merely a DDL comment on an element in a particular form:

TEXT

* @LightWaveAttribute(attribute-name="attribute-value"[,attribute-name="attribute-value"]...)

where "*" in column one is the DDL comment indicator character; attribute-name and attribute-value are any of the attribute name-value pairs that are valid for the <element> element. Any number of attributes can be specified as a comma-separated list of name-value pairs. The values of the specified attributes supersede any that Dictionary Manager would ordinarily generate.

LightWave annotations can coexist with any other DDL comments you may have on a given DDL element. You must, however, include the "?COMMENTS" DDL directive in your DDL source in order to direct the DDL compiler save the comments in the compiled DDL dictionary; otherwise the comments are discarded during compilation and won't be available for the Dictionary Manager to read.

Consider the following DDL definition.

TEXT

?COMMENTS
DEF MY-IPM.
  02 REPLY-CODE TYPE BINARY 16.
* @LightWaveAttribute(type="boolean")
  02 BOOLEAN-VALUE TYPE BINARY 32.
END.

Assume that the DDL element BOOLEAN-VALUE is a 32-bit integer value 0 or 1. We'd like to have LightWave Server interpret this field as a JSON boolean when serialization and deserialzation occurs. LightWave Server supports this conversion; we need only to indicate that BOOLEAN-VALUE should be treated as a 'boolean' data type. Ordinarily, the Dictionary Manager would translate this element as an 32-bit integer data type. If we annotate the DDL as shown above, the following is generated in the Dictionary File:

XML

<type name="my_ipm" size="10">
  <element name="replyCode" type="short" offset="0" size="2"/>
  <element name="boolanValue" type="boolean" offset="2" size="4"/>
</type>

Here's another example:

TEXT

?COMMENTS
DEF MY-IPM.
  02 REPLY-CODE TYPE BINARY 16.
  02 ARRAY-1-COUNT PIC 9(4) COMP.
* @LightWaveAttribute(dependsOn="array1Count",minOccurs="0")
  02 ARRAY-1-ITEM PIC 9(4) COMP OCCURS 20 TIMES.
  02 ARRAY-2-COUNT PIC 9(4) COMP.
  02 ARRAY-2-ITEM PIC 9(4) COMP OCCURS 0 TO 10 TIMES DEPENDING ON ARRAY-2-COUNT.
END.

Here our definition contains two arrays. DDL only will allow the "DEPENDING ON" clause to be used on the last element of the definition, but our first array is, logically, a variable-length array as well. We've annotated the DDL to specify the "dependsOn" element name and the "minOccurs" count. The maximum size of the array will still be allocated for the server interprocess message, but only the actual count of array items will be serialized for the Web service client. The resulting <type> is shown below:

XML

<type name="my_ipm" size="">
  <element name="replyCode" type="short" offset="0" size="2"/>
  <element name="array1Count" type="unsignedShort" offset="2" size="2"/>
  <element name="array1Item" type="unsignedShort" minOccurs="0" maxOccurs="20" offset="4" size="2" dependsOn="array_1_count"/>
  <element name="array2Count" type="unsignedShort" offset="44" size="2"/>
  <element name="array2Item" type="unsignedShort" minOccurs="0" maxOccurs="10" offset="46" size="2" dependsOn="array_2_count"/>
</type>