Usage guide

Concepts

A TERSE file is a container holding a small header (describing the source data set’s record format and length) and a 12-bit-code compressed payload produced by one of two dictionary codecs:

Method	Algorithm	Notes
SPACK	LZMW	Default; better compression. Header 0x05.
PACK	LZW	Slightly faster, larger output. Header 0x02.

Host files always store EBCDIC internally. Whether output is rendered as text (EBCDIC translated to ASCII, records as LF-terminated lines) or binary (the exact stored bytes) is chosen at decompression time — it is not recorded in the file.

Compressing

$ terse report.txt                # text mode: lines -> EBCDIC VB records
$ terse -b image.png              # binary mode: lossless FB LRECL-1
$ terse -m pack --recfm f -l 80 src.txt
$ terse --native payload.bin      # native SPACK container (4-byte header)
$ terse -c cp1047 unix.txt        # translate with a specific code page

Text mode splits the input into lines (CRLF is normalised to LF), translates ASCII to EBCDIC and stores one logical record per line — exactly what FTP in text mode would have uploaded to a data set. Binary mode stores the bytes untouched.

Decompressing

$ unterse DATA.TRS                # auto-detect text/binary content
$ unterse -b DATA.TRS             # exact bytes; VB records get RDWs
$ unterse -b --no-rdw DATA.TRS    # exact bytes, RDWs stripped
$ unterse -t -c cp037 DATA.TRS    # force text via code page cp037
$ unterse -i DATA.TRS             # header info only

In auto mode the decompressor decodes the payload, checks whether the record contents look like EBCDIC text, and renders text if so. Binary output written without an explicit output name gets a file extension chosen by content sniffing (libmagic), e.g. KENNEDY.TRS → KENNEDY.xls.

Interoperability notes

• Transfer .trs files to/from z/OS in binary mode. Host TERSE files are always a multiple of 1024 bytes; RECFM=FB LRECL=1024 data sets suit them well.

• For byte-exact round trips use binary mode: EBCDIC↔ASCII translation is lossy for some byte values, and text mode normalises line endings.

• Variable-format binary output is RDW-framed, matching z/OS FTP with SITE RDW; text output matches FTP with SITE TRAILINGBLANKS.

• AMATERSE’s own SPACK encoder writes an empty payload when the whole input fits in a single dictionary match (e.g. a one-byte file) — such files are unrecoverable everywhere, including on z/OS. TerseLib encodes these correctly.

Logging

The library is silent by default. Enable diagnostics with:

import terselib
terselib.enable_verbose_logging()   # or configure logger "terselib"

On the command line, pass -v (progress) or -vv (debug).