home *** CD-ROM | disk | FTP | other *** search
/ Photo CD Demo 1 / Demo.bin / hdf / migratin.txt next >
Text File  |  1980-02-06  |  27KB  |  802 lines
  1. The following "migration notes" should help you switch over
  2. from HDF 3.1 to HDF 3.2.  These notes should be used as a
  3. supplement the the manuals "HDF Calling Interfaces and Utilities"
  4. and "HDF Vset."
  5.  
  6. This version of the MigrationNotes supercedes the version that
  7. was distributed with HDF 3.2 Release 1.  It contains the
  8. following additional material:
  9.  
  10.          1. Description of a calibration tag that can be
  11.             used to store information about how data in 
  12.             an SDS has been calibrated, or normalized. Two
  13.             new routines are available for storing and
  14.             retrieving calibration information.
  15.  
  16.          2. Description of a routine to test whether an SDS
  17.             in a file was written by HDF3.2 or a previous release. 
  18.             
  19.          3. Explanation of changes in the return values for 
  20.             VSsetfields() and VSinquire().
  21.  
  22.          4. Explanation of changes in argument types
  23.             for the routines VSwrite and VSread.
  24.  
  25.  
  26.  
  27.  
  28.  
  29.                        HDF 3.2 Release 2
  30.                         Migration Notes
  31.                         ===============
  32.  
  33. This is a preliminary document describing the differences 
  34. between HDF 3.2 release 2 and earlier versions of HDF.  
  35. It is written for people who already use HDF 3.1 (or earlier 
  36. versions), and wish to migrate to HDF 3.2.  Special emphasis 
  37. is given to changes that might be required in existing code.  
  38. HDF3.2r1 users will find in these notes the information about 
  39. the changes between HDF3.2r1 and HDF3.2r2.
  40.  
  41. Documentation is now being written that more fully explains 
  42. this new version of HDF.  If you have any questions or 
  43. comments, please send them to sxu@ncsa.uiuc.edu.
  44.  
  45. Table of contents:
  46.  
  47.          Platforms Supported
  48.          SDS Interface
  49.             New number types
  50.             Arrays no longer transposed
  51.             Calibration tag
  52.          RIS8 Interface
  53.          RIS24 Interface
  54.          Palette Interface
  55.          Annotations Interface
  56.          Vset Interface
  57.          General Purpose Interface
  58.          Old General Purpose Interface
  59.          Test Modules
  60.  
  61.  
  62.  
  63.                       Platforms Supported
  64.                       ===================
  65.  
  66. HDF 3.2 is supported on the following platforms:
  67.  
  68.         Platform        Machine Type
  69.         --------        ------------
  70.         Sun-4           SUN
  71.         Cray-2          UNICOS
  72.         Cray-Y/MP       UNICOS
  73.         Convex          CONVEX
  74.         SGI Iris 4D     IRIS4
  75.         IBM RS/6000     IBM6000
  76.         DECstation 3100 MIPSEL
  77.         DECstation 5000 MIPSEL
  78.         Vax/VMS         VMS
  79.         HP 9000         HP9000
  80.         Macintosh       MAC    
  81.         IBM PC/clone    PC    
  82.         NeXT            NEXT
  83.         Convex native   CONVEXNATIVE
  84.           format
  85.  
  86. These ports include the full HDF library (C and FORTRAN interfaces, 
  87. where appropriate), and the following utilities: hdfls, hdfrseq, 
  88. ristosds, hdfpack, hdfcomp, hdftor8, r8tohdf, hdf24hdf8, hdftopal, 
  89. and paltohdf.  Hdfed has been ported to some platforms.  Fp2hdf 
  90. has not yet been ported.
  91.  
  92.  
  93.                          SDS Interface
  94.                          =============
  95.  
  96. This interface has undergone the most changes that affect 
  97. typical users. Some of them may necessitate changes to 
  98. your code.  Here is an outline of this section:
  99.  
  100.     (1) New number types
  101.  
  102.          - DFSDsetNT (dssnt) and DFSDgetNT (dsgnt)
  103.          - DFSDsetrange (dssrang) and DFSDgetrange (dsgrang)
  104.          - New Tag
  105.          - Backward compatibility
  106.  
  107.     (2) Arrays no longer transposed
  108.          - Implications of change to "no-transpose"
  109.          - DFSDpre32 (dspre32)
  110.  
  111.     (3) Calibration tag
  112.  
  113.  
  114.     The two biggest changes are: (1) the addition of 
  115. support for new number types in SDS, and (2) changes to SDS 
  116. so that the code no longer transposes arrays. 
  117.  
  118. These changes, which are described in detail below, have 
  119. necessitated some changes in the SDS interface.
  120.  
  121. THE FOLLOWING ROUTINES ARE NO LONGER SUPPORTED:
  122.  
  123.    DFSDsettype (dsstype)
  124.    DFSDsetmaxmin (dssmaxm)
  125.    DFSDgetmaxmin (dsgmaxm)
  126.  
  127. THE FOLLOWING NEW ROUTINES HAVE BEEN ADDED:
  128.  
  129.    DFSDsetNT (dssnt)      tells which number type is to be 
  130.                           used for next DFSDadddata or 
  131.                           DFSDputdata; replaces DFSDsettype
  132.  
  133.    DFSDgetNT (dsgnt)      determines number type of current 
  134.                           SDS
  135.  
  136.    DFSDsetrange (dssrang) specifies max and min values of 
  137.                           next SDS to be written; replaces
  138.                           DFSDsetmaxmin
  139.  
  140.    DFSDgetrange (dsgrang) determines max and min values of 
  141.                           current SDS; replaces DFSDgetmaxmin
  142.  
  143.    DFSDpre32 (dspre32)    tests if the current SDS was written 
  144.                           by HDF3.2 or a previous release. 
  145.  
  146. (NOTE: DFSDsettype also was used to set the storage order of 
  147. SDS data.  This function is no longer needed, as explained in 
  148. the section "(2) Arrays no longer transposed.")
  149.  
  150.  
  151.  
  152. (1) New number types
  153.     ----------------
  154.  
  155. The previous SDS interface allowed storage of 32-bit floats 
  156. and Cray native mode floats only.  The HDF 3.2 SDS interface 
  157. has been expanded to handle  8-bit, 16- bit, and 32-bit 
  158. integers, 32-bit and 64-bit floats, and native mode for all 
  159. of these.
  160.  
  161. In the C interface, integers can be signed or unsigned.  In 
  162. the FORTRAN interface, there is no distinction, so all 
  163. integers are assumed to be signed.  The names used to 
  164. describe the new data types are
  165.  
  166.     int8        8-bit signed integer
  167.     uint8       8-bit unsigned integer (C only)
  168.     int16      16-bit signed integer
  169.     uint16     16-bit unsigned integer (C only)
  170.     int32      32-bit signed integer
  171.     uint32     32-bit unsigned integer (C only)
  172.     float32    32-bit float
  173.     float64    64-bit float
  174.  
  175. DFSDsetNT (dssnt) and DFSDgetNT (dsgnt)
  176. ---------------------------------------
  177.  
  178. To handle the new data types, the DFSDsettype routine has 
  179. been replaced by DFSDsetNT.  DFSDsetNT must be called if a 
  180. number type other than float32 is to be stored.  DFSDsetNT 
  181. and DFSDsetdims can be called in any order, but they should 
  182. be called before any other  "DFSDset" functions and before 
  183. DFSDputdata or DFSDadddata.
  184.  
  185. Valid parameter values for DFSDsetNT (e.g. DFNT_INT8) are 
  186. defined in the file hdf.h.  They are of the general form 
  187. "DFNT_<numbertype>", all capital letters.  
  188.  
  189. DFSDgetNT allows you to query about the number type of the 
  190. SDS that is current.  As with other "DFSDget..." routines, 
  191. you must call DFSDgetdims, or DFSDgetdata to "move to" a 
  192. particular SDS before calling DFSDgetNT.  
  193.  
  194. These routines are illustrated in the following examples:
  195.  
  196. For example:
  197.  
  198. C:
  199.     DFSDsetNT(DFNT_INT8);
  200.     DFSDadddata("myfile.hdf", rank, dims, i8data);
  201.     ...
  202.     DFSDgetdims("myfile.hdf", rank, dimsizes, 3);
  203.     DFSDgetNT(&numtype);
  204.  
  205.  
  206. FORTRAN:
  207.     ret  = dssnt(DFNT_INT8)
  208.     ret = dsadata('myfile.hdf', rank, dims, i8data)
  209.     ...
  210.     ret = dsgdims('myfile.hdf', rank, dimsizes, 3)
  211.     ret = dsgnt(numtype)
  212.  
  213.  
  214. DFSDsetrange (dssrang) and DFSDgetrange (dsgrang)
  215. -------------------------------------------------
  216.  
  217. The obsolete routines DFSDsetmaxmin and DFSDgetmaxmin assumed
  218.  that all numbers were floating point, and these routines were 
  219. hard- coded accordingly.  Now that the maximum and minimum 
  220. values can be of different number types, the corresponding 
  221. parameters can have different number types.  Because of this 
  222. it was necessary to redefine the parameters in the C versions 
  223. of the routines from 'floats' to pointers.  To avoid 
  224. confusion, and possible undetected errors, these routines 
  225. have been replaced by DFSDsetrange and DFSDgetrange, as 
  226. illustrated in the following examples, in which 16-bit data 
  227. is written to an HDF file.
  228.  
  229. C:
  230.     int16 max, min;  /* max and min must be the same */
  231.                      /* data type as the SDS array */
  232.      .
  233.      .
  234.     DFSDsetrange(&max, &min);
  235.     DFSDadddata("myfile.hdf", rank, dims, data);
  236.     ...
  237.     DFSDgetdims("myfile.hdf", rank, dimsizes, 3);
  238.     DFSDgetrange(&max, &min);
  239.  
  240.     NOTE: The arguments to DFSDsetrange and DFSDgetrange
  241.           are now pointers, rather than simple variables.
  242.           This is required because they must be able to
  243.           pass different types of variables.
  244.  
  245. FORTRAN:
  246.     ret = dssrang(max, min)
  247.     ret = dsadata('myfile.hdf', rank, dims, data)
  248.     ...
  249.     ret = dsgdims('yourfile.hdf', rank, dimsizes, 3)
  250.     ret = dsgrang(max, min)
  251.  
  252. Since the max/min values are supposed to relate to the data 
  253. itself, it is assumed that the type of max/min is the same as 
  254. the type of the data.  The same assumption is made for 
  255. scales, although eventually an option is planned to allow 
  256. scale number types that are different from data number types.
  257.  
  258.  
  259. New tag
  260. -------
  261.  
  262. In order to support the new number types and at the same time 
  263. make it easier to add new features (e.g. data compression) to 
  264. future versions of SDS, a new structure for the SDG 
  265. (scientific data group) and some new tags have been 
  266. implemented.  The new structure is called NDG, for "numeric 
  267. data group", and has the tag DFTAG_NDG (720).  The NDG 
  268. structure will be described in detail in the next edition of 
  269. the manual "HDF Specifications."
  270.  
  271.  
  272. Backward compatibility
  273. ----------------------
  274.  
  275. To maintain backward compatibility, HDF examines each new NDG 
  276. that it writes to a file to determine whether it is backward 
  277. compatible with the old SDG structure (float32 data only, 
  278. etc.), and if it is, writes out an SDG as well as an NDG.  A 
  279. new "link tag" (710) stored in the NDG tells HDF that it 
  280. represents the same SDS as the corresponding SDG.
  281.  
  282.  
  283. (2) Arrays no longer transposed
  284.     ---------------------------
  285.  
  286. In earlier versions of HDF the SDS interface would, by 
  287. default, transpose arrays written by FORTRAN programs so that 
  288. matrices that were declared the same way in C and FORTRAN 
  289. programs would be stored with the same physical ordering in 
  290. an HDF file.  This caused a great deal of confusion among HDF 
  291. users, and often resulted in very inefficient program 
  292. execution, so it was decided with release 3.2 to eliminate 
  293. array transposition.  This means that the way you dimension 
  294. arrays, and the way you pass dimensions to HDF routines may 
  295. have to change.
  296.  
  297. Implications of change to "no-transpose"
  298. ---------------------------------------
  299.  
  300. Here is a synopsis of the implications of this change.
  301.  
  302.   1. SDS C calls should appear the same as they appeared in 
  303. HDF 3.1 and earlier versions.
  304.  
  305.   2. SDS FORTRAN calls should appear the same as they 
  306. appeared in HDF 3.1 and earlier versions.  (NOTE: For users 
  307. of HDF 3.2 beta dfsd_notranspose.c, see point No. 5 below.) 
  308.  
  309.   3. HDF 3.2 stores SDS data arrays in HDF files in the same 
  310. order as they are stored in memory, without transposition. 
  311. This is done even when the SDS are written by the FORTRAN 
  312. interface.
  313.  
  314.   4.  Dimension sizes, scales, labels, units and formats for 
  315. each dimension are written to 3.2 HDF files in C order, from 
  316. slowest changing dimension to the fastest changing dimension.  
  317. It follows from this that if you want to maintain 
  318. compatibility between C and FORTRAN (for instance, when an 
  319. SDS is written out by a C program, then read in by a FORTRAN 
  320. program), you'll need to reverse, in Fortran programs, the 
  321. dimension specifications for dimension-related information 
  322. (array dimensions, scales, labels, units, and formats) 
  323. from what they were in the corresponding C program.  
  324.  
  325. For example, suppose the following calls are made in a C 
  326. program:
  327.  
  328.    float data[4][5][6];
  329.    int dimsizes[3];
  330.    dimsizes[0] = 4;
  331.    dimsizes[1] = 5;
  332.    dimsizes[2] = 6;
  333.    strcpy(label1, "pressure");
  334.  
  335.    DFSDsetdims(3, dimsizes);
  336.    DFSDsetdimstrs(1, label1, unit1, format1);
  337.    DFSDadddata("myfile.hdf", 3, dimsizes, data);
  338.  
  339. In a FORTRAN program that reads back this information, 
  340. references to dimensions are reversed, as illustrated in the 
  341. following:
  342.  
  343.    real data(6,5,4)
  344.    integer dimsizes(3)
  345.    dimsizes(1) = 6
  346.    dimsizes(2) = 5
  347.    dimsizes(3) = 4
  348.  
  349.  
  350.    dsgdat('myfile.hdf', 3, dimsizes, data)
  351.    dsgdist(3, label, unit, format)
  352.  
  353. After calling dsgdist, the value assigned to label is 
  354. "pressure."
  355.  
  356. 5. FOR USERS OF HDF 3.2 BETA, dfsd_notranspose.c:  In 
  357. dfsd_notranspose.c, the ordering of dimensions in the 
  358. 'dimsizes' parameter was the reverse of what it had been in 
  359. HDF 3.1.  The confusion that this caused for users led to our 
  360. changing back, so that now the dimensions in the dimsizes 
  361. parameter are the same as they were in HDF 3.1 and before, 
  362. where the order of dimensions in dimsizes is the same as it 
  363. is in array declarations.  This is illustrated in the example 
  364. above.  (We sincerely regret the inconvenience that this 
  365. causes early users of HDF 3.2beta dfsd_notranspose.c.)
  366.  
  367.  
  368.   6. HDF 3.2 will read an SDS from HDF 3.1 files in the way 
  369. that HDF 3.1 does, so that old files can be read by the new 
  370. library without any extra programming.  This means that 
  371. aberrations in the way HDF 3.1 read old, transposed files 
  372. continue in HDF 3.2.  This is done to maintain consistency 
  373. for those users who wrote their code specifically to 
  374. accommodate these aberrations.
  375.  
  376. NOTE: Although we have made our best effort with HDF 3.2 to 
  377. maintain backward compatibility, we are aware that some of 
  378. these changes will cause difficulty, especially when old 
  379. programs need to be changed to accommodate the new ordering.  
  380. Please contact us if we can help you smooth the transition 
  381. to HDF 3.2.
  382.  
  383. DFSDpre32 (dspre32)
  384. -------------------
  385.  
  386. In HDF 3.1 and earlier versions, when an SDS is written from 
  387. a Fortran program, the data is transposed to keep the dimension 
  388. and data arrays in C order. Accordingly, when a Fortran program 
  389. reads an SDS from an hdf file, it transposes the data back. 
  390. This is fine as long as a FORTRAN program is reading the data
  391. back. But, when a C program reads the SDS, the data is transposed 
  392. compared to the original array. In order to handle this problem, 
  393. some C programmers have written their own routines to transpose 
  394. the data array and the dimensions.
  395.  
  396. HDF3.2 no longer transposes data when it is written from Fortran 
  397. programs. So now, some C programmers need to know whether the 
  398. SDS was written by HDF3.1 or HDF3.2, and then decide whether or
  399. not to call the transpose routine. HDF3.2r2 supplies a function 
  400. DFSDpre32() and its Fortran version dspre32(). It tests whether 
  401. the current SDS was written by HDF3.2 or by HDF3.1r5 and previous 
  402. releases. 
  403.  
  404. Function: DFSDpre32(void) and dspre32(void) 
  405.  
  406. returns: TRUE (1) if the SDS was written by previous version, 
  407. FALSE (0) otherwise.
  408.  
  409. Remarks: This routine can be called only after DFSDgetdims(), 
  410. DFSDgetdata() or DFSDgetslice() was called.
  411.  
  412.  
  413. (3) Calibration Tag
  414.     ---------------
  415.  
  416.  
  417. HDF 3.2 release 2 supports a new tag for calibrating the data in 
  418. an SDS.  The  calibration tag has the following specification:
  419.  
  420.  
  421.   SDCAL   Scientific data offset and calibration
  422.           record size: 36 bytes
  423.           tag number:731
  424.  
  425.           This record contains four 64-bit floating point
  426.           values followed by a 32-bit integer, to be interpreted 
  427.           as follows:
  428.  
  429.            cal       calibration factor
  430.            cal_err   calibration error
  431.            ioff      uncalibrated offset
  432.            ioff_err  uncalibrated offset error
  433.            cal_nt    numbertype of uncalibrated data
  434.  
  435. The relationship between a value 'iy' stored in an SDS and the 
  436. actual value is defined as:
  437.  
  438.     y = cal * (iy - ioff)
  439.  
  440. The variable ioff_err contains a potential error of ioff, and 
  441. cal_err contains  a potential error of cal.  Currently the tag is 
  442. provided for information only.   The SDS interface performs no 
  443. operations on the data based on the calibration  tag.
  444.  
  445. Two new routines have been added to the SDS interface for storing 
  446. and  retrieving calibration information. The C versions are 
  447. defined as follows:
  448.  
  449.     int DFSDsetcal(float64 cal, float64 cal_err, float64 ioff,
  450.                                  float64 ioff_err, int32 cal_nt)
  451.  
  452.     int DFSDgetcal(float64 *pcal, float64 *pcal_err, 
  453.                float64 *pioff,  float64 *pioff_err, int32 *cal_nt)
  454.  
  455. The FORTRAN versions are defined as follows:
  456.  
  457.       integer function dsscal(cal, calerr, ioff, iofferr, ctype)
  458.       real*8    cal,  calerr,  ioff,  iofferr
  459.       integer*4 ctype
  460.  
  461.       int DFSDgetcal(cal, calerr, ioff, iofferr, ctype)
  462.       real*8 ical, icale, iioff, iioffe
  463.       integer*4 ctype
  464.  
  465. DFSDsetcal works like other SDS 'set' routines, with one  
  466. exception: calibration information is automatically cleared 
  467. after call to  DFSDputdata or DFSDadddata.  Hence, DFSDsetcal 
  468. must be called anew for each  data set that is to be written.
  469.  
  470. In the following examples a 100x100 array of 16-bit integers is 
  471. stored in an  SDS, together with calibration information 
  472. indicating that the values in the  array should be converted to 
  473. 32-bit floats, and each value should be  multiplied by 10.0 then 
  474. added to 16.75.
  475.  
  476. /************************* C example **************************/
  477. /*                                                            */
  478.  
  479. #include "hdf.h"
  480.     ...
  481.     int16   i16[100][100], ti16[100][100];
  482.     float64 cal, cale, ioff, ioffe, ical, icale, iioff, iioffe
  483.     int32   calNT, icalNT
  484.     ...
  485.     cal   = 10.0;
  486.     cale  =  0.0;
  487.     ioff  = 16.75;
  488.     ioffe = 7.8
  489.     calNT = DFNT_FLOAT32;
  490.     ...
  491.     DFSDsetNT(DFNT_INT16);
  492.     DFSDsetcal(cal, cale, ioff, ioffe, calNT);
  493.     DFSDputdata("myfile.hdf", rank, dims, i16);
  494.     ...
  495.     DFSDgetdata("ntcheck.hdf", rank, dims, tf32);
  496.     DFSDgetcal(&ical,&icale, &iioff, &iioffe, &icalNT);
  497.     ...
  498.  
  499. C******************** FORTRAN example ***********************
  500. C 
  501.  
  502.       integer dsadata, dspdata, dssnt, dsscal, dsgcal
  503.       integer DFNT_FLOAT32, DFNT_INT16
  504.       real*8 cal,  cale,  ioff,  ioffe, ical, icale, iioff, iioffe
  505.       integer*4 ctype, ictype
  506.       integer*2 i16(100,100), ti16(100,100)
  507.  
  508.       DFNT_INT16 = 22
  509.       DFNT_FLOAT32 = 5
  510.       ...
  511. C
  512. C Set up calibration info
  513. C
  514.       cal   = 10.0
  515.       cale  = 0.0
  516.       ioff  = 16.75
  517.       ioffe = 47.8
  518.       ctype = DFNT_FLOAT32
  519. C
  520. C  Write array and calibration information to HDF file
  521. C
  522.       err1  = dssnt(DFNT_INT16)
  523.       err2 = dsscal(cal, cale, ioff, ioffe, ctype)
  524.       err3 = dsadata('of.hdf', rank, dims, i16)
  525.       ...
  526. C
  527. C  Read back array and calibration information from HDF file
  528. C
  529.       err1 = dsgdata('of.hdf', rank, dims, ti16)
  530.       err2 = dsgcal(ical, icale, iioff, iioffe, ictype)
  531.       ...
  532.  
  533.  
  534.                          RIS8 Interface
  535.                          ==============
  536.  
  537. Only one small change: DFR8lastref is now available in both C 
  538. and FORTRAN.
  539.  
  540.  
  541.                         RIS24 Interface
  542.                         ===============
  543.  
  544. No changes.
  545.  
  546.  
  547.                        Palette Interface
  548.                        =================
  549.  
  550. No changes.
  551.  
  552.  
  553.                      Annotations Interface
  554.                      =====================
  555.  
  556.  
  557. The following annotations interface routines require 
  558. programmers to explicitly handle the opening and closing of 
  559. files.  
  560.  
  561.    DFANaddfid
  562.    DFANaddfds
  563.    DFANgetfidlen
  564.    DFANgetfid
  565.    DFANgetfdslen
  566.    DFANgetfds
  567.  
  568. In the past, this was accomplished by calling DFopen() and 
  569. DFclose(), which use a structure called a DF.  In HDF 3.2 the 
  570. DF structure is no longer in use, and the annotation routines 
  571. mentioned above have instead been modified to accept the new-
  572. style int32 "file handle" (discussed in the section "General 
  573. Purpose Interface").  
  574.  
  575. For this reason, 
  576.  
  577.    PROGRAMMERS WHO PREVIOUSLY USED DFopen() AND DFclose() 
  578.    IN CONJUNCTION WITH THE ANNOTATIONS INTERFACE SHOULD USE 
  579.    Hopen() AND Hclose() TO DO FILE OPENING AND CLOSING. 
  580.  
  581. Hopen() takes the same arguments as DFopen(), but returns an 
  582. int32 file handle, which is suitable for use with the newly 
  583. modified annotations routines and Hclose().
  584.  
  585.  
  586. These changes are illustrated in the following examples.
  587.  
  588. C:
  589.     #include "hdf.h"
  590.     #define MAXLEN 50
  591.     #define ISFIRST 1
  592.     int32 file_id, ret;
  593.     char  tempstr[MAXLEN];
  594.     .
  595.     .
  596.     .
  597.     file_id = Hopen("myfile.hdf", DFACC_WRITE, 0);
  598.     ret = DFANaddfid(file_id, "some label");         
  599.     ret = DFANaddfds(file_id, "some description", 
  600.                       strlen("some description"));
  601.     ret = Hclose(file_id);
  602.     .
  603.     .
  604.     .
  605.     file_id = Hopen("myfile.hdf", DFACC_READ, 0);
  606.     ret = DFANgetfidlen(file_id, 1);
  607.     ret = DFANgetfid(file_id, tempstr, MAXLEN, ISFIRST);
  608.     ret = DFANgetfdslen(file_id, 1);
  609.     ret = DFANgetfds(file_id, tempstr, MAXLEN, ISFIRST);
  610.     ret = Hclose(file_id);
  611.  
  612.  
  613. FORTRAN:
  614.  
  615.       integer DFACC_WRITE, DFACC_READ, MAXLEN, ISFIRST
  616.       integer fid, ret
  617.       character*100 tempstr
  618.       MAXLEN = 50
  619.       ISFIRST = 1
  620.       DFACC_WRITE = 2
  621.       DFACC_READ = 1
  622.       .
  623.       .
  624.       .
  625.       fid = hopen('myfile.hdf', DFACC_WRITE, 0)
  626.       ret = daafid(fid, 'some label')
  627.       ret = daafds(fid, 'a description',len('a description'))
  628.       ret = hclose(fid)
  629.       .
  630.       .
  631.       .
  632.       fid = hopen('myfile.hdf', DFACC_READ, 0)
  633.       ret = dagfidl(fid, ISFIRST)
  634.       ret = dagfid(fid, templab, MAXLEN, ISFIRST)
  635.       ret = dagfdsl(fid, ISFIRST)
  636.       ret = dagfds(fid, tempstr, MAXLEN, ISFIRST)
  637.       ret = hclose(fid)
  638.  
  639.  
  640.                         Vset Interface
  641.                         ==============
  642.  
  643.  
  644. Several changes are to be noted in the Vset interface:
  645.  
  646.  
  647. 1. Previously, the Vset calling interface had its own 
  648. library.In HDF 3.2, the Vset calling interface is contained 
  649. in the same library as the other HDF interfaces.
  650.  
  651. 2. The most important change to the Vset interface is that the 
  652. constants for data types have changed.  Previously the types 
  653. of data had been specified with constants such as 
  654. 'LOCAL_INTTYPE'.  This was a problem in two ways:
  655.  
  656.   1) Not every machine's local integer is the same size, but
  657.      Vsets treated them all as the same.
  658.  
  659.   2) It made the Vset interface incompatible with the new
  660.      data conversion routines used by all of the other
  661.      interfaces.
  662.  
  663. So, with this release, rather than specifying the type of 
  664. data as 'LOCAL_XXXTYPE' you should now use the same type 
  665. specifier as if you were storing the data through the SDS 
  666. interface:
  667.  
  668. DFNT_INT8, DFNT_INT16, DFNT_INT32, DFNT_FLOAT32, etc.
  669.  
  670.  
  671. Vsets also now allow the modification of existing VDatas.  By 
  672. attaching to an existing VData with write access you are now 
  673. able to seek (via VSseek()) to any location and place new 
  674. data (via VSwrite()).  
  675.  
  676. It is also possible to seek beyond the end of an existing 
  677. vdata and write data leaving gaps of non-data areas with a 
  678. vdata. The Vset interface does not keep track of the gaps, 
  679. and as such, care must be taken when reading in from such 
  680. vdatas.
  681.  
  682. 3.  When opening a file for vset operations, you need to
  683. open the file using Hopen, then perform some initialization 
  684. for the vset operations.  Hence, you will need to make the 
  685. following sequence of calls:
  686.  
  687.      f = Hopen (fname, access, defDDs);
  688.      Vinitialize(f);
  689.  
  690. Similarly, before closing a file on which vset operations
  691. were performed, call Vfinish before calling Hclose, as in:
  692.  
  693.      Vfinish(f);
  694.      Hclose(f);
  695.  
  696.  
  697. 4. VSsetfields() and VSinquire() now return the value SUCCEED 
  698. (0) on success.  This used to be 1.
  699.  
  700.  
  701. 5. The new versions of some VSET functions require a (BYTE *) 
  702. cast in their actual argument list, most notably:
  703.  
  704.        VSwrite(vs, (BYTE *) buf, nv4, NO_INTERLACE);
  705.  
  706.        VSread(vs, (BYTE *) buf, nelt, interlace);
  707.  
  708.  
  709.  
  710.                  General Purpose Interface
  711.                  =========================
  712.  
  713. The lower layer of HDF has been completely redesigned and re-
  714. implemented, and all application interfaces, such as RIS8 and
  715. SDS, have been re-implemented on this layer.  The new lower
  716. layer incorporates the following improvements:
  717.  
  718.     - More consistent data and function types
  719.     - More meaningful and extensive reporting of errors.
  720.     - Simplification of key lower level functions
  721.     - Improved techniques for facilitating portability
  722.     - Support for alternate forms of physical storage, such
  723.       as linked blocks storage, and storage of the data
  724.       portion of an object in an external file.
  725.     - A version tag indicating which version of the HDF
  726.       library last changed an HDF file.
  727.     - Hooks to support simultaneous access to multiple files
  728.  
  729. Changes most likely to affect users' programs
  730. ---------------------------------------------
  731.  
  732. Since users do not normally access the general purpose layer 
  733. of HDF, most changes will not affect users.  However, a few 
  734. changes should be noted:
  735.  
  736.   (1) Hopen should be used instead of DFopen
  737.  
  738.   (2) Hclose should now be used instead of DFclose
  739.  
  740.   (3) File handles are now of type int32, rather than
  741.       pointers.  Thus, Hopen returns a value of type
  742.       int32, and all routines that previously had arguments
  743.       of type "DF *" now take arguments of type int32
  744.       instead.  The routines that this is most likely to
  745.       affect for most users are DFfindnextref and the 
  746.       annotation routines that involve file labels and 
  747.       descriptions (see "Annotations Interface").
  748.  
  749.   (4) There is no FORTRAN version of this interface.
  750.  
  751.   (5) Hnumber should now be used instead of DFnumber.
  752.  
  753.   (6) Hishdf should now be used instead of DFishdf.
  754.  
  755. Details of the new interface are currently being documented 
  756. and will be available soon.
  757.  
  758.  
  759.                   Old General Purpose Interface
  760.                   =============================
  761.  
  762. Although the previous general purpose interface has been 
  763. replaced by the new general purpose routines, backward 
  764. compatibility is maintained by a set of routines that emulate 
  765. the old routines.  All of the old routines that begin with 
  766. the letters "DF" (DFopen, DFclose, DFgetelement, etc.) have 
  767. been rewritten on top of the new "H" layers.  Users who 
  768. currently use the "DF" routines should be able to continue to 
  769. use them, although they are encouraged to switch to using the 
  770. new "H" routines as soon as possible.
  771.  
  772.  
  773.                         Test Modules
  774.                         ============
  775.  
  776. In an effort to work towards having an HDF "test suite", a 
  777. number of test modules are included with HDF 3.2. Following 
  778. is a list of the test files currently in the test suite.  
  779. There are C and a FORTRAN versions for all of these test 
  780. routines, except those that test general purpose routines.
  781.  
  782. trig       RIS8, RIS24, and Palette interface
  783. tan        Object annotations
  784. tanfile    File annotations
  785. tsdmms     SDS max/min and scales
  786. tsdnmms    SDS max/min and scales, new number types
  787. tsdnt      SDS new number types (HDF standard formats)
  788. tsdnnt     SDS new number types (native mode)
  789. tsdstr     SDS dimstrs and datastrs routines
  790. tv1        Vsets:  vgroup and vdata creation routines
  791. tv2        Vsets: creating vsets in 2 different files
  792. egchi      Vsets: high level routines
  793. tvers      Version tag reading and writing
  794. thfile     General purpose routines
  795. thfile1    Limits on open files and access elements
  796. terr       Err-handling routines
  797. thblocks   Routines for storing objects as linked blocks
  798. thextelt   Storing HDF objects as external elements
  799. tlinkage   Test linkage of functions
  800. tstubs     Stubs that emulate old general routines
  801.  
  802.