Our next lexical function is F$CVTIME. It converts a given time into a specific format. Here is the definition:

F$CVTIME converts an absolute or combination time string to an absolute, delta, or a string of the form yyyy-mm-dd hh:mm:ss.cc. All arguments are optional,

If the input_time argument is a delta time and the output_format argument is "DELTA", then this argument cannot be MONTH, WEEKDAY, YEAR, DAYOFYEAR, HOUROFYEAR, MINUTEOFYEAR, or SECONDOFYEAR.

This is equivalent to:
$ X = F$CVTIME("","COMPARISON","DATETIME") In this example, the current date/time is returned in the form yyyy-mm-dd hh:mm:ss.cc, for instance, "21-DEC-2019 11:55:12.20".

The resulting string can be compared using UCL operators (for instnace, .LTS. and .GTS.).

In this example, F$CVTIME returns the weekday that corresponds to the input time of "YESTERDAY". Thus, if the current day is tuesday, the function will return "Monday".

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

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

var Input_Time, Output_Time, Output : string ;
    TS : int64 ;
    Output_Flag, Output_Time_Flag : integer ;

begin
    // Setup...
    Result := False ;
    Err := 0 ;
    Output := '' ;
    Output_Time := '' ;

    // Get parameters...
    Input_Time := lowercase( Get_Parameter( Err, Context, True ) ) ;
    if( Err <> 0 ) then
    begin
        exit ;
    end ;
    if( Parser.Peek <> ')' ) then
    begin
        if( Missing_Comma( Err ) ) then
        begin
            exit ;
        end ;
        Output := lowercase( Get_Parameter( Err, Context, True ) ) ;
        if( Err <> 0 ) then
        begin
            exit ;
        end ;
        if( Parser.Peek <> ')' ) then
        begin
            if( Missing_Comma( Err ) ) then
            begin
                exit ;
            end ;
            Output_Time := lowercase( Get_Parameter( Err, Context ) ) ;
            if( Err <> 0 ) then
            begin
                exit ;
            end ;
        end ;
    end ;

    // Process output format keywords...
    if( Output = 'absolute' ) then
    begin
        Output_Flag := CVF_Absolute ;
    end else
    if( Output = 'delta' ) then
    begin
        Output_Flag := CVF_Delta ;
    end else
    if( ( Output = 'comparison' ) or ( Output = '' ) ) then
    begin
        Output_Flag := CVF_Comparison ;
    end else
    begin
        Err := UCL_IVKEYW ;
        exit ;
    end ;

    // Process output time keywords...
    if( ( Output_Time = 'datetime' ) or ( Output_Time = '' ) ) then
    begin
        Output_Time_Flag := CVO_DateTime ;
    end else
    if( Output_Time = 'date' ) then
    begin
        Output_Time_Flag := CVO_Date ;
    end else
    if( Output_Time = 'time' ) then
    begin
        Output_Time_Flag := CVO_Time ;
    end else
    if( Output_Time = 'hour' ) then
    begin
        Output_Time_Flag := CVO_Hour ;
    end else
    if( Output_Time = 'second' ) then
    begin
        Output_Time_Flag := CVO_Second ;
    end else
    if( Output_Time = 'minute' ) then
    begin
        Output_Time_Flag := CVO_Minute ;
    end else
    if( Output_Time = 'hundreth' ) then
    begin
        Output_Time_Flag := CVO_Hundredth ;
    end else
    if( Output_Time = 'day' ) then
    begin
        Output_Time_Flag := CVO_Day ;
    end else
    if( Output_Time = 'month' ) then
    begin
        Output_Time_Flag := CVO_Month ;
    end else
    if( Output_Time = 'weekday' ) then
    begin
        Output_Time_Flag := CVO_Weekday ;
    end else
    if( Output_Time = 'year' ) then
    begin
        Output_Time_Flag := CVO_Year ;
    end else
    if( Output_Time = 'dayofyear' ) then
    begin
        Output_Time_Flag := CVO_DayofYear ;
    end else
    if( Output_Time = 'hourofyear' ) then
    begin
        Output_Time_Flag := CVO_HourofYear ;
    end else
    if( Output_Time = 'minuteofyear' ) then
    begin
        Output_Time_Flag := CVO_MinuteofYear ;
    end else
    if( Output_Time = 'secondofyear' ) then
    begin
        Output_Time_Flag := CVO_SecondofYear ;
    end else
    begin
        Err := UCL_IVKEYW ;
        exit ;
    end ;

    // Call LIB$CVTime...
    Err := LIB_CVTime( Input_Time, Output_Flag, Output_Time_Flag ) ;
    if( Err <> 0 ) then
    begin
        case Err of
            LIB_BADTOPT :
                begin
                    Err := UCL_IVKEYW ;
                    Context := Output_Time ;
                end ;
            LIB_EVDTIME :
                begin
                    Err := UCL_IVDTIME ;
                    Context := Input_Time ;
                end ;
        end ;
        exit ;
    end ;
    Context := Input_Time ;
end ; // Parse_CVTime

We will discuss LIB_CVTIME, and the flag constant values used above, in the next article. But first, let's look at a modification to the Get_Parameter function.

function Get_Parameter( var Err : integer ; var Context : string ;
    Allow_Blank : boolean = False ) : string ;

begin
    Result := '' ;
    if( ( Parser.Peek = ',' ) or ( Parser.Peek = ')' ) ) then
    begin
        if( not Allow_Blank ) then
        begin
            Err := UCL_ARGREQ ;
        end ;
        exit ;
    end ;
    if( Parser.Token_EOL ) then
    begin
        Err := UCL_ARGREQ ;
        exit ;
    end ;
    Result := Get_Expression( Err, Context ) ;
    if( ( Err = UCL_EXPSYN ) and ( ( Parser.Peek = ',' ) or ( Parser.Peek = ')' ) ) ) then
    begin
        Err := 0 ;
    end ;
end ;

In the next article, we will look at date/time support provided in Starlet, including the LIB_CVTIME function.