XML Convert 2.2

Installation Steps

Please complete the following steps to install XML Convert 2.2 on your computer.

Step 1. Extract the Contents of the ZIP File

Using WinZip (version 7.0 or higher), extract (i.e., unzip) the contents of xmlconvert_2_2.zip. If you don't have WinZip installed on your computer, then you can download an evaluation version from http://www.winzip.com/.

When you unzip the xmlconvert_2_2.zip file, WinZip will create the xmlconvert folder, which will contain the following subfolders:

The xmlconvert folder will also contain the license agreement and the following Windows executables:

In order to run these executables, you must have the Microsoft Java Virtual Machine (VM) installed on your PC. The Microsoft Java VM came with versions 4.x and 5.x of Internet Explorer (IE). So, if you already have IE 4.x or 5.x on your machine, then you should also have the Microsoft Java VM on your machine. The Microsoft Java VM on your machine must support Java 1.1.7 or higher.

The docs subfolder contains the XML Convert documentation. The index.htm file in the docs subfolder contains the table of contents for the XML Convert documentation.

The jars subfolder contains the xflat.jar file, which includes the classes of XML Convert 2.2, James Clark's XP 0.5 and SAX 2.0. XML Convert 2.2 has been tested with only version 0.5 of XP. XML Convert 2.2 has not been tested with any other version of XP nor with any other XML parser. The xflat.jar file does not include the classes of James Clark's XT nor the classes of the SAXON XSLT processor.

The samples subfolder contains sample XFlat schemas, flat files, XML documents and XSLT stylesheets. It also contains sample Java programs that invoke XML Convert.

If you plan to run XML Convert on a computer that does not run MS-DOS or Windows (e.g., if you plan to run it on a Unix or Macintosh computer), then we recommend that you unzip the xmlconvert_2_2.zip file on a Windows computer and then transfer the extracted files to the non-Windows computer (i.e., to the computer where you plan to run XML Convert). In this case, be sure to transfer the text files in such a manner that the line separators in the text files are converted from CR/LF to the line separator used by your non-Windows computer. All the XML Convert files, with the exception of the JAR file (i.e., xflat.jar) and the Windows executables, are text files. Also, be sure to transfer the JAR file to your non-Windows computer using "binary mode", so that the contents of the JAR file is not modified during the transfer. If you unzip the xmlconvert_2_2.zip file on a non-Windows computer, then you won't be able to use the sample XFlat schemas and flat files, unless you modify the XFlat schemas or flat files, so that the sample XFlat schemas specify record separators that are consistent with the record separators in the sample flat files.

Step 2. Confirm that You Have a Java Virtual Machine

In order to run XML Convert 2.2 on your computer, you must have a Java virtual machine (version 1.1.7 or higher) installed on your computer. XML Convert is a Java application that uses some of the Java classes and methods that were introduced in Java 1.1.7.

If Microsoft's Internet Explorer 4.x or 5.x is installed on your PC, then the Microsoft Java Virtual Machine, which is invoked at the MS-DOS command prompt using the jview command, should be installed on your PC. You can confirm that you have the Microsoft Java Virtual Machine installed on your PC by typing the jview/? command at the MS-DOS command prompt. If the jview/? command displays usage information (e.g., "... Usage: JView [options] <classname> [arguments] ..."), then the Microsoft Java Virtual Machine is installed on your PC. If the jview/? command fails with an error message (e.g., "Bad command or file name"), then you probably don't have the Microsoft Java Virtual Machine installed on your PC.

If you do not have a Java virtual machine (version 1.1.7 or higher) on your computer, then you can download and install one of the following:

Step 3. Update the CLASSPATH and/or PATH Variables

If you plan to invoke XML Convert using the Windows executables (flat2xml.exe, xml2flat.exe, flat2flat.exe and flat2xt.exe), then you may want to update the PATH environment variable to include the path name of the directory in which the Windows executables reside. If the Windows executables are on your PC in the C:\xmlconvert folder, then the value of your PATH environment variable should include the following:

    C:\xmlconvert

On Windows 95 and 98, the PATH variable is set in the C:\autoexec.bat file. On Windows NT, Windows 2000 and Windows XP, the PATH environment variable is set via the "System" control panel (i.e., Start/Settings/Control Panel/System).

If you plan to invoke XML Convert using the flat2xml.exe, xml2flat.exe, flat2flat.exe or flat2xt.exe executables and don't plan to invoke it using the java or jview command, then you do not need to update your CLASSPATH environment variable to include the xflat.jar file. However, if you plan to invoke the flat2xt.exe program, then you need to have James Clark's XT installed on your computer and you need to update your CLASSPATH environment variable to include full path name of the xt.jar file (i.e., James Clark's XT jar file).

If you plan to invoke the flat2xml, xml2flat, flat2flat or flat2xt applications using the java or jview command, or if you plan to invoke XML Convert from XT or from your Java application, then you should update the value of the CLASSPATH environment variable, so that it includes the full path name of the xflat.jar file. This file is located in the jars subfolder in the xmlconvert folder.

If the xflat.jar file is on your PC in the C:\xmlconvert\jars folder, then the value of your CLASSPATH environment variable must include the following:

    C:\xmlconvert\jars\xflat.jar

On Windows 95 and 98, you set the CLASSPATH variable in the C:\autoexec.bat file using a command such as the following:

    set CLASSPATH=C:\xmlconvert\jars\xflat.jar

On Windows NT, Windows 2000 and Windows XP, you set the CLASSPATH variable via the "System" control panel (i.e., Start/Settings/Control Panel/System).

If the xflat.jar file is on your Unix machine in the /jars directory, then the value of your CLASSPATH environment variable must include the following:

    /jars/xflat.jar

On Unix, you set (i.e., export) the CLASSPATH variable in your $HOME/.profile file using a command such as the following:

    CLASSPATH=/jars/xflat.jar; export CLASSPATH

Step 4. Verify that XML Convert Runs on Your System

You can verify that XML Convert will run on your system by running the xml2flat application to convert one of the sample XML files that resides in the samples subfolder. Let's assume that your samples subfolder is on your PC in the C:\xmlconvert folder.

If you are running XML Convert on a Windows 95/98/Me/NT/2000/XP PC, then you can run the xml2flat.exe program by issuing the following commands at the MS-DOS command prompt:

cd C:\xmlconvert\samples
..\xml2flat contacts.xfl contacts.xml out.txt

If you use Sun's Java Virtual Machine on your PC and have updated your CLASSPATH environment variable per the instructions in step 3, then you can run the following commands from the MS-DOS command prompt:

cd C:\xmlconvert\samples
java xml2flat contacts.xfl contacts.xml out.txt

If you use Microsoft's Java Virtual Machine on your PC and have updated your CLASSPATH environment variable per the instructions in step 3, then you can run the following commands from the MS-DOS command prompt:

cd C:\xmlconvert\samples
jview xml2flat contacts.xfl contacts.xml out.txt

When xml2flat finishes, make sure that you didn't get any error messages and that the contents of the out.txt file are the same as the contents of the contacts.txt file. If you get an error message, then please refer to the DIAGNOSTICS section of the xml2flat manual page.