XML Convert 2.2

Invoking the flat2xml Application from the Command Line

This page describes how to invoke the flat2xml application from the command line. XML Convert includes a public Java class, named flat2xml, that converts a flat file into an XML document. The flat2xml class contains a public static method named main(), so that the class can be invoked from the command line. The flat2xml application is also available as a Windows executable (flat2xml.exe) that is invoked from the MS-DOS command line.

NAME

flat2xml – converts a flat file into XML

SYNOPSIS

Using Sun's Java virtual machine:

java flat2xml [options] schema_file flat_file [xml_file]

Using Microsoft's Java virtual machine, which is included with Internet Explorer 4.0 and 5.0:

jview flat2xml [options] schema_file flat_file [xml_file]

Using the Windows executable (flat2xml.exe):

flat2xml [options] schema_file flat_file [xml_file]

DESCRIPTION

The flat2xml application converts a flat file into an XML document. The conversion process is driven by an XFlat schema. The flat2xml application verifies that the flat file data conforms to the XFlat schema.

The following is a description of the command line arguments:

If the XML output contains markup characters in an attribute value or in the text content of an element, then the flat2xml application will replace each of these markup characters with the corresponding predefined entity as necessary. For example, let's say that the XML output contains an element named "group" and the value of the group element is "Tom & Jerry"; in this case, the flat2xml application would write this XML element as:

<group>Tom &amp; Jerry</group>

Note that XML documents are not allowed to contain binary data, such as control characters. In general, an XML document must contain only printable characters (including whitespace characters). If the value of a field in your flat file contains a non-printable character and this field is mapped to an XML element or attribute, such that the non-printable character is not trimmed via the LeadingFillerChars or TrailingFillerChars attribute, then the XML output of flat2xml will include the non-printable character.

For information about how to specify a non-printable character in the value of the LeadingFillerChars and TrailingFillerChars attributes, please see the Handling Special Characters section of the XFlat Language page.

To run the flat2xml application, you must have a Java 1.1.7 (or higher) virtual machine installed on your computer. See the installation instructions for information about installing a Java virtual machine on your computer.

To run the flat2xml application using the java or jview command, you must first update your CLASSPATH environment variable, so that it includes the xflat.jar file. Please see the installation instructions for details about setting the CLASSPATH environment variable.

The flat2xml.exe program will run on a Windows 95/98/Me/NT/2000/XP PC on which the Microsoft Java Virtual Machine (supporting Java 1.1.7 or higher) has been installed. See the installation instructions for information about installing the Microsoft Java virtual machine on your PC.

You do not need to update your CLASSPATH environment variable in order to invoke the flat2xml.exe Windows executable. However, it will be easier to invoke flat2xml.exe if you first update the PATH environment variable to include the path name of the directory in which flat2xml.exe resides. Please see the installation instructions for details about setting the PATH environment variable on your PC.

OPTIONS

flat2xml accepts the following options:

-s    Suppress the startup message that flat2xml displays to standard output.

DIAGNOSTICS

If you get the following error message when you invoke the flat2xml application using Sun's java command, then your CLASSPATH environment variable probably doesn't contain the path name of the xflat.jar file:

Exception in thread "main" java.lang.NoClassDefFoundError: flat2xml

If you get the following error message when you invoke the flat2xml application using Microsoft's jview command, then your CLASSPATH environment variable probably doesn't contain the path name of the xflat.jar file:

ERROR: Could not execute flat2xml : The system cannot find the file specified.

For information about setting your CLASSPATH environment variable, please see the installation instructions.

If you get the "Bad command or file name" error message when you try to invoke the flat2xml.exe program, then you probably did not specify the correct path name of the executable, or you probably did not update your PATH environment variable to include the path name of the directory in which the executable resides.

If you get the following error message when you try to invoke the flat2xml.exe program, then you probably don't have the Microsoft Java Virtual Machine installed on your PC.

Error Starting Program
A required .DLL file, MSVCRT.DLL, was not found.

To confirm that you don't have the Microsoft Java Virtual Machine installed on your PC, type the "jview/?" command at the MS-DOS command prompt. If the command fails with an error message of "Bad command or file name", then you probably don't have the Microsoft Java Virtual Machine installed on your PC. See the installation instructions for information about installing the Microsoft Java Virtual Machine on your PC.

If you get the following error message when you try to invoke the flat2xml.exe program, then you probably have an old version of the Microsoft Java Virtual Machine that does not support Java 1.1.7 or higher.

The Microsoft virtual machine does not support this application.
No such interface supported

In this case, see the installation instructions for information about installing a version of the Microsoft Java Virtual Machine that supports Java 1.1.7.

If you get an error message stating that a standard Java class (e.g., java.io.FileReader) or method could not be found, then you are probably running a pre-1.1.7 version of the Java virtual machine. In this case, you will need to upgrade to a virtual machine that supports Java 1.1.7 or higher. The flat2xml application uses some of the classes and methods that were introduced in Java 1.1.7. See the installation instructions for information about installing a Java virtual machine that supports Java 1.1.7 or higher.

If the flat2xml application encounters any errors (e.g., an invalid XFlat schema, the flat file data does not conform to the XFlat schema, etc.), then the conversion is aborted and an error message is written to standard error. The error message will include a detailed description of the error.

If an error is found in the XFlat schema, then the error message will include the following information about the location of the error:

The file name is displayed as a system identifier (e.g., file:/c:/invoices.xfl). The line number of the first line in the file is one. The column number of the first character in a line is one.

If an error is found in the flat file, then the error message will include the following information about the location of the error:

The file name is displayed as a system identifier (e.g., file:/c:/invoices.txt). The record number of the first record is one. The column number of the first character in a record is one. If the first record in a file is 80 bytes in length, then the record offset of the second record is 81.

Note that if an error is found in the flat file, then the XML output will contain a partial XML document. The partial document is useful for troubleshooting the error, especially if the XFlat schema maps all the fields, records, sequences and choices to XML.

EXIT CODES

The flat2xml application will exit with one of the following two exit codes:

0  –  Success.

1  –  Failure.

EXAMPLES

The following ksh script invokes the flat2xml application using Sun's java command:

java flat2xml -s invoices.xfl invoices.txt invoices.xml
return_code=$?
if [ $return_code -ne 0 ] ; then
    exit 1
fi

The following MS-DOS batch program invokes the flat2xml application using Microsoft's jview command:

jview flat2xml -s employees.xfl employees.txt employees.xml
if not errorlevel 1 goto next
echo Aborting batch program.
goto end
:next
send_xml.bat employees.xml
:end

The following MS-DOS batch program invokes the flat2xml.exe Windows executable:

flat2xml -s employees.xfl employees.txt employees.xml
if not errorlevel 1 goto next
echo Aborting batch program.
goto end
:next
send_xml.bat employees.xml
:end