Getting input from a terminal is more complicated than doing output. The main issue is that input is unsolicited. Another way of saying this is that input happens asynchronously - while the program is doing something else. That is, input may come in even before we ask for it. With a store, we only get input after we request it, so we have a place for the data to go. We know ahead of time how big the buffer needs to be because we request a specific amount of data. We have none of these advantages when dealing with terminal input.

Just as we have an output buffer to hold output for a terminal until the terminal is ready for it, we also need an input buffer to hold input from a terminal until the program is ready for it. We will discuss this in one of the following articles.

Also, just as we have an output filter to cook terminal output, we also have an input filter to cook input from the terminal. But the input filter does a lot more work than the output filter, as we will see in a following article.

So, we can see that the input and output stacks have a similar struture, however the input stack has more going on. As we did with output, we will start with the application (UCL) and work our way back to the UOS code that interfaces with the hardware. But first, we need to consider something about outputting a prompt that we didn't address when we discussed using Put_Output.

We used LIB_Put_Output to write the UCL prompt to the terminal. But, as we've discussed, UCL can get commands from any source that sys$command points to, including a file. If we are getting commands from a file, there is no need to write a prompt. In fact, if the command source is not a terminal, we don't want to try writing a prompt to it. We could query UOS for information on the device and see if it is a terminal, but VMS/UOS has a system call named LIB_Get_Command. This call will get input from sys$command, and it will also write a prompt if the device is a terminal.

function Get_Command : string ;

var S : Ansistring ;

begin
    S := LIB_Get_Symbol( '$ucl_prompt' ) ;
    if( S = '' ) then
    begin
        S := '$ ' ;
    end ;
    Result := LIB_Get_Command( S ) ;
end ;


procedure Run ;

var S : string ;

begin
    while( True ) do
    begin
        S := Get_Command ;
    end ;
end ;

function LIB_Get_Command( const Prompt : string ) : string ;

var RAB : TRAB ;

begin
    fillchar( RAB, sizeof( RAB ), 0 ) ;
    RAB.RAB_Size := sizeof( RAB ) ;
    RAB.RAB_W_ISI := RH_SysCommand ;
    RAB.RAB_L_RBF := integer( PAnsiChar( Prompt ) ) ;
    RAB.RAB_W_RSZ := length( Prompt ) ;
    Result := RMS.Get_Command( RAB ) ;
end ;

var Temp : string ;

function Get_Command( var RAB : TRAB ) : PChar ;

var Length : int64 ;
    Status : byte ;
    SysRequest : TString2I1_Request ;
    ResString : string ;

begin
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem := UOS_Subsystem_FIP ;
    SysRequest.Request.Request := UOS_FIP_Get_Command ;
    SysRequest.Request.Length := sizeof( TString2I1_Request ) - sizeof( SysRequest.Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.String2.Buffer := RAB.RAB_L_RBF ;
    SysRequest.String2.Length := RAB.RAB_W_RSZ ;

    setlength( ResString, 256 ) ;
    SysRequest.String1.Buffer := integer( PChar( ResString ) ) ; // Address of buffer to receive input
    SysRequest.String1.Length := system.length( ResString ) ; // Max buffer size
    SysRequest.Integer1 := integer( @Length ) ; // Where to write result length

    Call_To_Ring0( integer( @SysRequest ) ) ;
    setlength( ResString, Length ) ;
    Temp := ResString ;
    Result := PChar( Temp ) ;
end ;

      UOS_FIP_Get_Command:
          begin
              UE := Enter_System_Call( Request, SReq, PID, MMC, sizeof( TString2I1_Request ) - sizeof( SReq ), Address ) ;
              if( UE <> nil ) then
              begin
                  Set_Last_Error( UE ) ;
                  exit ;
              end ;
              try
                  String2I1_Request := PString2I1_Request( Address ) ;

                  // Read input into user's buffer...
                  QIO( 0, RH_SysCommand, IO_READPROMPT, IOSB, 0, 0,
                      String2I1_Request.String1.Buffer,
                      String2I1_Request.String1.Length, 0, {timeout} 0, {read terminator block}
                      String2I1_Request.String2.Buffer,
                      String2I1_Request.String2.Length ) ;
                  Status := Write_User_int64( Kernel, PID, String2I1_Request.Integer1, IOSB.r_io_64.r_bcnt_32.l_bcnt ) ;
              finally
                  Exit_System_Call( integer( String2I1_Request ), PID, MMC, sizeof( TString2I1_Request ) - sizeof( SReq ) ) ;
              end ;
          end ;

We call QIO to perform most I/O operations. QIO stands for "Queue I/O", which will make sense in the future when we discuss I/O queues. Upon return, we call Write_User_int64 to write the length value.

We will discuss QIO in the next article, but before we end this article, let's briefly discuss the other functions that we call in this code.

function Enter_System_Call( Request : int64 ; const SReq : TSystem_Request ;
    PID : TPID ; MMC : TUOS_Memory_Manager ; Size : integer ;
    var Address : int64 ) : TUnified_Exception ;

var Base, Offset : int64 ;

begin
    // Setup and sanity check...
    Result := nil ; // Assume success
    if( SReq.Length < Size ) then
    begin
        Result := Create_Error( UOSErr_Invalid_System_Request ) ;
        exit ;
    end ;
    Size := Size + sizeof( SReq ) ;

    // Get access to Request structure...
    Offset := MMC.Lock_Pages( PID, Request,  Size ) ;
    try
        Base := MMC.Map_Pages( PID, 0, Request, Size, MAM_Read or MAM_Lock ) ;
        if( Base = 0 ) then // Couldn't map memory
        begin
            if( MMC.Last_Error = nil ) then
            begin
                Result := Create_Error( UOSErr_Memory_Address_Error ) ;
            end else
            begin
                Result := MMC.Last_Error ;
            end ;
            exit ;
        end ;
        Address := Base + Offset ;
    finally
        if( Result <> nil ) then // Failure
        begin
            MMC.Unlock_Pages( PID, Base, Size ) ;
        end ;
    end ;
end ; // Enter_System_Call


procedure Exit_System_Call( Address : int64 ; PID : TPID ;
    MMC : TUOS_Memory_Manager ; Size : integer ) ;

begin
    // Release system request structure...
    Size := Size + sizeof( TSystem_Request ) ;
    MMC.UnMap_Pages( 0, Address, Size ) ;
    MMC.Unlock_Pages( PID, Address, Size ) ;
end ;

function Write_User_int64( Kernel : TUOS_Kernel ; PID : TPID ;
    Address, Value : int64 ) : 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, sizeof( Value ) ) ;
    try
        Buffer := PAnsiChar( MMC.Map_Pages( PID, 0, Address, sizeof( Value ), 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 ], sizeof( Value ) ) ;
        end ;
        MMC.UnMap_Pages( 0, Address, sizeof( Value ) ) ;
    finally
        MMC.Unlock_Pages( PID, Address, sizeof( Value ) ) ;
    end ;
end ; // Set_User_String