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).