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.
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.