next up previous
Next: ENQUIRIES
Up: USING LOCATORS
Previous: Container File Reference Counts

Promoting and Demoting Locators   

A locator may, at any time, be "promoted" to become a primary locator (thus incrementing the container file's reference count) or "demoted" to become a secondary locator (and decrementing the reference count). This is done by using the DAT_PRMRY routine with its (first) SET argument set to .TRUE., thus:

      PRMRY = .TRUE.             ! Promote the locator
      CALL DAT_PRMRY( .TRUE., LOC, PRMRY, STATUS )

With its first argument set to .FALSE., the same routine may also be used to enquire whether a locator is primary or not.

The main reason for promoting locators is to allow HDS objects to be passed between routines while ensuring that the associated container file remains open, so that the object remains accessible. For example, consider the following simple routine which returns a locator for a named object inside a container file:

      SUBROUTINE FINDIT( FILE, LOC, STATUS )

      <declarations, etc.>

*  Open the container file and find the required object.
      CALL HDS_OPEN( FILE, 'READ', TMPLOC, STATUS )
      CALL DAT_FIND( TMPLOC, 'MY_OBJECT', LOC, STATUS )

*  Promote the new locator and annul the original.
      CALL DAT_PRMRY( .TRUE., LOC, .TRUE., STATUS )
      CALL DAT_ANNUL( LOCTMP, STATUS )
      END

Note how the temporary locator returned by HDS_OPEN is annulled after first promoting the secondary locator derived from it, so that the container file remains open. If this is the first time the file has been opened, its reference count will be 1 when this routine exits, so it will be closed when the caller later annuls the returned locator LOC.



next up previous
Next: ENQUIRIES
Up: USING LOCATORS
Previous: Container File Reference Counts

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