WRITE

We will start our survey of UCL commands with WRITE. The reason is that this will allow us to examine the values of symbols and the results of lexical functions that we've covered over the past numerous articles. Up until now, it has been theoretical that the lexical functions work properly, but now we can examine the output to see the results. In point of fact, I've been doing internal tests of the functions to verify proper operation, but now they can be checked from the command line as well. Here is the definition of the write command:

This command writes the specified data as one record to the specified open file.

Format

WRITE file expression{,...}

Parameters
file

This specifies a file - either a file handle returned by the OPEN command or one of the process permanent files identified by the SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND logicals.

expression

Specifies data to be written to the file. This can be a literal, or an expression consisting of variables, lexical functions, literals and operators. A list of expressions delimited by commas (,) can be specified. In that case, the expressions are concatenated and then written to the file.

Description

The WRITE command updates the file position when it completes. The file must have been opened with either the /WRITE or /APPEND qualifier on the OPEN command or the WRITE command will fail except for SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND files, which don't have to be explicitly opened in order to be written to.

Qualifiers
/ERROR=label

If an I/O error occurs during the operation, control transfers to the specified label. If this qualifier isn't defined, the current ON condition action is taken if an error occurs. The $STATUS global symbol contains the error code.

/SYMBOL

This qualifier is provided for compatibility with DCL, but has no effect in UCL. There is effectively no UCL limit on the size of data written with the WRITE command.

/UPDATE

Replaces the last record read with this data. This only applies to RMS files. The file must have been read prior to this command. If replacing a sequential file record, the data must be the same size.

/WAIT
/NOWAIT

If /NOWAIT is specified, the operation will complete immediately instead of synchronizing with another reader of the mailbox. /WAIT is the default.

Example

$ WRITE SYS$OUTPUT "Beginning update..."

                    if( Sym = 'write' ) then
                    begin
                        Process_Write ;
                    end else

This code is added to the Process procedure.

procedure Process_Write ;

var Err : integer ;
    Context, Error : string ;
    I, Index : integer ;
    I64 : int64 ;
    Result, S : string ;
    Status : integer ;
    Switches : TStringList ;
    Update : boolean ;
    Wait : boolean ;

begin
    // Setup...
    Switches := Parse_Switches ;
    Update := False ;
    Wait := True ;
    Error := '' ;

    // Process switches...
    for I := 0 to Switches.Count - 1 do
    begin
        S := lowercase( Switches[ I ] ) ;
        if( S = 'symbol' ) then
        begin
            // This switch intentionally ignored
        end else
        if( S = 'update' ) then
        begin
            Update := True ;
        end else
        if( S = 'wait' ) then
        begin
            Wait := True ;
        end else
        if( S = 'nowait' ) then
        begin
            Wait := False ;
        end else
        if( copy( S, 1, 6 ) = 'error=' ) then
        begin
            Error := copy( S, 7, length( S ) ) ;
        end else
        begin
            Output_Line( RH_SysError, UCL_ERT( UCL_IVQUAL ) ) ;
            Output_Line( RH_SysError, '    \' + S + '\' ) ;
            Switches.Free ;
            exit ;
        end ;
    end ;
    Switches.Free ;

After initializing variables and obtaining the switches, if any, we process through the list of switches. We will look at the Parse_Switches function later in the article. We iterate through the list, setting the appropriate flags and ignoring the /SYMBOL switch. We exit with an error if we encounter a switch we don't support. /SYMBOL is used in DCL to allow symbols that contain more than 255 characters to overcome a limitation in DCL. We have no such limitation in UCL, so /SYMBOL does nothing for us.

    // Get output file...
    S := lowercase( Get_Token ) ;

    // Get text...
    Result := '' ;
    while( true ) do
    begin
        Result := Result + Get_Expression( err, context ) ;
        if( Err <> 0 ) then
        begin
            if( ( Err = UCL_EXPSYN ) and ( Parser.Peek <> ',' ) ) then
            begin
                Output_Line( RH_SysError, UCL_ERT( Err ) ) ;
                Output_Line( RH_SysError, '    \' + Context + '\' ) ;
                exit ;
            end ;
        end ;
        if( Parser.Peek <> ',' ) then
        begin
            break ;
        end ;
        Get_Token ; // eat the comma and loop back for next expression
    end ;

Next we obtain the file specification. Then we obtain the data to write out. We use Get_Expression to evaluate the expression and obtain a string to write. If the expression returns a UCL_EXPSYN (syntax error) and the next token is a comma, then we ignore the error (since the comma is what caused the error), skip over the comma, and then loop back to get the next expression. Each time through the loop we accumulate the data to output into the Result buffer.

    // Do the output...
    if( S = 'sys$output' ) then
    begin
        Output_Line( RH_sysOutput, Result ) ;
        Check_Error ;
    end else
    if( S = 'sys$input' ) then
    begin
        Output_Line( RH_sysInput, Result ) ;
        Check_Error ;
    end else
    if( S = 'sys$error' ) then
    begin
        Output_Line( RH_sysError, Result ) ;
        Check_Error ;
    end else
    if( S = 'sys$command' ) then
    begin
        Output_Line( RH_sysCommand, Result ) ;
        Check_Error ;
    end else

We check for the special cases and call Output_Line to write the data and check for errors.

    begin
        S := LIB_Get_Symbol( S ) ;
        if( not Valid_Int( S, I64 ) ) then
        begin
            Output_Line( RH_sysError, UCL_ERT( UCL_UNDSYM ) ) ;
            exit ;
        end ;
        Index := File_Handles.Indexof( pointer( I64 ) ) ;
        if( Index = -1 ) then
        begin
            Output_Line( RH_sysError, UCL_ERT( UCL_UNDSYM ) ) ;
            exit ;
        end ;
        Result := Result + CRLF ;
        if( Update ) then
        begin
            TCOM_File64( I64 ).Seek( Last_Read_Positions[ Index ] ) ;
        end ;
        TCOM_File64( I64 ).Write( PAnsichar( Result )[ 0 ] ) ;
        if( TCOM_File64( I64 ).IO_Error <> nil ) then
        begin
            Status := LIB_Set_Symbol( '$STATUS',
                '%X' + CVTB( 10, 16, inttostr( TCOM_File64( I64 ).IO_Error.Get_Error ) ), LNM_JOB ) ;
            if( Error <> '' ) then
            begin
                Parser.Put_Token( 'goto ' + Error ) ;
            end ;
        end else
        begin
            Status := LIB_Set_Symbol( '$STATUS', '%X0000000', LNM_JOB ) ;
        end ;
    end ;
end ; // Process_Write

In the other case, we assume that the symbol indicates a file handle created by the OPEN command, that we will use to access the file. First we translate the symbol and verify that it is numeric. If not, we exit with an error. We then look at our list of file handles to see if the value represents an actual handle. If not, we again exit with an error. Finally we add a CRLF to the data and write the buffer to the file. We then check for an error result and set the $STATUS symbol appropriately. If there was an error and the /ERROR qualifier was used, we push the Error code so it will execute next.

Note that we aren't handling any of the switches at this point. /UPDATE has to do with RMS files, and /WAIT and /NOWAIT have to do with mailboxes. We will address those in the future.

    procedure Check_Error ;

    var Status, Err : integer ;
        Work : string ;

    begin
        Err := LIB_Get_Exception( 0 ) ;
        if( Err <> 0 ) then
        begin
            Set_Exception( LIB_Get_Exception_Text( 0, Err ) ) ;
            Err := LIB_Get_Exception_Code( 0, Err ) ;
        end ;
        Status := LIB_Set_Symbol( '$STATUS',
            '%X' + CVTB( 10, 16, inttostr( Err ) ), LNM_JOB ) ;
        if( ( Error <> '' ) and ( Err <> 0 ) ) then
        begin
            Parser.Put_Token( 'goto ' + Error ) ;
        end ;
    end ;

This local function checks for an exception due to writing data to the output device. If so, the $STATUS variable is set and we push any jump to an error handler onto the token stack.

function Parse_Switches : TStringList ;

var S : string ;

begin
    Result := TStringList.Create ;
    S := Parser.Peek ;
    while( S = '/' ) do
    begin
        Get_Token ; // Eat slash
        S := Get_Token ;
        if( Parser.Peek = '=' ) then
        begin
            S := S + Get_Token + Get_Token ;
        end ;
        Result.Add( S ) ;
        S := Parser.Peek ;
    end ;
end ;

This function parses a list of qualifiers (switches) and returns a string list containing the switches.

In the next article, we will look at symbol assignment.