Binary to XML version 1.1, User Documentation


Table of Contents


Overview of Binary to XML

This program converts one or more MVS binary files to XML format based on its associated copybook by translating each record field as defined in the copybook into an XML element. The advantage of converting to XML format is that the document becomes industry standard and can be viewed over internet or intranet using a standard browser or ported into another system. This application provides an option to auto generate a report using a style sheet language, known as XSLT for transformation; when included in XML document, the document will be presented as an HTML report when open with a browser. If the report does not suit you, you can just change the generated XSLT to the format you want.

In mainframe enviroment, the reports are generally despatched to the users or viewed on the spool system. The reports are in plain text and not easily ported to another platform. Any changes, as simple as heading change, will involve coding change which is costly and time-consuming. If the data file, from which the report is generated, is converted to XML document, it can be transformed easily to a text-rich report by the script language like XSLT which is free and supported by most browsers.

This application can either run interatively or unattended (batch). With running in the batch mode, the transformation can be run in a regular basis, for example the mainframe transfers the binary file to the server by a scheduler and kicks off this application automatically.

Installing the software

Unzip the download file, jkje_Binary4xml_v1_1, to your pc. This deployment came with java runtime jre1.6 which is required to run this application, they are in folder jre1.6. The sceenshot below shows all the jkje applications folders, you may only have one of them. For binary to xml, they are in folder called binary4xml

The sub-folder, binary4xml, consists of the following files as shown in the screenshot below:

runBinary4xml.bat is the run command file which you double click to run this application interactively, while runBinary4xml(batch).bat is for running the application unattended (i.e. in the background). You may use the "sample binay file.bin" and "sample copybook.txt" to test this application.

FTP binary file and copybook to your pc

You can FTP the mainframe file to your pc via ISPF command shell. Under the top menu bar, click on actions and select "Receive File From Host"


Type in the input binary file name as host file and output file name as PC File, make sure you select binary in the dropdown list for "transfer type". Click "add to list" then click "receive" button to transfer


Please note: To check the transfer setting, Click "Options" button. You will see the screen below and with binary file transfer type, make sure "ascii", "crlf" and "append" are unchecked for "File Options"


Next transfer the copybook to pc with "text" transfer type and similarly click on "Options" button to check that the transfer settng for text with "ascii" and crlf" checked.

Running the application interactively

Double click on "runBinary4xml.bat and the following screen will be displayed


Click on "Add to List" for the first file to be converted. When the next screen apprears, enter the binary file and the output filename with extension ".xml". If you wish this application to auto-generate a HTML report, select an appropriate format from the dropdown list and enter the filename with file extension ".xsl" for "Output XSLT filename":

If input file record format is not fixed, please follow the instruction in the text box before you run this program. The full instruction in the text box for converting a variable record length file is as follows:

    If you select the Input Record Format as VB i.e when your input file has
    RECFM=V or VB, you need to read this because this type of file when FTPed to pc, 
    the RDW is striped off, even in binary transfer mode. In order for this program to 
    work properly, you need to reformat the original file with IEBGENER from type VB to 
    type U with IEBGENER. The sample jcl is listed as below (please note that 
    the input and output RECFM has been overrided with U in order to retain BDW). 
    After the job is run, FTP the outout file to pc in binary format as before. 

    //&SYSUID.VB JOB ABC,'CONVERT VB TO U',MSGCLASS=X,TIME=1440, 
    //         CLASS=Q,COND=(0,NE),RESTART=(*),
    //         REGION=4196K,NOTIFY=&SYSUID
    //COPY1    EXEC PGM=IEBGENER
    //SYSPRINT DD SYSOUT=*
    //SYSUT1   DD DSN=myinput.file,
    //         DCB=(BLKSIZE=32760,RECFM=U),DISP=SHR
    //SYSUT2   DD DSN=myoutput.file,
    //         DISP=(,CATLG,DELETE),
    //         SPACE=(TRK,(10,50),RLSE),
    //         DCB=(BLKSIZE=32760,RECFM=U)
    //SYSIN    DD DUMMY"




Click "next" button to continue to next screen as shown below.


Enter a copybook name for each layout in the binary file and click "Next" button


Click "Next" button to continue to next screen as follows:

Check the required fields to convert, enter the appropriate record id for the layout under column 3 "Enter Record ID". In this illustration, it is record id "01". If a field consists of sub-fields with data type other than text, like COMP or COMP-3, it is advisable to uncheck it and check the individual fields because a group field by default is considered having text data type.

If you need to change any input in the previous screens, click the "previous" button to go back.

Click "Next" button to the next screen


Click "DONE" button to saved to the list



If you have more file layout, click on "Add to List" and enter the next file as before. In this example, enter the same copybook filename but check the required fields for the second layout for record id "02"



Click "Next" button to continue to next screen as follows


Click "DONE" button and the second file will be saved on the list as follows


Click "Next" button to the next screen as shown when all record layouts are done


Click the button "Done" to return to the very first screen


To save the list, click "Save List" button and enter the file name to save to save the list. In this example the file name is called sample saved xml list



To run the appplication, click "Next" and the following screen appears



Click button "Load" to run the application and some messages will be displayed on the screen


Rerun with the previous saved entry

To re-run with the saved list, click "Open List" button to retrieve the previous entry, in this example the file name is "sample saved xml list"


Click "Open" to select the file and the screen will be refreshed with the new entry


Running the application in the background

Before you can run this program in the background (batch mode), you need to save your entry via "Running the application interactively", then edit "runBinary4xml (batch).bat" and change the second parameter to the list you have saved, in this example it is "sample saved xml list". Double click on "runBinary4xml (batch).bat and the following command prompt window will appear. When the application is finished running, the command prompt window will disappear automatically.


To verify your run is ok, view the text file with extension ".log" in the "logs" folder using Notepad or WordPad


Edit Run command

You can use the standard editor like Notepad or WordPad to edit the run command

The run command file, runBinary4xml.bat, contains the following line:
"..\jre1.6\bin\javaw" -Xms256m -Xmx1024m -classpath "binary4xml.jar;jkje.jar" binary4xml.ui.JBinary4xml log

For running in batch mode, add the saved list as second parameter, after the "log" parameter
"..\jre1.6\bin\javaw" -Xms256m -Xmx1024m -classpath "binary4xml.jar;jkje.jar" binary4xml.ui.JBinary4xml log "sample saved xml list"

The first parameter can either be "log" or "std", if "log" is specified, the traces are written to a log file otherwise are displayed on the standard output console

You may want to change the run command if you want to use a different version of java run time. This application came with jave run time version 1.6. You can update the java run time from time to time from Sun Microsystems for free. To use a different version, change "..\jre1.6\bin\javaw" to the new location of java run time on your pc.

If you encounter stack overflow error, you need to increase the stack size(or heap size) by changing the number next to "-Xmx". It is set to 1024m. Please note that the option "-Xms" is the initial heap size and is set to 256m.

Sample copybook and binary file

The sample copybook, "sample copybook.txt", is shown below:


The sample binary file, "sample binary file.bin", cannot be viewed by a normal text editor like Notepad, you need a hex editor like the one you can download from this site, hexEditor or EBCDIC Editor, to view the content:

Sample output files

The sample output xml file, "sample xml file.xml", is shown below when open with WordPad without transformation:


The sample output xsl file, "sample xsl file.xsl", is shown below when open with the internet browser:


The sample output xml file, "sample xml file.xml", is shown below when open with the internet browser with "sample xsl file.xsl" transformation. This is HTML table format report



The sample output xml file, "sample xml file.xml", is shown below when open with the internet browser with "sample xsl file 2.xsl" transformation. This is HTML normal report


Troubleshooting

If the conversion does not run properly, it may be due to the following reasons:

Please direct your queries to support@jkje.com.au


Limits of Liability

IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE


Copyright © 2011 JKJE Pty Ltd. All rights reserved.