UCL Command execution

UCL processes commands, one at a time, as they are typed at the terminal or read from a command file. When we read and parse a command, we pass it to the Process procedure for execution. Here is the start of the Process procedure:

procedure Process( S : string ) ;

var Command_Line : AnsiString ;
    S1, Sym : Ansistring ;

begin
    Command_Line := '' ;

The command line is passed to the Process procedure. We will process it and assign it to the Command_Line variable, so we first clear that variable. You may note that this procedure is not a method of a class. There are basically two extremes when doing Object Oriented Programming. On one extreme, there are those who make literally everything a class. On the opposite extreme, there are those who don't use classes at all. Personally, I lean toward making almost everything a class. However, there are cases where there is no advantage to using a class. The UCL processing is one example of this. We could make the Process procedure a method of a TUCL class. But there is no reason to other than a blind adherence to using objects for everything. We don't need multiple UCL instances in the UCL shell, and all the data that would be encapsulated in the class is simply global (and private) to the unit.

Tokens
UCL scripts, like other scripts/programs, have variables, expressions, functions, and commands. To process command lines that contain these elements, we need a means of interpreting the lines. The way we are approaching this in UCL is to use a parser. Parsers break a longer line (the command line in this case), into smaller pieces called "tokens". A token is a single complete item - a variable name, an operator, a string literal, or some other symbol. We won't address the parser code itself here, but we will describe its basic operation since we will be using it.

A token is

anything that is a series of numeric digits
anything starting with a letter (A-Z), underscore(_), or dollar sign ($) and ends with anything other than a letter, underscore, dollar sign, or numeric digit
a literal - any set of characters delimited by double quotes (")
any character that is not a letter, underscore, dollar sign, numeric digit, whitespace (space or tab), or part of a literal

When we ask the parser for a token, it returns one or more characters comprising a single token. All white space is discarded unless it is within a literal. However, there are certain other combinations of characters that UCL considers as a token. So we tell the parser what those tokens are.

    if( Parser <> nil ) then
    begin
        Parser.Free ;
    end ;
    Parser := TParser.Create ;
    try
        Parser.Command := S ;
        Parser.Add_Special_Token( '==' ) ;
        Parser.Add_Special_Token( ':==' ) ;
        Parser.Add_Special_Token( ':=' ) ;
        Parser.Set_Quotes( '"' ) ;

First we dispose any previous parser instance for the previous command. Then we create a new instance. We assign the passed command line to the parser, then we define additional tokens that don't match the aforementioned rules:

By default, the parser handles both single (') and double (") quotes, but UCL only uses double quotes to delimit strings, so we set the valid quotes only to a double qoute. Since the parser's default behavior is to treat A-Z, 0-9, dollar signs, and underscores as valid parts of a single token (as long as the token doesn't start with a numeric digit), we are ready to start parsing a command line at this point.

    while( true ) do
    begin
        Handle_Exception ;

We will loop until a condition occurs that will cause us to exit Process (such as the end of the line). The first thing we do is check for any error conditions from the previous operation, if any.

UCL Condition Handling
Here is the code for Handle_Exception.

var Current_Exception : string ;
    Severe_Error : string ; // Command to execute on severe errors
    Error : string ; // Command to execute on errors
    Warning : string ; // Command to execute on warning

procedure Handle_Exception ;

var I : integer ;

begin
    if( Current_Exception = '' ) then
    begin
        exit ; // No current exception
    end ;
    I := pos( '-', Current_Exception ) ;
    if( copy( Current_Exception, I + 1, 1 ) = 'F' ) then
    begin
        if( Severe_Error <> '' ) then
        begin
            Parser.Put_Token( Severe_Error ) ;
            Severe_Error := '' ;
            exit ;
        end ;
    end ;
    if( copy( Current_Exception, I + 1, 1 ) = 'E' ) then
    begin
        if( Error <> '' ) then
        begin
            Parser.Put_Token( Error ) ;
            Error := '' ;
            exit ;
        end ;
    end ;
    if( copy( Current_Exception, I + 1, 1 ) = 'W' ) then
    begin
        if( Warning <> '' ) then
        begin
            Parser.Put_Token( Warning ) ;
            Warning := '' ;
            exit ;
        end ;
    end ;
    Output_Line( RH_SysError, Current_Exception ) ;
    Current_Exception := '' ;
end ;

UCL has the ability to catch certain conditions and execute UCL code when those conditions occur. One such condition is when an error/exception occurs. The variables Severe_Error, Error, and Warning contain code to execute when errors of the corresponding severity occur.
Current_Exception contains the text of the last error message. If the variable is null, there are no unhandled errors. As we have discussed previously, UOS exceptions contains a three-part prefix, delimited by dashes. The second part is a code indicating the severity of the error. So, we look for the first dash, then compare the next position in the error text for 'F' (fatal or severe error), 'E' for normal error, or 'W' for warnings. There are three global variables, one for each of the three types of errors. These strings hold the UCL code for what to do in the case of the error. For instance, 'EXIT'. We take the contents of the string and call Parser.Put_Token. This essentially prefixes the current command line with the UCL code for the error, which will be executed after we return from Handle_Exception. If there was no error handler, we output the text of the error.

More on QIO
Here is the Output procedure.

procedure Output( Handle : int64 ; const S : string ) ;

begin
    SYS_QIOW( 0, Handle, IO_WRITEPBL, integer( @IOSB ), 0, 0, integer( PChar( S ) ), length( S ), 0, 0, 0, 0 ) ;
end ;


procedure Output_Line( Handle : int64 ; const S : string ) ;

begin
    Output( Handle, S + CRLF ) ;
end ;

The Output procedure is used to write text to a given handle. The Output_Line procedure appends a CRLF to the text and calls Output. In the Current_Exception code above, we call with a handle of RH_SysError to indicate that we want to output to the current error device.

We discussed QIO in article 55, but here we introduce a new QIO function code - IO_WRITEPBL, so let's look at the changes to the FIP QIO function.

    if( ( Func and IO_Function_Mask ) = IO_WRITEPBL ) then
    begin
        if( p2 {length} > 0 ) then
        begin
            SRB.Buffer := p1 ;
            SRB.Length := p2 ;
            Prompt := Get_User_String( Kernel, Kernel.PID, SRB, IOSB.r_io_64.w_status ) ;
            if( IOSB.r_io_64.w_status = UE_Error ) then
            begin
                exit ;
            end ;
            Write_File( Handle, 0, Prompt.Contents, Prompt.Size, 0 ) ;
        end ;
        exit ;
    end ; // IO_WRITEPBL

We are reusing the Prompt variable to grab the output text, so don't let that confuse you. We obtain the string from the user memory, then call Write_File to write it out.

Previously, QIO was only called internally but now we have a case of it being called from an application. Therefore, we need to include the code to link the application to the Kernel. Here is the method in the Sys unit:

procedure SYS_QIOW( efn, Handle, func, iosb, astadr, astprm, p1, p2, p3, p4, p5, p6 : integer ) ;

var Status : byte ;
    SysRequest : TQIO_Request ;

begin
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem := UOS_Subsystem_FIP ;
    SysRequest.Request.Request := UOS_FIP_QIOW ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( Sysrequest.Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.Integer1 := efn ;
    SysRequest.Integer2 := Handle ;
    SysRequest.Integer3 := func ;
    SysRequest.Integer4 := astadr ;
    SysRequest.Integer5 := astprm ;
    SysRequest.Integer6 := p1 ;
    SysRequest.Integer7 := p2 ;
    SysRequest.Integer8 := p3 ;
    SysRequest.Integer9 := p4 ;
    SysRequest.Integer10 := p5 ;
    SysRequest.Integer11 := p6 ;
    SysRequest.Integer12 := IOSB ;

    Call_To_Ring0( integer( @SysRequest ) ) ;
end ;

The only thing to note at this point has to do with the the name of the procedure being QIOW instead of QIO. The difference is that the first is synchronous and the second is asynchronous. We will eventually add a QIO procedure as well.

Here is the change to the TUOS_FiP.API method:

        UOS_FIP_QIOW:
            begin
                UE := Enter_System_Call( Request, SReq, PID, MMC, sizeof( QIO_Request ) - sizeof( SReq ), Address ) ;
                if( UE <> nil ) then
                begin
                    Set_Last_Error( UE ) ;
                    exit ;
                end ;
                try
                    QIO_Request := PQIO_Request( Address ) ;
                    QIO( QIO_Request.Integer1, QIO_Request.Integer2,
                        QIO_Request.Integer3, IOSB, QIO_Request.Integer4,
                        QIO_Request.Integer5, QIO_Request.Integer6,
                        QIO_Request.Integer7, QIO_Request.Integer8,
                        QIO_Request.Integer9, QIO_Request.Integer10,
                        QIO_Request.Integer11 ) ;
                    Write_User( Kernel, Kernel.PID, QIO_Request.Integer12, sizeof( IOSB ), IOSB ) ;
                finally
                    Exit_System_Call( integer( String2I1_Request ), PID, MMC, 
                        sizeof( TString2I1_Request ) - sizeof( SReq ) ) ;
                end ;
            end ;

The only thing new here is the Write_User function, which is a generalized version of the Write_User_int64 that we've used before. It allows writing any number of bytes to the user memory.

Here is the code for Write_User and the updated Write_User_Int64 procedure:

function Write_User_int64( Kernel : TUOS_Kernel ; PID : TPID ;
    Address, Value : int64 ) : integer ;

begin
    Result := Write_User( Kernel, PID, Address, sizeof( Value ), Value ) ;
end ;


function Write_User( Kernel : TUOS_Kernel ; PID : TPID ;
    Address, Size : int64 ; var Value ) : integer ;

var Buffer : PAnsiChar ;
    Offset : int64 ;
    MMC : TUOS_Memory_Manager ;
    USC : TUOS_User_Security ;

begin
    MMC := Kernel.MMC ;
    USC := Kernel.USC ;
    Result := UE_Success ;
    Offset := MMC.Lock_Pages( PID, Address, Size ) ;
    try
        Buffer := PAnsiChar( MMC.Map_Pages( PID, 0, Address, Size, MAM_Write or MAM_Lock ) ) ;
        if( Buffer = nil ) then
        begin
            USC.Set_Process_Exception( PID, MMC.Last_Error ) ;
            Result := UE_Error ;
        end else
        begin
            move( Value, Buffer[ Offset ], Size ) ;
        end ;
        MMC.UnMap_Pages( 0, Address, Size ) ;
    finally
        MMC.Unlock_Pages( PID, Address, Size ) ;
    end ;
end ; // Write_User

And here is the definition of TQIO_Request:

type TQIO_Request = packed record
                        Request : TSystem_Request ;
                        Integer1 : int64 ; // Event flags
                        Integer2 : int64 ; // Handle
                        Integer3 : int64 ; // Function
                        Integer4 : int64 ; // astadr
                        Integer5 : int64 ; // astprm
                        Integer6 : int64 ; // p1
                        Integer7 : int64 ; // p2
                        Integer8 : int64 ; // p3
                        Integer9 : int64 ; // p4
                        Integer10 : int64 ; // p5
                        Integer11 : int64 ; // p6
                        Integer12 : int64 ; // iosb
                    end ;
     PQIO_Request = ^TQIO_Request ;

In the next article, we will continue our discussion of UCL command processing.