XML Convert 2.2

What's New in Version 2.2

This page, which describes the changes in XML Convert 2.2, is organized as follows:

• New Features
• Bug Fixes
• Minor Changes

New Features

The new features of XML Convert 2.2 are as follows:

• In the previous version of XML Convert, a field had to be fixed-length and/or the field had to be delimited with a field separator or the record separator. XML Convert 2.2 supports variable-length, non-delimited fields. The FieldDef elements for such fields must specify a non-null value for the ValidChars, InvalidChars or ValidValue attribute, so that XML Convert will be able to find the end of such fields. See the Fields are Separated By One or More Spaces and/or Tabs section of the Examples page for an example of a flat file that contains variable-length, non-delimited fields; in this example, the FieldDef elements for the variable-length, non-delimited fields include the ValidChars or InvalidChars attribute, so that XML Convert can find the end of these fields. Also, see the File Containing a Group of Unordered Records section of the XFlat Language page for an example of an XFlat schema, in which the FieldDef elements for the variable-length, non-delimited fields include the ValidValue attribute, so that XML Convert can find the end of these fields.
• Added support for non-printable characters (e.g., control characters). A character that is illegal in XML documents can now be specified in an XFlat schema by encoding it using printable characters. For example, the Unicode x1A character (i.e., the control-Z character) can be encoded as "\#x1A;". See the Handling Special Characters section of the XFlat Language page for more information.
• The flat file parser in XML Convert 2.2 is available as a SAX 2.0 driver, which uses an XFlat schema to parse flat file data and convert it into a stream of SAX 2.0 document events. The com.unidex.xflat.Sax2FlatFileParser class is an implementation of the SAX 2.0 org.xml.sax.XMLReader interface. (In other words, it's a SAX 2.0 driver for the XML Convert flat file parser.)
• XML Convert now includes a SAX 2.0 content handler that uses an XFlat schema to convert a stream of SAX 2.0 document events into flat file data. The com.unidex.xflat.Sax2FlatFileBuilder class is an implementation of the org.xml.sax.ContentHandler interface. Loosely speaking, the Sax2FlatFileBuilder class converts an XML document into flat file data, the layout of which is specified by an XFlat schema. More precisely, the class converts a stream of SAX 2.0 document events into flat file data. The class also verifies that the SAX document events conform to the XFlat schema.
• Added the Standalone attribute to the XFlat language. When converting flat files to XML, this attribute can be used to place a standalone document declaration in the XML declaration of the XML output file. Please see the description of the Standalone attribute in the XFlat Language page for more details.
• Added the OmitXmlDeclaration attribute to the XFlat language. When converting flat files to XML, this attribute can be used to omit the XML declaration from the XML output file. Please see the description of the OmitXmlDeclaration attribute in the XFlat Language page for more details.
• Updated the xflat.dtd file in the xmlconvert\samples folder to include the Standalone and OmitXmlDeclaration attributes.

Bug Fixes

The bug fixes in XML Convert 2.2 are as follows:

• The previous version of XML Convert validated a field value against the ValidValue attribute when the field value is null; it does this even when the NullAllowed attribute for the field is set to "Yes". (The previous version of XML Convert does not validate a field value against the MinValue, MaxValue, DataType, ValidChars and InvalidChars attributes when the field value is null.)

  In XML Convert 2.2, if a field value is null, then the field value is not validated against the ValidValue attribute. Please note that this change may require you to update some of your existing XFlat schemas.

  Specifically, if you have an XFlat schema in which a FieldDef element includes the ValidValue attribute and the minimum field length for the field is zero, then you should add the NullAllowed="No" attribute to this FieldDef element if you want the flat2xml application of XML Convert 2.2 to report an error when the field value is null. (Note that the default value of the MinFieldLength attribute is zero.)
• Fixed an array-index-out-of-bounds bug. The previous version of XML Convert would fail with an array-index-out-of-bounds exception when it encountered a RecordDef element that had no subelements. XML Convert 2.2 displays a helpful error message when it encounters a RecordDef element that has no subelements.
• Fixed an array-index-out-of-bounds bug. The xml2flat application of the previous version of XML Convert would fail with an array-index-out-of-bounds exception when the text content of an XML element/attribute that maps to a field was longer than the maximum field length for the field. The xml2flat application in XML Convert 2.2 displays a helpful error message when it encounters this type of error.
• When generating a CSV (Comma Separated Value) file, in which the value of the last field of a record requires enclosing quotes, the xml2flat application of the previous version of XML Convert does not enclose the field value with quotes when the field value contains the field separator that is defined within the RecordDef element. This bug has been fixed in XML Convert 2.2.
• Fixed a bug that would cause the flat2xml and flat2flat applications to skip data in the flat file under certain rare circumstances.
• Fixed a bug that would cause the flat2xml and flat2flat applications to falsely report an error under certain rare circumstances.
• Fixed a bug that would cause the xml2flat application to omit a record from the output file under certain circumstances. This occurred when the record and its fields were not mapped to XML and the record would be the last record in the flat file.
• Fixed a problem in an error message that was displayed by the xml2flat application. When the value of a field was not compatible with the field's data type, the error message was missing the name of the field.
• Fixed a problem in an error message that was displayed by the flat2xml application of the previous version of XML Convert. When the first record in the file was mandatory and flat2xml could not find the record, the error message incorrectly stated that the record number was 0 and the character offset was -1.
• Fixed a problem in an error message that was displayed by the flat2xml application of the previous version of XML Convert. When the application displayed an error message that described a bad field within the first record of the file, the offset of the bad field was not included in the error message.
• Fixed the declarations of the MapToXml attribute for the SequenceDef, ChoiceDef and RecordDef elements in the xflat.dtd file in the xmlconvert\samples folder. Prior to being fixed, these declarations had mistakenly allowed the MapToXml attribute to have values other than "No" and "Element".

Minor Changes

XML Convert 2.2 includes the following minor changes:

• Improved the wording of some error messages.
• The comments.xfl, contacts.xfl, contacts_crlf.xfl, contacts_dtd.xfl and employees_header.xfl files in the xmlconvert\samples folder were updated. Specifically, the following changes were made to the FieldDef elements for the label and column heading fields:
  • The MinFieldLength and MaxFieldLength attributes were removed, since XML Convert can now determine where a field ends using the ValidValue attribute.
  • The NullAllowed="No" attribute was added, since the labels are mandatory and since a null field value is no longer validated against the ValidValue attribute.
• Added a sample XFlat schema for a flat file that may contain an optional control-Z character at the end of the file. Please see the Optional Control-Z Character at the End of File section of the Examples page for more details.
• Added a sample XFlat schema for a flat file in which fields are separated by one or more spaces and/or tabs. Please see the Fields are Separated By One or More Spaces and/or Tabs section of the Examples page for more details.
• Added a sample XFlat schema for a flat file in which the last record in the file may or may not be terminated by the record separator. Please see the Last Record May or May Not Be Terminated With a Record Separator section of the Examples page for more details.
• Added a generic XFlat schema that can be used to convert any CSV file into XML. Please see the Generic XFlat Schema for CSV Files section of the Examples page for more details.
• Added a generic XFlat schema that can be used to convert a wide variety of tab-delimited flat files into XML. Please see the Generic XFlat Schema for Tab-Delimited Files section of the Examples page for more details.
• Added a generic XFlat schema that can be used to convert a Windows Configuration Settings file (e.g., an INI file, such as win.ini) into XML. Please see the Generic XFlat Schema for Windows Configuration Settings Files section of the Examples page for more details.
• Added an XSLT stylesheet that generates XFlat schemas for delimited flat files. Please see the An XSLT Stylesheet that Generates XFlat Schemas for Delimited Flat Files section of the Examples page for more details.
• Added a sample XFlat schema for a flat file that contains a batch of purchase orders. Please see the Batch of Purchase Orders section of the Examples page for more details.
• Added a sample XFlat schema that illustrates the ChoiceDef element. Please see the ChoiceDef Example section of the Examples page for more details.
• The catalog.xsl and employees_goodbad.xsl files in the xmlconvert\samples folder were updated, in order to make them compliant with XSLT 1.0.
• The register.xfl and register.txt files in the xmlconvert\samples folder were updated. The flat file now contains two pages of check register entries. The XFlat schema has some minor improvements.
• Fixed a minor bug in the employees.xfl, employees_dtd.xfl, employees_goodbad.xfl, employees_header.xfl and enrollment_csv.xfl files in the xmlconvert\samples folder. The MaxFieldLength values now account for the optional quotes that may enclose the fields.
• Added the Invoking XML Convert from SAXON page to the user documentation. Also added new sections to the Examples page illustrating how XML Convert can be invoked from SAXON.
• Fixed the outdated links in the Installation Steps page.
• Updated the xflat.dtd file in the xmlconvert\samples folder, so that it no longer uses parameter entities. A user's XML editor was not able to handle the parameter entities in the xflat.dtd file that was included in the previous version of XML Convert.
• Deleted the declaration of the RecId attribute from the xflat.dtd file in the xmlconvert\samples folder. The RecId attribute was deprecated in the previous version of XML Convert.