Mailboxes, Part 2

We've covered much of the mailbox code in the past few articles. In this article, we will look at the rest of the mailbox support code in the File Processor. Note: we will cover the mailbox delete service in a future article.

    // Mailboxes...
    if(
        ( copy( S, 1, 5 ) = 'MAILA' ) or ( copy( S, 1, 5 ) = 'MAILB' ) or
        ( copy( S, 1, 6 ) = '_MAILA' ) or ( copy( S, 1, 6 ) = '_MAILB' )
      ) then
    begin
        Index := pos( ':', S ) ;
        if( Index > 0 ) then
        begin
            setlength( S, Index - 1 ) ;
        end ;
        if( copy( S, 1, 1 ) = '_' ) then
        begin
            if( not trystrtoint( copy( S, 7, length( S ) ), Index ) ) then
            begin
                exit ;
            end ;
        end else
        begin
            if( not trystrtoint( copy( S, 6, length( S ) ), Index ) ) then
            begin
                exit ;
            end ;
        end ;
        if( ( copy( S, 1, 5 ) = 'MAILA' ) or ( copy( S, 1, 6 ) = '_MAILA' ) ) then
        begin
            List := Permanent_Mailboxes ;
        end else
        begin
            List := Temporary_Mailboxes ;
        end ;
        if( ( Index < 0 ) or ( Index >= List.Count ) ) then
        begin
            exit ;
        end ;
        MB := TMailbox( List[ Index ] ) ;
        if( MB = nil ) then
        begin
            exit ;
        end ;
        Result := MB.Device ;
        exit ;
    end ;

    // Other devices...

This code is added to the UOS_FiP.Get_Device method, just after the existing setup code (before the existing main body of code). If the device type is "MAIL" or "_MAIL", then the specified device is potentially a mailbox, so we enter the new code, otherwise we drop through to the original code. In the mailbox code, we first check for a valid mailbox device name, which will be of the format: MAILcu
where "c" is "A" or "B", and "u" is a number between 0 and the max mailbox unit, inclusive. If MAILA is used, we check the permanent mailbox list, otherwise we check the temporary mailbox list. If "c" or "u" is invalid, we exit (the default return is nil, indicating the device was not found). Also, if the unit corresponds to a nil in the appropriate list (indicating a previously deleted mailbox), we do the same. If everything is okay, we return the virtual device associated with the specified mailbox.

    List : TList ;
    MB : TMailbox ;

These two new variables are added to the UOS_FiP.Get_Device method to support the above code.

                    if( copy( Name, 1, 4 ) = 'MAIL' ) then
                    begin
                        VMS_Class := DC_MAILBOX ;
                    end else

In the USC component, we add this code to the TDevice_Scan_Context.Next_Device method. This code sets the class for mailboxes so that if the scan is filtered by class, mailbox devices are properly included/excluded.

function TUOS_FiP.Get_Device_By_Index( Index : cardinal ) : TFIP_Device ;

var I : integer ;

begin
    Result := nil ;
    if( Index < _Devices.Count ) then
    begin
        Result := _Devices.Get_Device( Index ) ;
    end else
    begin
        Index := Index - _Devices.Count ;
        for I := 0 to Permanent_Mailboxes.Count - 1 do
        begin
            if( Permanent_Mailboxes[ I ] <> nil ) then
            begin
                dec( Index ) ;
                if( Index < 0 ) then
                begin
                    Result := TMailBox( Permanent_Mailboxes[ I ] ).Device ;
                    exit ;
                end ;
            end ;
        end ;
        for I := 0 to Temporary_Mailboxes.Count - 1 do
        begin
            if( Temporary_Mailboxes[ I ] <> nil ) then
            begin
                dec( Index ) ;
                if( Index < 0 ) then
                begin
                    Result := TMailBox( Temporary_Mailboxes[ I ] ).Device ;
                    exit ;
                end ;
            end ;
        end ;
    end ;
end ; // TUOS_FiP.Get_Device_By_Index

This method is expanded to handle the mailbox virtual devices. The method is used to allow a device scan to scan through all devices on the system - whether physical or logical - using sequential integer indexes. When we were only dealing with physical devices, we could get the device from the device list which was built when UOS started up. However, to deal with virtual devices, we modify this to handle indexes beyond the physical device list. We simply iterate through the mailboxes, decrementing the requested index for each until we find the one requested (at which point the index becomes negative). If the scans through the mailbox lists fail, the function returns nil indicating the end of devices.

    if( Dev.Tag <> 0 ) then
    begin
        I := Permanent_Mailboxes.Indexof( TObject( Dev.Tag ) ) ;
        if( I <> -1 ) then
        begin
            Device_Name_Temp := 'MAILA' + inttostr( I ) ;
            Result := PAnsiChar( Device_Name_Temp ) ;
            exit ;
        end ;
        I := Temporary_Mailboxes.Indexof( TObject( Dev.Tag ) ) ;
        if( I <> -1 ) then
        begin
            Device_Name_Temp := 'MAILB' + inttostr( I ) ;
            Result := PAnsiChar( Device_Name_Temp ) ;
            exit ;
        end ;
    end ;

This code is added to the TUOS_FIP.Device_Name method. The purpose is to return the device name for a given device object instance. Mailbox devices have a tag that indicates that is a pointer to the mailbox. Thus, if the tag is not nil, we can look up the device in one of the mailbox lists and generate a name from that. If the tag is unassigned, we continue on to the existing code.

                    DVI_DEVCHAR : begin
                                      .
                                      .
                                      .
                                      if( Device.Tag <> 0 ) then
                                      begin
                                          Res := Res or DEV_V_MBX or // Device is a mailbox.
                                              DEV_V_REC ; // Record oriented
                                      end ;
                                      .
                                      .
                                      .
                                   end ;
                    DVI_DEVCLASS : begin
                                       S := copy( This_Device_Name, 1, 5 ) ;
                                       if( S = '_DISK' ) then
                                       begin
                                           Res := DC_DISK ; // Disk device
                                       end else
                                       if( S = '_MAIL' ) then
                                       begin
                                           Res := DC_MAILBOX ; // Mailbox
                                       end else
                                       if( S = '_TERM' ) then
                                       begin
                                           Res := DC_TERM ; // Terminal
                                       end else
                                       begin
                                           Res := DC_MISC ; // Miscellaneous device
                                       end ;
                                       if( Write_Integer( Res ) = UE_Error ) then
                                       begin
                                           exit ;
                                       end ;
                                   end ;
                    DVI_DEVDEPEND : begin
                                        Res := 0 ;
                                        if( Device.Terminal <> nil ) then
                                        begin
                                            Res := Device.Terminal.Terminal_Flags and $4FFFF ;
                                        end else
                                        if( Device.Tag <> 0 ) then
                                        begin
                                            MB := TMailbox( Device.Tag ) ;
                                            Res := MB.Queue.Count ;
                                        end ;
                                        if( Write_Integer( Res ) = UE_Error ) then
                                        begin
                                            exit ;
                                        end ;
                                    end ;

The TUOS_FiP.Get_Device_Info method is modified in several places to support mailboxes. The above are the modified paragraphs, showing the existing code plus the mailbox-related changes. The changes make sure the proper flags and values are returned. In the case of DVI_DEVDEPEND, the maximum message size for the mailbox is returned.

    if(
        ( TDevice( Resource._Device ).Tag <> 0 )
        and
        ( TObject( TDevice( Resource._Device ).Tag ) is TMailBox )
      ) then
    begin
        MB := TMailbox( TDevice( Resource._Device ).Tag ) ;
        MB.Remove_Handle( Resource ) ;
        MB.Check_Delete ;
    end ;

This code is added to the TUOS_FiP.Close_Handle method to handle closing a handle to a mailbox. If the device's tag data is non-zero, we first remove the handle from the mailbox, then call the Check_Delete method of the Mailbox. As we covered in the past, this will delete the mailbox if it has no more handles assigned to it and it is marked for deletion or is temporary.

function TFile_Resource.Read( Stream : longint ; Position : TStore_Address64 ;
    Length : TStore_Size64 ; var Buff ; Flags : longint ) : TStore_Size64 ;

begin
    Result := _File.Read( Stream, Position, Length, Buff, Flags ) ;
    if( _File.Is_Store ) then
    begin
        Position := Position + Result ;
    end ;
end ;


function TMailbox_Resource.Read( Stream : longint ; Position : TStore_Address64 ;
    Length : TStore_Size64 ; var Buff ; Flags : longint ) : TStore_Size64 ;

var MB : TMailbox ;

begin
    MB := TMailbox( TDevice( _Device ).Tag ) ;
    Result := MB.Read( 0, 0, Length, Buff, 0 ) ;
end ;

These methods are added to the TResource descendants that we discussed in the previous article. They handle read operations to the device or files associated with the handle. We update the Read_File method to access the file through the resource rather than through the file.

    if( ( Func and IO_Function_Mask ) = IO_READVBLK ) then
    begin
        if( ( Mode and IOM_TIMED ) <> 0 ) then
        begin
            Timeout := p3 ;
        end ;
        Request := Create_Request( Handle, 0, p1, p2 ) ;
        Pending_IOs.Add( Request ) ;
        Result := int64( Request ) ;
    end else

This code is added to the TUOS_FiP.QIO method to handle write operations.

function TMailbox_Resource.SetMode( Kernel : TUOS_Kernel ; var IOSB : TIOSB ;
    Mode, p1, p2, p3, p4, p5, p6 : int64 ) : int64 ;

var MB : TMailbox ;

begin
    MB := TMailbox( TDevice( _Device ).Tag ) ;
    if( Mode = IOM_SETPROT ) then
    begin
        P2 := P2 and PROTECTION_MASK ;
        if( MB.Device.Owner.Owner <> Kernel.USC.Get_Process_Info( Kernel.PID, JPI_UIC ) ) then 
        begin // Not the owner
            if( ( Kernel.USC.Get_Process_Info( Kernel.PID, JPI_CURPRIV ) and BYPASS ) = 0 ) then 
            begin // Does not have BYPASS
                IOSB.r_io_64.w_status := SS_ACCVIO ;
                Kernel.FIP.Set_Last_Error( Create_Error( IOSB.r_io_64.w_status ) ) ;
                exit ;
            end ;
            MB.Device.Owner.Protections := P2 ;
        end ;
    end ;
end ;


function TMailbox_Resource.SenseMode( Kernel : TUOS_Kernel ; var IOSB : TIOSB ;
    Mode, p1, p2, p3, p4, p5, p6 : int64 ) : int64 ;

var MB : TMailbox ;

begin
    MB := TMailbox( TDevice( _Device ).Tag ) ;
    IOSB.r_io_64.r_bcnt_16.w_bcnt := MB.Queue.Count ;
    IOSB.r_io_64.r_bcnt_16.l_dev_depend := MB.Current_Storage ;
    Result := 0 ;
end ;

Finally, we have added SetMode and SenseMode to the TResource class and its descendants. The above shows the implementation for the mailbox descendant. The existing code in QIO has been extracted to the TFile_Resource class. For mailboxes, the SetMode function is used to alter the protection mask for the mailbox. The caller must be the mailbox owner or have BYPASS privilege to do this. For the SenseMode function, the number of messages and current memory allocation for those messages (in bytes) is returned.

For operating systems, drivers are independent pieces of code that the operating system uses to access hardware devices. This provides some abstraction away from the hardware, which allows new devices to be added with relative ease. VMS drivers are quite extensive, taking care of the hardware interface, but also everything else related to the devices, such as buffers and meta data (e.g. insert/overwrite mode for the terminal driver). UOS, however, breaks this functionality into multiple pieces. The hardware interface is what UOS calls a driver and default drivers are included in the Hardware Abstraction Layer (HAL). Sitting on top of that, we have optional filters (for some devices) which alter the data coming from, or going to, the driver. On top of that, we have another abstraction layer, which is the resource object. Granted, it is a little more complicated than that, but that is a generalized way of looking at the pieces that implement what VMS calls a "driver". In the case of mailboxes, there is no physical hardware and therefore no UOS driver. The resource class is the only thing that sits between UOS and the mailbox "device" (which is an instance of the TMailbox class).

In the next article, we will look at the DEFINE CUSP.