F.1NCSA HDF Calling Interfaces and Utilities

NCSA HDF README Files on Anonymous FTPF.1

National Center for Supercomputing Applications

November 1989



November 1989




Appendix  FNCSA HDF README Files on Anonymous FTP





This appendix includes listings of the README files which can be found in the anonymous FTP directory that contains NCSA HDF. These listings were made on December 1, 1989, and do not necessarily reflect the current contents of the files. The best way to obtain the most recent versions is to access them through anonymous FTP. 

Figure F.1. README.FIRST

***********************************************************************

NCSA HDF version 3.00
                     December 1, 1989
***********************************************************************

This is NCSA HDF version 3.00. Suggestions and bug reports are welcome.
For the current release of HDF, see the directory "HDF" under anonymous ftp.

Included in this version are:
the basic low-level routines to perform I/O to HDF files, 
routines to process 8-bit Raster Image Sets
routines to process Scientific Data Sets.
routines to process 24-bit Raster Image Sets
routines to extract slabs from Scientific Data Sets
routines to process Palettes (independently of images)
routines to process Annotations for data items

NCSA HDF is the Hierarchical Data Format, a standard file format 
developed by NCSA. For more information about HDF, see the 
January/February 1989 NCSA Data Link article, the document "NCSA HDF", and 
the document "HDF  Specification".

This version of HDF runs on CRAYs running UNICOS, ALLIANTs, SUNs and 
IRIS 4D machines running Unix, MACs running MacOS, VAXen running VMS and 
PCs running MS/DOS.

Compilation of these programs produces a library of HDF routines that 
can be called from either FORTRAN or C programs.

There is an older version of HDF implemented for CRAYs running CTSS, available
from NCSA. This version only implements the 8-bit Raster Image Set. If you
are interested in this, please contact Mike Folk (see below).



Figure F.1. README.FIRST(continued)


This document describes how to obtain a version of HDF for your system. 
Other information, including hints on using HDF, descriptions of  the 
files that comprise the distribution, and instructions on how to to 
create a library, can be found in other README files in this directory. 

There are two ways of obtaining HDF, depending on whether you are 
accessing this system by remote login or anonymous ftp.
Accordingly, this document contains the following sections:

Obtaining HDF using anonymous ftp
Obtaining HDF using remote login

If you have any questions, problems or suggestions, you can contact us 
via Email at mfolk@ncsa.uiuc.edu or likkai@ncsa.uiuc.edu,  or by writing 
to Mike Folk, Software Development, NCSA, 605 East Springfield Ave., 
Champaign, IL 61820, or call 217 244 0647.


************************************************************************
Obtaining HDF using anonymous ftp
************************************************************************

Login to zaphod.ncsa.uiuc.edu (128.174.20.50), with a login name of 
"anonymous". Give your real name as password. Move to the directory 
"HDF" by issuing the command "cd HDF" to ftp. Now you are ready to 
transfer files. There are two ways to do this:

1. You may use the command "get hdf3.00.tar.Z" to download a compressed
"tar" format file. (Be sure to set file transfer mode to binary with the
command "binary".)   Unpacking hdf.tar with the Unix "uncompress" and "tar"
utility on your system will produce a tree of subdirectories similar to
the ones in this directory. These files are described in INSTALL. They
must be compiled according to the instructions in that section. (NOTE: this
tar file is very large, as it contains all the source files, plus
all of the documentation. If space is dear, consider using the method
described in the next paragraph.) 

1a) For MacII/MPW users, there is a binhexed stuffit file called
hdf3.00.sit.hqx. Use ascii mode to get this file, unbinhex it, then
unstuff it. This will provide you will all the files for the MacII.

2. As an alternative to "tar", you may download the files you require 
directly. Use "cd src" to move to the directory containing source 
files. Then use the command "mget *". If your system is VMS, get the
files in src/fixatr also. If your system is a MacII and you need to use
fortran, get the fortran files in src/mac. This will prompt you for each
of the source files, asking if you want to download them. Answer "y" to each.
This will produce the source files for that system in your directory. 
Compile these files according to the instructions in the file INSTALL.

To obtain the documentation enter "cd ../../doc" to move to the 
directory containing the documentation. There are two subdirectories, 
with "ascii" providing the documentation in readable form, and "word" 
providing it in Macintosh Microsoft Word format. Each subdirectory has 
two subdirectories, containing the user documentation (NCSA_HDF) and the 
technical specification (HDF_Specs), respectively. The Word files must 
be downloaded in binary mode with Macbinary mode enabled. The ascii 
files may be downloaded in ascii mode. 
Figure F.1. README.FIRST(continued)



**********************************************************************
Obtaining HDF using remote login 
**********************************************************************

If you have an account on the NCSA Suns, you may download HDF in this way.
To obtain a copy of HDF for a particular system, login to zaphod.ncsa.uiuc.edu,
cd to the directory /sdg/ftp/HDF and use the "transfer" script.

Usage: transfer systemtype hostname [directory]

where systemtype is "unicos", "sun", "alliant", "iris4", "mac", 
"vms" or "pc", hostname is the ftp name of the host you want to transfer 
the files to, and directory is the directory on the target system in 
which you want the files to be placed.

Transfer will create the source files appropriate for the system type, 
then open an ftp connection to the target machine and ask you to login. 
When you do, it will automatically copy the required files to the target 
system in the directory you specified. It will also deposit all the 
documentation, in Macintosh Microsoft Word format if transferring to a 
Macintosh, in ascii format otherwise. It will deposit all the files in 
the same directory, as contrasted to using the "tar" approach outlined 
in the section on anonymous ftp, which will create a tree of 
subdirectories.


*----------------------------------------------------------------------
*  * NCSA HDF Version 3.00 source code and documentation are in the 
* public domain. Specifically, we give to the public domain all rights 
* for future licensing of the source code, all resale rights, and all 
* publishing rights. 
*  
* We ask, but do not require, that the following message be included in
* all derived works: 
*  
* Portions developed at the National Center for Supercomputing 
* Applications at the University of Illinois at Urbana-Champaign. 
*  
*  
* THE UNIVERSITY OF ILLINOIS GIVES NO WARRANTY, EXPRESSED OR IMPLIED, 
* FOR THE SOFTWARE AND/OR DOCUMENTATION PROVIDED, INCLUDING, WITHOUT 
* LIMITATION, WARRANTY OF MERCHANTABILITY AND WARRANTY OF FITNESS FOR 
* A PARTICULAR PURPOSE. 

*  
* If you want to see more software like NCSA HDF, you need to send us a 
* letter, email or US mail, telling us what you are doing with NCSA HDF. 
* We need to know: 
* 1) What science you are working on (an abstract of your work would be 
* fine); 
* 2) How NCSA HDF has helped you, e.g., whether it has increased your 
* productivity or allowed you to perform operations you were unable to 
* do before. 
*  
* We encourage you to cite the use of NCSA HDF , and any other NCSA 
* software you have used, in your publications. A bibliography of your 
* work would be extremely helpful. 

Figure F.1. README.FIRST (continued)
*  
* This is a new kind of shareware. You share your science and successes
* with us, and we attain the resources necessary to share more software 
* like NCSA HDF with you. 
* 
***********************************************************************



Figure F.2. README.NCSA. For HDF Users of NCSA Computers.
*********************************************************************
                       NCSA HDF version 3.00
                           December 1, 1989
*********************************************************************
 HDF is installed on various systems at NCSA. The following is a list 
of directories in which HDF is installed on different systems:


       Cray-2:      /usr/local/apps/hdf
       Cray-XMP:    /usr/local/apps/hdf
       Suns:        /soft/hdf
       Medusa:      /usr/hdf
       Replicant:   /usr/hdf

The current version of HDF will be in that directory and its 
subdirectories.

In the bin/ directory you will find several HDF utilities, such as:

   hdfls - a utility to display information about the contents of an HDF file.

   hdfrseq - a utility to display a raster 8 bit image remotely using
              the NCSA Interactive Color Raster protocol.

   hdftor8 - a utility to convert an HDF raster 8 bit image into a raw
              raster image.

   r8tohdf - a utility to convert a raw raster image to an HDF raster 8
              bit image.

   hdfcomp - a utility to change the compression scheme used for 8-bit
             raster images in HDF files.

If you execute any of these commands with no parameters, it will display 
the list of acceptable parameters.

In the doc/ directory you will find files containing the HDF 
documentation.

In the examples/ directory you will find example codes using HDF. The 
example codes should be self explanatory.

In the include/ directory you will find the necessary include files for 
use in your own programs that link with the HDF library.

In the lib/ directory you will find the HDF library which contains the 
necessary subroutines for developing your own HDF applications.

In the src/ directory you will find the source for all of the HDF 
utilities and library.
If you have any questions, please contact the NCSA Consulting Office.

Figure F.3  INSTALL:   Compiling the HDF Source.

***********************************************************************
NCSA HDF version 3.00
    December 1, 1989
***********************************************************************

----------- Compiling the HDF source ------------

**For Unix users: Use the Makefile and other files in that directory
to create the HDF libraries and utilities. You might want to edit the
MACHINE define in ./src/Makefile to the machine used.

If you plan to use fortran with HDF, you need to run either configlong
or configshort to use the right fortran files. If your fortran compiler
accepts functions names of over 8 characters, then run configlong;
otherwise, run configshort.

If you wish to install these in a different directory from where you 
keep the source, edit Makefile and fill in the desired values for 
BINDIR, LIBDIR and INCDIR. Then, using "make all" will compile all the 
source files and install the files according to the variable settings. 
If you merely wish to compile the files and leave the utilities and 
library in the same directory, you may use "make build".

**For UNICOS users: Use ./src/Mfile.UNICOS as the Makefile and follow
the instructions for Unix.

**For VMS users: Use the script [.SRC]MAKE.COM by typing:
@make
to make the HDF library (libdf.a), then in the directory
[.SRC.FIXATR], use MAKEFIX.COM to make fixatr which is useful for
converting fixing VMS file attributes for HDF to work properly.

**For PC users: Run the batch file .\SRC\MAKE.BAT to compile the
HDF library using Lattice C. If you do not use this script, make sure
that the symbol 'PC' is defined for the C compiler.

**For MacII users: This version only works with MPW C. Fortran
support for the mac is added in version3.0. Unbinhex
the file Makefile.hqx to get a usable MPW makefile.

*****

(Note to Macintosh and PC users:  These routines have been compiled and 
run successfully on Macs using MPW C Version 2.0.2, and on PCs using 
Lattice C  Version 3.0. We cannot guarantee that they will compile 
correctly with other compilers. We would appreciate any feedback you 
can give on experiences you have compiling them on other compilers.

For a non-Unix system, the Makefile may be used as a guide for compiling 
the files. An approximate summary of the procedure is:

  cc -c df.c dfr8.c dfgroup.c dfcomp.c dfimcomp.c dfsd.c dfkit.c
  ar libdf.a df.o dfr8.o dfgroup.o dfcomp.o dfimcomp.o dfsd.o 
  ranlib libdf.a

This creates the library file "libdf.a".

To create the utilities "hdfls", "hdfrseq", "r8tohdf", "hdftor8", 
"tektohdf", "hdftotek", and "hdfcomp", the procedure is:
Figure F.3  INSTALL  (continued)


     cc hdfls.c libdf.a -o hdfls
     cc hdfrseq.c libdf.a -o hdfrseq
     cc r8tohdf.c libdf.a -o r8tohdf
     cc hdftor8.c libdf.a -o hdftor8
     cc tektohdf.c libdf.a -o tektohdf
     cc hdftotek.c libdf.a -o hdftotek
     cc hdfcomp.c libdf.a -o hdfcomp

To use the program "hdfseq", create "hdfseq" as a symbolic link to the
executable "hdfrseq". "hdfseq" displays images on the console of a
Sun or Iris workstation.

--------------- Compiling Subsets of HDF ---------------

If you wish to use only some of the HDF Sets, it is possible to create 
versions of the library which only contain the desired interfaces. For 
instance, a user who works only with images, but not with raw floating 
point data may wish to have only the Raster Image Set (RIS) but not the 
Scientific Data Set. The following is the list of source files necessary 
for each of the Sets included in the current version of HDF.

Basic Low level HDF:   df.c dfkit.c df.h dfi.h
Basic Low level Fortran: df.c dfF.c dfFf.f dfkit.c df.h dfi.h

8-bit Raster Image Set (RIS-8): dfr8.c df.c dfkit.c dfcomp.c dfimcomp.c 
    dfgroup.c df.h dfi.h dfrig.h
8-bit Raster Image Set Fortran: dfr8.c dfr8F.c dfr8Ff.f df.c dfkit.c
    dfcomp.c dfimcomp.c dfgroup.c df.h dfi.h dfrig.h

Scientific Data Set (SDS): dfsd.c df.c dfkit.c dfgroup.c df.h dfi.h dfsd.h
Scientific Data Set Fortran: dfsd.c dfsdF.c dfsdFf.f df.c dfkit.c
    dfgroup.c df.h dfi.h dfsd.h

------------ Compiling C programs with HDF ----------------

To use HDF routines in your program, use "#include dfrig.h", "#include dfsd.h"
etc. at the top of your program, depending on the Sets you are using.
Call the appropriate HDF routines as described in the 
documentation. Compile your C program "myprog.c" as follows:

    cc myprog.c libdf.a -o myprog

If the include file "dfrig.h" is in the directory "incdir", and the 
library file "libdf.a" is in "libdir", use

    cc -Iincdir myprog.c libdir/libdf.a -o myprog

--------------- Description of HDF source files ----------------

The following is a description of the various subdirectories and files. 
Note that since many of the source files for the various systems are 
identical, many of the files in the src/xxx subdirectories are hard 
links to files in the src directory.

Subdirectories:
     src:            source code
src/fixatradditional source code for VMS
     doc:            documentation

Figure F.3  INSTALL  (continued)

Files:    (description of files in each source directory)
       df.h - header file included in all HDF source files and user programs
       dfi.h - internal header file, included automatically by df.h
       df.c - low-level routines which perform I/O to HDF files etc.
       dfrig.h - header file for the Raster Image Group set
       dfr8.c - routines to implement 8-bit raster image groups
       dfgroup.c - routines to read and write groups (of tag/refs)
       dfcomp.c - routines for data compression
       dfimcomp.c - routines to implement the IMCOMP compression scheme
       dfsd.c - routines to implement the Scientific Data set
       dfsd.h - header file for the Scientific Data set
       dfkit.c - HDF internal utility routines
       dfgr.h - header for general raster
       dfgr.c - routines for general raster
       dfan.h - header for annotations
       dfan.c - routines for annotations
       dfp.c - routines for palette
       df24.c - routines for 24 bit raster
       hdfls.c - source for "hdfls" which lists contents of HDF files and
       hdfrseq.c - source for "hdfseq" which displays images in HDF files
               which produces ICR output for display on remote screen
       r8tohdf.c - source for "r8tohdf" which converts raw image,
              palette files to HDF
       hdftor8.c - src for "hdftor8" which extracts raw 8 bit image and
       palette files from HDF.
       tektohdf.c - src for "tektohdf" which converts tek format to HDF
       hdftotek.c - src for "hdftotek" which extracts tek files from HDF
       srtohdf.c - src for "srctohdf" which converts sun-raster files to HDF
       Makefile - makefile for the HDF system

       Files for fortran stubs:
       dfF.c
       dfr8F.c
       dfsdF.c
       dfanF.c
       dfpF.c
       df24F.c
       dfFf.f (l.dfFf.f s.dfFf.f)
       dfr8Ff.f (l.dfr8Ff.f s.dfr8Ff.f)
       dfsdFf.f (l.dfsdFf.f s.dfsdFf.f)
       dfanFf.f (l.dfanFf.f s.dfanFf.f)
       dfpFf.f (l.dfpFf.f s.dfpFf.f)
       df24Ff.f (l.df24Ff.f s.df24Ff.f)

       dfivms.h - VMS specific header file
       MAKE.COM - VMS make script
       fixatr/* - files and scripts for makeing fixatr for VMS

       Makefile.hqx - binhexed MPW makefile

       MAKE.BAT - IBM PC make batch-script

       doc/ascii/NCSA_HDF/* - ASCII format documentation for HDF
       doc/ascii/HDF_Specs/* - ASCII format technical specification of HDF
       doc/word/NCSA_HDF/* - Microsoft Word format documentation for HDF
       doc/word/HDF_Specs/* - Microsoft Word format technical specification of HDF


Figure F.4  README.NEW.DIR.STRUCT. New Directory Structure for HDF Version 3.0. on Anonymous FTP.

The files in the src directory are reorganized so that now there will
only be one (1) directory for source. This means that for all machines,
the HDF source files are in the ./src directory.

To tell the unix compilers what machine to compile for, you have to edit
in ./src/Makefile the MACHINE definition. The comment in the file gives
more information. For IBM PC, we provide the batch file ./src/make.bat
and for VMS, we provide the command file ./src/make.com (to be invoked
by @make).
