next up previous
Next: OBSOLETE ROUTINES
Up: ROUTINE DESCRIPTIONS
Previous: HDS_TUNE - Set HDS tuning parameter

   
HDS_WILD - Perform a wild-card search for HDS container files

Description:
The routine searches for HDS container files whose names match a given wild-card file specification, and which are accessible using a specified mode of access. It is normally called repeatedly, returning a locator for the top-level object in a new container file on each occasion, and a null locator value (DAT__NOLOC) when no more container files remain to be located.

In normal use, the IWLD argument should be set to the value DAT__NOWLD before the first call to HDS_WILD. The value returned through this argument subsequently identifies the search context, which is retained between calls. In this way, several wild-card searches may be performed concurrently if required.

A call to HDS_EWILD should be made to annul the search context identifier when the search is complete. This will release any resources used.

Invocation:
CALL HDS_WILD( FSPEC, MODE, IWLD, LOC, STATUS )

Arguments:
FSPEC = CHARACTER * ( * ) (Given)
The wild-card file specification identifying the container files required (a default file type extension of `.sdf' is assumed, if not specified). The syntax of this specification depends on the host operating system (see §[*]).
MODE = CHARACTER * ( DAT__SZMOD ) (Given)
The mode of access required to the container files: 'READ', 'UPDATE' or 'WRITE' (case insensitive).
IWLD = INTEGER (Given and Returned)
If a value of DAT__NOWLD is supplied on input, then a new wild-card search context will be started, a new value for IWLD will be returned, and the first HDS container file matching the file specification given in FSPEC will be located. If an IWLD value saved from a previous invocation of HDS_WILD is supplied, then the previous search context will be used and the next container file appropriate to that context will be located. In this case, the value of FSPEC is not used.
LOC = CHARACTER * ( DAT__SZLOC ) (Returned)
A primary locator to the top-level object in the next container file to satisfy the file specification given in FSPEC. A value of DAT__NOLOC will be returned (without error) if no further container files remain to be located.
STATUS = INTEGER (Given and Returned)
The global status.

Notes:
  • This routine does not return locators for files which are not valid HDS container files or which are not accessible using the specified access mode.
  • The routine takes a "snapshot" of the file system when it is first called (with IWLD set to DAT__NOWLD) and subsequently returns locators for each of the HDS container files found, one at a time. This strategy avoids possible run-away conditions if (say) output files created by an application were later to be selected by a wild-card search used to identify further input files.
  • An error may result if any file matched by an initial call to HDS_WILD (with IWLD set to DAT__NOWLD) cannot be accessed when a subsequent call requires that a locator be returned for it. This might happen, for instance, if the file has been deleted in the intervening time. If the resulting error condition is annulled, the offending file may be skipped and subsequent calls to HDS_WILD will continue to locate any remaining files.
  • An error will result and a STATUS value of DAT__FILNF will be returned if no HDS container files can be found which match the wild-card specification supplied on an initial call to HDS_WILD.
  • A value of DAT__NOLOC will be returned for the LOC argument if this routine is called with STATUS set, or if it should fail for any reason. In addition, the value of IWLD will be returned unchanged if the routine is called with STATUS set or if failure should occur during an initial call (i.e. when IWLD is set to DAT__NOWLD on entry).
  • The DAT__NOLOC and DAT__NOWLD constants are defined in the include file DAT_PAR. The DAT__FILNF error code is defined in the include file DAT_ERR.



next up previous
Next: OBSOLETE ROUTINES
Up: ROUTINE DESCRIPTIONS
Previous: HDS_TUNE - Set HDS tuning parameter

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