Data Format Description Language (DFDL) v1.0 Specification
OGF Proposed Recommendation GFD-P-R.174, January 31, 2011


7.8 The dfdl:newVariableInstance Annotation Element

Scoped instances of defined variables are created using dfdl:newVariableInstance:
<dfdl:newVariableInstance
 ref = qname
defaultValue? = logical value or dfdl expression
<!-- Content: logical value or dfdl expression (value) -->
</dfdl:newVariableInstance>

Since an initial instance is created when the variable is defined, the use of dfdl:newVariableInstance is optional. It would be used if an instance with restricted scope is required.

The dfdl:newVariableInstance annotation can be used on any element, element reference, group reference, sequence or choice.

The scope of the instance of variable name is the dynamic scope of the schema component and its contents and so is inherited by any contained constructs or construct references.

The ref attribute is a QName. That is, it may be qualified with a namespace prefix.

An optional dfdl:defaultValue for the instance may be specified. It can be specified as an attribute or as the element value. The expression must not contain forward references to elements which have not yet been processed nor to the current component. If specified the default value must match the type of the variable as specified by dfdl:defineVariable. If the instance is not assigned a new default value then it will inherit the default value specified by dfdl:defineVariable or externally provided by the DFDL processor. If a default value is not specified (and has not been specified by dfdl:defineVariable) then the value of this instance is undefined until explicitly set (using dfdl:setVariable).

If a default value is specified this initial value of the instance will be set when the instance is created. The value will override any (global) default value which was specified by dfdl:defineVariable or which was provided externally to the DFDL processor. A variable instance with a valid value (specified or default) can be referenced anywhere within the scope of the element on which the instance was created.

Note that the syntax supports both a dfdl:defaultValue attribute and the 'defaultValue' being specified by the element value. Only one or the other may be present. (Schema definition error otherwise.)

It is a schema definition error to have more than one newVariableInstances for the same variable at any given point in the document.

There is no short form syntax for creating variable instances.

7.8.1 Examples

<dfdl:newVariableInstance ref="EDIFACT_DS" defaultValue=","/>
<dfdl:newVariableInstance ref="lengthUnitBits">
    { if dfdl:property("lengthUnits")eq "bits" then 1 else 8 }   
</dfdl:newVariableInstance>

Copyright (C) Open Grid Forum (2005-2010). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the OGF or other organizations, except as needed for the purpose of developing Grid Recommendations in which case the procedures for copyrights defined in the OGF Document process must be followed, or as required to translate it into languages other than English.