XML Convert 2.2
The XFlat Language
This page, which describes the XFlat language in detail, is organized as follows:
XFlat is an XML language for defining flat file schemas. An XFlat schema is an XML document that conforms to the XFlat language and that describes the format of a class of flat files. An XFlat schema defines the structure and syntax of a class of flat files that contain non-XML data. An XFlat schema also defines the structure and syntax of a class of XFlat instances. An XFlat instance is an XML document whose structure is the same as a flat file and whose data is the same as the data in a flat file. In other words, an XFlat schema describes the structure of a class of flat files and the corresponding class of XFlat instances. XML Convert transforms flat files into XFlat instances and vice versa.
The flat files that are described by an XFlat schema must consist of records, where each record is a sequence of fields. A field is an atomic piece of data (e.g., a postal code). Records and fields may be delimited. A record separator (i.e., delimiter) occurs at the end of a record and helps a parser determine where the record ends. Likewise, a field separator occurs at the end of a field and helps a parser to determine where a field ends. Fields that are not delimited must meet one or both of the following constraints:
The records may be grouped, and groups of records may be nested in a hierarchical structure (in other words, groups of records may contain subgroups).
The XFlat element types are as follows:
The XFlat element types, and which element types they may have as children, are as follows:
The following subsections describe the XFlat element types in more detail:
The XFlat element type is used to define an XFlat schema. The XFlat element is always the document element (i.e., root element) of an XFlat schema.
The XFlat element in an XFlat schema is a container element that contains one subelement. This subelement, which may be a SequenceDef, ChoiceDef or RecordDef element, models the flat file (or the XFlat instance). In other words, the subelement of the XFlat element (rather than the XFlat element itself) models the flat file (or XFlat instance). For example, if the flat file consists of a sequence of different record types (e.g., a header record followed by detail records followed by a trailer record), then the XFlat schema for this flat file would consist of an XFlat element whose subelement is a SequenceDef element. If the flat file consists of a single record, then the XFlat schema for this flat file would consist of an XFlat element whose subelement is a RecordDef element.
The XFlat element may contain any of following optional attributes:
Please see the Sample XFlat Schemas section below and the Examples page for examples of XFlat schemas, in which the XFlat element contains the Name and Description attributes.
A SequenceDef element type is used to model a sequence of one or more objects in a flat file (or XFlat instance). An object is a record, a sequence of objects or a choice of one object from a set of objects. For example, if a flat file contains a header record followed by one or more detail records followed by a trailer record, then the flat file would be modeled using a SequenceDef element that contains the following subelements:
The following XFlat attributes may be used in the SequenceDef element: Description, DTD, EncodingName, MapToXml, MaxOccur, MinOccur, Name, OmitXmlDeclaration, Standalone, StyleSheet and StyleSheetType.
Please see the Sample XFlat Schemas section below for examples of XFlat schemas that contain the SequenceDef element.
A ChoiceDef element is used to model a choice of one object among a set of objects in a flat file (or XFlat instance). An object is a record, a sequence of objects or a choice among objects. A ChoiceDef element should contain two or more subelements; each of these subelements should be a SequenceDef, ChoiceDef or RecordDef element.
The following XFlat attributes may be used in the ChoiceDef element: Description, DTD, EncodingName, MapToXml, MaxOccur, MinOccur, Name, OmitXmlDeclaration, Standalone, StyleSheet and StyleSheetType.
The following sections discuss examples of XFlat schemas that include the ChoiceDef element:
A RecordDef element is used to model a record (i.e., a sequence of fields) in a flat file (or XFlat instance). A RecordDef element can model many kinds of flat file records, including the following:
A RecordDef element can also be used to model a composite field (i.e., a field that consists of subfields) or a group of contiguous fields within a record. For example, suppose a flat file record contains three groups of fields. We could model the record using a SequenceDef element that contains three RecordDef elements (one for each group of fields in the record).
A RecordDef element must contain one or more FieldDef subelements. When a RecordDef element is modeling a flat file record, the RecordDef element will contain a FieldDef element for each field in the record.
The following XFlat attributes may be used in the RecordDef element: Description, DTD, EncodingName, FieldSep, MapToXml, MaxOccur, MinOccur, Name, OmitXmlDeclaration, RecSep, Standalone, StyleSheet and StyleSheetType.
Please see the Sample XFlat Schemas section below and the Examples page for examples of XFlat schemas that contain at least one RecordDef element. (Note that every XFlat schema must contain at least one RecordDef element.)
A FieldDef element is used to model a field (i.e., an atomic piece of data) in a flat file (or XFlat instance). A FieldDef element can model many kinds of flat file fields, including the following:
Note that a FieldDef element can be used to model a subfield of a composite field. In this case, the composite field would be modeled using a RecordDef element, and the record that contains the composite field would probably be modeled using a SequenceDef element that contains a RecordDef element for the composite field.
A FieldDef element is always empty (i.e., it never contains any subelements or text content).
The following XFlat attributes may be used in the FieldDef element: DataType, DefaultValue, Description, DTD, EncodingName, FieldSep, InvalidChars, LeadingFillerChars, MapToXml, MaxFieldLength, MaxValue, MinFieldLength, MinValue, Name, NullAllowed, OmitXmlDeclaration, QuotedValue, Standalone, StyleSheet, StyleSheetType, TrailingFillerChars, ValidChars and ValidValue.
Please see the Sample XFlat Schemas section below and the Examples page for examples of XFlat schemas, each of which contain at least one FieldDef element. (Note that every XFlat schema must contain at least one FieldDef element.)
This section provides the DTD for the XFlat language. The following DTD is provided to help you understand the syntax of the XFlat language.
<!DOCTYPE XFlat [
<!ELEMENT XFlat ( SequenceDef | ChoiceDef | RecordDef ) >
<!ELEMENT SequenceDef ( SequenceDef | ChoiceDef | RecordDef )+ >
<!ELEMENT ChoiceDef ( SequenceDef | ChoiceDef | RecordDef )+ >
<!ELEMENT RecordDef ( FieldDef )+ >
<!ELEMENT FieldDef EMPTY >
<!ATTLIST XFlat
Description CDATA #IMPLIED
Name NMTOKEN #IMPLIED >
<!ATTLIST SequenceDef
Description CDATA #IMPLIED
DTD CDATA #IMPLIED
EncodingName CDATA #IMPLIED
MapToXml (Element | No) 'Element'
MaxOccur CDATA '1'
MinOccur CDATA '1'
Name NMTOKEN #IMPLIED
OmitXmlDeclaration (Yes|No) 'No'
Standalone (Yes|No) #IMPLIED
StyleSheet CDATA #IMPLIED
StyleSheetType CDATA #IMPLIED >
<!ATTLIST ChoiceDef
Description CDATA #IMPLIED
DTD CDATA #IMPLIED
EncodingName CDATA #IMPLIED
MapToXml (Element | No) 'Element'
MaxOccur CDATA '1'
MinOccur CDATA '1'
Name NMTOKEN #IMPLIED
OmitXmlDeclaration (Yes|No) 'No'
Standalone (Yes|No) #IMPLIED
StyleSheet CDATA #IMPLIED
StyleSheetType CDATA #IMPLIED >
<!ATTLIST RecordDef
Description CDATA #IMPLIED
DTD CDATA #IMPLIED
EncodingName CDATA #IMPLIED
FieldSep CDATA #IMPLIED
MapToXml (Element | No) 'Element'
MaxOccur CDATA '1'
MinOccur CDATA '1'
Name NMTOKEN #IMPLIED
OmitXmlDeclaration (Yes|No) 'No'
RecSep CDATA #IMPLIED
Standalone (Yes|No) #IMPLIED
StyleSheet CDATA #IMPLIED
StyleSheetType CDATA #IMPLIED >
<!ATTLIST FieldDef
DataType (String|Integer|Float) 'String'
DefaultValue CDATA #IMPLIED
Description CDATA #IMPLIED
DTD CDATA #IMPLIED
EncodingName CDATA #IMPLIED
FieldSep CDATA #IMPLIED
InvalidChars CDATA #IMPLIED
LeadingFillerChars CDATA #IMPLIED
MapToXml (Element |
Attribute |
ElementIfNotNull |
AttributeIfNotNull |
No) 'Element'
MaxFieldLength CDATA '80'
MaxValue CDATA #IMPLIED
MinFieldLength CDATA '0'
MinValue CDATA #IMPLIED
Name NMTOKEN #IMPLIED
NullAllowed (Yes|No) 'Yes'
OmitXmlDeclaration (Yes|No) 'No'
QuotedValue (Yes|No) 'No'
Standalone (Yes|No) #IMPLIED
StyleSheet CDATA #IMPLIED
StyleSheetType CDATA #IMPLIED
TrailingFillerChars CDATA #IMPLIED
ValidChars CDATA #IMPLIED
ValidValue CDATA #IMPLIED >
]>Please note the following about the XFlat DTD:
The xmlconvert\samples folder contains the xflat.dtd file, which contains the XFlat DTD declarations.
Note that you can edit an XFlat schema using an XML editor. The XMLSoftware web site provides a list of XML editors (Xeena, XML Spy, XMetaL, TurboXML, XML Pro, etc.). Most of these XML editors can use the DTD declarations in the xflat.dtd file to verify the validity of your XFlat schema and to simplify the editing of the XFlat schema.
Please note that an XFlat schema does not need to contain a DTD. Also, the XML parser used by XML Convert is not a validating parser; thus, XML Convert will not validate an XFlat schema against any DTD that the XFlat schema contains. However, your XFlat schema may contain a DTD, in order to define general entities and/or default values for attributes. Please refer to the Examples page for an example XFlat schema that includes a DTD, in order to define default values for attributes. The Examples page also includes an example XFlat schema that includes a DTD, in order to define general entities.
This section describes the XFlat attributes, which include the following:
DataType, DefaultValue, Description, DTD, EncodingName, FieldSep, InvalidChars, LeadingFillerChars, MapToXml, MaxFieldLength, MaxOccur, MaxValue, MinFieldLength, MinOccur, MinValue, Name, NullAllowed, OmitXmlDeclaration, QuotedValue, RecId, RecSep, Standalone, StyleSheet, StyleSheetType, TrailingFillerChars, ValidChars, ValidValue
The attributes below are listed in alphabetical order (by attribute name). For each attribute, the following information is provided:
Some (but not all) of the information in this section is provided in the XFlat DTD.
Specifies the data type for a field. The set of strings that conform to an XFlat data type is the same as the set of strings that conform to the corresponding Java data type.
When converting a flat file into XML, XML Convert validates a field value against the data type for the field after any filler characters and surrounding quotes have been deleted from the field value.
When converting an XML document into a flat file, XML Convert validates a field value against the data type for the field before any filler characters and surrounding quotes have added to the field value.
If the field value is null and a default value has been defined, then XML Convert validates the default value against the data type. If the field value is null and a default value has not been defined, then XML Convert will not validate the null value against the data type.
Specifies the default value for the field.
When XML Convert is converting a field value into an XML element or attribute, if the field value is null and a default value is defined for the field, then the resultant XML element or attribute will contain the DefaultValue, if any.
When XML Convert is converting an XML element/attribute value into a field value, if the element/attribute value is null, then the field value will be set to the DefaultValue, if any.
When converting an XML document into a flat file and building a record that will be written to the flat file, if a field in this record does not map to XML, but the field has a ValidValue or a DefaultValue, then this field will be populated with the ValidValue or the DefaultValue (if the field has both a ValidValue and a DefaultValue, then the ValidValue is used).
When XML Convert assigns a DefaultValue to a null field, it will validate the DefaultValue against the DataType, MinValue, MaxValue, InvalidChars and ValidChars (if any).
See the NullAllowed attribute for more details.
Specifies the description of the XFlat schema, choice, sequence, record or field. The value of the Description attribute is treated as a comment.
Specifies the document type declaration for the outputted XML document.
XML Convert ignores this attribute when converting an XML document into a flat file.
When converting a flat file into XML, if this attribute is specified on the XFlat schema element that maps to the document element of the XML output, then the value of the DTD attribute will be the document type declaration of the resulting XML document. If the DTD attribute is specified on an XFlat schema element that maps to an element beneath the document element of the XML output, then the attribute is ignored. Note that the value of the DTD attribute is the actual text that comprises the document type declaration (as opposed to the name of a file that contains the DTD).
The value of the DTD attribute will contain the
"<" character and possibly
the "&" character; each occurrence of the
"<" and
"&" characters in the DTD attribute
value must be encoded as an entity or as
a numeric character reference. The "<"
character can be encoded as
"<",
and the "&" character can be encoded as
"&".
XML Convert does not verify the syntax of the specified document type declaration and does not check to see if the resulting XML document conforms to the DTD in the document type declaration.
Please refer to the Examples page for a sample XFlat schema that uses the XFlat DTD attribute to specify a document type declaration that defines a fixed attribute. The Examples page also describes an XSLT stylesheet that transforms an XFlat schema into a DTD.
Specifies the name of the encoding (e.g.,
"UTF-8")
for the outputted XML document.
XML Convert ignores this attribute when converting an XML document into a flat file.
When converting a flat file into XML, if this attribute is specified on the XFlat schema element that maps to the document element of the XML output, then an encoding declaration will be inserted into the XML declaration of the outputted XML document.
Note that the value of the EncodingName attribute does not affect the encoding of the
outputted XML document. The encoding of the outputted XML document can be controlled via
the java.io.OutputStreamWriter constructor or the file.encoding
system property of the Java language.
If the EncodingName attribute is specified on an XFlat schema element that maps to an element beneath the document element of the XML output, then the attribute is ignored.
XML Convert does not validate the value of the EncodingName attribute.
The field separator terminates the field value, but is not part of the field value. The field separator is a string containing one or more characters.
When specified in a FieldDef element, the FieldSep attribute specifies the field separator for the field. When specified in a RecordDef element, the FieldSep attribute specifies the default field separator for all the fields in the record except for the last field; in this case, the value of the last field must not contain the default field separator.
A quoted value field must be delimited by a field separator and/or a record separator. If a field is not delimited by a field separator or a record separator, then it must meet one or more of the following constraints:
See also the RecSep attribute.
Specifies the set of characters that may not appear in the field value.
When converting a flat file into XML, the field value is checked for invalid characters after any filler characters and surrounding quotes have been deleted from the field value.
When converting an XML document into a flat file, the field value is checked for invalid characters before any filler characters and surrounding quotes are added to the field value.
If the field value is null and a default value has been defined, then XML Convert validates the default value against the InvalidChars. If the field value is null and a default value has not been defined, then XML Convert will not validate the null value against the InvalidChars.
If the InvalidChars attribute is not specified or is equal to a zero-length string, then the field value is not validated against a set of invalid characters.
Specifies the set of filler characters that may appear at the beginning of the field.
When XML Convert transforms a flat file to XML, leading filler characters are deleted from the field value (after any surrounding quotes have been removed).
When XML Convert transforms an XML document to a flat file, if the length of a field value is less than the MinFieldLength and LeadingFillerChars have been defined for this field, then XML Convert will pad the field value on the left using one or more occurrences of the first character in the value of the LeadingFillerChars attribute.
Controls how the flat file object (i.e., the sequence,
choice, record or field) is mapped to XML. If the value of the MapToXml attribute is
"No", then the object is not mapped to XML. If the value of the MapToXml
attribute is "Element" or
"ElementIfNotNull", then the object is
mapped to an XML element. If the value of the MapToXml attribute is
"Attribute"
or "AttributeIfNotNull",
then the flat file field value is mapped to an XML
attribute.
When XML Convert transforms a flat file to XML, if the value of the MapToXml
attribute is "ElementIfNotNull"
and the corresponding flat file field is not null, then the
XML output will include an element containing this field value; if the value of the
MapToXml attribute is "ElementIfNotNull"
and the flat file field is null, then
the XML output will not include an empty element for this null field value. (See the
NullAllowed
attribute for a definition of null.)
When XML Convert transforms an XML document
to a flat file, if the value of the
MapToXml attribute for a flat file field is
"ElementIfNotNull", then the XML
element that corresponds to this field is optional.
When XML Convert transforms a flat file to XML, if
the value of the MapToXml attribute
is "AttributeIfNotNull"
and the corresponding flat file field is not null, then the XML output
will include an attribute whose value is the field value;
if the value of the MapToXml
attribute is "AttributeIfNotNull"
and the flat file field is null, then the XML
output will not include an attribute for this null field value.
When XML Convert transforms an XML document to a flat file,
if the value of the MapToXml attribute for a flat file field is
"AttributeIfNotNull", then the XML
attribute that corresponds to this field is optional.
Only a FieldDef element can have a MapToXml attribute that is set to
"Attribute",
"ElementIfNotNull" or
"AttributeIfNotNull".
If a field is mapped to an XML attribute, then the record that contains the field must be modeled using the RecordDef element and must be mapped to an XML element, which will contain the attribute.
This implies that XML Convert cannot handle an element that contains an attribute and either of the following:
XML Convert cannot generate such an element when it converts a flat file into XML, and it cannot parse such an element when it converts XML into a flat file.
For example, XML Convert cannot handle the following element because it contains an attribute and text:
<company id="123">Acme</company>
XML Convert can handle the following similar element:
<company id="123">
<name>Acme</name>
</company>
XML Convert cannot handle the following element because it contains an attribute and a subelement that contains an attribute:
<company id="123">
<division id="789"/>
</company>
XML Convert can handle the following similar element:
<company>
<company_id>123</company_id>
<division>
<division_id>789</division_id>
</division>
</company>
XML Convert cannot handle the following element because it contains an attribute and a subelement that contains a subelement:
<company id="123">
<division>
<department>Quality Assurance</department>
</division>
</company>
XML Convert can handle the following similar element:
<company>
<company_id>123</company_id>
<division>
<department>Quality Assurance</department>
</division>
</company>
The MapToXml attribute of an object does not apply to
the object's descendants. Thus,
if a RecordDef element contains the MapToXml="No"
attribute, then, by default,
the fields of this record will be mapped to XML elements.
By default, an object is mapped to an XML element.
Specifies the maximum length of the field. If the field is delimited by a field separator, then the length of the field does not include the field separator.
When XML Convert transforms a flat file to XML, it checks the length of a field value against the MaxFieldLength before any surrounding quotes or filler characters are deleted from the field value.
When XML Convert transforms an XML document to a flat file, it checks the length of a field value against the MaxFieldLength after any surrounding quotes or filler characters are added to the field value.
When converting a flat file into XML, XML Convert uses the MaxFieldLength value to determine the amount of memory that should be allocated to the internal buffer that stores a flat file record. Thus, if you set this value too high, then the performance of XML Convert may degrade.
Please note that the default value is 80 characters. If the maximum length of a field is greater than 80 characters, then you must explicitly define this maximum using the MaxFieldLength attribute.
The maximum number of times that the object may repeat within the flat file or the XFlat instance. A value of zero implies infinity (i.e., no maximum). The default value is 1 occurrence.
The maximum value for a field.
When XML Convert transforms a flat file to XML, the maximum value is compared with the field value after any filler characters and surrounding quotes have been deleted from the field value.
When XML Convert transforms an XML document to a flat file, the maximum value is compared with the field value before any filler characters and surrounding quotes are added to the field value.
If the field value is null and a default value has been defined, then XML Convert validates the default value against the MaxValue. If the field value is null and a default value has not been defined, then XML Convert will not validate the null value against the MaxValue.
The value of the MaxValue attribute must conform to the data type of the field.
If the MaxValue attribute is not specified or is equal to a zero-length string, then the field value is not compared to a maximum value.
Specifies the minimum length of the field. If the field is delimited by a field separator, then the length of the field does not include the field separator.
When XML Convert transforms a flat file to XML, it checks the length of a field value against the MinFieldLength before any surrounding quotes or filler characters are deleted from the field value.
When XML Convert transforms an XML document to a flat file, it checks the length of a field value against the MinFieldLength after any surrounding quotes or filler characters are added to the field value.
The default value is zero characters.
The minimum number of times that the object may repeat within the flat file or the XFlat instance. The default value is one occurrence.
The minimum value for a field.
When XML Convert transforms a flat file to XML, the minimum value is compared with the field value after any filler characters and surrounding quotes have been deleted from the field value.
When XML Convert transforms an XML document to a flat file, the minimum value is compared with the field value before any filler characters and surrounding quotes are added to the field value.
If the field value is null and a default value has been defined, then XML Convert validates the default value against the MinValue. If the field value is null and a default value has not been defined, then XML Convert will not validate the null value against the MinValue.
The value of the MinValue attribute must conform to the data type of the field.
If the MinValue attribute is not specified or is equal to a zero-length string, then the field value is not compared to a minimum value.
Specifies the name of the XFlat schema, sequence, choice, record or field. If an object is mapped to an XML element or attribute (i.e., if the MapToXml attribute of this object is not equal to "No"), then the object must have a name, which is specified via the Name attribute; the value of the Name attribute is used as the XML element/attribute name. Within each record, the names of any fields that are mapped to XML attributes must be unique. It’s a good idea to use the Name attribute for each element in the XFlat schema, since the object names are included in the XML Convert error messages.
Indicates whether or not a field value can be null.
When XML Convert transforms a flat file to XML, if a field value is zero length after any filler characters and surrounding quotes have been removed from a quoted value, then it is null.
When XML Convert transforms an XML document to a flat file, if a field value is zero length before any filler characters and surrounding quotes have been added to a quoted value, then it is null.
The default value of this attribute is
"Yes".
This attribute is used to suppress the inclusion of the
XML declaration
(e.g., <?xml
version='1.0'?>)
in the XML output.
When converting a flat file into XML, if this attribute is set to
"Yes"
and the attribute is specified on the XFlat schema
element that maps to the document element of the XML output,
then XML Convert will not include the XML declaration in the XML output.
(By default, an XML declaration is included in the XML output.)
If the OmitXmlDeclaration attribute is specified on an XFlat schema element that maps to an element other than the document element of the XML output, then the attribute is ignored.
When converting an XML document into a flat file, XML Convert ignores this attribute.
The default value of this attribute is "No".
The QuotedValue attribute is used for a field whose value
may be enclosed in quotes, such that the surrounding quotes
are not part of the field value. In an XFlat schema for a
Comma Separated Value (CSV) flat file, each FieldDef element
would contain the QuotedValue="Yes" attribute.
When converting a flat file into XML, if the FieldDef element
for a field contains the QuotedValue="Yes" attribute,
then the value of the field may be enclosed in quotes and
XML Convert will strip off the surrounding quotes (if any).
If the value of a quoted-value-field contains a quote
character (other than the surrounding quotes), then the
field value must be surrounded by
quotes and the quote character in
the field value must be prefixed with an additional quote.
If the value of a quoted-value-field contains the field separator
or the record separator, then the field
value must be surrounded by quotes; the surrounding
quotes will escape the meaning of the
separators. If a quoted-value-field is not the last
field in the record, then a field separator must be defined
for the field. If a quoted-value-field is the last field in the
record and there is no field separator for the field,
then a record separator must be defined for the parent record.
When XML Convert transforms an XML document to a flat
file, it will add surrounding quotes to the value of a
quoted-value-field only if
necessary. The default value of the QuotedValue attribute
is "No".
Please note that a quoted-value-field must be delimited by a field separator and/or a record separator.
Deprecated. This attribute, which was used by XML Convert 1.0, is ignored by versions 1.1 and higher of XML Convert.
Specifies the record separator for the record. The record separator is a string containing one or more characters. The record separator follows the last field of the record (and also follows the field separator, if any, of the last field).
If the last field in a record is a quoted-value-field and the FieldDef element for the field does not define a field separator, then the RecordDef element for the record must define a record separator.
In addition, a record must have a record separator defined via the RecSep attribute if the last field in the record meets all of the following conditions:
See also the FieldSep attribute.
This attribute is used to place a standalone document declaration
in the XML declaration of the XML output
(e.g., <?xml version='1.0' standalone='yes'?>).
When converting a flat file into XML, if the Standalone attribute is set to
"Yes" and the
OmitXmlDeclaration
attribute is not set to "Yes"
and the Standalone attribute is specified on the XFlat schema
element that maps to the document element of the XML output,
then XML Convert will include standalone='yes'
in the XML declaration in the XML output.
When converting a flat file into XML, if the Standalone attribute is set to
"No" and the
OmitXmlDeclaration
attribute is not set to "Yes"
and the Standalone attribute is specified on the XFlat schema
element that maps to the document element of the XML output,
then XML Convert will include standalone='no'
in the XML declaration in the XML output.
If the Standalone attribute is not specified in the XFlat schema element that maps to the document element of the XML output, then the XML declaration (if any) in the XML output will not contain a standalone document declaration.
If the Standalone attribute is specified on an XFlat schema element that maps to an element other than the document element of the XML output, then the attribute is ignored.
When converting an XML document into a flat file, XML Convert ignores this attribute.
This attribute does not have a default value.
Specifies the URL of a stylesheet to be included in an
xml-stylesheet processing instruction
(e.g.,<?xml-stylesheet
href="style.xsl"
type="text/xsl"?>).
When converting an XML document into a flat file, this attribute is ignored.
When converting a flat file into XML, if this attribute
is specified on the XFlat schema
element that maps to the document element of the XML output, then an
xml-stylesheet processing instruction
will be inserted before the document element
of the resulting XML document; if this attribute is specified on
an XFlat schema element that maps to an XML element
beneath the document element of the XML output,
then the attribute is ignored.
XML Convert does not validate the value of the StyleSheet attribute.
See also the StyleSheetType attribute.
Specifies the type of the stylesheet, whose URL is specified by the StyleSheet attribute. This attribute should only be used with the StyleSheet attribute.
XML Convert does not validate the value of the StyleSheetType attribute.
Specifies the set of filler chars that may appear at the end of the field value.
When XML Convert transforms a flat file to XML, the trailing filler characters are deleted from the field value (after any surrounding quotes have been removed).
When XML Convert transforms an XML document to a flat file, if the length of a field value is less than the MinFieldLength and TrailingFillerChars have been defined for this field, but the LeadingFillerChars have not been defined for this field, then XML Convert will pad the field value on the right using one or more occurrences of the first character in the value of the TrailingFillerChars attribute.
Specifies the set of characters that are allowed to appear in the field value.
When converting a flat file into XML, the field value is validated against the set of valid characters after any filler characters and surrounding quotes have been deleted from the field value; if the field value is zero length (after any filler characters and surrounding quotes have been deleted), then it is not validated against the ValidChars attribute value.
When converting an XML document into a flat file, the field value is validated against the set of valid characters before any filler characters and surrounding quotes are added to the field value; if the field value is zero length (before any filler characters and surrounding quotes have been added), then it is not validated against the ValidChars attribute value.
If the field value is null and a default value has been defined, then XML Convert validates the default value against the ValidChars. If the field value is null and a default value has not been defined, then XML Convert will not validate the null value against the ValidChars.
If the ValidChars attribute is not specified or is equal to a zero-length string, then the field value is not validated against a set of valid characters.
Specifies the only valid value allowed for the field.
When converting a flat file into XML, the valid value is compared with the field value after any filler characters and surrounding quotes have been deleted from the field value; if the field value is zero length (after any filler characters and surrounding quotes have been deleted), then it is not validated against the ValidValue attribute value.
When converting an XML document into a flat file, the valid value is compared with the field value before any filler characters and surrounding quotes have been added to the field value; if the field value is zero length (before any filler characters and surrounding quotes have been added), then it is not validated against the ValidValue attribute value.
When converting an XML document into a flat file and building a record that will be written to the flat file, if a field in this record does not map to XML, but the field has a ValidValue or a DefaultValue, then this field will be populated with the ValidValue or the DefaultValue (if the field has both a ValidValue and a DefaultValue, then the ValidValue is used).
The value of the ValidValue attribute must conform to the data type of the field; the ValidValue must also conform to any MaxValue, MinValue, InvalidChars and ValidChars.
If the ValidValue attribute is not specified or is equal to a zero-length string, then the field value is not validated against the ValidValue attribute value.
This section describes how to encode special characters (e.g., whitespace, control characters, XML markup characters, etc.), so that they can be included in the values of XFlat attributes.
If an XML attribute value contains line feeds, tabs or carriage returns, then an XML parser must convert each of these characters into a space character (Unicode #x20). (For more details, see section "3.3.3 Attribute-Value Normalization" in the XML 1.0 recommendation.)
Also, most of the ASCII control characters are not allowed in an XML document, even though the first 128 Unicode characters are the ASCII characters. For example, the value of the RecSep attribute cannot contain the ASCII formfeed character (Unicode #xC).
In order to allow you to include the line feed, tab, carriage return and control characters within an XFlat attribute value, the XFlat language defines the following encodings for these special characters:
| Encoding | Special Character |
|
\n |
The line feed character (Unicode #xA), which is also known as the Unix newline character. |
|
\r |
The carriage return character (Unicode #xD). |
|
\N |
The line separator for the local operating system. On Unix, \N is converted to the line feed character (Unicode #xA). On Windows, \N is converted to the carriage return character (Unicode #xD) followed by the line feed character (Unicode #xA). On the Macintosh, \N is converted to the carriage return character (Unicode #xD). |
|
\t |
The tab character (Unicode #x9). |
|
\#N; |
The Unicode character whose Unicode number is equal to N, which represents a decimal number. For example, the formfeed character (Unicode #xC) can be represented by "\#12;", since the hexadecimal number C is equal to the decimal number 12. Also, the line feed character (Unicode #xA) can be represented as "\#10;", since the hexadecimal number A is equal to the decimal number 10. |
|
\#xH; |
The Unicode character whose Unicode number is equal to H, which represents a hexadecimal number. For example, the formfeed character (Unicode #xC) can be represented by "\#xC;". The line feed character (Unicode #xA) can be represented as "\#A;". |
|
\\ |
The backslash character (Unicode #x5C). |
Note that if an XFlat attribute value contains any other character that is escaped by a backslash, then XML Convert will ignore (i.e., delete) the backslash when it reads the XFlat schema. For example, if XML Convert encounters ValidValue="\YES" in the XFlat schema, then it will behave as though the value of the ValidValue attribute is "YES".
If the last character in an XFlat attribute value is a backslash that is not escaped by a backslash, then the backslash is left alone. For example, if XML Convert encounters ValidValue="YES\" in the XFlat schema, then it will behave as though the value of the ValidValue attribute is "YES\".
You can define a record separator whose value is the carriage return followed by the line feed as follows:
RecSep="\r\n"
Alternatively, you can define this record separator as:
RecSep="\#13;\#10;"
You can define a record separator whose value is the operating system's line separator as follows:
RecSep="\N"
You can define a field separator whose value is the tab character as follows:
FieldSep="\t"
Alternatively, you can define this field separator as:
FieldSep="\#x09;"
You can define a field separator whose value is the backslash character as follows:
FieldSep="\\"
In addition to control characters, XML does not allow the "<" and "&" characters to appear in an attribute value, since these characters are XML markup characters. For example, the following is not allowed:
InvalidChars="&<>"
If an attribute value contains the "<" or "&" character, then this character must be encoded as an entity or as a character reference. The "<" character can be encoded as "<", and the "&" character can be encoded as "&". For example, if you want to set the value of the InvalidChars attribute to "&<>", then you could represent it in the FieldDef element as follows:
InvalidChars="&<>"
XML does not allow an attribute value to contain a double quote character (") when the attribute value is enclosed in double quotes. For example, the following is not allowed:
LeadingFillerChars=";":"
Likewise, XML does not allow an attribute value to contain an apostrophe character (') when the attribute value is enclosed in apostrophes. For example, the following is not allowed:
Description='Fred's record'
If an XFlat attribute value contains a double quote character (") but does not contain an apostrophe character ('), then you should enclose the value with apostrophes. For example:
LeadingFillerChars=';":'
If an XFlat attribute value contains an apostrophe character but does not contain a double quote character, then you should enclose the value with double quotes. For example:
Description="Fred's record"
If an XFlat attribute value contains an apostrophe character and a double quote character, then you will need to encode the apostrophes or the double quotes. The apostrophe character can be encoded as "'", and the double quote character can be encoded as """. For example:
LeadingFillerChars='"''
TrailingFillerChars=""'"
Before writing your first XFlat schema, we recommend that you review the sample XFlat schemas below. This section presents a variety of sample XFlat schemas. Each example includes a listing of the XFlat schema, a listing of a flat file that conforms to the schema and a listing of an XFlat instance that conforms to the schema.
The examples are as follows:
For additional examples of XFlat schemas, please refer to the Examples page.
In this example, we have a simple flat file containing employee data. Each record contains information about one employee. The flat file is in CSV format, which means that the record separator is the operating system's line separator and the field separator is the comma. In addition, a field value may be enclosed in quotes, which escape any commas or line separators that appear within the field value. Note that the quotes that surround the field value are not actually part of the field value. Also, if a field value contains a quote character, then the field value must be surrounded by quotes and the quote character in the field value must be prefixed with an additional quote.
The flat file may contain one or more employee records. Each record contains the following three fields:
The following are the contents of the employees flat file:
123456789,"Carr, Lisa",100000.00 444556666,"Barr, Clark",87000.00 777227878,"Parr, Jack",123000.00 998877665,"Charr, Lee",92000.00
This flat file is in the samples directory under the XML Convert home directory; the file name is employees.txt.
Each of the three records in the flat file is terminated by the operating system's line separator.
The following XFlat schema describes the layout of the employee flat file:
<?xml version='1.0'?>
<XFlat Name="employees_schema" Description="Schema for CSV flat file">
<SequenceDef Name="employees" Description="employees flat file">
<RecordDef Name="employee" FieldSep="," RecSep="\N" MaxOccur="0">
<!-- The max field length of the ssn field is 11, since
the field value can be enclosed in quotes. -->
<FieldDef Name="ssn" NullAllowed="No"
MinFieldLength="9" MaxFieldLength="11"
DataType="Integer" MinValue="0"
QuotedValue="Yes"/>
<FieldDef Name="name" NullAllowed="No"
QuotedValue="Yes"/>
<FieldDef Name="salary" NullAllowed="No"
DataType="Float" MinValue="0"
QuotedValue="Yes"/>
</RecordDef>
</SequenceDef>
</XFlat>
This XFlat schema is in the samples directory under the XML Convert home directory; the file name is employees.xfl.
Please note the following about this XFlat schema:
Using this schema, the flat2xml application would convert the flat file above into the following XML document:
<?xml version='1.0'?> <employees> <employee> <ssn>123456789</ssn> <name>Carr, Lisa</name> <salary>100000.00</salary> </employee> <employee> <ssn>444556666</ssn> <name>Barr, Clark</name> <salary>87000.00</salary> </employee> <employee> <ssn>777227878</ssn> <name>Parr, Jack</name> <salary>123000.00</salary> </employee> <employee> <ssn>998877665</ssn> <name>Charr, Lee</name> <salary>92000.00</salary> </employee> </employees>
This XML document is in the samples directory under the XML Convert home directory; the file name is employees.xml.
Using the employees.xfl schema, the xml2flat application will convert the employees.xml file into the original flat file (i.e., employees.txt).
The flat file in this example is the same as the flat file in the previous example, with the exception that the flat file below has a header record that contains the headings for the fields.
The following are the contents of the employees flat file:
Social Security Number,Employee Name,Salary
123456789,"Carr, Lisa",100000.00
444556666,"Barr, Clark",87000.00
777227878,"Parr, Jack",123000.00
998877665,"Charr, Lee",92000.00
This flat file is in the samples directory under the XML Convert home directory; the file name is employees_header.txt.
Each of the four records in the flat file is terminated by the operating system's line separator.
Note that there are two types of records in this employee flat file: the header record and the employee record. The employees flat file contains exactly one header record followed by zero or more employee records.
The following XFlat schema describes the layout of the employee flat file:
<?xml version='1.0'?>
<XFlat Name="employees_schema" Description="Schema for CSV flat file">
<SequenceDef Name="employees" Description="employees
flat file">
<RecordDef Name="header"
MapToXml="No" FieldSep="," RecSep="\N">
<FieldDef
Name="ssn" MapToXml="No"
ValidValue="Social Security Number"
NullAllowed="No"
QuotedValue="Yes"/>
<FieldDef
Name="name" MapToXml="No"
ValidValue="Employee Name"
NullAllowed="No"
QuotedValue="Yes"/>
<FieldDef
Name="salary" MapToXml="No"
ValidValue="Salary"
NullAllowed="No"
QuotedValue="Yes"/>
</RecordDef>
<RecordDef Name="employee"
FieldSep="," RecSep="\N" MaxOccur="0">
<!-- The max field length of the ssn field is 11, since
the field value can be enclosed in quotes. -->
<FieldDef
Name="ssn" NullAllowed="No"
MinFieldLength="9" MaxFieldLength="11"
DataType="Integer" MinValue="0"
QuotedValue="Yes"/>
<FieldDef
Name="name" NullAllowed="No"
QuotedValue="Yes"/>
<FieldDef
Name="salary" NullAllowed="No"
DataType="Float" MinValue="0"
QuotedValue="Yes"/>
</RecordDef>
</SequenceDef>
</XFlat>
This XFlat schema is in the samples directory under the XML Convert home directory; the file name is employees_header.xfl.
Please note the following about this XFlat schema:
Using this schema, the flat2xml application will convert the flat file above into the following XML document:
<?xml version='1.0'?>
<employees>
<employee>
<ssn>123456789</ssn>
<name>Carr, Lisa</name>
<salary>100000.00</salary>
</employee>
<employee>
<ssn>444556666</ssn>
<name>Barr, Clark</name>
<salary>87000.00</salary>
</employee>
<employee>
<ssn>777227878</ssn>
<name>Parr, Jack</name>
<salary>123000.00</salary>
</employee>
<employee>
<ssn>998877665</ssn>
<name>Charr, Lee</name>
<salary>92000.00</salary>
</employee>
</employees>
This XML output file is in the samples directory under the XML Convert home directory; the file name is employees_header.xml.
Using the employees_header.xfl schema, the xml2flat application would convert the employees_header.xml file into the original flat file (i.e., employees_header.txt). Note that xml2flat will automatically write the header record to the flat file, even though the employees_header.xml file does not contain the column headings.
The flat file in this example contains fixed length records and fields. Such files are commonly used to exchange data with mainframe applications. The flat file contains a product catalog. The first record in the flat file is the header record. The header record is followed by zero or more product records.
The first character in the header record is always the "H" character. This is followed by a 10 character vendor identifier. The vendor ID is followed by 35 filler characters. The header record is not terminated by a record separator. None of the fields in the header record are terminated by a field separator.
The first character in the product record is always the "P" character. This is followed by a 10 character product identifier. The product ID is followed by a 35 character product description. The product record is not terminated by a record separator. None of the fields in the product record are terminated by a field separator.
The following are the contents of the catalog flat file:
H1234567890
<EOR>
P22TT445501Tinky Winky Doll (includes bag) <EOR>
P22TT445502Dipsy Doll (includes
hat) <EOR>
P22TT445503Laa-Laa Doll (includes ball) <EOR>
P22TT445504Po Doll (includes
scooter) <EOR>
This flat file is in the samples directory under the XML Convert home directory; the file name is catalog.txt.
Note that in the flat file above, we use the "<EOR>" designator to help the reader see where each record ends; however, this designator does not appear in the flat file, and the flat file does not contain any record separator characters nor any line separators. The records are displayed on separate lines, in order to improve the readability of the listing.
The following XFlat schema describes the layout of the catalog flat file:
<?xml version='1.0'?>
<XFlat Name="catalog_schema" Description="Schema for catalog flat file">
<SequenceDef Name="Catalog" Description="Entire flat
file">
<RecordDef Name="Vendor"
Description="Header record">
<FieldDef
Name="RecordID" ValidValue="H"
MinFieldLength="1" MaxFieldLength="1"
MapToXml="No"/>
<FieldDef
Name="ID" MapToXml="Attribute"
MinFieldLength="10" MaxFieldLength="10"/>
<FieldDef
Name="Filler" MapToXml="No"
MinFieldLength="35" MaxFieldLength="35"
LeadingFillerChars=" "/>
</RecordDef>
<RecordDef Name="Product"
Description="Product record"
MaxOccur="0">
<FieldDef
Name="RecordID" ValidValue="P"
MinFieldLength="1" MaxFieldLength="1"
MapToXml="No"/>
<FieldDef
Name="ID" MapToXml="Attribute"
MinFieldLength="10" MaxFieldLength="10"/>
<FieldDef
Name="Description"
MinFieldLength="35" MaxFieldLength="35"
TrailingFillerChars=" "/>
</RecordDef>
</SequenceDef>
</XFlat>
This XFlat schema is in the samples directory under the XML Convert home directory; the file name is catalog.xfl.
Please note the following about this XFlat schema:
Using this schema, the flat2xml application would convert the flat file above into the following XML document:
<?xml version='1.0'?>
<Catalog>
<Vendor ID="1234567890"/>
<Product ID="22TT445501">
<Description>Tinky Winky Doll (includes
bag)</Description>
</Product>
<Product ID="22TT445502">
<Description>Dipsy Doll (includes
hat)</Description>
</Product>
<Product ID="22TT445503">
<Description>Laa-Laa Doll (includes
ball)</Description>
</Product>
<Product ID="22TT445504">
<Description>Po Doll (includes
scooter)</Description>
</Product>
</Catalog>
This XML output file is in the samples directory under the XML Convert home directory; the file name is catalog.xml.
Using the catalog.xfl schema, the xml2flat application will convert the catalog.xml schema, file into the original flat file (i.e., catalog.txt). Note that xml2flat will automatically add the Filler field to the Vendor record, even though this field does not appear in the XML document; xml2flat will populate this field with spaces, since the first (and only) character of the LeadingFillerChars for this field is the space character. Also, the xml2flat application will automatically pad the value of the Description field in the Product records with space characters on the right as needed, so that the value of the Description field has the proper length.
In this example, our flat file contains a list of contacts. Each contact consists of a begin contact record followed by three optional records. The three optional records, which can appear in any order, are as follows:
The begin contact record consists of the string "[contact]".
The following are the contents of the contacts flat file:
[contact]
name=Nancy Magill
email=lil.magill@blackmountainhills.com
phone=(100) 555-9328
[contact]
email=molly.jones@oblada.com
name=Molly Jones
[contact]
phone=(200) 555-3249
name=Penny Lane
email=plane@bluesuburbanskies.com
This flat file is in the samples directory under the XML Convert home directory; the file name is contacts.txt.
Each line (i.e., record) in the flat file is terminated by the operating system's line separator.
The following XFlat schema describes the layout of the contacts flat file:
<?xml version='1.0'?>
<XFlat Name="contacts_schema" Description="Schema for contacts flat file">
<SequenceDef Name="contacts" Description="Contacts flat file">
<SequenceDef Name="contact"
MinOccur="0" MaxOccur="0">
<RecordDef
Name="begin_contact" MapToXml="No" RecSep="\N">
<FieldDef Name="label"
ValidValue="[contact]"
NullAllowed="No"
MapToXml="No"/>
</RecordDef>
<ChoiceDef
Name="choice_of_one" MapToXml="No"
MinOccur="0" MaxOccur="3">
<RecordDef Name="full_name" RecSep="\N" MapToXml="No">
<FieldDef Name="label"
ValidValue="name="
NullAllowed="No"
MapToXml="No"/>
<FieldDef Name="full_name"/>
</RecordDef>
<RecordDef Name="phone_num" RecSep="\N" MapToXml="No">
<FieldDef Name="label"
ValidValue="phone="
NullAllowed="No"
MapToXml="No"/>
<FieldDef Name="phone_number"/>
</RecordDef>
<RecordDef Name="email" RecSep="\N" MapToXml="No">
<FieldDef Name="label"
ValidValue="email="
NullAllowed="No"
MapToXml="No"/>
<FieldDef Name="email_address"/>
</RecordDef>
</ChoiceDef>
</SequenceDef>
</SequenceDef>
</XFlat>
This XFlat schema is in the samples directory under the XML Convert home directory; the file name is contacts.xfl.
Please note the following about this XFlat schema:
Using this schema, XML Convert will convert the flat file above into the following XML document:
<?xml version='1.0'?>
<contacts>
<contact>
<full_name>Nancy Magill</full_name>
<email_address>lil.magill@blackmountainhills.com</email_address>
<phone_number>(100)
555-9328</phone_number>
</contact>
<contact>
<email_address>molly.jones@oblada.com</email_address>
<full_name>Molly Jones</full_name>
</contact>
<contact>
<phone_number>(200)
555-3249</phone_number>
<full_name>Penny Lane</full_name>
<email_address>plane@bluesuburbanskies.com</email_address>
</contact>
</contacts>
This XML output file is in the samples directory under the XML Convert home directory; the file name is contacts.xml.
Using the contacts.xfl schema, the xml2flat application will convert the contacts.xml file into the original flat file (i.e., contacts.txt). Please note that xml2flat will automatically write the appropriate labels (e.g., "[contact]", "name=", etc.) to the flat file, even though the label fields are not mapped to XML.
|
Copyright © 1999 - 2007 Unidex, Inc. |