INQUIRE

The primary use for UCL during startup is to dialog with the user to set up UOS. Although we've covered ways to output text for the user, we will also need to provide a means of getting input from the user. This is accomplished via the INQUIRE command. Here is the user documentation:

INQUIRE

Reads a value from SYS$COMMAND (usually the terminal or the next line in the current command procedure) and assigns that value to a symbol.

Format

INQUIRE {qualifiers} symbolname {prompt}

Parameters

symbolname
Specifies the name of the symbol to which the value is assigned. If the symbol doesn't exist, it is created.

prompt
Specifies optional prompt text to be displayed to the user just prior to accepting input. The prompt is converted to upper case unless enclosed in quotes ("). Quotes must be used if the prompt contains punctation or whitespace (tabs and/or spaces). To include quotes in the prompt, use doubled quotes.
If a prompt is not specified, UCL uses the symbol name as the prompt. The prompt is displayed with a colon (:) and space at the end of the prompt string. This behavior can be modified with the /PUNCTUATION qualifier.

Description

INQUIRE displays the prompt and reads the response from the process' command stream. That is: the sys$command device originally assigned to the process. That means that if the INQUIRE command is encountered inside a command procedure file (however deeply nested), the prompt will be sent to the terminal that started the command file, and the input value will be read from the same.
If the command file is being run as a batch job, the input value is read from the next line of the topmost nesting level. If that line begins with a dollar sign ($), it is considered to be a command instead of input. In this case, the symbol is assigned a null value.
When the value is assigned to the symbol, the value is first converted to upper case, leading and trailing whitespace is trimmed, and multiple spaces/tabs between characters are reduced to a single space. This conversion is not done within quotes (") within the input.
Single quotes (') not occurring within double quotes (") will trigger the symbol substitution feature of UCL.

Qualifiers

/GLOBAL
This indicates that the symbol is a global symbol rather than a local symbol.

/LOCAL (default)
This indicates that the symbol is a local symbol rather than a global symbol. This is the default behavior

/{NO}PUNCTUATION
The default is /PUNCTUATION, which displays a colon and space after the prompt. Using /NOPUNCTUATION suppresses the colon and space.

Example:


$ INQUIRE/NOPUNCTUATION CONFIRM "Are you sure you want to proceed? "
$ IF .NOT. CONFIRM THEN RETURN

This code would result in the following prompt being shown on the terminal (no colon is shown due to the /NOPUNCTUATION):


Are you sure you want to proceed?

If the user enters an odd numeric value or a string that begins with T, t, Y, or y, the command file will continue. Otherwise it will return to the caller.

The behavior described above might seem a little convoluted. Certainly, if I weren't using the VMS documentation as the specification, I would have implemented this as read from SYS$INPUT as it exists at the time of the execution of INQUIRE, rather than using SYS$COMMAND of the outermost level. But one of the reasons we are following the VMS specification is because the designers of VMS put a lot of thought into the design, which was refined over many years of wide usage (VMS has been around longer than MS Windows), so I tend to defer to its behavior despite the few deviations we've made so far. And if you think about it, the VMS behavior makes sense: one may want to query the user for information during some long, involved process. SYS$COMMAND may have been redirected due to a nested command file, but we still want to query the user. That is, essentially, what the above description defines. As we will see in a future article, there are ways of getting input from a specific place, but INQUIRE is used to query the user.
Of course, the situation with a batch file (a command file running without an attached terminal) is a little different. Basically, the outermost level serves as the terminal would in an interactive process.

                    if( Sym = 'inquire' ) then
                    begin
                        Process_Inquire ;
                    end else

This code is added to the Process routine.

procedure Process_Inquire ;

var Err : integer ;
    Buffer : PAnsiChar ;
    Context : string ;
    F : TCOM_File64 ;
    I, Index : integer ;
    E, I64 : int64 ;
    Prompt, S, Sym : string ;
    Res : int64 ;
    Status : integer ;
    Switches : TStringList ;
    Local, Punctuation : boolean ;
    Table : integer ;
    Original_Context : TUCL_Context ;

begin
    // Setup...
    Local := True ;
    Punctuation := True ;
    Switches := Parse_Switches ;

    // Process switches...
    for I := 0 to Switches.Count - 1 do
    begin
        S := uppercase( Switches[ I ] ) ;
        if( Name_Match( S, 'LOCAL', 1 ) ) then
        begin
            Local := True ;
        end else
        if( Name_Match( S, 'GLOBAL', 1 ) ) then
        begin
            Local := False ;
        end else
        if( Name_Match( S, 'PUNCTUATION', 1 ) ) then
        begin
            Punctuation := True ;
        end else
        if( Name_Match( S, 'NOPUNCTUATION', 1 ) ) then
        begin
            Punctuation := False ;
        end else
        begin
            Exception( UCL_IVQUAL, S ) ;
            Switches.Free ;
            exit ;
        end ;
    end ;
    Switches.Free ;

This new function handles the INQUIRE command. First we parse the switches, setting the appropriate flags and exiting on unrecognized switches.

    // Get symbol name...
    Sym := lowercase( Get_Token ) ;
    if( Sym = '' ) then // No symbol specified
    begin
        Exception( UCL_PARMDEL, '' ) ;
        exit ;
    end ;
    if( not Valid_Symbol_Name( Sym ) ) then // Invalid symbol
    begin
        Exception( UCL_PARMDEL, Sym ) ;
        exit ;
    end ;

After switches, we get the symbol name that is the target of the input. If one was not provided or isn't a valid symbol name, we exit with an error.

    // Get prompt...
    Prompt := Edit( Get_Token, 8 or 16 or 32 or 128 or 256 ) ;
    if( length( Prompt ) = 0 ) then
    begin
        Prompt := uppercase( Sym ) ;
    end ;
    if( Punctuation ) then
    begin
        Prompt := Prompt + ': ' ;
    end ;

Next we get the prompt. If no prompt was provided, we use the uppercase of the symbol name. Either way, if /NOPUNCTUATION wasn't specified, we suffix the prompt with a colon and a space.

    // Prompt the user...
    F := nil ;
    Original_Context := TUCL_Context( Contexts[ 0 ] ) ;
    if( Original_Context.syscommand_name = This_UCL_Context.syscommand_name ) then
    begin
        if( Interactive ) then
        begin
            Output( RH_SysCommand, Prompt ) ;
        end ;
    end else
    if( Interactive( Original_Context.syscommand_name ) ) then
    begin
        F := Open_Binary_File( Original_Context.syscommand_name, 0 ) ;
        F.Blockwrite( PChar( S )[ 0 ], length( S ), Res ) ;
    end ;
    F.Free ;
    F := nil ;

Now it is time to prompt the user. We get the outermost context and compare its syscommand name to the current syscommand name. If they are the same, we can simply output the prompt to the current sys$command if we are interactive. If they differ, we are currently using a different source for commands, which is probably not the terminal. In that case, we open the file and write the prompt if the device is interactive. Note that we have added a parameter to Interactive, which we will address in a bit.
You might be saying, "Wait! You're outputting to the input-only sys$command!" Well, we only do that if the sys$command is interactive - meaning it is a terminal. In such a case, the terminal isn't open as read-only, so we can write to it without problem. Why not use sys$output? Because that might have been redirected (either by reassignment or by a /OUTPUT switch), and the point of INQUIRE is to prompt the user, so will send the prompt to the terminal, regardless of any output redirection.

    // Get input from user...
    if( F = nil ) then
    begin
        S := Get_Line( '' ) ;
        if( not Interactive ) then
        begin
            if( copy( S, 1, 1 ) = '$' ) then
            begin
                Put_Line( S ) ;
                S := '' ;
            end ;
        end ;
    end else
    begin
        for I := 0 to Original_Context.syscommand_line do // Read up to current line
        begin
            F.Readln( Buffer ) ;
        end ;
        S := Buffer ;
        F.Free ;
        if( copy( S, 1, 1 ) = '$' ) then
        begin
            S := '' ;
        end else
        begin
            inc( Original_Context.syscommand_line ) ;
        end ;        
    end ;

Now we are ready to read the user's response. If no file is assigned (F is nil), we are already getting our input from the outermost source, so we use Get_Line (with no prompt) to get the value. If it begins with a dollar sign and we're not interactive, the source must be a command file that doesn't have data for the prompt. This means that we've read a line that is actually the next command, so we use Put_Line (covered below) to essentially put the command back. And we clear S.
However, if we opened a file for the prompt, we need to read the input from that file. Likewise, if the first character isn't a dollar sign, we clear the value to be assigned to the symbol. Otherwise, we increment the syscommand_line of the outermost nesting level, so that when we return to that level, UCL will read up to, and past, the line that we just read as the response to the INQUIRE.

    // Massage value and do symbol substitution...
    S := Edit( S, 4 or 8 or 16 or 32 or 128 or 256 or $100000 ) ;
    // Remove CR/LF/etc, leading/trailing spaces, and reduce whitespace to single
    // space, but not within quotes

    S := Trim_Quotes( S ) ;
    S := Phase_I_Substitution( S ) ;

Now that we have a response, we format it according to the above rules. We trim any quotes from the start/end of the string, and then run the phase I substitution process on the data to do symbol substitution.

    // Set symbol...
    if( Local ) then
    begin
        Table := LNM_PROCESS ;
    end else
    begin
        Table := LNM_JOB ;
    end ;
    LIB_Set_Symbol( Sym, S, Table ) ;
    E := LIB_Get_Exception( 0 ) ;
    if( E <> 0 ) then
    begin
        S := LIB_Get_Exception_Text( 0, Status ) ;
        Set_Exception( S ) ;
    end ;
end ; // Process_Inquire

Finally, we assign the value to the symbol. We choose the appropriate table, do the assignment, and report any errors.

function Interactive( Dev : string = '' ) : boolean ;

begin
    Buff := 0 ;
    BufLen := 0 ;
    fillchar( Descriptor, sizeof( Descriptor ), 0 ) ;
    Descriptor[ 0 ].Buffer_Length := sizeof( Buff ) ;
    Descriptor[ 0 ].Item_Code := DVI_DEVCHAR ; // DVIDEF item
    Descriptor[ 0 ].Buffer_Address := integer( @Buff ) ;
    Descriptor[ 0 ].Return_Length_Address := integer( @BufLen ) ;
    if( Dev = '' ) then // Default command
    begin
        GETDVIW( 0, RH_SysCommand, '', integer( @Descriptor ), integer( @IOSB ),
            0, 0, '', 1 ) ;
    end else
    begin
        GETDVIW( 0, 0, Dev, integer( @Descriptor ), integer( @IOSB ), 0, 0, '',
            1 ) ;
    end ;
    Result := ( ( Buff and DEV_V_TRM ) <> 0 ) ; // Terminal device
end ;

This function has been updated to take an optional parameter indicating which device to check - it defaults to the current sys$command.

var Pushed_Lines : TStringList = nil ;

procedure Put_Line( const S : string ) ;

begin
    if( Pushed_Lines = nil ) then
    begin
        Pushed_Lines := TStringList.Create ;
    end ;
    Pushed_Lines.Add( S ) ;
end ;

This new code is to support "putting a line back" if we got one that we didn't expect. Specifically: a command line instead of a data line.

    if( ( Pushed_Lines <> nil ) and ( Pushed_Lines.Count > 0 ) ) then
    begin
        Result := Pushed_Lines[ 0 ] ;
        Pushed_Lines.Delete( 0 ) ;
        exit ;
    end ;

This paragraph of code is inserted at the beginning of the Get_Line function to return the next line that was put back with Put_Line, if any, rather than reading from the actual command source.

We referenced the Blockwrite method for the file object in the code above. We've covered reading data from files, but we haven't yet discussed writing to files. So, in the next article, we will look at the WRITE system service.