SCRIPT/VS 3.0.5: DEVICE 1403N6 CHARS MONO ¤   MVS: HIERARCHICAL DATA FORMAT (HDF)  Document Number SG23  Effective: 12/12/90   Ú----------------------------------------------------------¿  | |  | Note: The following document describes HDF as |  | installed on the IBM 3090 at UCLA's Office of Academic |  | Computing, and constitutes documentation which OAC |  | distributes to its users. It is being made available |  | with the IBM MVS port of HDF because it may be helpful |  | to those planning or presently installing the product. |  | Please note that the implementation described here |  | reflects the UCLA/OAC environment, and not a general |  | solution to HDF implementation. Procedures and JCL |  | examples may differ from installation to installation. |  | Further, this document does not reflect the |  | installation of the DF24 and DFP routines. When the |  | base document has been updated to reflect these recent |  | changes, a copy will be made available to NCSA. |  | |  À----------------------------------------------------------Ù   CONTENTS  ________  I. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 1  II. WHAT IS AN HDF FILE . . . . . . . . . . . . . . . . . 1  III. OAC MODIFICATIONS TO HDF CODE . . . . . . . . . . . 2  A. CHANGES THAT APPLY GENERALLY . . . . . . . . . . . 3  Subroutines' Names . . . . . . . . . . . . . . . . 3  File Name Operands . . . . . . . . . . . . . . . . 3  Scientific Data and 8-Bit Raster Images . . . . . . 4  Handling Errors . . . . . . . . . . . . . . . . . . 4  Transfer as Binary Files . . . . . . . . . . . . . 4  B. Changes Affecting Only Fortran . . . . . . . . . . 5  Matrix Storage Difference . . . . . . . . . . . . . 5  No Character String Constants . . . . . . . . . . . 5  Shortened Names . . . . . . . . . . . . . . . . . . 6  Fortran Callable Routines . . . . . . . . . . . . . 6  IV. RUNNING HDF FROM C . . . . . . . . . . . . . . . . . 6  V. RUNNING HDF FROM FORTRAN . . . . . . . . . . . . . . . 7  VI. REFERENCES . . . . . . . . . . . . . . . . . . . . . 7 ¤  I. INTRODUCTION  Hierarchical Data Format (HDF) is a multi-object, public  domain file format designed to facilitate the transfer of  scientific visualization data between various computers and  operating systems. The format allows you to store data  objects of many different types, such as floating point  data, palettes, raster images, and text notes, in the same  file.  HDF was written for various machines at the National Center  for Supercomputer Applications (NCSA) at the University of  Illinois in Champaign-Urbana. NCSA and Apple are involved  with OAC in a project to port HDF to the IBM 3090.  OAC has been interested in HDF because of visualization  software, also from NCSA, that can be used on Macintoshes to  display and animate images. While this software can work  with raw raster images, it works best with HDF files.  We believe HDF will be most useful to UCLA users for  generating files on the IBM 3090 that can be transferred to  a Macintosh or other platforms for viewing. The Macintoshes  in the visualization lab have software running on them that  can display HDF files.   II. WHAT IS AN HDF FILE  HDF is a self-documenting file format for both data and  graphical images: information about matrix sizes, labeling,  and descriptive text is saved along with the data. HDF files  can contain:  ù 8-bit raster images with color lookup tables  ù scientific (floating point) data plus various types of  labeling  ù annotation  ù 24-bit raster images  Currently 8-bit raster images, scientific data, and  annotation are supported in the OAC port of HDF.  Eight-bit raster images can be compressed with either  run-length encoding or IMCOMP compression.  HDF files contain information about the machine that created  them, including the machine type and the machine's  character, integer, and floating-point formats.  As well as being a file format, HDF is a library of  subroutines that resides on various platforms and can be  called to read and write HDF files. HDF subroutines can be  called from C and Fortran programs.  - 1 - ¤  Versions of the subroutine library already run on Crays  under UNICOS; Silicon Graphics machines; VAXs under UNIX;  Alliants under CONCENTRIX; Macintoshes under MacOS; and IBM  PCs under MS-DOS.  Versions of HDF for all of these machines are in the public  domain and can be obtained from NCSA via Internet. To  download a copy, do an Anonymous FTP to  ZAPHOD.NCSA.UIUC.EDU.   III. OAC MODIFICATIONS TO HDF CODE  NCSA has produced an excellent manual for HDF which is  available in all three of OAC's public facilities. However,  because the IBM 3090 is different from the machines on which  HDF has previously been run, a number of changes had to be  made to the code.  You must be aware of these changes, because not everything  works with the 3090 just as described in the HDF manual. The  changes are documented in this writeup.              - 2 - ¤  A. CHANGES THAT APPLY GENERALLY   Subroutines' Names   The following subroutines must be called by their shortened  names:  Name Shortened name  DFANgetlablen dagllen  DFANgetlabel daglab  DFANgetdesclen dagdlen  DFANgetdesc dagdesc  DFANgetfidlen dagflen  DFANgetfid dagfid  DFANgetfdslen dagfdlen  DFANgetfds dagfds  DFANputlabel daplab  DFANputdesc dapdesc  DFANaddfid daafid  DFANaddfds daafds  DFANlablist dallist  DFSDadddata dsadata  DFSDclear dsclear  DFSDendslice dseslc  DFSDgetdata dsgdata  DFSDgetdatastrs dsgdast  DFSDgetdims dsgdims  DFSDgetdimscale dsgdisc  DFSDgetdimstrs dsgdist  DFSDgetmaxmin dsgmaxm  DFSDgetslice dsgslc  DFSDputslice dspslc  DFSDrestart dsfirst  DFSDsetdatastrs dssdast  DFSDsetdims dssdims  DFSDsetdimscale dssdisc  DFSDsetdimstrs dssdist  DFSDsetlengths dsslens  DFSDsetmaxmin dssmaxm  DFSDsettype dsstype  DFSDstartslice dssslc   File Name Operands   Wherever the HDF manual shows a file name operand in a  calling sequence (written in C) such as:  int DFSDgetdata(filename, rank, sizes, data);  ___________________________  - 3 - ¤  or in Fortran:  INTEGER FUNCTION DFSDgetdata(filename, rank, bufsizes, data)  ______________________________  replace filename with a character string of the form:  ________  "dd:ddname"  ______  where ddname is the ddname of a DD statement included in  ______  your JCL.  Ú----------------------------------------------------------¿  | Warning: if you replace filename with a dataset name, |  ________  | a dataset will be created for you but that dataset may |  | be placed on any disk pack on the system. Datasets |  | placed on private disk packs other than the data packs |  | or a pack belonging to you will be scratched without |  | notice. |  À----------------------------------------------------------Ù   Scientific Data and 8-Bit Raster Images   Even though you can place both 8-bit raster images and  scientific data in the same HDF file, you cannot call the  8-bit raster routines and the scientific data routines from  the same program.   Handling Errors   The error handling included with HDF does not give you, in  many cases, enough information to actually determine what is  wrong. NCSA has told us it will fix this problem with the  next release.   Transfer as Binary Files   HDF files created on non-IBM systems can be transferred to  the IBM 3090. All HDF files must be transferred as binary  files and the receiving files must either be pre-allocated  or specified as:  RECFM=U, BLKSIZE=512.  To read a HDF file that has been transferred to the IBM 3090  from a non-IBM system, you must then run the following job  to convert the record format to F.  - 4 - ¤  //aaaaiiic JOB job-parameters  ________ ______________  // EXEC LOADP,PROG=RECFMF  //STEPLIB DD DISP=SHR,DSN=APP1.HDF3.LOAD  //GO.IN DD DISP=OLD,DSN=aaaaiii.name1  _____________  //GO.OUT DD DISP=(NEW,CATLG),UNIT=DATA,DSN=aaaaiii.name2,  _____________  // SPACE=(TRK,(p,s),RLSE),DCB=(RECFM=F,BLKSIZE=512)  ___  Replace aaaaiii with your Userid and c with an optional  _______ _  letter or number. Replace aaaaiii.name1 with the name of the  _____________  RECFM=U dataset. Replace aaaaiii.name2 with the name of the  _____________  RECFM=F dataset to be created.  HDF files created on an IBM system can be transferred as  binary files to any other system.   B. Changes Affecting Only Fortran   Matrix Storage Difference   The HDF routines are written in C. Matrices in C are stored  rowwise, while matrices in Fortran are stored columnwise.  You have to take this difference into consideration when  calling the HDF routines.   No Character String Constants   Do not pass character string constants to the HDF routines.  For example, to call this routine discussed earlier:  INTEGER FUNCTION DFSDgetdata(filename, rank, bufsizes, data)  ______________________________  code:  character*9 filename  ________  filename = 'dd:myfile'  ________ ______  .  .  .  i = dsgdata(filename, rank, bufsizes, data)  _ ______________________________  Do not code:  i = dsgdata('dd:myfile', rank, bufsizes, data)  _ ______ ____________________    - 5 - ¤  Shortened Names   From Fortran, you must use shortened names for the following  additional routines:  Name Shortened Name  DFR8addimage d8aimg  DFR8getdims d8gdims  DFR8getimage d8gimg  DFR8putimage d8pimg  DFR8restart d8first  DFR8setpalette d8spal   Fortran Callable Routines   The routines beginning with DF alone cannot be called from  Fortran. Those routines beginning DFR8, DFSD, and DFAN can  be called from Fortran.   IV. RUNNING HDF FROM C  To run HDF from C use the following JCL:  //aaaaiiic JOB job-parameters  ________ ______________  // EXEC CCLG,LEVEL=N,RG=nnnnK  ____  //C.USERLIB DD DSN=dsname,DISP=SHR  ______  ( C program )  //LKED.HDF DD DISP=SHR,DSN=APP1.HDF3.LOAD  //LKED.SYSIN DD  INCLUDE HDF(name1,name2,...)  _______________  //GO.ddname DD dd-parameters  ______ _____________  Replace aaaaiii with your Userid and c with an optional  _______ _  letter or number. Replace name1,name2,... with a list  _______________  containing any of the following:  DF - you always need these routines because they are  the "base level" or "common" routines that are  called by all the other routines  DFR8 - the 8-bit raster routines  DFSD - the scientific data routines  DFAN - the annotation routines  Remember that you cannot ask for both the DFR8 and the DFSD  routines at the same time.  Replace GO.ddname etc. with the DD statements for any files,  _________  including HDF files, you are reading or writing.   - 6 - ¤  V. RUNNING HDF FROM FORTRAN  To run HDF from Fortran use the following JCL:  //aaaaiiic JOB job-parameters  ________ ______________  // EXEC FORTCLG,RG=nnnnK,LIBB='APP1.C370IBMN.LIBRARY'  ____  ( FORTRAN program )  //LKED.HDF DD DISP=SHR,DSN=APP1.HDF3.LOAD  //LKED.SYSIN DD  INCLUDE HDF(name1,name2,...)  _______________  //GO.ddname DD dd-parameters  ______ _____________  Replace aaaaiii with your Userid and c with an optional  _______ _  letter or number. Replace name1,name2,... with any of the  _______________  following:  DFF - you always need these routines  DFR8F - the 8-bit raster routines  DFSDF - the scientific data routines  DFANF - the annotation routines  Remember that you cannot ask for both the DFR8F and the  DFSDF routines at the same time.  Replace GO.ddname etc. with the DD statement for any files,  _________  including HDF files, you are reading or writing.   VI. REFERENCES  1. MVS: Visualizing Supercomputer Scientific Data on  Macintoshes (OAC writeup SG22)           - 7 -