The Data Stream Interface

Although we introduced data streams many articles ago (at least in terms of the UOS native file header structures and low-level code), in the last article we started to use them. So it is time to discuss the the data stream interface - at least reading them. We will cover writing to them in the future.

function TUOS_File_Wrapper.Stream_Index( Value : PChar ) : int64 ;

var Name : string ;
    SRB : TSRB ;

begin
    Result := -1 ; // Assume failure
    Name := Value ;
    Name := trim( Name ) ;
    if( Name = '' ) then
    begin
        Result := 0 ; // Data stream
        exit ;
    end ;
    SYS_GETSTREAMINDEX( int64( @FAB ), int64( @SRB ), int64( @Result ) ) ;
end ;


function TUOS_File_Wrapper.Stream_Length( Stream : int64 ) : int64 ;

begin
    SYS_GETSTREAMLENGTH( int64( @FAB ), int64( @Stream ), int64( @Result ) ) ;
end ;


function TUOS_File_Wrapper.Read_Stream( Stream, Position, Size,
    Dst : int64 ) : int64 ;

var RAB : TRAB ;

begin
    fillchar( RAB, sizeof( RAB ), 0 ) ;
    RAB.RAB_Size := sizeof( RAB ) ;
    RAB.RAB_L_BKT := Position ;
    RAB.RAB_W_ISI := FAB.FAB_Q_HANDLE ;
    RAB.RAB_L_UBF	:= Dst ; // User buffer address
    RAB.RAB_W_USZ	:= Size ; // Bytes to read
    RAB.RAB_Data_Stream := Stream ;
    SYS_READ( int64( @RAB ), 0, 0 ) ;
    Result := RAB.RAB_W_RSZ ; // Bytes actually read
end ;

These three methods are added to the TUOS_File_Wrapper class. Like most other methods of the class, these simply wrap the appropriate system calls. The Read_Stream method is nearly identical to the Read method we've covered in the past. The only difference is that Read passes 0 in the RAB_Data_Stream field of the RAB, whereas Read_Stream passes the specified stream.

function SYS_GETSTREAMINDEX( FAB, SRB, Dst : int64 ) : int64 ;

var Status : int64 ;
    SysRequest : TS1I2_Request ;

begin
    if( FAB = 0 ) then
    begin
        Result := RMS_FAB ;
        exit ;
    end ;
    Status := 0 ;
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem :=  UOS_Subsystem_FIP ;
    SysRequest.Request.Request := UOS_FIP_Get_Stream_Index ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( TSystem_Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.SRB := PSRB( SRB )^ ;
    SysRequest.Integer1 := FAB ;
    SysRequest.Integer2 := Dst ;

    Call_To_Ring0( integer( @SysRequest ) ) ;
    Result := Status ;
end ;


function SYS_GETSTREAMLENGTH( FAB, Stream, Dst : int64 ) : int64 ;

var Status : int64 ;
    SysRequest : TInteger3_Request ;

begin
    if( FAB = 0 ) then
    begin
        Result := RMS_FAB ;
        exit ;
    end ;
    Status := 0 ;
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem :=  UOS_Subsystem_FIP ;
    SysRequest.Request.Request := UOS_FIP_Get_Stream_Length ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( TSystem_Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.Int1 := FAB ;
    SysRequest.Int2 := Stream ;
    SysRequest.Int3 := Dst ;

    Call_To_Ring0( integer( @SysRequest ) ) ;
    Result := Status ;
end ;

These additions to the SYS unit are wrappers to the executive services, like the other routines we've looked at in the past.

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

                    Status := File_Get_Stream_Index( S1I2_Request.Integer1,
                        S1I2_Request.SRB, S1I2_Request.Integer2, IOSB ) ;
                    Write_User_int64( Kernel, PID, S1I2_Request.Request.Status,
                        IOSB.r_io_64.r_bcnt_32.l_bcnt ) ;
                finally
                    Exit_System_Call( integer( S1I2_Request ), PID, MMC,
                        sizeof( S1I2_Request ) - sizeof( SReq ) ) ;
                end ;
            end ;
        UOS_FIP_Get_Stream_Length:
            begin
                UE := Enter_System_Call( Request, SReq, PID, MMC,
                    sizeof( Integer3_Request ) - sizeof( SReq ), Address ) ;
                if( UE <> nil ) then
                begin
                    Set_Last_Error( UE ) ;
                    exit ;
                end ;
                try
                    Integer3_Request := PInteger3_Request( Address ) ;

                    Status := File_Get_Stream_Length( Integer3_Request.Int1,
                        Integer3_Request.Int2, Integer3_Request.Int3, IOSB ) ;
                    Write_User_int64( Kernel, PID, Integer3_Request.Request.Status,
                        IOSB.r_io_64.r_bcnt_32.l_bcnt ) ;
                finally
                    Exit_System_Call( integer( Integer3_Request ), PID, MMC,
                        sizeof( Integer3_Request ) - sizeof( SReq ) ) ;
                end ;
            end ;

This code is added to the FiP's API method to handle the two new services.

function TUOS_FiP.File_Get_Stream_Index( _FAB : int64 ; Name : TSRB ;
    Dst : int64 ; var IOSB : TIOSB ) : int64 ;

var FAB : TFAB ;
    Index : int64 ;
    SName : string ;
    PID : TPID ;
    Resource : TResource ;
    US : TUOS_String ;

begin
    // Initial check...
    Result := 0 ;
    if( _FAB = 0 ) then
    begin
        Result := RMS_FAB ;
        IOSB.r_io_64.w_status := Result ;
        exit ;
    end ;

    // Get the FAB...
    fillchar( FAB, sizeof( FAB ), 0 ) ;
    PID := Kernel.PID ;
    Get_User_Data( Kernel, PID, _FAB, 2, FAB, IOSB.r_io_64.w_status ) ; // Get RAB length
    if( IOSB.r_io_64.w_status <> 0 ) then
    begin
        Result := IOSB.r_io_64.w_status ;
        exit ;
    end ;
    if( FAB.FAB_B_BLN > sizeof( FAB ) ) then
    begin
        FAB.FAB_B_BLN := sizeof( FAB ) ;
    end ;
    Get_User_Data( Kernel, PID, _FAB, FAB.FAB_B_BLN, FAB, IOSB.r_io_64.w_status ) ; // Get FAB
    if( IOSB.r_io_64.w_status <> 0 ) then
    begin
        Result := IOSB.r_io_64.w_status ;
        exit ;
    end ;

This method starts by obtaining and validating the FAB. We've seen similar code in other routines in the past.

    // Validate...
    if( not USC.Valid_Handle( PID, FAB.FAB_Q_HANDLE ) ) then
    begin
        Set_Last_Error( Create_Error( UOSErr_Invalid_Handle ) ) ;
        Result := UOSErr_Invalid_Handle ;
        exit ;
    end ;
    if( USC.Check_Quota( PID, Quota_BIOLM, 1 ) ) then
    begin
        Result := UOSErr_Quota_Exceeded ;
        Set_Last_Error( Create_Error( UOSErr_Quota_Exceeded ) ) ;
        exit ;
    end ;

Next we validate that the handle is valid for the process and check this read requests against the Buffered I/O quota.

    // Get name...
    US := Get_User_String( Kernel, PID, Name, IOSB.r_io_64.w_status ) ;
    if( IOSB.r_io_64.w_status = UE_Error ) then
    begin
        Result := IOSB.r_io_64.w_status ;
        exit ;
    end ;
    SName := US.Contents ;
    US.Free ;

    // Get file...
    Resource := TResource( FAB.FAB_Q_HANDLE ) ;
    if( Resource._File = nil ) then // Only files have streams
    begin
        Result := UOSErr_Invalid_Operation ;
        Set_Last_Error( Create_Error( UOSErr_Invalid_Operation ) ) ;
        exit ;
    end ;

    // Return value...
    Index := Resource._File.Stream_Index( PChar( SName ) ) ;
    Result := Write_User_int64( Kernel, PID, Dst, Index ) ;
end ; // TUOS_FiP.File_Get_Stream_Index

Next we obtain the stream name from the user address space, get the resource and validate that this is a store file (no other files have ancillary data streams). Assuming we don't exit with an error, we ask the file for the stream index for the passed name and write the result to the user-specified destination.

function TUOS_FiP.File_Get_Stream_Length( _FAB, _Stream, Dst : int64 ;
    var IOSB : TIOSB ) : int64 ;

var FAB : TFAB ;
    I : integer ;
    Index, Len : int64 ;
    PID : TPID ;
    Resource : TResource ;

begin
    // Initial check...
    Result := 0 ;
    if( _FAB = 0 ) then
    begin
        Result := RMS_FAB ;
        IOSB.r_io_64.w_status := Result ;
        exit ;
    end ;

    // Get the FAB...
    fillchar( FAB, sizeof( FAB ), 0 ) ;
    PID := Kernel.PID ;
    Get_User_Data( Kernel, PID, _FAB, 2, FAB, IOSB.r_io_64.w_status ) ; // Get RAB length
    if( IOSB.r_io_64.w_status <> 0 ) then
    begin
        Result := IOSB.r_io_64.w_status ;
        exit ;
    end ;
    if( FAB.FAB_B_BLN > sizeof( FAB ) ) then
    begin
        FAB.FAB_B_BLN := sizeof( FAB ) ;
    end ;
    Get_User_Data( Kernel, PID, _FAB, FAB.FAB_B_BLN, FAB, IOSB.r_io_64.w_status ) ; // Get FAB
    if( IOSB.r_io_64.w_status <> 0 ) then
    begin
        Result := IOSB.r_io_64.w_status ;
        exit ;
    end ;
    Index := Get_User_Integer( Kernel, PID, _Stream, I ) ;
    if( I <> 0 ) then
    begin
        Result := I ;
        exit ;
    end ;

    // Get file...
    Resource := TResource( FAB.FAB_Q_HANDLE ) ;
    if( Resource._File = nil ) then // Only files have streams
    begin
        Result := UOSErr_Invalid_Operation ;
        Set_Last_Error( Create_Error( REsult ) ) ;
        exit ;
    end ;

This method starts like the previous one, getting and verifying the FAB and resource. It also obtains the stream index from the user's address space.

    // Return value...
    Len := Resource._File.Get_Stream_Size( Index ) ;
    Result := Write_User_int64( Kernel, PID, Dst, Len ) ;
end ; // TUOS_FiP.File_Get_Stream_Length

Finally, we request the data stream size and write it to the user's specified destination.

    if(
        ( RAB.RAB_B_RAC = 0 )
        or
        ( RAB.RAB_L_BKT <> 0 )
         or
        ( RAB.RAB_Data_Stream > 0 ) // NEW (this line only)
      ) then // Binary I/O or non-zero position or stream read
    begin
        Resource.Position := RAB.RAB_L_BKT ;
    end ;

    // Read the file...
    S := Read_File( RAB.RAB_W_ISI, RAB.RAB_Data_Stream, RAB.RAB_W_USZ, 0, IOSB ) ;
    if( RAB.RAB_Data_Stream = 0 ) then // NEW (if)
    begin
        Resource.Position := Resource.Position + length( S ) ;
    end ;

We've made a couple minor, but important, modifications to the TUOS_FiP.File_Read method. The lines with the "// NEW" comments are the additions. These changes support data streams. Previously assumptions were made that the only stream being read was the default data stream. We don't keep track of position for ancillary streams - that is reserved for the default data stream.

function TFS_File.Stream_Index( Name : PChar ) : integer ;

var ACM : TNative_File_ACM ;
    Index : integer ;
    N : string ;

begin
    Result := -1 ; // Assume failure
    N := lowercase( string( Name ) ) ;
    for Index := 1 to Max_Stream do
    begin
        ACM := Find_Data_Stream( Index ) ;
        if( lowercase( FS.Get_String( ACM.Name ) ) = Name ) then
        begin
            Result := Index ; // Found stream with a matching name
            exit ;
        end ;
    end ;
end ;

This method has been added to the TFS_File class to return the index for a data stream with the specified name. It merely iterates through the data streams, does a case-insensitive comparison and returns the index if a match is found. Otherwise it returns -1.

    .
    .
    .
    if( ACM.Index = 0 ) then
    begin
        EOF := Header.EOF ;
    end else
    begin
        EOF := Get_Size( ACM ) ;
    end ;
    .
    .
    .

    if( ( ( Header.Flags and FAF_CONTIGUOUS ) <> 0 ) and ( ACM.Index = 0 ) ) then
    begin
        P := Header.Clusters[ 0 ] + Position ;
        P := P and ( Clustersize - 1 ) ;
    end else
    .
    .
    .

These changes to TUOS_Native_File._Read also support streams. As was mentioned, a logical size is not saved for ancillary data streams, so we cannot compare against the Header.EOF field, which is the logical size of the default data stream. Instead, we compare against the stream's physical size. Also ancillary data streams are not logically contiguous, so we only check the contiguous flag if the stream in quesstion is the default data stream (ACM.Index = 0).

In the next article, we will look at the processing necessary to prepare for running a program.