Data Format Description Language (DFDL) v1.0 Specification
OGF Proposed Recommendation GFD-P-R.174, January 31, 2011
A variable is a binding between a (qualified) name and a (typed) value. Variables are defined using the dfdl:defineVariable annotation (see 7.7); defining a variable causes an initial instance also to be created. Further instances of variables are created using the dfdl:newVariableInstance annotation. Instances of variables are assigned a value using the dfdl:setVariable annotation. Variables are referenced in expressions by preceding the QName with '$'.
This section describes the semantics of variables. Any implementation consistent with the behavior described here is acceptable.
The memory where the information about a variable is stored during DFDL processing is called the variable memory. A variable is a name that is associated with a storage tuple in the variable memory.
Specifically, the variable memory contains:
a counter used to generate locations for new tuples. Initial value is 1.
an ordered list of locations. Each location contains a tuple of values:
has-been-set flag. This Boolean is originally false. dfdl:setVariable changes this flag to true.
has-been-referenced flag. This Boolean is originally false. Evaluation of an expression that uses the variable value changes the value to true.
has-value flag. This Boolean is originally true if the dfdl:defineVariable or dfdl:newVariableInstance annotation has a default value specified, or if a default value has been supplied externally. Otherwise it is false, but is set to true if a dfdl:setVariable annotation is processed.
typeID. This string is a type identifier taken from the type specified in the dfdl:defineVariable annotation.
value. This is a typed value, or the distinguished value "unknown". The type of the value must correspond to the typeID. The value is optionally specified in dfdl:defineVariable or dfdl:newVariableInstance annotations in which case we refer to it as the default value for the variable. A default value may also be provided by the DFDL processor when the variable is defined with external=”true”.
The variable memory is initialized when a dfdl:defineVariable annotation is encountered.
Each time a dfdl:newVariableInstance annotation is encountered, the parser captures the current value of the counter from the variable memory. It then creates a new variable memory where the location counter's value is one greater, and where the list of locations has been augmented with a new tuple at the location given by the prior value of the location counter. The tuple is initialized based on the specifics of the dfdl:defineVariable annotation.
Upon exit of the scope where the new variable instance was created, the newly created variable memory is discarded and the prior variable memory is restored.
Note that the above algorithm insures that each time a dfdl:newVariableInstance is encountered, a fresh location is initialized for it, and once the scope containing that variable goes out of scope, the instance tuple for the variable can no longer be reached. A different variable instance tuple may now be visible if there is one still in an enclosing scope.
DFDL annotation |
before annotation processed |
after annotation processed |
||||
---|---|---|---|---|---|---|
has-been-set |
has-been-referenced |
has-value |
has-been-set |
has-been-referenced |
has-value |
|
defineVariable (without default or external value) |
tuple doesn’t exist |
false |
false |
false |
||
defineVariable (with default value) |
tuple doesn’t exist |
false |
false |
true |
||
defineVariable (with external value) |
tuple doesn’t exist |
false |
false |
true |
||
newVariableInstance (without default value) |
tuple doesn't exist |
false |
false |
false |
||
newVariableInstance (with default value) |
tuple doesn't exist |
false |
false |
true |
||
setVariable |
tuple doesn't exist |
schema definition error |
||||
false |
false |
false |
true |
false |
true |
|
false |
false |
true |
true |
false |
true (also value changed to new value) |
|
false |
true |
false |
impossible state. The flags cannot get into this configuration. |
|||
false |
true |
true |
schema definition error – set after reference not allowed. |
|||
true |
false |
false |
impossible state. The flags cannot get into this configuration. |
|||
true |
false |
true |
schema definition error – double set not allowed |
|||
true |
true |
false |
impossible state. The flags cannot get into this configuration. |
|||
true |
true |
true |
validator should issue warning – double set not allowed unless on separate branches of a choice and this can only be determined reliably at runtime |
|||
reference variable (from DFDL expression) |
tuple doesn't exist |
schema definition error |
||||
false |
false |
false |
schema definition error – undefined variable |
|||
false |
false |
true |
false |
true (value is returned) |
true |
|
false |
true |
false |
impossible state. The flags cannot get into this configuration. |
|||
false |
true |
true |
false |
true (value is returned) |
true |
|
true |
false |
false |
impossible state. The flags cannot get into this configuration. |
|||
true |
false |
true |
true |
true (value is returned) |
true |
|
true |
true |
false |
impossible state. The flags cannot get into this configuration. |
|||
true |
true |
true |
true |
true (value is returned) |
true |
The above table describes a set of rules which might be abbreviated as:
write once, read many
no write after the value has been read
An exception to this behavior occurs whenever the DFDL processor backtracks because it is processing multiple arms of a choice or as a result of speculative parsing. In this case the variable state is also rewound.
It is a schema definition error if a dfdl:setVariable or a variable reference occurs and there is no corresponding variable name defined by a dfdl:defineVariable annotation.
It is a schema definition error if a dfdl:setVariable provides a value of incorrect type which does not correspond to the type specified by the dfdl:defineVariable.
It is a schema definition error if a variable reference in an expression is able to return a value of incorrect type for the evaluation of that expression. That is, DFDL - including the expressions contained in it - is a statically type-checkable language. DFDL implementations may issue these schema definition errors prior to processing time.
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.