F$PARSE has to do with parsing a filename into its constituent parts. We've seen code for parsing filenames before, but here we will address an expanded parsing capability that handles all valid UOS file and device specifications. A fully-qualified file specification contains the following fields:
node::device:\path\name.type;version
For instance:
MYNODE::DISKA0:\UOS\System\ucl.exe;1
Note that the node name may include access information within quotes. For example:
UNICORN"access"::
This would include the specified access information (user name, password, etc) for access to the node named UNICORN.

Note that if no node name is specified, the current node is assumed. Also note that if the value following the semicolon is not an integer value, it is considered part of the file type and it is assumed that there is no version field. As a reminder, a UOS filename can contain any number of periods (.), thus only the last period found in the specification will be considered the start of the file type. Likewise, any number of semi-colons can appear in the filename or file type, in which case only the last semi-colon in the specification is considered the start of the version (and then only if followed by an integer).

For instance, "Myfile.123.exe" would be parsed as having the filename "Myfile.123" and the file type of ".exe".
"File.exe;abcdef" would be parsed as having the filename "File", the type ".exe;abcdef", and no version field.

As we discussed when we taked about the File Processor many articles ago, the FIP doesn't consider any characters in a file specification to be significant except for those which are used to delimit the node, device, and paths. Thus, to the FIP, file types and versions mean nothing - syntactically, they are just part of the filename. However, certain other parts of UOS can attribute special significance to certain fields of a file specification. We will talk about these in the future, but as an example in the meantime, a file type can be associated with a default action under certain circumstances (for instance, the ".txt" type could default to a given text editor when it is double-clicked in the file explorer, if no other action has been explicitly defined for that specific file).

As we've discussed before, certain characters are not allowed in filenames (including in file types and versions). For instance, colons are used to delimit node and device names and cannot appear in the file's name. Likewise, backslash (\) can only be used as a delimiter for directory names in a path - never in a filename. Asterisk (*) and question mark (?) are reserved for use as wildcards and cannot be part of a file's name. Finally, certain characters act as delimiters (such as slashes and spaces) and, as such, are interpreted as a delimiter ending a file specification. So, if those characters are part of a filename, the filename must be enclosed in quotes (") - which also means that quotes are not valid in a filename.

F$PARSE parses a file specification and returns either the expanded file specification or the requested field requested.

Return Value
A character string containing the expanded file specification or the specified field. If a complete file specification is not provided for the filespec argument, F$PARSE will supply defaults from the default argument, and if the corresponding item isn't in either the filespec or default, it is provided from the related argument.

If an error is detected during the parse, a null string is returned by F$PARSE. This can occur if the node, device, or directory do not exist. However, if a field name or a type argument of "SYNTAX_ONLY" is passed, F$PARSE returns the requested item without checking for the existence of the node, device, or directory.

Description
All but the first argument may be omitted, but commas must be provided in all cases. The SYS$PARSE system call is used to process the file specifications.

If the device and/or path are not provided in any of the arguments, F$PARSE substitutes the current default device and directory. Any other fields not provided in any of the arguments is returned as null.

F$PARSE can validate that a node, device, and path exist, but it will not validate the presence of a specific file.

F$PARSE will ignore any text that occurs after any character that is not valid for use in a file specification unless the specification is included in quotes. For the case of access information for a node, which is enclosed within quotes, a double-quote can be used within quoted node names to indicate the access information, which will be returned as part of the node field.

Examples
$ A = F$PARSE("INFO.DAT","_DISKA1:\uos",,,,"SYNTAX_ONLY")
The symbol A would be set to "_DISKA1:\uos\INFO.DAT".

$ A = F$PARSE("_DISKB0:\UOS\Users\Fred\INFO.DAT",,,"DIRECTORY",)
The symbol A would be set to "\UOS\Users\".

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

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

var I : integer ;
    Code : integer ;
    Name, Default, Related, Field, Parse_Type, S : string ;
    Name_List, Default_List, Related_List : TStringList ;

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

    // Get items...
    Name := Get_Parameter( Err, Context ) ;
    if( Err <> 0 ) then
    begin
        exit ;
    end ;
    if( Parser.Peek = ',' ) then
    begin
        Get_Token ; // Eat comma
        Default := Get_Parameter( Err, Context ) ;
        if( Err <> 0 ) then
        begin
            exit ;
        end ;
    end ;
    if( Parser.Peek = ',' ) then
    begin
        Get_Token ; // Eat comma
        Related := Get_Parameter( Err, Context ) ;
        if( Err <> 0 ) then
        begin
            exit ;
        end ;
    end ;
    if( Parser.Peek = ',' ) then
    begin
        Get_Token ; // Eat comma
        Field := lowercase( Get_Parameter( Err, Context ) ) ;
        if( Err <> 0 ) then
        begin
            exit ;
        end ;
    end ;
    if( Parser.Peek = ',' ) then
    begin
        Get_Token ; // Eat comma
        Parse_Type := lowercase( Get_Parameter( Err, Context ) ) ;
        if( Err <> 0 ) then
        begin
            exit ;
        end ;
    end ;
    if( ( Parse_Type <>  'no_conceal' ) and ( Parse_Type <>  'syntax_only' ) and ( Parse_Type <>  '' ) ) then
    begin
        Err := UCL_IVKEYW ; // Unrecognized keyword
        Context := Parse_Type ;
        exit ;
    end ;

    // Handle logical translation...
    if( copy( Name, length( Name ), 1 ) = ':' ) then
    begin
        S := Get_Symbol_Value( '', Name ) ;
        if( S <> '' ) then
        begin
            Name := S ;
        end ;
    end ;
    if( copy( Default, length( Default ), 1 ) = ':' ) then
    begin
        S := Get_Symbol_Value( '', Default ) ;
        if( S <> '' ) then
        begin
            Default := S ;
        end ;
    end ;
    if( copy( Related, length( Related ), 1 ) = ':' ) then
    begin
        S := Get_Symbol_Value( '', Related ) ;
        if( S <> '' ) then
        begin
            Related := S ;
        end ;
    end ;

    // Parse file specs...
    Name_List := FILESCAN( Name ) ;
    Default_List := FILESCAN( Default ) ;
    Related_List := FILESCAN( Related ) ;

    try
        // Substitute defaults...
        for I := FSCN_V_NODE to FSCN_V_VERSION do
        begin
            if( Name_List[ I ] = '' ) then
            begin
                if( Default_List[ I ] <> '' ) then
                begin
                    Name_List[ I ] := Default_List[ I ] ;
                end else
                if( Related_List[ I ] <> '' ) then
                begin
                    Name_List[ I ] := Related_List[ I ] ;
                end ;
            end ;
        end ;

        // Default the device and path, if necessary...
        if( S := Name_List[ FSCN_V_DEVICE ] = '' ) then
        begin
            S := Get_Symbol_Value( '', 'sys$disk' ) ;
            if( S = '' ) then
            begin
                S := 'sys$disk:' ;
            end ;
            Name_List[ FSCN_V_DEVICE ] := S ;
        end ;
        if( Name_List[ FSCN_V_DIRECTORY ] = '' ) then
        begin
            S := GETDDIR ;
            Name_List[ FSCN_V_DIRECTORY ] := S ;
        end ;

        // Process the specification...
        if( Name_List[ FSCN_V_DEVICE ] <> '' ) then
        begin
            S := Name_List[ FSCN_V_DEVICE ] ;
            setlength( S, length( S ) - 1 ) ; // Trim colon
            S := Get_Symbol_Value( '', S, Parse_Type = 'no_conceal' ) ;
            if(
                ( S <> '' )
                and
                ( copy( S, length( S ), 1 ) = ':' )
                and
                ( copy( S, length( S ) - 1, 2 ) <> '::' )
              ) then
            begin
                Name_List[ FSCN_V_DEVICE ] := S ;
            end ;
        end ;

        if( Field <> '' ) then
        begin
            S := '' ;
            if( Field = 'node' ) then
            begin
                S := Name_List[ FSCN_V_NODE ] ;
            end else
            if( Field = 'device' ) then
            begin
                S := Name_List[ FSCN_V_DEVICE ] ;
            end else
            if( Field = 'directory' ) then
            begin
                S := Name_List[ FSCN_V_DIRECTORY ] ;
            end else
            if( Field = 'name' ) then
            begin
                S := Name_List[ FSCN_V_NAME ] ;
            end else
            if( Field = 'type' ) then
            begin
                S := Name_List[ FSCN_V_TYPE ] ;
            end else
            if( Field = 'version' ) then
            begin
                S := Name_List[ FSCN_V_VERSION ] ;
            end else
            begin
                Err := UCL_IVKEYW ; // Unrecognized keyword
                Context := Field ;
                exit ;
            end ;
        end else
        begin
            S := Name_List[ FSCN_V_NODE ] + Name_List[ FSCN_V_DEVICE ] +
                Name_List[ FSCN_V_DIRECTORY ] + Name_List[ FSCN_V_NAME ] +
                Name_List[ FSCN_V_TYPE ] + Name_List[ FSCN_V_VERSION ] ;
            if( Parse_Type <> 'syntax_only' ) then
            begin
                if( not Directory_Exists( Name_List[ FSCN_V_NODE ] + 
                  Name_List[ FSCN_V_DEVICE ] + Name_List[ FSCN_V_DIRECTORY ] ) ) then
                begin
                    S := '' ;
                end ;
            end ;
        end ;

        Context := S ;
    finally
        Name_List.Free ;
        Default_List.Free ;
        Related_List.Free ;
    end ;
end ; // Parse_Parse

function Directory_Exists( S : string ) : boolean ;

var SRB : TSRB ;

begin
    if( copy( S, length( S ), 1 ) = '\' ) then
    begin
        setlength( S, length( S ) - 1 ) ; // Trim trailing backslash
    end ;
    Set_String( S, SRB ) ;
    if( SYS_File_Exists( int64( @SRB ) ) = 0 ) then
    begin
        Result := True ; // No error on check
    end else
    begin
        Result := False ;
    end ;
end ;

function SYS_File_Exists( Name : int64 ) : int64 ;

var SRB : PSRB ;
    Status : int64 ;
    SysRequest : TString_Request ;

begin
    SRB := PSRB( pointer( Name ) ) ;
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    Status := 0 ;
    SysRequest.Request.Subsystem :=  UOS_Subsystem_FIP ;
    SysRequest.Request.Request := UOS_FIP_File_Exists ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( Sysrequest.Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.SRB.Buffer := SRB.Buffer ;
    SysRequest.SRB.Length := SRB.Length ;

    Call_To_Ring0( integer( @SysRequest ) ) ;

    Result := Status ;
end ;

        UOS_FIP_File_Exists:
            begin
                UE := Enter_System_Call( Request, SReq, PID, MMC, 
                    sizeof( String_Request ) - sizeof( SReq ), Address ) ;
                if( UE <> nil ) then
                begin
                    Set_Last_Error( UE ) ;
                    exit ;
                end ;
                try
                    String_Request := PString_Request( Address ) ;

                    US := Get_User_String( Kernel, PID, String_Request.SRB, Status ) ;
                    try
                        if( Status = 0 ) then
                        begin
                            Status := ord( not File_Exists( Kernel.PID, US.Contents ) ) ;
                        end ;
                    finally
                        US.Free ;
                    end ;
                    Write_User( Kernel, Kernel.PID, String_Request.Request.Status, sizeof( Status ), 
                        Status ) ;
                finally
                    Exit_System_Call( Request, PID, MMC, sizeof( String_Request ) - sizeof( SReq ) ) ;
                end ;
            end ;