XML Convert 2.2

Invoking the flat2xt Application from the Command Line

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

NAME

flat2xt – invokes XT to transform a flat file as if it was an XML document

SYNOPSIS

Using Sun's Java virtual machine:

java flat2xt [options] xflat_schema source_flat_file stylesheet [result] [name=value ...]

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

jview flat2xt [options] xflat_schema source_flat_file stylesheet [result] [name=value ...]

Using the Windows executable (flat2xt.exe):

flat2xt [options] xflat_schema source_flat_file stylesheet [result] [name=value ...]

DESCRIPTION

The flat2xt application uses an XFlat schema to convert flat file data into a stream of SAX document events that are processed by XT. Thus, the flat2xt application invokes XT to transform flat file data in the same way that XT transforms an XML document. The flat2xt application can be used to convert a flat file into XML, HTML or text, even if the result document does not conform with the XFlat schema that describes the layout of the source flat file.

The following is a description of the command line arguments:

• xflat_schema - The name of the XFlat schema file. The XFlat schema describes the structure of the source flat file. This argument is mandatory.
• source_flat_file - The name of the flat file that will be converted into a stream of SAX 1.0 document events that are processed by XT. This argument is mandatory.
• stylesheet - The name of the XSLT stylesheet file. This argument is mandatory.
• result - The name of the results file, to which XT will write the results of the transformation. The result argument is optional. If it is provided, then the results will be written to the specified file. If it is not provided, then the results will be written to standard output. The name of the results file must not contain an equal sign ("="); if the file name does contain an equal sign, then the flat2xt application will treat the result argument as a name=value argument.
• name=value - These arguments specify parameters that are passed to the XSLT stylesheet. Each name=value argument specifies a parameter name and the corresponding parameter value. A name=value argument is ignored unless the XSLT stylesheet contains a corresponding top-level xsl:param element. The name=value arguments are optional. If any name=value arguments are specified, then they must appear at the end of the command line (i.e., they must follow the stylesheet argument and the result argument, if any).

If you specify the com.unidex.xflat.XtFlatFileBuilder class as the output method of your XSLT stylesheet, then the flat2xt application will convert the source flat file into a target flat file (i.e., XT will write flat file data to the result file). In this case, flat2xt will convert the source flat file data into a stream of SAX 1.0 document events, and XT will transform this stream into a result tree. XT will pass the result tree to the com.unidex.xflat.XtFlatFileBuilder class as a stream of SAX 1.0 document events; the XtFlatFileBuilder class will convert this stream into the target flat file data and write this data to the result file. For more information about this feature, see the documentation for the com.unidex.xflat.XtFlatFileBuilder class.

NOTE: Before you can run the flat2xt application, you must first have XT installed on your computer. XML Convert does not include XT.

To run the flat2xt application, you must have XT and 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 flat2xt application using the java or jview command, you must first update your CLASSPATH environment variable, so that it includes the xflat.jar file and the xt.jar file, which is available at http://www.jclark.com/xml/xt.html. Please see the installation instructions for details about setting the CLASSPATH environment variable.

The flat2xt.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.

To run the flat2xt.exe Windows executable, you must first update your CLASSPATH environment variable, so that it includes the xt.jar file. Also, it will be easier to invoke flat2xt.exe if you first update the PATH environment variable to include the path name of the directory in which flat2xt.exe resides. Please see the installation instructions for details about setting the PATH environment variable on your PC.

OPTIONS

flat2xt accepts the following options:

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

DIAGNOSTICS

If you get the following error message when you invoke the flat2xt 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: flat2xt

If you get the following error message when you invoke the flat2xt 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 flat2xt : The system cannot find the file specified.

If you get the following error message when you invoke the flat2xt application, then you have not installed XT on your computer or your CLASSPATH environment variable does not include the xt.jar file:

java.lang.NoClassDefFoundError: com/jclark/xsl/sax/XSLProcessorImpl

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 flat2xt.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 flat2xt.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 flat2xt.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 flat2xt 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 flat2xt 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 name of the XFlat schema file
• the line number
• the column number

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 source flat file, then the error message will include the following information about the location of the error:

• the name of the source flat file
• the record number
• the column number with the record
• the record offset within the file

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 source flat file, then the result file will be empty, since XT reads the entire source file data into memory before it writes any data to the result file.

EXIT CODES

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

0  –  Success.

1  –  Failure.

EXAMPLES

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

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

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

jview flat2xt -s invoices.xfl invoices.txt invoices.xsl invoices.html
if not errorlevel 1 goto next
echo Aborting batch program.
goto end
:next
send_doc.bat invoices.html
:end

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

flat2xt -s invoices.xfl invoices.txt invoices.xsl invoices.csv
if not errorlevel 1 goto next
echo Aborting batch program.
goto end
:next
send_file.bat invoices.csv
:end