Lexical functions - F$UNIQUE, F$USER, and F$VERIFY

The F$UNIQUE lexical function generates a unique string. Here is the definition:

F$UNIQUE generates a string that is suitable to be a file name and is guaranteed to be unique across the cluster. Unique file names can be used when creating temporary files. Note that this function guarantees a unique name for each time it is called, no matter which process or node is making the call. However, it does not guarantee that the name is not already in use on the system.

Format
F$UNIQUE()

Return Value
A unique character string.

Arguments
none

Example
$ A = F$UNIQUE()
This call will set the symbol A to a unique string which can be used as a filename.

        Function_UNIQUE : begin
                              if( Missing_Parentheses( '(' ) ) then
                              begin
                                  exit ;
                              end ;
                              if( Process_Unique( Err, Context ) ) then
                              begin
                                  exit ;
                              end ;
                              if( Missing_Parentheses( ')' ) ) then
                              begin
                                  exit ;
                              end ;
                              S := Context ;
                          end ;

This code is added to the Function_Reference function.

function Process_Unique( var Err : integer ; var Context : string ) : boolean ;

var I : integer ;
    L : int64 ;
    N, S : string ;

begin
    // Setup...
    Result := False ; // Assume no problems

    setlength( S, sizeof( int64 ) ) ;
    L := LIB_Get_Timestamp ;
    move( L, PChar( S )[ 0 ], sizeof( int64 ) ) ;
    S := S + Get_SYI( SYI_NODENAME, '', 0 ) ;
    N := '' ;
    for I := length( S ) downto 1 do
    begin
        N := N + Hex( ord( S[ I ] ) ) ;
    end ;
    Context := N ;
end ;

This function constructs a unique filename. The idea here is that the system clock interval is fast enough that no two processes will request the current time at the same time. In actuality, that is quite possible, given the low resolution of most hardware clocks used in computers these days. However, the UOS rule is that each request for a timestamp from the HAL must return a different value. In our simulated HAL, we do this by remembering the last time a request was made and, if the time is the same as that, we add an internal nanosecond offset, and increment that offset. In essence, multiple requests within the minimum resolution of the hardware will result in values indicting the current time, plus 1 nanosecond for each subsequent call. Thus, the timestamp we get will be a unique value. We can use this to generate a unique name. Note: Just so you know, this still holds for multi-processor systems since reading the timestamp is a serialized feature (only one access at a time).

While this approach yields a guaranteed unique value for each call on a given computer, there is no guarantee that the same value cannot be obtained from two or more different computers in a cluster. Because the value has to be unique within the cluster, we need to take this situation into account. Since each node in a cluster must be unique, we'll use the node name as a prefix for the timestamp. Problem solved.

We use a string in this case as a binary buffer. We move the timestamp into the string, then prepend the node name. Next we iterate through the buffer, converting each byte to a hexadecimal value, and building the result string from that.

The F$USER lexical function returns the username of the user running the script. Here is the definition.

F$USER returns the current user name as a string. The function takes no arguments, but must be followed by parentheses.

Format
F$USER()

Return Value
A character string containing the current user's username.

Arguments
none

Example
$ A = F$USER()
This call will set the symbol A to the user name of the user running the script.

function Process_User( var Err : integer ; var Context : string ) : boolean ;

begin
    Result := False ; // Assume no problems

    Context := Get_JPI( 0, JPI_USERNAME ) ;
end ;

This function simply makes a GETJPI system service call and returns the user name.

UCL (and DCL) has a means of logging the input file to the terminal when a script is run. Normally, the script is not echoed to the terminal. There are two aspects of what is in a command file: commands and data. UCL has two flags that indicate whether or not to echo those items. When a command procedure is started, these flags are set to False, but the F$VERIFY lexical function can be used to change their state. Here is the definition:

F$VERIFY returns an integer value indicating whether the procedure verification flag is currently on or off. If arguments are provided, the procedure and/or image verification can be changed. The parentheses must follow the function name even if no arguments are provided.

Format
F$VERIFY({proc} {,image})

Return Value
The function returns 0 if procedure verification is off, or 1 if it is on.

Arguments
proc

Specifies 1 to turn procedure verification on, or 0 to turn it off. If omitted, the current procedure verification setting is left unchanged. Note that the function returns the procedure verification state prior to making any change to it.

image

Specifies 1 to turn image verification on, or 0 to turn it off. If omitted, the current image verification setting is left unchanged.

Examples
$ A = F$VERIFY()
This code will set the symbol A to the current procedure verification flag. No other processing occurs.

$ A = F$VERIFY(,1)
This code will set the symbol A to the current procedure verification flag. The procedure verification is left unaltered, and the image verification is enabled.

$ A = F$VERIFY(0)
This code will set the symbol A to the current procedure verification flag and then turns procedure verification off.

$ A = F$VERIFY(1,0)
This call will set the symbol A to the current procedure verification flag and then turns procedure verification on and image verification off.

var Verify_Procedure : boolean = False ; // True to verify procedure
var Verify_Image : boolean = False ; // True to echo

These are the flags that control verification.

        Function_VERIFY : begin
                              if( Missing_Parentheses( '(' ) ) then
                              begin
                                  exit ;
                              end ;
                              if( Process_Verify( Err, Context ) ) then
                              begin
                                  exit ;
                              end ;
                              if( Missing_Parentheses( ')' ) ) then
                              begin
                                  exit ;
                              end ;
                              S := Context ;
                          end ;

This code is added to the Function_Reference function.

function Process_Verify( var Err : integer ; var Context : string ) : boolean ;

var P, Image, Res : string ;

begin
    // Setup...
    Result := False ; // Assume no problems

    // Set result...
    if( Verify_Procedure ) then
    begin
        Res := '1' ;
    end else
    begin
        Res := '0' ;
    end ;

    // Get parameters...
    P := uppercase( Get_Parameter( Err, Context, True ) ) ;
    if( Err <> 0 ) then
    begin
        exit ;
    end ;
    Image := '' ;
    if( Parser.Peek = ',' ) then
    begin
        Image := uppercase( Get_Parameter( Err, Context, True ) ) ;
        if( Err <> 0 ) then
        begin
            exit ;
        end ;
    end ;

This function first saves the state of the procedure verification flag. Then we get the parameters.

    // Alter flags...
    if( P <> '' ) then
    begin
        if( UCL_Strtoint( P ) = '0' ) then
        begin
            Verify_Procedure := False ;
        end else
        begin
            Verify_Procedure := True ;
        end ;
    end ;
    if( Image <> '' ) then
    begin
        if( UCL_Strtoint( Image ) = '0' ) then
        begin
            Verify_Image := False ;
        end else
        begin
            Verify_Image := True ;
        end ;
    end ;
    Context := Res ;
end ; // Process_Verify

We set the procedure verification flag appropriately, if the argument was provided. Likewise the image verification flag. Then we return the original procedure verification state.

    if( S = 'verify_image' ) then
    begin
        Context := TrueFalse( Verify_Image ) ;
    end else
    if( S = 'verify_procedure' ) then
    begin
        Context := TrueFalse( Verify_Procedure ) ;
    end else

This code in the Parse_Environment function is modified to handle the verify flags.

function TrueFalse( Value : boolean ) : string ;

begin
   if( Value ) then
   begin
       Result := 'TRUE' ;
   end else
   begin
       Result := 'FALSE' ;
   end ;
end ;

This new function is used by the above code.

In the next few articles, we will examine the last lexical function and delve more deeply into file I/O.