SYS_SEARCH

In the previous articles, we've covered the Lookup system service and its use by the F$SEARCH lexical function. VMS has a similar service, which is the SEARCH service. So we need to provide that interface for compatibility sakes. Why didn't we just use that as the lookup service instead? Primarily it has to do with the fact that UOS file specification length is arbitrary, but SYS_Lookup is also simpler to use. As you will see, the SEARCH system service has a lot of setup required in order to manage the FAB/NAML structures. The UOS lookup service is easier to use with less overhead. Here is the definition for SYS_SEARCH.

The SEARCH system service scans a directory looking for matches to a file specification and then sets the NAML block appropriately. The PARSE service should be called prior to this service so that the NAML block is correctly initialized. Note: this service uses the Lookup service and is provided for compatibility with VMS.

Format
SYS$SEARCH(fab,err,suc)

Return Value
A condition code indicating the success of the operation.

Arguments
fab

A pointer to the FAB control block.

err

The address of the error routine to call if an error occurs. If 0, there is no error routine to call.

suc

The address of the routine to call when the operation completes successfully. If 0, there is no routine to call.

Description
The SEARCH service searches for a file, or files, matching a specification. If a match is found, the service sets the appropriate fields of the NAML block associated with the passed FAB block. The following table indicates the input/output fields used by this service.

Field	Read/Write	Description
FAB_L_NAM	Read	Address of the NAML block.
FAB_L_STS	Write	Completion status code.
NAML_L_LONG_RESULT	Read	Address of where to write the matching file name.
NAML_L_LONG_RESULT_SIZE	Write	Length of result string.
NAML_L_LONG_RESULT_ALLOC	Read	Maximum length of result string.
NAML_L_LONG_DEV	Read	Device name.
NAML_L_LONG_DEV_SIZE	Read	Device name length.
NAML_L_LONG_DIR	Read	Path.
NAML_L_LONG_DIR_SIZE	Read	Path length.
NAML_L_LONG_NAME	Read	File's name.
NAML_L_LONG_NAME_SIZE	Read	Length of file name.
NAML_L_LONG_NODE	Read	Node name.
NAML_L_LONG_NODE_SIZE	Read	Length of node name.
NAML_L_LONG_TYPE	Read	File's extension.
NAML_L_LONG_TYPE_SIZE	Read	Length of file extension.
NAML_L_LONG_VER	Read	File's version.
NAML_L_LONG_VER_SIZE	Read	Length of file version.
NAML_L_USER_CONTEXT	Read/Write	On a new search, the new context is written here. Otherwise, it provides the context for the next lookup.

Condition codes returned
RMS_SUC RMS_FAB RMS_NAML

function SYS_SEARCH( fab : int64 ; err : int64 = 0 ; suc : int64 = 0 ) : int64 ;

var _FAB : PFAB ;
    NAM : PNAML ;
    ResLen : int64 ;
    S : string ;
    SRB : TSRB ;

begin
    // Validate structures and set up...
    if( FAB = 0 ) then
    begin
        Result := RMS_FAB ;
        if( Err <> 0 ) then
        begin
            PProcedure( err ) ;
        end ;
        exit ;
    end ;
    _FAB := PFAB( fab ) ;
    if( _FAB.FAB_B_BID <> FAB_C_BID ) then
    begin
        Result := RMS_FAB ;
        if( Err <> 0 ) then
        begin
            PProcedure( err ) ;
        end ;
        exit ;
    end ;
    if( _FAB.FAB_L_NAM = 0 ) then
    begin
        Result := RMS_NAML ;
        _FAB.FAB_L_STS := Result ;
        if( Err <> 0 ) then
        begin
            PProcedure( err ) ;
        end ;
        exit ;
    end ;
    NAM := PNAML( _FAB.FAB_L_NAM ) ;
    if( NAM.NAML_B_BID <> NAML_C_BID ) then
    begin
        Result := RMS_NAML ;
        _FAB.FAB_L_STS := Result ;
        if( Err <> 0 ) then
        begin
            PProcedure( err ) ;
        end ;
        exit ;
    end ;
    ResLen := 0 ;

The SEARCH system service is provided for VMS compatibility. First we need to validate the FAB and NAML structures passed to us. If the FAB address is 0, we exit. If an error procedure address is passed, we call that as well. Then we check the FAB block ID, verify that the NAML pointer is non-null, and that the NAML structure has the proper ID.

    if( NAM.NAML_L_USER_CONTEXT = 0 ) then // First time (no context)
    begin
        S := Get_NAM_Value( NAM.NAML_L_LONG_NODE, NAM.NAML_L_LONG_NODE_SIZE ) +
            Get_NAM_Value( NAM.NAML_L_LONG_DEV, NAM.NAML_L_LONG_DEV_SIZE ) +
            Get_NAM_Value( NAM.NAML_L_LONG_DIR, NAM.NAML_L_LONG_DIR_SIZE ) +
            Get_NAM_Value( NAM.NAML_L_LONG_NAME, NAM.NAML_L_LONG_NAME_SIZE ) +
            Get_NAM_Value( NAM.NAML_L_LONG_TYPE, NAM.NAML_L_LONG_TYPE_SIZE ) +
            Get_NAM_Value( NAM.NAML_L_LONG_VER, NAM.NAML_L_LONG_VER_SIZE ) ;
        SRB.Buffer := integer( PChar( S ) ) ;
        SRB.Length := length( S ) ;
        Result := SYS_Lookup( int64( @SRB ), int64( @NAM.NAML_L_USER_CONTEXT ), int64( @ResLen ) ) ;
    end else
    begin
        Result := SYS_Lookup( 0, int64( @NAM.NAML_L_USER_CONTEXT ), int64( @ResLen ) ) ;
    end ;
    if( Result <> 0 ) then
    begin
        _FAB.FAB_L_STS := Result ;
        if( Err <> 0 ) then
        begin
            PProcedure( err ) ;
        end ;
        exit ;
    end ;

If the context passed is 0, we consider this the first lookup and we build up the name from the NAM block value. Then we call SYS_Lookup, passing that file specification. If we have a context we call SYS_Lookup with a null specification. If either lookup returns an error, we call the error procedure (if one was passed), and exit.

    setlength( S, ResLen ) ;
    if( ResLen > 0 ) then
    begin
        Result := SYS_Lookup_Name( int64( @NAM.NAML_L_USER_CONTEXT ), int64( PChar( S ) ) ) ;
        if( Result <> 0 ) then
        begin
            _FAB.FAB_L_STS := Result ;
            if( Err <> 0 ) then
            begin
                PProcedure( err ) ;
            end ;
            exit ;
        end ;
        if( ResLen > NAM.NAML_L_LONG_RESULT_ALLOC ) then
        begin
            setlength( S, NAM.NAML_L_LONG_RESULT_ALLOC ) ;
        end ;
        system.move( PChar( S )[ 0 ], PChar( NAM.NAML_L_LONG_RESULT )[ 0 ], length( S ) ) ;
    end ;
    NAM.NAML_L_LONG_RESULT_SIZE := length( S ) ;
    if( Suc <> 0 ) then
    begin
        PProcedure( suc ) ;
    end ;
end ; // SYS_SEARCH

Next we set the length of S to the result length from the lookup. If the result length is non-zero, we call SYS_Lookup_Name to get the result filename. If there was an error, we exit. Otherwise, if the result file spec is longer than the size of the NAML result buffer, we trim the spec to that length so that we don't overwrite the result buffer. Then we copy from the local spec string to the result buffer. Finally, we write the actual length to the NAML_L_LONG_RESULT_SIZE field and call the success procedure (if one was provided).

function Get_NAM_Value( Addr, Len : int64 ) : string ;

begin
    Result := '' ;
    if( ( Addr = 0 ) or ( Len = 0 ) ) then
    begin
        exit ;
    end ;
    setlength( Result, Len ) ;
    move( PChar( Addr )[ 0 ], PChar( Result )[ 0 ], Len ) ;
end ;

This function is used to return a Pascal string given an address and a length. This is used by SYS_SEARCH to obtain the file specification fields from the NAML block.

As you can see, SYS_SEARCH is nothing more than a wrapper for SYS_Lookup that uses the FAB/NAML block and returns the file specification result into the provided buffer. As noted previously, this approach is problematic because it requires that an appropriately sized buffer is set up for a file specification that is of arbitrary length. If the buffer isn't large enough, the file specification will be truncated and the calling code will probably not work. So, this is solely for VMS compatibility. All UOS code ought to use the SYS_Lookup and related system calls directly instead.

In the next article, we will examine the next lexical function.