iNCSA HDF Calling Interfaces and Utilities Introductioni National Center for Supercomputing Applications November 1989 Introduction Overview This introduction provides an overview of NCSA Hierarchical Data Format (HDF) capabilities on the Cray, Alliant, Sun, Iris, Macintosh, and IBM PC. The organization and use of this manual are described and notational conventions explained. What Is HDF? Hierarchical Data Format (HDF) is a multi-object file format for the transfer of graphical and floating-point data between machines. The design of this format allows self-definition of data content, and easy extensibility for future enhancements or compatibility with other standard formats. Features of NCSA HDF Version 3.0 include the following: ¥Facilities for sharing data across machines and systems, including Cray (UNICOS), Silicon Graphics (UNIX), Alliant (CONCENTRIX), Sun (UNIX), VAX (UNIX), Macintosh (MacOS), and IBM PC (MS-DOS) ¥FORTRAN and C calling interfaces for storing and retrieving 8 and 24-bit raster images, palettes, scientific data and accompanying annotations ¥Utilities for editing and displaying HDF files, and converting raw data files to HDF files and vice versa ¥General purpose routines for creating HDF files Differences Between HDF 2.0 and HDF 3.0 All of the features of HDF 2.0 are present in HDF 3.0. HDF 3.0 contains the following new features: ¥An interface for basic input and output of 24-bit raster images ¥An interface for annotating HDF data objects and files ¥An interface for input and output of 8-bit palettes ¥Scientific dataset routines for storing and retrieving subsets (slices) of scientific data, and for choosing optional storage formats and data types ¥New utilities, including an HDF editor, and routines to convert floating-point data to images, 24-bit images to 8-bit images, and raw palettes to and from HDF palettes ¥Minor routines to help fill out existing interfaces System Requirements In order to use HDF software, you need access to one of the following computer systems: a Cray with UNICOS, Silicon Graphics system with UNIX, an Alliant with CONCENTRIX, a Sun System 3 with UNIX, a VAX terminal with UNIX, a Macintosh with MacOS, or an IBM PC with MS-DOS, or compatible model. Use of This Manual This manual is designed for users who are working on an application that involves the use of HDF files. If you are completely unfamiliar with HDF, you should read or scan Chapter 1, "HDF Basics." The most important information about a particular interface is covered in the chapter that deals with that interface. Each chapter contains a description of the set with which the interface deals, descriptions of the routines that constitute the interface, and examples. .c3.Manual Contents The manual is organized into the following chapters: Chapter 1, "NCSA HDF Basics," describes HDF, explains the reasons for its creation, and gives a brief overview of available applications software. Chapter 2, "Storing Raster Images," describes the routines that are available for storing and retrieving raster images in HDF format, with or without compression, and with or without palettes. Chapter 3, "Storing Palettes," describes the routines that are available for storing and retrieving 8-bit palettes. Chapter 4, "Storing Rectangular Gridded Arrays of Scientific Data," describes the routines that are available for storing and retrieving scientific datasets. Chapter 5, "Annotating Data Objects and Files," describes the routines that are available for storing and retrieving data and file annotations. Chapter 6, "General Purpose HDF Routines," provides a reference to the set of general purpose low-level routines youÕll use when working with HDF files. Chapter 7, ÒNCSA HDF Command Line Utilities,Ó lists currently available utility routines and command line utilities that are available for working with HDF files. Chapter 8, ÒError Handling in HDF,Ó discusses the error reporting procedures of HDF. Appendix A, "NCSA HDF Tags," presents a table of brief descriptions of most of the tags assigned at NCSA for general use. Appendix B, "Header Files," includes the general header files used in compiling all HDF libraries. Appendix C, "Eight-Character FORTRAN Names," lists the official identifier names and their short form equivalents. Appendix D, "Public HDF Directories on NCSA Computers," lists the names and contents of NCSA-supported HDF directories. Appendix E, ÒRoutine Lists,Ó lists all the current routines available for use with NCSA HDF. Appendix F, ÒNCSA HDF README Files on Anonymous FTP,Ó includes listings of the README files which can be found in the anonymous FTP directory that contains NCSA HDF. .c2.Form of Presentation The material in this manual is presented in text, screen displays, or command line notation. Text In explaining various features and commands, this manual often presents a word within a paragraph in italics to indicate that the word is defined within the paragraph, or that it is a significant term that should be noted and/or is bing mentioned for the first time. So that they are more easily identifiable within this manuscript, utilities, variables, integer arguments, tags, etc. have been presented in 10 point courier style. Portions of this manual refer to other portions of the manual where the other portions explain related topics. These cross references usually mention the title of sections or chapters enclosed in quotation marks, such as, See Chapter 1, "NCSA HDF Basics." Command Line Format Notation Throughout this manual, many explanations instruct you to make entries by typing on the keyboard. These entry instructions are printed in courier bold type and appear within a paragraph or on a separate line. The command lines in this manual are normally shown in lowercase, except in rare instances where uppercase is required. When it is necessary for you to press a key that is labeled with more than one character (such as the RETURN key), this manual identifies the key with all capital (uppercase) letters. Keys to be entered are printed in bold type. Keys that are pressed simultaneously or in succession are linked with a hyphen. For example, press CONTROLA. The meaning of each special notation applied to format lines is listed in Table 1. Table I.1 Meaning of Entry Format Notations AppearanceExampleEntry Method On separate line; dothisEnter the keys for each character. lowercase, courier bold type Within a text line; RETURNPress the single key indicated. uppercase Within a text line; uppercase;CONTROL-AWhile holding down the first one or two key(s) hyphens between key namesindicated, press the last key indicated. On separate line or within afilenameThis notation is a variable, which represents text line; italic, lowercase,a certain kind of entry, but may consist of courier bold typedifferent characters every time you make the entry. Square brackets; bold type[ ]Do not enter the square brackets. Material presented between brackets is optional and should be entered only in certain cases. Ellipses; bold type. . .Do not enter ellipses. Ellipses indicate you may enter more material similar to the material preceding the ellipses. Figure 1 shows you how to read and enter a command line. Figure I.1Reading and Entering a Command Line Further Reading More detailed information about the basic HDF structure and how it works can be found in NCSA HDF Specifications, which you may download via FTP (refer to "How to Get HDF" in Chapter 1) or may request by writing NCSA at the addresses listed on the Bugs and Suggestions report form at the back of this manual.