LIB_SPAWN

In this article we will look at the SPAWN service.

function SPAWN( Command : string ; _Input : string ;
    _Output : string ; Flags : integer ; Name : string ;
    PID : integer ; var Status : int64 ; Event_Flags : int64 = 0 ;
    AST : int64 = 0 ; ASTPrm : int64 = 0 ; Prompt : string = '' ;
    CLI : string = '' ; Table : string = '' ) : int64 ;

var SRB_Command, SRB_Input, SRB_Output, SRB_Name, SRB_Prompt, SRB_CLI, SRB_Table : TSRB ;

begin
    Set_String( Command, SRB_Command ) ;
    Set_String( _Input, SRB_Input ) ;
    Set_String( _Output, SRB_Output ) ;
    Set_String( Name, SRB_Name ) ;
    Set_String( Prompt, SRB_Prompt ) ;
    Set_String( CLI, SRB_CLI ) ;
    Set_String( Table, SRB_Table ) ;
    Result := LIB_SPAWN( int64( @SRB_Command ), int64( @SRB_Input ),
        int64( @SRB_Output ), int64( @Flags ), int64( @SRB_Name ),
        int64( @PID ), int64( @Status ), int64( @Event_Flags ),
        int64( @AST ), int64( @ASTPrm ), int64( @SRB_Prompt ),
        int64( @SRB_CLI ), int64( @SRB_Table ) ) ;
end ;

This is the Pascal interface for LIB_SPAWN.

function LIB_SPAWN( Command : int64 = 0 ; _Input : int64 = 0 ;
    _Output : int64 = 0 ; Flags : integer = 0 ; Name : int64 = 0 ;
    PID : integer = 0 ; Status_Addr : int64 = 0 ; Event_Flags : int64 = 0 ;
    AST : int64 = 0 ; ASTPrm : int64 = 0 ; Prompt : int64 = 0 ; CLI : int64 = 0 ;
    Table : int64 = 0 ) : int64 ;

var Request : TString7I6_Request ;
    Status : int64 ;
    Prv, Prvadr, stsflg : int64 ;
    Temp : TSRB ;
    Monitor_Flags : int64 ;
    New_PID : TPID ;

begin
    // Setup...
    if( Flags <> 0 ) then
    begin
        Flags := Pint64( Flags )^ ;
    end ;
    Prvadr := 0 ;
    stsflg := 0 ;

    // Validation...
    if( ( Flags > 511 ) or ( Flags < 0 ) ) then
    begin
        Result := LIB_INVARG ; // Invalid bits set
        exit ;
    end ;

You may have gathered from previous articles, that Starlet provides two basic functions. First, it provides services at the Application layer. Second, it provides simplified interfaces to executive layer services. This is true of both VMS and UOS. LIB_SPAWN is one of the second types. Creating new processes is obviously something left to the executive for security reasons, so LIB_SPAWN simply provides a programming shortcut to the SYS_CREPRC system service.

The first thing we do is get and validate parameters. Only the lower 9 bits of the flags are supported and using any others generates an error.

    // Prepare parameters...
    if( ( Flags and CLI_M_AUTHPRIV ) <> 0 ) then // Wants to use authorized privileges
    begin
        fillchar( Temp, sizeof( Temp ), 0 ) ;
        fillchar( Itemlist, sizeof( Itemlist ), 0 ) ;
        Itemlist[ 0 ].Item_Code := UAI_PRIV ;
        Itemlist[ 0 ].Buffer_Length := sizeof( Prv ) ;
        Itemlist[ 0 ].Buffer_Address := int64( @Prv ) ;
        Itemlist[ 0 ].Return_Length_Address := 0 ;
        Result := SYS_GETUAI( 0, 0, Temp, int64( @Itemlist ), 0, 0, 0 ) ;
        if( Result <> 0 ) then
        begin
            exit ;
        end ;
        Prvadr := int64( @Prv ) ;
    end ;

If the CLI_M_AUTHPRIV flag is set, we want the created process to have all of its authorized privileges. This requires that we obtain the authorized privileges for the user via SYS_GETUAI and having them written to the Prv variable so we can pass them to SYS_CREPRC.

    if( ( Flags and CLI_M_TRUSTED ) <> 0 ) then
    begin
        stsflg := stsflg or PRC_M_TRUSTED ;
    end ;
    if( ( Flags and CLI_M_NONRANDOM ) <> 0 ) then
    begin
        stsflg := stsflg or PRC_M_NONRANDOM ;
    end ;
    if( ( Flags and CLI_M_SUBSYSTEM ) <> 0 ) then
    begin
        stsflg := stsflg or PRC_M_SUBSYSTEM ;
    end ;
    if( ( Flags and CLI_M_SUBSYSTEM ) <> 0 ) then
    begin
        stsflg := stsflg or PRC_M_SUBSYSTEM ;
    end ;
    if( ( Flags and ( CLI_M_NOCLISYM or CLI_M_NOLOGNAM ) ) = 0 ) then
    begin
        stsflg := stsflg or PRC_M_CLONE_SYMBOLS ;
    end ;

Many of the flags for LIB_SPAWN are passed on to SYS_CREPRC. We translate them into the appropriate values. Note that because VMS separates symbols from logicals, whereas UOS combines them both into symbols, if either VMS flag is specified, we set the PRC_M_CLONE_SYMBOLS flag.

    // Create the process...
    Result := SYS_CREPRC( int64( @New_PID ), CLI, _Input, _Output, 0, Prvadr, 0,
        Name, 0, 0, 0, int64( @stsflg ), 0, 0, 0 ) ;
    if( Result <> 0 ) then
    begin
        exit ;
    end ;
    if( PID <> 0 ) then
    begin
        pPID( PID )^ := New_PID ;
    end ;

Now we call SYS_CREPRC to create the process. If an error is returned, we exit with that error. Otherwise, we take the PID written from SYS_CREPRC to New_PID, and write it to the return address passed to us (unless the address passed to us was 0).

    if( ( Flags and CLI_M_NOWAIT ) = 0 ) then
    begin
        Monitor_Flags := 1 ;
        SYS_Monitor_Process( int64( @PID ), Event_Flags, AST, ASTPrm, int64( @Monitor_Flags ) ) ;
        if( ( Flags and CLI_M_NOTIFY ) <> 0 ) then
        begin
            LIB_Put_Output( 'Process terminated' + CRLF ) ;
        end ;
    end ;
end ; // LIB_SPAWN

Finally, if the CLI_M_NOWAIT flag isn't specified, the user wants to wait until the subprocess ends. In VMS, I suspect that a "mailbox" is created to receive the process termination notification, but I don't know that for certain. But rather than that, we will make a call to a new service: SYS_Monitor_Process, which will block our process until the notification occurs. After our process is resumed, if the CLI_M_NOTIFY flag is set, we'll output a notification. Why not use a mailbox? Because it would count against the process' mailbox quota and it has a fair bit of overhead. Plus I have some ideas for how the SYS_Monitor_Process could be used for additional features in the future. I won't bother to document that service quite yet, but we will look at the implementation as of now.

function SYS_Monitor_Process( PID, EFN, AST, ASTPrm, Flags : int64 ) : int64 ;

var Status : int64 ;
    SysRequest : TInteger5_Request ;

begin
    Status := 0 ;
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem := UOS_Subsystem_USC ;
    SysRequest.Request.Request := UOS_USC_Monitor ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( Sysrequest.Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.Int1 := PID ;
    SysRequest.Int2 := efn ;
    SysRequest.Int3 := AST ;
    SysRequest.Int4 := astprm ;
    SysRequest.Int5 := Flags ;

    Call_To_Ring0( integer( @SysRequest ) ) ;
end ;

This is a standard system service wrapper - nothing unusual to comment on.

        UOS_USC_Monitor:
            begin
                UE := Enter_System_Call( Request, SReq, PID, MMC, sizeof( TInteger5_Request ) - 
                    sizeof( SReq ), Address ) ;
                if( UE <> nil ) then
                begin
                    Set_Last_Error( UE ) ;
                    exit ;
                end ;
                try
                    I5_Request := PInteger5_Request( Address ) ;
                    Monitor_Process( I5_Request.Int1, I5_Request.Int2, I5_Request.Int3, 
                        I5_Request.Int4, I5_Request.Int5 ) ;
                finally
                    Exit_System_Call( Request, PID, MMC, 
                        sizeof( TItem_Request ) - sizeof( SReq ) ) ;
                end ;
            end ;

This code is added to the USC.API method. This is also typical of what we've seen before.

procedure TUSC.Monitor_Process( PID, EFN, AST, ASTPrm, Flags : int64 ) ;

var Op : TUOS_Operation ;
    Process : TProcess ;
    Status : integer ;

begin
    // Get source process...
    if( PID = 0 ) then
    begin
        PID := Kernel.PID ;
    end else
    begin
        PID := Get_User_Integer( Kernel, Kernel.PID, PID, Status ) ;
        if( Status = UE_Error ) then
        begin
            if( MMC.Last_Error = nil ) then
            begin
                Generate_Exception( UOSErr_Memory_Address_Error ) ;
            end ;
            exit ;
        end ;
        Process := Get_Process( PID ) ;
        if( Process = nil ) then
        begin
            Generate_Exception( UOSErr_Nonexistent_Process ) ;
            exit ;
        end ;
        if( ( PID <> Kernel.PID ) and ( Kernel.PID <> Process.Parent._PID ) ) then
        begin
            Generate_Exception( UOSErr_Invalid_Context ) ;
            exit ;
        end ;
    end ;

This method is used to set up a callback notification for a process. For now, the only notification is for process termination. First, we get the PID for the process we want a notification from and verify that it is a valid process. If not, we exit with an error. Also, the process must be the calling process or an immediate child of the calling process.

    // Get Remaining parameters...
    if( EFN <> 0 ) then
    begin
        EFN := Get_User_Integer( Kernel, Kernel.PID, EFN, Status ) ;
        if( Status = UE_Error ) then
        begin
            if( MMC.Last_Error = nil ) then
            begin
                Generate_Exception( UOSErr_Memory_Address_Error ) ;
            end ;
            exit ;
        end ;
    end ;
    if( AST <> 0 ) then
    begin
        AST := Get_User_Integer( Kernel, Kernel.PID, AST, Status ) ;
        if( Status = UE_Error ) then
        begin
            if( MMC.Last_Error = nil ) then
            begin
                Generate_Exception( UOSErr_Memory_Address_Error ) ;
            end ;
            exit ;
        end ;
    end ;
    if( ASTPrm <> 0 ) then
    begin
        ASTPrm := Get_User_Integer( Kernel, Kernel.PID, ASTPrm, Status ) ;
        if( Status = UE_Error ) then
        begin
            if( MMC.Last_Error = nil ) then
            begin
                Generate_Exception( UOSErr_Memory_Address_Error ) ;
            end ;
            exit ;
        end ;
    end ;
    if( Flags <> 0 ) then
    begin
        Flags := Get_User_Integer( Kernel, Kernel.PID, Flags, Status ) ;
        if( Status = UE_Error ) then
        begin
            if( MMC.Last_Error = nil ) then
            begin
                Generate_Exception( UOSErr_Memory_Address_Error ) ;
            end ;
            exit ;
        end ;
    end ;

    Op := Create_Operation ;
    Op.PID := Kernel.PID ;
    Op.EF := EFN ;
    Op.AST := AST ;
    Op.ASTPrm := ASTPrm ;
    if( ( Flags and 1 ) = 1 ) then
    begin
        Op.Blocking := True ;
    end ;
    Process.Monitor_Operation := Op ;
end ; // TUSC.Monitor_Process

Next we get the remaining parameters, construct a operation object, set the values and then set the process' Monitor_Operation to this object. Note that if flag bit 1 is specified, we block the calling process.

                        _Monitor_Operation : TUOS_Operation ;

This item is added to the TProcess instance data.

type TUOS_Operation = class
                          public // Property handlers...
                              function Get_PID : TPID ;
                                  virtual ; stdcall ; abstract ;
                              procedure Set_PID( Value : TPID ) ;
                                  virtual ; stdcall ; abstract ;
                              function Get_EF : longint ;
                                  virtual ; stdcall ; abstract ;
                              procedure Set_EF( Value : longint ) ;
                                  virtual ; stdcall ; abstract ;
                              function Get_Blocking : boolean ;
                                  virtual ; stdcall ; abstract ;
                              procedure Set_Blocking( Value : boolean ) ;
                                  virtual ; stdcall ; abstract ;
                              function Get_AST : int64 ;
                                  virtual ; stdcall ; abstract ;
                              procedure Set_AST( Value : int64 ) ;
                                  virtual ; stdcall ; abstract ;
                              function Get_ASTPrm : int64 ;
                                  virtual ; stdcall ; abstract ;
                              procedure Set_ASTPrm( Value : int64 ) ;
                                  virtual ; stdcall ; abstract ;

                          public // Properties...
                              property PID : TPID
                                  read Get_PID
                                  write Set_PID ;
                              property EF : longint
                                  read Get_EF
                                  write Set_EF ;
                              property Blocking : boolean
                                  read Get_Blocking
                                  write Set_Blocking ;
                              property AST : int64
                                  read Get_AST
                                  write Set_AST ;
                              property ASTPrm : int64
                                  read Get_ASTPrm
                                  write Set_ASTPrm ;
                      end ;

This is the definition of TUOS_Operation.

type TOperation = class( TUOS_Operation )
                      private // Instance data...
                          _PID : TPID ; // Process
                          _EF : longint ; // Event flag
                          _Blocking : boolean ; // True if process blocked
                          _AST : int64 ;
                          _ASTPrm : int64 ;

                      public // Overrides...
                          function Get_PID : TPID ; override ;
                          procedure Set_PID( Value : TPID ) ; override ;
                          function Get_EF : longint ; override ;
                          procedure Set_EF( Value : longint ) ; override ;
                          function Get_Blocking : boolean ; override ;
                          procedure Set_Blocking( Value : boolean ) ; override ;
                          function Get_AST : int64 ; override ;
                          procedure Set_AST( Value : int64 ) ; override ;
                          function Get_ASTPrm : int64 ; override ;
                          procedure Set_ASTPrm( Value : int64 ) ; override ;
                  end ; // TOperation


function TOperation.Get_PID : TPID ;

begin
    Result := _PID
end ;


procedure TOperation.Set_PID( Value : TPID ) ;

begin
    _PID := Value ;
end ;


function TOperation.Get_EF : longint ;

begin
    Result := _EF ;
end ;


procedure TOperation.Set_EF( Value : longint ) ;

begin
    _EF := Value ;
end ;


function TOperation.Get_Blocking : boolean ;

begin
    Result := _Blocking ;
end ;


procedure TOperation.Set_Blocking( Value : boolean ) ;

begin
    _Blocking := Value ;
end ;


function TOperation.Get_AST : int64 ;

begin
    Result := _AST ;
end ;


procedure TOperation.Set_AST( Value : int64 ) ;

begin
    _AST := Value ;
end ;


function TOperation.Get_ASTPrm : int64 ;

begin
    Result := _ASTPrm ;
end ;


procedure TOperation.Set_ASTPrm( Value : int64 ) ;

begin
    _ASTPrm := Value ;
end ;

This is the implementation of an operation descendant.

                        _Monitor_Operation : TUOS_Operation ;

                        property Monitor_Operation : TUOS_Operation
                            read _Monitor_Operation
                            write Set_Monitor_Operation ;

This instance data and property is added to the TProcess class.

procedure TProcess.Set_Monitor_Operation( Value : TUOS_Operation ) ;

begin
    if( _Monitor_Operation <> nil ) then
    begin
        _Monitor_Operation.Free ;
    end ;
    _Monitor_Operation := Value ;
end ;

This is the handler for the Monitor_Operation property. Only one Monitor_Operation is allowed at a time, so we free any pre-existing ones before assigning the new one.

    if( _Monitor_Operation <> nil ) then
    begin
        if( _Monitor_Operation.EF <> 0 ) then
        begin
            //TODO
        end ;
        if( _Monitor_Operation.AST <> 0 ) then
        begin
            _Kernel.Call_AST( _Monitor_Operation.PID, _Monitor_Operation.AST, 
                _Monitor_Operation.ASTPrm ) ;
        end ;
        if( _Monitor_Operation.Blocking ) then
        begin
            _Kernel.USC.Unblock( _Monitor_Operation.PID ) ;
        end ;
        Monitor_Operation := nil ;
    end ; // if( _Monitor_Operation <> nil )

The only remaining thing now is to add the above code to the TProcess destructor so that when the process is destroyed, a callback is made. We are leaving the event flag handling to future articles. If the process in question blocked on this notification, it is unblocked.

In the next article, we will look at the documentation for the SYS_CREPRC service.