Merge pull request #5 from andrew890/omp-master

Version 5: Add support for binary variable length records

Author: andrew890

.gitignore

@@ -1,3 +1,77 @@
+
+# Created by https://www.gitignore.io/api/java,maven,eclipse
+# Edit at https://www.gitignore.io/?templates=java,maven,eclipse
+
+### Eclipse ###
+.metadata
+bin/
+tmp/
+*.tmp
+*.bak
+*.swp
+*~.nib
+local.properties
+.settings/
+.loadpath
+.recommenders
+
+# External tool builders
+.externalToolBuilders/
+
+# Locally stored "Eclipse launch configurations"
+*.launch
+
+# PyDev specific (Python IDE for Eclipse)
+*.pydevproject
+
+# CDT-specific (C/C++ Development Tooling)
+.cproject
+
+# CDT- autotools
+.autotools
+
+# Java annotation processor (APT)
+.factorypath
+
+# PDT-specific (PHP Development Tools)
+.buildpath
+
+# sbteclipse plugin
+.target
+
+# Tern plugin
+.tern-project
+
+# TeXlipse plugin
+.texlipse
+
+# STS (Spring Tool Suite)
+.springBeans
+
+# Code Recommenders
+.recommenders/
+
+# Annotation Processing
+.apt_generated/
+
+# Scala IDE specific (Scala & Java development for Eclipse)
+.cache-main
+.scala_dependencies
+.worksheet
+
+### Eclipse Patch ###
+# Eclipse Core
+.project
+
+# JDT-specific (Eclipse Java Development Tools)
+.classpath
+
+# Annotation Processing
+.apt_generated
+
+.sts4-cache/
+
+### Java ###
 # Compiled class file
 *.class
 
@@ -21,3 +95,18 @@
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
+
+### Maven ###
+target/
+pom.xml.tag
+pom.xml.releaseBackup
+pom.xml.versionsBackup
+pom.xml.next
+release.properties
+dependency-reduced-pom.xml
+buildNumber.properties
+.mvn/timing.properties
+.mvn/wrapper/maven-wrapper.jar
+.flattened-pom.xml
+
+# End of https://www.gitignore.io/api/java,maven,eclipse

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "test-data"]
+	path = test-data
+	url = [email protected]:openmainframeproject/tersedecompress-testdata.git

README.md

@@ -1,66 +1,69 @@
 # tersedecompress
-TerseDecompress is a java program that can be used to decompress files which have been previously compressed on an IBM Mainframe using the TERSE / AMATERSE program (on IBM z/OS or IBM z/VM).
-
-
-
-Description:
-
-============
 
 TerseDecompress is a java program that can be used to decompress files
-
 which have been previously compressed on an IBM Mainframe
-
 using the TERSE / AMATERSE program (on IBM z/OS or IBM z/VM).
 
-Purpose & benefit:
-
-==================
+## Purpose & benefit ##
 
 As java programs can virtually run on any platform / operating system
-
 with a JVM, this java decompression program can be very useful if you
-
 don't have access to an IBM mainframe but need to analyze or process a
-
 file which had been compressed on a IBM mainframe using TERSE on IBM z/OS.
-
 With this java version of TerseDecompress, you can decompress those tersed
-
 IBM Mainframe files on any workstation or laptop etc. that supports Java.
 
-How to run it:
+## Updates ##
 
-==============
+**Version 5: March 2021**
 
-TerseDecompress will uncompress a file that was compressed using the TERSE
+- Support for variable length binary records. Variable length records processed in binary mode will be prefixed with a 4 byte field in the same format as the IBM RDW i.e. 2 byte record length field (including RDW length, big-endian) followed by 2 bytes of zeros.
 
-program on IBM z/OS.
+## How to run it ##
 
-For execution, TerseDecompress needs a JVM runtime environment
+For execution, TerseDecompress needs a JVM runtime environment.
 
-Usage: "TerseDecompress [-b]"
+Usage:
 
- Default mode is text mode, which will attempt ebcdic -> ASCII conversion
+```java -jar tersedecompress-5.0.0.jar [-b] tersed-file output-file```
 
- The -b flag turns on binary mode, no conversion will be attempted
+Default mode is text mode, which will attempt EBCDIC -> ASCII conversion.
 
-How to build it:
+The **-b** flag turns on binary mode, no conversion will be attempted.
 
-================
+**Recommendation:** Use binary mode if possible. EBCDIC->ASCII conversion is not a lossless process, unless the data strictly contains only characters that are common to both code pages used for the translation, **and** the original data does not contain line ending characters.  
 
-For compiling the java source code, a JDK is required
+## How to build it ##
 
-Build command: "javac TerseDecompress.java"
+To build tersedecompress you need the Java JDK and Apache Maven.
 
-How to report problems and get support/help:
+In the project directory (the directory containing **pom.xml**):
 
-============================================
+```mvn clean package```
 
-If you have a problem / need help with TerseDecompress.java, please create a GitHub issue.
+## Unit Tests ##
+
+The project contains unit tests to verify that the decompression is correct.
+
+Due to the size of the test data, it is stored in a separate git repository and referenced via a submodule. The test data is not required to build tersedecompress, unless you want to run the unit tests.
+
+The test data can be found here:
+[https://github.com/openmainframeproject/tersedecompress-testdata](https://github.com/openmainframeproject/tersedecompress-testdata)
+
+Descriptions of the data are here:
+[https://github.com/openmainframeproject/tersedecompress-testdata/tree/master/tests](https://github.com/openmainframeproject/tersedecompress-testdata/tree/master/tests)
 
-You can also send an email to: [email protected] or contact us on Slack at https://slack.openmainframeproject.org channel #tersedecompress
 
-Please do not send code changes, but explain in a mail
+### Building with Unit Tests ###
+
+1. Initialize (download) the submodule containing the test data:
+```git submodule update --init```
+2. Build with unit tests:
+```mvn -DskipTests=false clean package```
+
+## How to report problems and get support/help ##
+
+If you have a problem / need help with TerseDecompress.java, please create a GitHub issue.
+
+There is also a Slack channel: [https://slack.openmainframeproject.org](https://slack.openmainframeproject.org) channel #tersedecompress
 
-what you want TerseDecompress to do.