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:
Note that once a primitive has been mapped, the associated locator cannot be used to access further data until the original object is unmapped.
HDS Hierarchical Data System