DOS ain't dead

---=---=---=---=---
NJPL1I00PDS100000000 = SFDU_LABEL
RECORD_TYPE = STREAM
OBJECT = TEXT
NOTE = "Description of software provided with the
Voyager CD-ROM set."
END_OBJECT
END

Decompression Software
----------------------

The SOFTWARE directory contains software source code files for the
decompression of compressed image files. In order to make the software
available to a wide community of users, different versions of the
decompression software exist in VAX/VMS FORTRAN, IBM/PC FORTRAN,
C-language, and VAX/VMS Assembler language. Some modification of these
routines may be required in order to adapt the software to a particular
computer and operating system. This directory also contains a sample
utility program to read the image index flat table (IMGINDEX.FOR).

These routines assume that the user can access the compressed image
files through normal system input/output (I/O) commands. Otherwise
special utilities may be needed to move image files from the CD-ROM
to the user's fixed-disk prior to executing the decompression programs.

Information describing the compressed image files can be found in the
VOLINFO.TXT file located in the DOCUMENT directory. The document
describes the organization of the CD-ROM. It provides information on how
to access files stored on a CD-ROM, and gives details on the format and
contents of the image files and their supporting supplemental files.

The decompression software is supplied as callable subroutine
modules for use with existing applications; as source code for
stand-alone programs which can be copied to the users
host-computer, compiled, linked and executed; and as executables
for IBM PC and VAX users. The practice of distributing software on
read-only archival media is known to be risky. The executables
are being placed on this disk for evaluation and no guarantee is
made that they will work in specific computer configurations.

SUBROUTINES

The decompression software has two subroutines to be called by an
application program. Typically, an application program will open an
image file, read the image data from the file, call the decompression
routines to restore the image, and then transfer the image to the
appropriate output media or display device.

The software has two top-level subroutines, DECMPINIT and DECOMPRESS.
They provide a common base from which to call the processing
routines. DECMPINIT builds the Huffman tree from the encoding histogram
and is called only once per image. DECOMPRESS processes one compressed
input line per call and returns the line completely restored. These
routines are fully documented. Consult the source code files for a full
explanation of their use.

A Programmer's View
-------------------

From the programmer's view point, the calling sequence of these routines
are as follows:

1) First, extract the encoding histogram from the image file. (Consult
VOLINFO.TXT document for details). The encoding histogram contains
511 32-bit elements. Note, the encoding histogram is configured
in "least significant byte first" order. This is the order for integer
values used by VAX and IBM PC computer systems. Users of other
computer architectures (IBM Mainframes, Macintosh, SUN, and Apollo)
will need to swap the byte pairs 1 and 4, and 2 and 3. (Example,
hexadecimal value AA BB CC DD becomes DD CC BB AA.)

2) Pass the encoding histogram to the DECMPINIT routine to initialize
the Huffman coding tree.

3) After the initialization call, read compressed image lines, one at
at a time, from the image file and pass the lines to the DECOMPRESS
routine for restoration. After the image line has been restored,
transfer the line to an output image file or display screen.


FORTRAN Considerations
-----------------------

The VAX/VMS FORTRAN version of the decompression software resides in the
DECOMP.FOR file. This file contains the DECMPINIT and DECOMPRESS
routines, and the internal subroutines DCMPRS, HUFF_TREE, and SORT_FREQ.
A version of these routines for Sun workstations is in file DECOMPS.FOR.
Additionally, for VAX/VMS users there is an assembler language version
of the DCMPRS routine located in the file DCMPRS.MAR. Use of this
routine will improve the performance of the decompression software by a
factor of two. The VAX/VMS assembler routine will only work with the
FORTRAN version of the decompression software. There is also a source
file called BTEST.FOR. This file contains a FORTRAN version of the
VAX/VMS BTEST intrinsic function. Use this routine only if you are not
running under the VAX/VMS environment. Finally, there is a main
program, located in the DETEST.FOR file, which tests the performance
of the decompression software. If you are adapting the software to your
particular hardware configuration, then this program will be useful for
testing the software. A summary of the FORTRAN related files is
presented below.

DECOMP.FOR - VAX/VMS FORTRAN versions of the decompression
software. Contains routines DECMPINIT, DECOMPRESS, and
working routines SORT_FREQ, HUFF_TREE, and DCMPRS.
DCMPRS.MAR - VAX/VMS macro assembler routine which can replace
the FORTRAN version of the DCMPRS subroutine.
BTEST.FOR - Contains the FORTRAN code for the VAX/VMS BTEST
intrinsic function.
DETEST.FOR - Tests the decompression subroutines.

Example FORTRAN Program
------------------------

The example FORTRAN program shown below demonstrates how to use the
decompression programs.


C*******************************************************************
C
C HIST - Buffer to contain 511 elements of the encoding histogram.
C The encoding histogram is extracted from the image file.
C NSI - Number of bytes obtained from the read of a compressed
C line.
C NSO - Number of output samples after decompression. For Voyager
C images, this value is 836.
C LINEI - Buffer containing the input compressed line.
C LINEO - Buffer to contain the restored line after decompression.
C NL - Number of lines in the image array. For Voyager images,
C this value is 800
C IL - DO loop counter for processing image lines.
C********************************************************************
INTEGER*4 NSI,NSO,NL,IL
INTEGER*4 HIST(511)
BYTE LINEI(836),LINEO(836)
.
.
C********************************************************************
C Assume the encoding histogram has been extracted from
C the image file and has been placed into the HIST array.
C Pass it to the DECMPINIT routine for initialization
C********************************************************************
CALL DECMPINIT(HIST)
.
.
C********************************************************************
C The DO loop will read one compressed line at a time from the input
C file and call the DECOMPRESS routine to restore the line
C********************************************************************
NL = 800
NSO = 836
DO IL = 1,NL
.
.
(read next compressed line (LINEI) and length of line (NSI))
CALL DECOMPRESS(LINEI,LINEO,NSI,NSO)
(line is restored in the LINEO subroutine)
.
END DO
.
.
STOP
END

C-language Considerations
-------------------------

The C-language versions of the decompression subroutines are more
portable than the equivalent FORTRAN versions. These routines have
been tested on a VAX 750 running under version 4.6 of VMS, a
Micro-VAX running under version 2.2 of ULTRIX, a SUN workstation
running under version 4.2 (release 3.4) of UNIX, and an IBM PC
running under MSDOS using versions 4.0 and 3.0 of MICROSOFT C.

The C-language version of the decompression software resides in the
DECOMP.C file. This file contains the decmpinit and decompress
routines, and the working routines dcmprs, huff_tree, and sort_freq.
Also, there is a main program, located in the DETEST.C file, which
tests the performance of the decompression software. If you are
adapting the software to your paricular hardware and operating system
environment, then this program will be useful for testing the
software.

Example C-language Program
--------------------------

The example program shown below demonstrates the use of the
decompression subroutines.

/********************************************************************
*
* hist - Buffer to contain 511 elements of the encoding histogram.
* The encoding histogram is extracted from the image area.
* nsi - Number of bytes obtained from the read of a compressed
* line.
* nso - Number of output samples after decompression. For Voyager
* images, this value is 836.
* linei - Buffer containing the input compressed line.
* lineo - Buffer to contain the restored line after decompression.
* nl - Number of lines in the image array. For Voyager images,
* this value is 800.
* il - Loop counter for processing image lines.
******************************************************************/
main ()
{
extern void decmpinit(); /* decmpinit is void function*/
extern void decompress();/* decompress is void fuction*/
long nsi,nso,nl,il;
long hist[511];
char linei[836],lineo[836];
.
.
/********************************************************************
* Assume the encoding histogram has been extracted from
* the image file and has been placed into the hist array.
* Pass it to the decmpinit routine for intialization
********************************************************************/
decmpinit(hist);
.
.
/********************************************************************
* The loop will read one compressed line at a time from the input
* file and call the decompress routine to restore the line
********************************************************************/
nl = 800;
nso = 836;
for (il=0; i<nl; ++i)
{
.
.
(read next compressed line (linei) and length of line (nsi))
decompress(linei,lineo,&nsi,&nso);
(line is restored in the LINEO variable.)
.
}
.
.
}



Stand-Alone Applications
------------------------

Stand-alone applications which will read a compressed image file,
reformat the labels and decompress the image to an output file
are provided in C and FORTRAN language versions.

The program CDCOMP.C includes all routines necessary to compile and
link, producing an executable version of the program. This program
has been tested on an IBM PC with Microsoft C, version 5.1, on a
VAX 11/780 using VMS C version 2.2-015, and on a Sun workstation
running BSD UNIX 4.2. IBM PC users will receive three compilation
warnings which may be ignored. VAX/VMS users may have to edit the
"#include <stdio.h>" statement at the beginning of the file depending
on their environment setup.

The program CDCOMP.C prompts the user for a input file name, output
file format choice, and output file name. The output file formats
supported by this version of CDCOMP.C include PDS labelled format,
FITS labelled format, a simple VICAR2 labelled format and an
unlabelled binary array format.

The following commands should be used to link subroutines and produce
an executable file:

On an IBM PC (using Microsoft C Version 5.1)
--------------------------------------------

cl /c cdcomp.c
link cdcomp/stack:10000;

On a VAX using VMS:
-------------------
cc cdcomp
link cdcomp

On a Unix host (Sun, Masscomp)
------------------------------
cc -o cdcomp cdcomp.c


The programs VAXDCOMP.FOR and PCDCOMP.FOR are VAX/VMS and IBM PC
versions of a program to decompress image files and write them out to
a PDS formatted file. Both programs need to be compiled, then linked
with DECOMP.FOR to produce an executable file. The programs are
identical except for the file open statements and the variable
length record I/O (read) statements.


On an IBM PC (using Microsoft FORTRAN Version 4.1)
--------------------------------------------------

fl pcdriv.for decomp.for

On a VAX/VMS system:
-------------------

for vaxdriv,decomp
link vaxdriv,decomp

There is also a sample program, IMGINDEX.FOR which will read and
display the contents of the image index table (IMGINDEX.TAB). It has
been tested on the VAX and IBM PC. The image index table must be in
the same directory as the executable for the program to operate
properly. The FILE='IMGINDEX.TAB' statement in the OPEN call can be
edited to reflect the location of the table (for example, on an IBM PC
it might be specified as FILE='L:INDEXIMGINDEX.TAB').


Executables
-----------

The CDCOMP program has been compiled and linked on IBM PC and VAX/VMS
systems to produce executable programs for decompressing images.
For users of IBM PC computers, the program PCDCOMP.EXE will prompt
for input and output file names, writing the decompressed file
to the specified file name. The program also supports writing
the image file out in PDS, FITS and VICAR2 format, or writing
an unlabelled 800 by 800 array of sample values. The FITS and
VICAR2 formats provide only minimal system labels to allow display
of the image on systems which support these label formats and have
not been carefully tested. For VAX/VMS users, the equivalent program
is VAXDCOMP.EXE, which writes out fixed-length files of 836-bytes
(PDS format), 2880-bytes (FITS format) or 800-bytes (VICAR2 or
unlabelled formats). The image histogram and all engineering
parameters discarded when writing the FITS, VICAR2 and unlabelled
formats.

No guarantee is made that these programs will work in your computer
configuration. The VAX program assumes that you have file-access
support for ISO format CD-ROM disks on your system, or that you have
used a CD-ROM utility routine to read the compressed file from CD-ROM
to a magnetic disk.

> > I am in.vestigate history of xbase-family languages and read about
> > JPLDIS.
> Its on any of the PDS CD-ROM's.

JPLDIS it is not about compression/decompression.

It is free first version of dbase, before Ashton-Tate buy it.
Ashton-Tate is owner of dbase, before Borland buy it.
Borland is owner of dbase, before Embarcadero kill all.

More newest owners i don't known (out of my scope).

---
Make DOS great again!

Carthago delenda est, Ceterum censeo Carthaginem delendam esse.