SYS_PARSE

VMS has another system service that operates similarly to FILESCAN. In fact, FILESCAN is most likely implemented as a simplified interface to PARSE on VMS. It does the same thing as FILESCAN but fills up a NAML file structure with the parsed information. Our implementation of FILESCAN bypassed all the messy handling of FAB/NAML structures, but fear not: we won't be reimplementing much code for PARSE. Most of the processing that is common to both system services was put into the Parse_Filename function. Like FILESCAN, PARSE is implemented in Starlet in UOS (as opposed to the executive in VMS). Note that, unlike VMS, we only fill in NAML structures. VMS supports both NAM and NAML. As we discussed previously, UOS is only supporting NAML. We may decide to add NAM support as well in the future, but we'll cross that bridge if we get to it.

You might question why we need to have PARSE if we already have FILESCAN. First, we include it for compatibility with VMS. Second, it does a useful job of setting up a NAML structure for us. And, in fact, we will be using it in some future file-related system calls.

Here is the definition of the system call.

The PARSE service parses a file specification string and fills in various NAML fields.

Format
SYS$PARSE( fab, err, suc )

Returns

The result of the operation is stored in the FAB_L_STS item in the FAB structure.

Arguments
fab

Pointer to a FAB block whose contents are to be used as arguments for the PARSE call.

err

Address of a user-written routine to be called if there was an error. If 0, no routine is called. The called routine is assumed to take no parameters and return void.

suc

Address of a user-written routine to be called if there were no errors. If 0, no routine is called. The called routine is assumed to take no parameters and return void.

Description

This function is automatically called as part of the OPEN, CREATE, and ERASE services. It is also used to prepare the FAB and NAML blocks for use in the SEARCH service. The following FAB and NAML fields are potentially read and/or written by this service.

Block Field R/W Description

FAB FAB_L_DNA Read Default file specification string.

FAB FAB_L_DNS Read Default file specification string length, in bytes.

FAB FAB_L_FNA Read File specification string address.

FAB FAB_B_FNS Read File specification string address length, in bytes.

FAB FAB_L_NAM Read Address of NAML block.

FAB FAB_L_STS Write Completion status code.

NAML NAML_B_NOP Read Processing flags. If the NAML_V_SYNCHK flag is set, only a syntax check is performed. Otherwise, the node, device, and path are checked for validity.

NAML NAML_L_LONG_EXPAND Read Address of output expanded string value.

NAML NAML_L_LONG_EXPAND_ALLOC Read Maximum size of expanded output buffer.

NAML NAML_L_LONG_EXPAND_SIZE Write Length of output expanded string value.

NAML NAML_L_LONG_DEFNAME Read Address of default file specification. If FAB.FAB_L_DNS is -1, this is used as the default.

NAML NAML_L_LONG_DEFNAME_SIZE Read Length of default file specification.

NAML NAML_L_LONG_FILENAME Read Address of file specification. If FAB.FAB_L_FNA is -1, this is used as the file specification.

NAML NAML_L_LONG_FILENAME_SIZE Read Length of file specification.

NAML NAML_L_LONG_DEV Write Address of device name, or 0 if none.

NAML NAML_L_LONG_DEV_SIZE Write Length of device name.

NAML NAML_L_LONG_DIR Write Address of the path, or 0 if none.

NAML NAML_L_LONG_DIR_SIZE Write Length of the path specification.

NAML NAML_L_LONG_NAME Write Address of the name portion of the file name, or 0 if none.

NAML NAML_L_LONG_NAME_SIZE Write Length of the name portion of the file name.

NAML NAML_L_LONG_NODE Write Address of the node name, or 0 if none.

NAML NAML_L_LONG_NODE_SIZE Write Length of the node name.

NAML NAML_L_LONG_TYPE Write Address of the type portion of the file name, or 0 if none.

NAML NAML_L_LONG_TYPE_SIZE Write Length of the type portion of the file name.

NAML NAML_L_LONG_VER Write Address of the version portion of the file name, or 0 if none.

NAML NAML_L_LONG_VER_SIZE Write Length of the version portion of the file name.

NAML NAML_L_LONG_RESULT_SIZE Write Set to 0.

NAML NAML_W_FID Write Set to 0.

NAML NAML_L_FNB Write Filename flags.

Condition Codes

The following condition values can be returned:
RMS_FAB
RMS_BLN
RMS_DNA

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

var _FAB : PFAB ;
    _NAML : PNAML ;
    FNode, FAccess, FNode2, FDevice, FPath, FName, FType, FVersion : string ;
    DNode, DAccess, DNode2, DDevice, DPath, DName, DType, DVersion : string ;
    CNode, CAccess, CNode2, CDevice, CPath, CName, CType, CVersion : string ;
    DeviceOffset, PathOffset, NameOffset, TypeOffset, VersionOffset : integer ;
    S : string ;
    DirCount, I : integer ;

begin
    // Setup...
    Result := 0 ;
    if( FAB = 0 ) then // No FAB provided
    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_B_BLN < sizeof( _FAB^ ) ) then
    begin
        Result := RMS_BLN ;
        if( err <> 0 ) then
        begin
            PProcedure( err ) ;
        end ;
        exit ;
    end ;
    if( _FAB^.FAB_L_NAM = 0 ) then // Nothing to do
    begin
        if( suc <> 0 ) then
        begin
            PProcedure( suc ) ;
        end ;
        exit ;
    end ;
    _NAML := PNAML( _FAB^.FAB_L_NAM ) ;
    if( _NAML^.NAML_B_BID <> NAML_C_BID ) then
    begin
        Result := RMS_FAB ;
        _FAB^.FAB_L_STS := Result ;
        if( err <> 0 ) then
        begin
            PProcedure( err ) ;
        end ;
        exit ;
    end ;
    if( _NAML^.NAML_B_BLN < sizeof( _NAML^ ) ) then
    begin
        Result := RMS_BLN ;
        _FAB^.FAB_L_STS := Result ;
        if( err <> 0 ) then
        begin
            PProcedure( err ) ;
        end ;
        exit ;
    end ;
    _FAB^.FAB_L_STS := 0 ;
    CNode := '' ;
    CAccess := '' ;
    CNode2 := '' ;
    CDevice := '' ;
    CPath := '' ;
    CName := '' ;
    CType := '' ;
    CVersion := '' ;
    DeviceOffset := 0 ;
    PathOffset := 0 ;
    NameOffset := 0 ;
    TypeOffset := 0 ;
    VersionOffset := 0 ;

This new function in Starlet first validates that a valid FAB was passed. Then we check the NAML to be sure it is valid. To be valid, there must be a non-zero address for both the FAB (as a parameter) and NAML (in the FAB), the block ID (BID) must be appropriate, and the block length (BLN) must be at least as long as the block. If any of these conditions are not met, we set the FAB_L_STS code, if the FAB is valid, and we call the error (err) procedure (if it is non-zero). Finally, we clear various variables as well as the FAB_L_STS value.

    // Parse the file spec...
    if( _FAB^.FAB_L_FNA = -1 ) then
    begin
        setlength( S, _NAML^.NAML_L_LONG_FILENAME_SIZE ) ;
        move( PChar( _NAML^.NAML_L_LONG_FILENAME )[ 0 ], PChar( S )[ 0 ], length( S ) ) ;
    end else
    begin
        setlength( S, _FAB^.FAB_B_FNS ) ;
        move( PChar( _FAB^.FAB_L_FNA )[ 0 ], PChar( S )[ 0 ], length( S ) ) ;
    end ;
    Parse_Filename( S, FNode, FAccess, FNode2, FDevice, FPath, FName, FType, FVersion ) ;
    if( FDevice <> '' ) then
    begin
        DeviceOffset := length( FNode ) ;
    end ;
    if( FPath <> '' ) then
    begin
        PathOffset := length( FNode ) + length( FDevice ) ;
    end ;
    if( FName <> '' ) then
    begin
        NameOffset := length( FNode ) + length( FDevice ) + length( FPath ) ;
    end ;
    if( FType <> '' ) then
    begin
        TypeOffset := length( FNode ) + length( FDevice ) + length( FPath ) + length( FName ) ;
    end ;
    if( FVersion <> '' ) then
    begin
        VersionOffset :=  length( FNode ) + length( FDevice ) + length( FPath ) + length( FName ) + 
            length( FType ) ;
    end ;

First, we parse the file specification. If FAB_L_FNA is -1, we grab the specification from the NAML block's pointer, otherwise we use the FAB_L_FNA pointer. We then calculate the offsets for each field in the file specification.

    // Parse the default spec...
    if( _FAB^.FAB_L_DNA = -1 ) then
    begin
        setlength( S, _NAML^.NAML_L_LONG_DEFNAME_SIZE ) ;
        move( PChar( _NAML^.NAML_L_LONG_DEFNAME )[ 0 ], PChar( S )[ 0 ], length( S ) ) ;
    end else
    begin
        setlength( S, _FAB^.FAB_B_DNS ) ;
        move( PChar( _FAB^.FAB_L_DNA )[ 0 ], PChar( S )[ 0 ], length( S ) ) ;
    end ;
    Parse_Filename( S, DNode, DAccess, DNode2, DDevice, DPath, DName, DType, DVersion ) ;
    if( ( DeviceOffset <> 0 ) and ( DDevice <> '' ) ) then
    begin
        DeviceOffset := length( DNode ) ;
    end ;
    if( ( PathOffset <> 0 ) and ( DPath <> '' ) ) then
    begin
        PathOffset := length( DNode ) + length( DDevice ) ;
    end ;
    if( ( NameOffset <> 0 ) and ( DName <> '' ) ) then
    begin
        NameOffset := length( DNode ) + length( DDevice ) + length( DPath ) ;
    end ;
    if( ( TypeOffset <> 0 ) and ( DType <> '' ) ) then
    begin
        TypeOffset := length( DNode ) + length( DDevice ) + length( DPath ) + length( DName ) ;
    end ;
    if( ( VersionOffset <> 0 ) and ( DVersion <> '' ) ) then
    begin
        NameOffset := length( DNode ) + length( DDevice ) + length( DPath ) + length( DName ) + 
            length( DType ) ;
    end ;

Next, we parse the default file specification. If FAB_L_DNA is -1, we grab the specification from the NAML block's pointer, otherwise we use the FAB_L_DNA pointer. We then calculate the offsets for each field in the file specification if the offset wasn't already set above.

    // Write extended string...
    if( ( _NAML^.NAML_L_LONG_EXPAND <> 0 ) and ( _NAML^.NAML_L_LONG_EXPAND_SIZE <> 0 ) ) then
    begin
        CNode := FNode ;
        if( CNode = '' ) then
        begin
            CNode := DNode ;
        end ;
        CAccess := FAccess ;
        if( CAccess = '' ) then
        begin
            CAccess := DAccess ;
        end ;
        CNode2 := FNode2 ;
        if( CNode2 = '' ) then
        begin
            CNode2 := DNode2 ;
        end ;
        CDevice := FDevice ;
        if( CDevice = '' ) then
        begin
            CDevice := DDevice ;
        end ;
        CPath := FPath ;
        if( CPath = '' ) then
        begin
            CPath := DPath ;
        end ;
        CName := FName ;
        if( CName = '' ) then
        begin
            CName := DName ;
        end ;
        CType := FType ;
        if( CType = '' ) then
        begin
            CType := DType ;
        end ;
        CVersion := FVersion ;
        if( CVersion = '' ) then
        begin
            CVersion := DVersion ;
        end ;
        S := Get_Symbol_Value( '', CNode, ( _NAML^.NAML_B_NOP and NAML_V_NOCONCEAL ) <> 0 ) ;
        if( S <> '' ) then
        begin
            CNode := S ;
        end ;
        S := CNode + CDevice + CPath + CName + CType + CVersion ;
        if( length( S ) > _NAML^.NAML_L_LONG_EXPAND_ALLOC ) then
        begin
            setlength( S, _NAML^.NAML_L_LONG_EXPAND_ALLOC ) ; // Restrict to max length
        end ;

        // Write final spec...
        _NAML^.NAML_L_LONG_EXPAND_SIZE := length( S ) ; // Update NAML length
        move( PChar( S )[ 0 ], PChar( _NAML^.NAML_L_LONG_EXPAND )[ 0 ], length( S ) ) ;

If an expanded output buffer is provided, we construct a full specification from the parsed fields. For each field, we use the field from the file spec. If the given field wasn't in the specification, we take it from the default. If the resulting string is longer than the expanded buffer size, we trim the string to fit. Then we write that value out to the buffer and set the length.

        // Prepare for following code...
        Parse_Filename( S, CNode, CAccess, CNode2, CDevice, CPath, CName, CType, CVersion ) ;
        FNode := '' ;
        FAccess := '' ;
        FNode2 := '' ;
        FDevice := '' ;
        FPath := '' ;
        FName := '' ;
        FType := '' ;
        FVersion := '' ;
        DNode := '' ;
        DAccess := '' ;
        DNode2 := '' ;
        DDevice := '' ;
        DPath := '' ;
        DName := '' ;
        DType := '' ;
        DVersion := '' ;
    end ; // if( ( _FAB^.NAM_L_ESA <> 0 ) and ( _FAB^.NAM_B_ESS <> 0 ) )

Now we parse the file specification. We do this after truncating the string, if we had to, because the fields we set in NAML will be pointing into this string. Let's say that the file version had been truncated from the string due to output buffer size constraints. If we parsed the string before the truncation, we'd incorrectly believe that we had a version and we'd set the NAML pointer to somewhere past the end of the buffer. But parsing after the truncation means we will not have a value for the version, thus the NAML pointer for the version will be properly set to 0. Finally, in this case of writing the expanded string, we clear all the strings for the file and default specifications since everything will be based off of the combined (expanded) string.

    _NAML^.NAML_L_LONG_NODE_SIZE := _Write( FNode, DNode, CNode, 0, int64( @_NAML^.NAML_L_LONG_NODE ) ) ;
    _NAML^.NAML_L_LONG_DEV_SIZE := 
        _Write( FDevice, DDevice, CDevice, DeviceOffset, int64( @_NAML^.NAML_L_LONG_DEV ) ) ;
    _NAML^.NAML_L_LONG_DIR_SIZE := 
        _Write( FPath, DPath, CPath, PathOffset, int64( @_NAML^.NAML_L_LONG_DIR ) ) ;
    _NAML^.NAML_L_LONG_NAME_SIZE := 
        _Write( FName, DName, CName, NameOffset, int64( @_NAML^.NAML_L_LONG_NAME ) ) ;
    _NAML^.NAML_L_LONG_TYPE_SIZE := 
        _Write( FType, DType, CType, TypeOffset, int64( @_NAML^.NAML_L_LONG_TYPE ) ) ;
    _NAML^.NAML_L_LONG_VER_SIZE := 
        _Write( FVersion, DVersion, CVersion, VersionOffset, int64( @_NAML^.NAML_L_LONG_VER ) ) ;

At this point, we either have the combined fields (CName, CType, etc) or the original and default values, so we set the NAML fields appropriate. We'll look at _Write shortly.

    // Fill file name flags...
    _NAML^.NAML_L_FNB := 0 ;
    if( _NAML^.NAML_L_LONG_VER_SIZE > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_exp_ver ;
    end ;
    if( _NAML^.NAML_L_LONG_TYPE_SIZE > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_exp_type ;
    end ;
    if( _NAML^.NAML_L_LONG_NAME_SIZE > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_exp_name ;
    end ;
    if( _NAML^.NAML_L_LONG_DIR_SIZE > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_exp_dir or NAM_V_root_dir ;
    end ;
    if( _NAML^.NAML_L_LONG_DEV_SIZE > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_exp_dev ;
    end ;
    if( length( FNode ) + length( DNode ) + length( CNode ) > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_node ;
    end ;
    if( pos( '*', FVersion + DVersion + CVersion ) + pos( '?', FVersion + DVersion + CVersion ) > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_wild_ver ;
    end ;
    if( pos( '*', FType + DType + CType ) + pos( '?', FType + DType + CType ) > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_wild_type ;
    end ;
    if( pos( '*', FName + DName + CName ) + pos( '?', FName + DName + CName ) > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_wild_name ;
    end ;
    if( pos( '*', FPath + DPath + CPath ) + pos( '?', FPath + DPath + CPath ) > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_wild_dir ;
    end ;
    if( ( _NAML^.NAML_L_FNB and ( NAM_V_wild_type or NAM_V_wild_ver or NAM_V_wild_name ) ) <> 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_wildcard ;
    end ;
    if( pos( '"', S ) > 0 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_quoted ;
    end ;
    FPath := FPath + DPath + CPath ;
    if( copy( FPath, 1, 1 ) = '\' ) then
    begin
        FPath := copy( FPath, 2, length( FPath ) ) ;
    end ;
    DirCount := 0 ;
    I := pos( '\', FPath ) ;
    while( I > 0 ) do
    begin
        inc( DirCount ) ;
        FPath := copy( FPath, I + 1, length( FPath ) ) ;
        I := pos( '\', FPath ) ;
        if( DirCount = 7 ) then
        begin
            if( pos( '*', FPath ) + pos( '?', FPath ) > 0 ) then
            begin
                _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_wild_sfdg7 ;
            end ;
        end ;
    end ;
    if( DirCount > 7 ) then
    begin
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or NAM_V_dir_lvls_g7 ;
    end else
    begin
        DirCount := DirCount shl 20 ;
        _NAML^.NAML_L_FNB := _NAML^.NAML_L_FNB or DirCount ;
    end ;

Next we set the appropriate flags in the NAML_L_FNB field of the NAML block. This is pretty simple until the end. There is a bitmask field in the FNB for the number of directories in the path. This is 3 bits wide, which means it can have the values 0 through 7. If there are more than 7 levels, the number won't fit in this field. Thus, we count up the number of directories in the path by counting the number of slashes (ignoring the initial one, if present). If the count is more than 7, we set the appropriate flag. Otherwise we shift the count appropriately and or it into the FNB. If we reach 7 levels in the loop, we check for any wildcards in the remainder of the path and set the NAM_V_wild_sfdg7 flag if so.

    // Zero out certain fields...
    _NAML^.NAML_L_LONG_RESULT_SIZE := 0 ;
    _NAML^.NAML_W_FID := 0 ;

    // Synatx check...
    if( ( _NAML^.NAML_B_NOP and NAML_V_SYNCHK ) = 0 ) then
    begin
        if( not Directory_Exists( FNode + FDevice + FPath ) ) then
        begin
            Result := RMS_DNF ;
        end ;
    end ;
    _FAB^.FAB_L_STS := Result ;
    if( Result = 0 ) then
    begin
        if( suc <> 0 ) then
        begin
            PProcedure( suc ) ;
        end ;
    end else
    if( err <> 0 ) then
    begin
        PProcedure( err ) ;
    end ;
end ; // LIB_SYS_PARSE

To finish up, we clear certain fields, as per the VMS specification. If the NOP flags indicate that a syntax-only check wasn't requested, we check to make sure the node, device, and path exist. If not, we return an error. Again, if there was an error and the err parameter was non-zero, we call the routine. Otherwise, if the suc parameter was non-zero, we call that routine.

    function _Write( F, D, C : string ; Offset, Out_Address : int64 ) : integer ;

    var I : int64 ;

    begin
        if( F <> '' ) then
        begin
            Result := length( F ) ;
            if( _FAB^.FAB_L_FNA = -1 ) then
            begin
                I := Offset + _NAML^.NAML_L_LONG_FILENAME ;
            end else
            begin
                I := Offset + _FAB^.FAB_L_FNA ;
            end ;
        end else
        if( D <> '' ) then
        begin
            Result := length( D ) ;
            I := Offset + _FAB^.FAB_L_DNA ;
        end else
        if( C <> '' ) then
        begin
            I := Offset + _NAML^.NAML_L_LONG_EXPAND ;
            Result := length( C ) ;
        end else
        begin
            Result := 0 ;
            exit ;
        end ;
        move( I, PChar( Out_Address )[ 0 ], sizeof( int64 ) ) ;
    end ; // ._Write

This local function is used to write the appropriate value to the NAML block. This is called for each field, as described earlier. The file specification, default specification, and combined specification for the field is passed in along with the field offset and the output address to write the offset into. If a file specification was passed, then we offset from the NAML address if that is where it came from (FAB_L_FNA is 0), otherwise we offset from the FAB address. If the value came from the default specification, we offset from the FAB or NAML pointers, as appropriate. If the value came from the combined specification, we know this is an offset into the expanded string, so we offset from that. If all strings are zero, the offset is 0. We return the length, which is the length of the appropriate field. Then we write the address to the passed output address (which will be in the NAML).

When we are finished, the NAML will contain pointers into the appropriate string, whether that was the FAB or NAML specification, the FAB or NAML default specification, or the output expanded string.

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

begin
    Result := LIB_SYS_PARSE( fab, err, suc ) ;
end ;

Finally, there is the SYS_PARSE routine which simply calls the Startlet function.

In the next article, we will look at the next lexical function.