next up previous
Next: MAPPING CHARACTER DATA
Up: HDS Hierarchical Data System
Previous: WRITING AND READING OBJECTS

ACCESSING OBJECTS BY MAPPING   

Another technique for accessing values stored in primitive HDS objects is termed "mapping".[*] An important advantage of this technique is that it removes a size restriction imposed by having to declare fixed size program arrays to hold data. This simplifies software, so that a single routine can handle objects of arbitrary size without recourse to accessing subsets.

HDS provides mapped access to primitive objects via the DAT_MAP routines. Essentially DAT_MAP will return a pointer to a region of the computer's memory in which the object's values are stored. This pointer can then be passed to another routine using the (non-standard, but widely available) Fortran "%VAL" facility,[*] together with the CNF_PVAL function[*] (described in SUN/209) which is defined in the CNF_PAR include file. An example will illustrate this:

 
      ...
      INCLUDE 'CNF_PAR'
      INTEGER PNTR, EL

*  Map the DATA_ARRAY component of the NDF structure as a vector of type
*  _REAL (even though the object is actually a 512 x 1024 array whose
*  elements are of type _UBYTE).
      CALL DAT_FIND( NLOC, 'DATA_ARRAY', LOC, STATUS )
      CALL DAT_MAPV( LOC, '_REAL', 'UPDATE', PNTR, EL, STATUS )

*  Pass the "array" to a subroutine.
      CALL SUB( EL, %VAL( CNF_PVAL( PNTR ) ), STATUS )

*  Unmap the object and annul the locator.
      CALL DAT_UNMAP( LOC, STATUS )
      CALL DAT_ANNUL( LOC, STATUS )

      END

*  Routine which takes the LOG of all values in a REAL array.
      SUBROUTINE SUB( N, A, STATUS )
      INCLUDE 'SAE_PAR'
      INTEGER N, STATUS
      REAL A( N )
      IF ( STATUS .NE. SAI__OK ) RETURN

      DO 1 I = 1, N
         A( I ) = LOG( A( I ) )
 1    CONTINUE

      END

This example illustrates two features of HDS which we haven't already mentioned:

Vectorisation:
It is possible to force HDS to regard objects as vectors, irrespective of their true shape. This facility was useful in the above example as it made the subroutine SUB much more general in that it could be applied to any numeric primitive object.
 Automatic type conversion:
The program can specify the data type it wishes to work with and the program will work even if the data is stored as a different type. HDS will (if necessary) automatically convert the data to the type required by the program.[*] This useful feature can greatly simplify programming - simple programs can handle all data types. Automatic conversion works on reading, writing and mapping.

Note that once a primitive has been mapped, the associated locator cannot be used to access further data until the original object is unmapped.



next up previous
Next: MAPPING CHARACTER DATA
Up: HDS Hierarchical Data System
Previous: WRITING AND READING OBJECTS

HDS Hierarchical Data System
Starlink User Note 92
R.F. Warren-Smith & M.D. Lawden
23rd February 1999
E-mail:rfws@star.rl.ac.uk

Copyright (C) 1999 Central Laboratory of the Research Councils