Lexical Functions - F$SEARCH

In this article, we examine the F$SEARCH lexical function, which is used to do file lookups. Here is the definition.

F$SEARCH searches a directory for a passed file specification and returns the first/next fully qualified file name matching that specification.

Format
F$SEARCH(filespec{,context})

Return Value
A string containing the fully qualified file name matching the specification. If no file is found, a null string ("") is returned.

Arguments
filespec

The string containing the file specification to be search for. If node/device/path is omitted, the current node/device/path is used. The filename is not defaulted. If the file specification includes wildcards, each time F$SEARCH is called, the next matching file is returned. When no more matches are found, a null string ("") is returned.

context

Specifies a positive integer value (between 0 and 2147483647, inclusive) representing the search context. This allows multiple multiple wildcard searches to be done simultaneously. If omitted, a default context is used.
If a different file specification is provided for a previously-used context (or for the default context), a new lookup is started.

Description
F$SEARCH can be used to iterate through files in a directory, if a wildcard is provided. Note: any loop should exit when a null string is returned. Any of the wildcards valid for a UOS file specification can be used here: *, ?, and **. Only files which exist during the call are returned. Files that are created or deleted during the iteration may or may not be returned.

Example
$ NAME = F$SEARCH("*.*")

    Search_Contexts : TStringList = nil ; // Name and user context
    UOS_Search_Contexts : TInteger64_List = nil ; // UOS contexts associated with Search_Contents
    Default_Search_Context : string ;
    Default_UOS_Search_Context : int64 = 0 ;

Because the UCL script can use an arbitrary integer context associated with an arbitrary file specification, we use a TStringList to hold the file specifications and associated the associated context value. Corresponding to this list is an integer list that contains the context from the UOS executive that corresponds to the script context in the same offset in the string list. Thus, UOS_Search_Contexts[10] would contain the uos context associated with the file specification and UCL context in Search_Contexts[10].
Because there is also the possibility of a default search context, we define the default search context (file specification) and default search context from the UOS executive associated with that file specification.

        Function_SEARCH : begin
                              if( Missing_Parentheses( '(' ) ) then
                              begin
                                  exit ;
                              end ;
                              if( Process_Search( Err, Context ) ) then
                              begin
                                  exit ;
                              end ;
                              if( Missing_Parentheses( ')' ) ) then
                              begin
                                  exit ;
                              end ;
                              S := Context ;
                          end ;

This code is added to the Function_Reference function.

function Process_Search( var Err : integer ; var Context : string ) : boolean ;

var Search_Context : int64 ;
    Filespec : string ;
    Have_Context : boolean ;
    I, Index : integer ;
    Node, Access, Secondary_Node, Device, Path, Name, Extension, Version : string ;

begin
    // Setup...
    Result := False ; // Assume no problems
    Context := '' ;

    // Get parameters...
    Filespec := Get_Parameter( Err, Context ) ;
    if( Err <> 0 ) then
    begin
        exit ;
    end ;
    Have_Context := False ;
    Search_Context := 0 ;
    if( Parser.Peek = ',' ) then
    begin
        Get_Token ; // Eat comma
        Search_Context := Get_Numeric_Parameter( Err, Context ) ;
        if( Err <> 0 ) then
        begin
            exit ;
        end ;
        if( ( Search_Context < 0 ) or ( Search_Context > 2147483647 ) ) then
        begin
            Err := UCL_IVCHAR ;
            Context := inttostr( Search_Context ) ;
            exit ;
        end ;
        if( Search_Contexts = nil ) then
        begin
            Search_Contexts := TStringList.Create ;
            UOS_Search_Contexts := TInteger64_List.Create ;
        end ;
        Have_Context := True ;
    end ;

First, we get the file specification. The second parameter is optional. If the next token is a comma then the second parameter is present, so we eat the comma and get the context. In that case, we validate that the context is between 0 and 2147483647. If not, we exit with an error. Note that DCL simply returns a null value if the provided context is invalid (such as negative). In this case, we are incompatible with VMS, but I try to avoid silent failures when there is no way to determine if there was an error. In DCL, a null result could indicate either an error or no matching files. This kind of ambiguity is generally a bad idea. I don't know if this was intentional (which would be a poor decision on someone's part) or a bug in DCL, but UCL will generate an error if there is an error.
If everything is fine, we construct the lists, if they haven't been constructed yet. Then we set the Have_Context flag.

    // Handle context...
    if( not Have_Context ) then
    begin
        if( Filespec = Default_Search_Context ) then // Same filename as last time
        begin
            Search_Context := Default_UOS_Search_Context ;
            Filespec := '' ;
        end else
        begin
            Search_Context := 0 ;
            Default_Search_Context := Filespec ;
            if( Default_UOS_Search_Context <> 0 ) then
            begin
                SYS_Lookup_Close( int64( @Default_UOS_Search_Context ) ) ;
            end ;
        end ;
        Index := -1 ;
    end else // Context provided...

Now it is time to deal with the script context and UOS context. First, we need to recall from the previous article that when the Lookup service is used, a new lookup takes a filename, but if we're continuing the search, we pass a null string. So, there are four things we need to deal with: 1) the script context, 2) the associated UOS file lookup context, 3) the passed specification, and 4) the specification string we will pass to the Lookup service.

If a context wasn't passed to the function, we use the default context. If the Filespec is different from the previous default value, we want to start a new search using the default context. So we delete the old context (if we had one), set the default filespec to compare against next time, and set Search_Context to 0 to indicate a new context (Search_Context now serves as the UOS search context).

If the filespec is the same as last time, we set the filespec to null, so that the lookup service looks for the next match (in the other case, we leave Filespec alone so that the first lookup is done). We also set Search_Context to the current default UOS context. In any case, if we are dealing with the default context, we set Index to -1.

    begin
        // Find script context in list...
        Index := -1 ;
        for I := 0 to Search_Contexts.Count - 1 do
        begin
            if( integer( Search_Contexts.Objects[ I ] ) = Search_Context ) then
            begin
                Index := I ;
                break ;
            end ;
        end ;

        if( Index = -1 ) then // New context
        begin
            Search_Contexts.AddObject( Filespec, pointer( Search_Context ) ) ;
            Search_Context := 0 ;
            Index := Search_Contexts.Count - 1 ;
            UOS_Search_Contexts.Add( 0 ) ;
        end else
        begin
            Search_Context := UOS_Search_Contexts[ Index ] ;
            if( lowercase( Filespec ) = lowercase( Search_Contexts[ Index ] ) ) then
            begin
                Filespec := '' ; // Continue current search
            end else
            if( Search_Context <> 0 ) then
            begin
                SYS_Lookup_Close( int64( @Search_Context ) ) ;
                Search_Context := 0 ;
            end ;
        end ;
    end ; // if( not Have_Context )

In the case when a context is provided, we look up the script context in the Search_Contexts. If found, Index is the index in the list, otherwise it is -1 if not found. If not found, we add the filespec and script context to the list. We also add 0 to the UOS_Search_Contexts to reserve a spot for the UOS context, and set the Index to the index of the new items in the list(s).

If the script context is found in the list, we compare the previous filespec to the one passed to the function. If they are the same, we clear the filespec so the lookup continues the search. Otherwise, we leave the filespec alone so a new lookup starts. And if the UOS context is in use (not 0), we close the old one and set the context to 0.

    // Default the device and path...
    if( Filespec <> '' ) then
    begin
        Parse_Filename( Filespec, Node, Access, Secondary_Node, Device, Path, Name, Extension, Version ) ;
        if( Node = '' ) then
        begin
            if( Device = '' ) then
            begin
                Device := 'sys$disk:' ;
            end ;
            if( Path = '' ) then
            begin
                Path := GETDDIR ;
            end ;
            Filespec := Device + Path + Name + Extension + Version ;
        end ;
    end ; // if( Filespec <> '' )

Next, we must default the device and path if they are not provided. Obviously if the filespec is null, we don't need to do this since we're continuing a search we already started. But if a filespec is provided, we parse it set the values for any missing device or path, then rebuild the filespec. Note that we do nothing if the node is specified since there is no default device/path on remote nodes. But what if the node is specified and is the current node? Shouldn't we default the device and path in that case? No, because if we are referring to a node, even our own, as a remote node, we let that node define the defaults.

    // Do the lookup...
    Context := Lookup( Filespec, Search_Context ) ;
    if( Filespec <> '' ) then // Initial lookup
    begin
        if( Index = -1 ) then // Default
        begin
            Default_UOS_Search_Context := Search_Context ;
        end else
        begin
            UOS_Search_Contexts[ Index ] := Search_Context ;
        end ;
    end ; // if( Filespec <> '' )
end ; // Process_Search

Finally, we have the filespec and context to pass to the Lookup service. We make the call, setting the result to the lookup value. If the filespec isn't null, this is the initial search, so we update the context - in the case of the default context we set Default_UOS_Search_Context, otherwise we update the UOS_Search_Contexts list value for the appropriate index.

procedure Parse_Filename( const S : string ;
    var Node, Access, Secondary_Node, Device, Path, Name, Extension, Version : string ) ;

begin
    UOS_Util.Parse_Filename( s, Node, Access, Secondary_Node, Device, Path, Name, Extension, Version ) ;
end ;

To support UCL being able to parse filenames without the extra work of calling the Parse service, we add the Parse_Filename function to PasStarlet, which simply surfaces the function from the UOS_Util unit.

In the next article, we will examine the SEARCH service.