home *** CD-ROM | disk | FTP | other *** search
/ Photo CD Demo 1 / Demo.bin / hdf / docs / hdfvset.int < prev    next >
Text File  |  1980-02-06  |  8KB  |  229 lines
  1. i    NCSA HDF Vset 
  2.  
  3. Introduction    i
  4.  
  5. National Center for Supercomputing Applications
  6.  
  7. November 1990
  8.  
  9.                                                                 
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17. Introduction
  18.  
  19.  
  20.  
  21.  
  22. Overview
  23.  
  24. This introduction provides an overview of NCSA Hierarchical 
  25. Data Format (HDF) Vset capabilities on the Cray, Alliant, Sun, 
  26. Iris, Macintosh, and IBM PC. The organization and use of this 
  27. manual are described and notational conventions explained.
  28.  
  29.  
  30. What Is an HDF Vset?
  31.  
  32. The HDF Vset is a new storage scheme that allows more than 
  33. raster images, palettes, scientific datasets and annotations to be 
  34. stored in the HDF file. It is a versatile storage scheme that 
  35. introduces two new and useful features.
  36.  
  37. 1.    Storage of multi-variate data fields
  38.     Applications may now define and store data from fields of 
  39. different types together within the HDF file and then access data 
  40. from all or some of the fields.
  41.  
  42. 2.    Hierarchical grouping of related datasets
  43.     Applications may explicitly link related datasets within the 
  44. HDF file to form logically-related groups called vsets.
  45.  
  46. The HDF Vset enables applications with the following capabilities 
  47. inherent to HDF:  (1) a means of defining data fields and types (2) 
  48. a means of specifying data layout in the HDF file, and (3) greater 
  49. control over data access.
  50.  
  51.  
  52. Uses of HDF Vsets 
  53.  
  54. The HDF Vset is especially targeted towards applications that 
  55. manipulate mesh, polygonal, or any connectivity data. Among the 
  56. applications that could benefit by using this storage scheme are 
  57. finite-element analysis, surface modeling, and sparse matrices. 
  58. Using HDF Vset you can group simulation data for animation, as 
  59. well as store and view images with original data for more 
  60. meaningful data interpretation.
  61.  
  62. NCSA developers originally designed the HDF Vset to store 
  63. irregularly-gridded and multi-variate graphical and scientific 
  64. data, and to facilitate data exchange among the research 
  65. community. It has since evolved into a general and simple 
  66. interface for storing almost any large non-uniform datasets. 
  67. Consistent  with existing HDF goals, vset data is self-describing 
  68. and portable. In addition, provision exists for attaching 
  69. annotations and textual descriptions.
  70.  
  71.  
  72. New Features in HDF Vset 2.0
  73.  
  74. NCSA HDF Vset 2.0 offers several new features and 
  75. improvements including memory allocation, long integer support, 
  76. a new secondary name field, and multiple file access.
  77.  
  78.  
  79. Memory Allocation
  80. HDF Vset allocates memory for vgroups and vdatas dynamically.
  81.  
  82. Therefore, there is no upper limit on how many vgroups or vdatas 
  83. that may be accessed by an application.
  84.  
  85.  
  86. Long Integer Support
  87. HDF Vset now allows storage of long integers in a vdata. Integer 
  88. datasets greater than 65353 must be stored as long integers or they 
  89. will be truncated. Each long integer will be stored in 4 bytes within 
  90. a vdata. 
  91.  
  92. The routine VSfdefine now recognizes the field type constant 
  93. LOCAL  LONGTYPE. Use this constant to define a field to be of type 
  94. long. VSwrite expects data corresponding to that field to be stored 
  95. in a long array. Similarly, VSread expects to be passed a long 
  96. array into which long integers will be retrieved and returned.
  97.  
  98.  
  99. New Secondary Name Field
  100. Each vgroup or vdata now has a secondary name field. This field, 
  101. called the class field of the vgroup or vdata, is just another text field 
  102. like the vgname or vsname. Its purpose is to provide another key 
  103. with which that vgroup or vdata may be classified. It is analogous 
  104. to the file-extension in a filename, e.g., "DAT" in the filename 
  105. "TEST1.DAT". Usage of the class field is optional, and is 
  106. application-dependent.
  107.  
  108. The routines Vsetclass and VSsetclass set this class field for a 
  109. vgroup and a vdata, respectively. Similarly, the routines 
  110. Vgetclass and VSgetclass return the class fieldname of a 
  111. vgroup and a vdata, respectively.
  112.  
  113.  
  114. Multiple File Access
  115. HDF Vset now allows several HDF files to be opened for reading 
  116. and writing Vsets simultaneously. This feature only works when 
  117. the Vset library is used with release 3.1 or later of the base HDF 
  118. library. No new routines are needed. 
  119.  
  120. Open as many files as needed using DFopen, and then use the file 
  121. pointers as usual in the Vset routines. Upon completion, each 
  122. opened file must be properly closed by a call to DFclose.
  123.  
  124. NOTE:  Please see Appendix E, "Compatibility Information for 1.0 
  125. Users" for important compatibility information for release 1.0 
  126. users.
  127.  
  128.  
  129. System Requirements
  130.  
  131. The HDF Vset library is available for any of the following 
  132. computer systems:  Cray/UNICOS, SGI/UNIX, Sun/UNIX, 
  133. Alliant/CONCENTRIX, VAX/Ultrix, Vax/VMS, 
  134. Macintosh/MacOS, and IBM PC/MS-DOS.
  135.  
  136.  
  137. Use of This Manual
  138.  
  139. This manual is designed for users whose applications access vsets 
  140. from HDF files.
  141.  
  142.  
  143. .c3.Manual Contents
  144. The manual is organized into the following chapters:
  145.  
  146. Chapter 1, "NCSA HDF Vset Basics," describes HDF Vsets and 
  147. gives simple examples on using it.
  148.  
  149. Chapter 2, "Vdatas," describes in detail the organization of data 
  150. within vdatas and techniques for manipulating the data.
  151.  
  152. Chapter 3, "Vset Utilities," describes in detail the utilities for 
  153. manipulating Vsets.
  154.  
  155. Chapter 4, "Vgroup Routine Descriptions," describes in detail the 
  156. routines that manipulate vgroups.
  157.  
  158. Chapter 5, "Vdata Routine Descriptions," describes in detail the 
  159. routines that manipulate vdatas.
  160.  
  161. Chapter 6, "HDF Vset FORTRAN Interface," describes Vset 
  162. calling sequences from FORTRAN.
  163.  
  164. Appendix A, "NCSA HDF Vset Calls at a Glance," allows quick 
  165. referencing of all present Vset Calls.
  166.  
  167. Appendix B, "NCSA HDF Vset Calls Summary," lists all HDF 
  168. Vset routines.
  169.  
  170. Appendix C, ╥Pre-defined Fieldnames,╙ lists all HDF predefined 
  171. fieldnames.
  172.  
  173. Appendix D, "Source Files," lists the source files needed for HDF 
  174. Vsets and describes how to compile and create applications that use 
  175. the HDF Vset.
  176.  
  177. Appendix E, "Compatibility Information for 1.0 Users," offers 
  178. important compatibility information for NCSA HDF Vset 1.0 
  179. users.
  180.  
  181. Appendix F, "Obtaining NCSA Software," outlines the procedures 
  182. for obtaining NCSA software.
  183.  
  184.  
  185. .c2.Form of Presentation
  186. The material in this manual is presented in text, screen displays, 
  187. or command line notation.
  188.  
  189.  
  190. Text
  191. In explaining various features and commands, this manual often 
  192. presents a word within a paragraph in italics to indicate that the 
  193. word is defined within the paragraph, or that it is a significant 
  194. term that should be noted and/or is being mentioned for the first 
  195. time.
  196.  
  197. So that they are more easily identifiable within this manuscript, 
  198. utilities, variables, integer arguments,  routine names, etc. have 
  199. been presented in 10 point courier style.
  200.  
  201. Portions of this manual refer to other portions of the manual where 
  202. the other portions explain related topics. These cross references 
  203. usually mention the title of sections or chapters enclosed in 
  204. quotation marks, such as, see Chapter 1, "NCSA HDF Vset 
  205. Basics."
  206.  
  207. Command Line Format Notation
  208. Throughout this manual, many explanations instruct you to make 
  209. entries by typing on the keyboard. These entry instructions are 
  210. printed in courier bold type and appear within a paragraph or 
  211. on a separate line. The command lines in this manual are 
  212. normally shown in lowercase, except in rare instances where 
  213. uppercase is required.
  214.  
  215. When it is necessary for you to press a key that is labeled with 
  216. more than one character (such as the RETURN key), this manual 
  217. identifies the key with all capital (uppercase) letters. Keys to be 
  218. entered are printed in bold type. Keys that are pressed 
  219. simultaneously or in succession are linked with a hyphen. For 
  220. example, press CONTROL-A.
  221.  
  222.  
  223. Further Reading
  224. Detailed information about the basic HDF structure and its calling 
  225. interface can be found in NCSA HDF Specifications and also 
  226. NCSA HDF Calling Interfaces and Utilities which you may 
  227. download via FTP, an archive server, or via U. S. mail. Refer to 
  228. Appendix F, "Obtaining NCSA Software," for more details.
  229.