XML Convert 2.2

Invoking the flat2flat Application from the Command Line

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

NAME

flat2flat - converts a source flat file into a target flat file

SYNOPSIS

Using Sun's Java virtual machine:

java flat2flat [options] source_schema source_flat_file target_schema [target_flat_file]

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

jview flat2flat [options] source_schema source_flat_file target_schema [target_flat_file]

Using the Windows executable (flat2flat.exe):

flat2flat [options] source_schema source_flat_file target_schema [target_flat_file]

DESCRIPTION

The flat2flat application converts a source flat file into a target flat file. The conversion process is driven by a source XFlat schema and a target XFlat schema. The flat2flat application uses the source XFlat schema to convert the source flat file into an intermediary stream of SAX 1.0 document events; flat2flat uses the target XFlat schema to convert the intermediary stream of SAX 1.0 document events into the target flat file. The flat2flat application verifies that the source flat file data conforms to the source XFlat schema and that the intermediary stream of SAX 1.0 document events conforms to the target XFlat schema.

The following is a description of the command line arguments:

To run the flat2flat 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 flat2flat 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 flat2flat.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 flat2flat.exe Windows executable. However, it will be easier to invoke flat2flat.exe if you first update the PATH environment variable to include the path name of the directory in which flat2flat.exe resides. Please see the installation instructions for details about setting the PATH environment variable on your PC.

Invoking the flat2flat application to convert a source flat file into a target flat file is equivalent to invoking the flat2xml application to convert the source flat file into an XML document, and then invoking the xml2flat application to convert this XML document into the target flat file. However, please note that the flat2flat application does not create an intermediary XML document (either in memory or in a file). Also, if the target XFlat schema file is the same as the source XFlat schema file, then the flat2flat application will not read the target XFlat schema file; instead, it will assume that the target XFlat schema file is the same as the source XFlat schema file. Thus, it is more efficient to use the flat2flat application than it is to use the flat2xml application followed by the xml2flat application.

OPTIONS

flat2flat accepts the following options:

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

DIAGNOSTICS

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

If you get the following error message when you invoke the flat2flat 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 flat2flat : 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 flat2flat.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 flat2flat.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 flat2flat.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 flat2flat 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 flat2flat application encounters any errors (e.g., an invalid XFlat schema, the source flat file data does not conform to the source 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 source or target 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 source 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.

If the intermediary stream of SAX 1.0 document events does not conform to the target XFlat schema, then the conversion is aborted and an error message is displayed. The error message will contain a detailed description of the syntax error. Even though the stream of SAX document events is essentially an XML document, the flat2flat application can not provide the location of the error within the stream. Instead, the exception message contains the record number of the last record that was read from the source flat file (as well as the name of the source flat file).

Note that if a syntax error is found in the source flat file or in the intermediary stream of SAX document events, then the target flat file will contain part of the target flat file data. The partial flat file data is useful for troubleshooting the error.

We recommend that you use the flat2xml application when developing and debugging the source XFlat schema, so that you are not debugging the source XFlat schema and the target XFlat schema at the same time. We recommend that you use the xml2flat application when developing and debugging the target XFlat schema, since xml2flat will include the line number and column number of any errors in the XML input file.

EXIT CODES

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

0  -  Success.

1  -  Failure.

EXAMPLES

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

java flat2flat -s invoices_csv.xfl invoices_csv.txt invoices_ini.xfl invoices_ini.txt
return_code=$?
if [ $return_code -ne 0 ] ; then
    exit 1
fi

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

jview flat2flat invoices_csv.xfl invoices_csv.txt invoices_ini.xfl invoices_ini.txt
if not errorlevel 1 goto next
echo Aborting batch program.
goto end
:next
send_file.bat invoices_ini.txt
:end

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

flat2flat -s invoices_csv.xfl invoices_csv.txt invoices_ini.xfl invoices_ini.txt
if not errorlevel 1 goto next
echo Aborting batch program.
goto end
:next
send_file.bat invoices_ini.txt
:end