SYS_GETTIM, LIB_Get_Timestamp, SYS_ASCTIM, and LIB_SYS_ASCTIM

In the previous articles, we covered some of the date/time functions in Starlet, and date/time contexts. In this article, we will cover a few last functions.

function LIB_Get_Timestamp : int64 ;

var I : int64 ;

begin
    SYS_GETTIM( int64( @I ) ) ;
    Result := I ;
end ;

The LIB_Get_Timestamp function is a wrapper for SYS_GETTIM, returning the current system timestamp.

function SYS_GETTIM( Adr : int64 ) : int64 ;

var Status : byte ;
    SysRequest : TInteger_Request ;

begin
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem := UOS_Subsystem_Kernel ;
    SysRequest.Request.Request := UOS_Kernel_Get_Time ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( Sysrequest.Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.Int := Adr ;

    Call_To_Ring0( integer( @SysRequest ) ) ;

    Result := Status ;
end ;

SYS_GETTIM has the standard interface to the executive that we've seen before.

    // Normal processing...
    Generate_Exception( 0 ) ; // Clear exception
    if( SReq.Request = UOS_Kernel_Get_Time ) then
    begin
        E := Enter_System_Call( Value, SReq, PID, MMC, sizeof( TInteger_Request ) - sizeof( SReq ), Address ) ;
        if( E <> nil ) then
        begin
            Set_Last_Error( E ) ;
            exit ;
        end ;
        try
            Integer_Request := PInteger_Request( Address ) ;
            Write_User_int64( Kernel, PID, Integer_Request.Int, HAL.Timestamp ) ;
        finally
            Exit_System_Call( Value, PID, MMC, sizeof( TItem_Request ) - sizeof( SReq ) ) ;
        end ;
        exit ;
    end ;

We add some code to the end of the Kernel's API method to handle this call. Besides the now familiar system call entry and exit code, we simply return the timestamp from the HAL.

function SYS_ASCTIM( LengthA : int64 ; SRBA : int64 ; Time : int64 = 0 ;
    Flags : cardinal = 0 ) : integer ;

begin
    Result := LIB_SYS_ASCTIM( LengthA, SRBA, Time, Flags ) ;
end ;

In VMS, LIB_SYS_ASCTIM is a wrapper for SYS_ASCTIM, and SYS_ASCTIM is handled in the executive. The situation is reversed in UOS for the reasons we discussed in couple articles ago. In UOS, all time formatting functions reside in starlet. So, this function is here only for compatibility with VMS.

// Flags: 0 = Date and time, 1 = time only, 2 = date only
function LIB_SYS_ASCTIM( LengthA : int64 ; SRBA : int64 ; Time : int64 = 0 ;
    Flags : cardinal = 0 ) : integer ;

var DoW : int64 ;
    I : integer ;
    SRB : PSRB ;
    Res : string ;
    SL : TStringList ;
    T : string ;
    Y, Mo, D, H, H12, M, Sec : word ;
    NS : longint ;
    TimePos : integer ;

begin
    // Setup and checks...
    Result := SS_NORMAL ; // Assume success
    if( LengthA = 0 ) then
    begin
        exit ;
    end ;
    if( SRBA = 0 ) then
    begin
        pint64( LengthA )^ := 0 ;
        exit ;
    end ;
    SRB := PSRB( SRBA ) ;
    if( ( SRB^.Length = 0 ) or ( SRB^.Buffer = 0 ) ) then
    begin
        pint64( LengthA )^ := 0 ;
        exit ;
    end ;
    if( Time = 0 ) then
    begin
        Time := LIB_Get_Timestamp ;
    end ;
    TimePos := 32767 ;

This function converts a timestamp to a string representation. "ASCTIM" stands for "ASCII Time". But since UOS uses UTF-8, it is a bit of a misnomer. However, we keep the name for compatibility sake with VMS. The Flags parameter indicates whether we want date and time, only date, or only time. However, it should be noted that if asked for both date and time, but the output string isn't large enough to hold both, only the date is returned.

First, we check that no null string pointers or lengths were passed to us. If one is found, we set the result length to 0 (unless the result address is 0 as well), and exit. If the passed time is 0, that means that the caller wants the current date/time, so we get it in that case. Then we set the TimePos variable to a large value (we picked 32767 because it is doubtful that a date/time string will ever approach that length). It will mark the position of the start of the time in the output string.

    // Convert time to ASCII...
    Res := '' ;
    if( Time < 0 ) then // Delta time
    begin
        Time := -Time ;
        Parse_Sirius_Timestamp( Time, Y, Mo, D, H, M, Sec, NS ) ;
        Res := '+' ;
        if( ( Flags and 1 ) = 0 ) then // Not requesting only time
        begin
            Res := Res + inttostr( Time div Day_Value ) ;
        end ;
        Res := Res + ':' + inttostr( H ) + ':' + inttostr( M ) + ':' + inttostr( Sec ) ;
        if( length( Res ) > SRB^.Length ) then
        begin
            setlength( Res, SRB^.Length ) ;
        end ;
        pint64( LengthA )^ := length( Res ) ;
        move( PChar( Res )[ 0 ], PChar( SRB^.Buffer )[ 0 ], length( Res ) ) ;
        exit ;
    end ;

If the timestamp passed in was negative, it indicates a delta time. So we negate it to make it positive, and then we parse the positive value. The output of a delta time will always start with a plus (+), so we initialize the result to that. If flags is 0, we add the day count to the result. Then we add the hour, minute, and second, delimited by colons (:). If the destination buffer is too small, we truncate our result to the size of that buffer. Then we set the result length and copy the output string to the buffer, and exit.

    // Get time and day of week...
    Parse_Sirius_Timestamp( Time, Y, Mo, D, H, M, Sec, NS ) ;
    H12 := H ;
    if( H > 11 ) then
    begin
        H12 := H - 12 ;
    end ;
    if( H12 = 0 ) then
    begin
        H12 := 12 ;
    end ;

Next, we parse the timestamp. The hour is always returned as a value from 0 to 23. Since the output format may request a 12-hour time, we calculate what the hour would be in 12-hour time (1-12).

    // Absolute time...

    // Get day of week...
    DoW := Time div Week_Value ;
    Dow := Time - Dow * Week_Value ;
    Dow := DoW div Day_Value + 1 ;
    if( Dow > 7 ) then
    begin
        Dow := Dow - 7 ;
    end ;

Since we may need the day of the week, we calculate it from the given time.

    // Get parsed list...
    case Flags and 3 of
        0 : // Requesting date and time
            SL := Default_Time_Context.Parsed_Output_Date_Time_List ;
        1 : // Requesting time only
            SL := Default_Time_Context.Parsed_Output_Time_List ;
        2 : // Requesting date only
            SL := Default_Time_Context.Parsed_Output_Date_List ;
    end ;

Depending upon the flags, we obtain the output format for date/time, date, or time. Now we're prepared for the conversion of an absolute time.

    // Build output string...
    for I := 0 to SL.Count - 1 do
    begin
        T := SL[ I ] ;
        if( copy( T, 1, 1 ) <> '!' ) then // A delimiter
        begin
            Res := Res + T ;
        end else
        begin
            // Date...
            if( T = '!D0' ) then
            begin
                Res := Res + LPad( inttostr( D ), 2, '0' ) ;
            end else
            if( T = '!DB' ) then
            begin
                Res := Res + LPad( inttostr( D ), 2, ' ' ) ;
            end else
            if( T = '!DD' ) then
            begin
                Res := Res + inttostr( D ) ;
            end else
            if( T = '!MAAC' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_MONTH_NAME_ABB_C )[ Mo - 1 ] ;
            end else
            if( T = '!MAAL' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_MONTH_NAME_ABB_L )[ Mo - 1 ] ;
            end else
            if( T = '!MAAU' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_MONTH_NAME_ABB_U )[ Mo - 1 ] ;
            end else
            if( T = '!MAC' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_MONTH_NAME_C )[ Mo - 1 ] ;
            end else
            if( T = '!MAL' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_MONTH_NAME_L )[ Mo - 1 ] ;
            end else
            if( T = '!MAU' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_MONTH_NAME_U )[ Mo - 1 ] ;
            end else
            if( T = '!MN0' ) then
            begin
                Res := Res + LPad( inttostr( Mo ), 2, '0' ) ;
            end else
            if( T = '!MNB' ) then
            begin
                Res := Res + LPad( inttostr( Mo ), 2, ' ' ) ;
            end else
            if( T = '!MNM' ) then
            begin
                Res := Res + inttostr( Mo ) ;
            end else
            if( T = '!WAC' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_WEEKDAY_NAME_ABB_C )[ DOW - 1 ] ;
            end else
            if( T = '!WAL' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_WEEKDAY_NAME_ABB_L )[ DOW - 1 ] ;
            end else
            if( T = '!WAU' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_WEEKDAY_NAME_ABB_U )[ DOW - 1 ] ;
            end else
            if( T = '!WC' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_WEEKDAY_NAME_C )[ DOW - 1 ] ;
            end else
            if( T = '!WL' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_WEEKDAY_NAME_L )[ DOW - 1 ] ;
            end else
            if( T = '!WU' ) then
            begin
                Res := Res + Default_Time_Context.Parsed_List( LIB_K_WEEKDAY_NAME_U )[ DOW - 1 ] ;
            end else
            if( T = '!Y4' ) then
            begin
                Res := Res + LPad( inttostr( Y ), 4, '0' ) ;
            end else
            if( T = '!Y3' ) then
            begin
                Res := Res + LPad( Rightmost( inttostr( Y ), 3 ), 3, '0' ) ;
            end else
            if( T = '!Y2' ) then
            begin
                Res := Res + LPad( Rightmost( inttostr( Y ), 2 ), 2, '0' ) ;
            end else
            if( T = '!Y1' ) then
            begin
                Res := Res + Rightmost( inttostr( Y ), 3 ) ;
            end else
            if( T = '!Z4' ) then
            begin
                Res := Res + LPad( inttostr( Y ), 4, '0' ) ;
            end else
            if( T = '!Z3' ) then
            begin
                Res := Res + LPad( Rightmost( inttostr( Y ), 3 ), 3, '0' ) ;
            end else
            if( T = '!Z2' ) then
            begin
                Res := Res + LPad( Rightmost( inttostr( Y ), 2 ), 2, '0' ) ;
            end else
            if( T = '!Z1' ) then
            begin
                Res := Res + Rightmost( inttostr( Y ), 3 ) ;
            end else

Now we can iterate through the parsed list. Each loop, we get the next item from the list. If it doesn't start with an exclamation (!), it is a delimiter and we simply add it to the output string. Otherwise, we process the code in this item. For instance, "!D0" indicates that we want a zero-padded two-digit day of month. So, based on the code, we build the appropriate part of the output string.

            begin
                // Time...
                if( length( Res ) < TimePos ) then
                begin
                    TimePos := Length( Res ) ;
                end ;
                if( T = '!C1' ) then
                begin
                    Res := Res + copy( LPad( inttostr( NS ), 9, '0' ), 1, 1 ) ;
                end else
                if( T = '!C2' ) then
                begin
                    Res := Res + copy( LPad( inttostr( NS ), 9, '0' ), 1, 2 ) ;
                end else
                if( T = '!C3' ) then
                begin
                    Res := Res + copy( LPad( inttostr( NS ), 9, '0' ), 1, 3 ) ;
                end else
                if( T = '!C4' ) then
                begin
                    Res := Res + copy( LPad( inttostr( NS ), 9, '0' ), 1, 4 ) ;
                end else
                if( T = '!C5' ) then
                begin
                    Res := Res + copy( LPad( inttostr( NS ), 9, '0' ), 1, 5 ) ;
                end else
                if( T = '!C6' ) then
                begin
                    Res := Res + copy( LPad( inttostr( NS ), 9, '0' ), 1, 6 ) ;
                end else
                if( T = '!C7' ) then
                begin
                    Res := Res + copy( LPad( inttostr( NS ), 9, '0' ), 1, 7 ) ;
                end else
                if( T = '!H02' ) then
                begin
                    Res := Res + LPad( inttostr( H12 ), 2, '0' ) ;
                end else
                if( T = '!H04' ) then
                begin
                    Res := Res + LPad( inttostr( H ), 2, '0' ) ;
                end else
                if( T = '!HB2' ) then
                begin
                    Res := Res + LPad( inttostr( H12 ), 2, ' ' ) ;
                end else
                if( T = '!HB4' ) then
                begin
                    Res := Res + LPad( inttostr( H ), 2, ' ' ) ;
                end else
                if( T = '!HH2' ) then
                begin
                    Res := Res + inttostr( H12 ) ;
                end else
                if( T = '!HH4' ) then
                begin
                    Res := Res + inttostr( H ) ;
                end else
                if( T = '!M0' ) then
                begin
                    Res := Res + LPad( inttostr( M ), 2, '0' ) ;
                end else
                if( T = '!MB' ) then
                begin
                    Res := Res + LPad( inttostr( M ), 2, ' ' ) ;
                end else
                if( T = '!MM' ) then
                begin
                    Res := Res + inttostr( M ) ;
                end else
                if( T = '!S0' ) then
                begin
                    Res := Res + LPad( inttostr( Sec ), 2, '0' ) ;
                end else
                if( T = '!SB' ) then
                begin
                    Res := Res + LPad( inttostr( Sec ), 2, ' ' ) ;
                end else
                if( T = '!SS' ) then
                begin
                    Res := Res + inttostr( Sec ) ;
                end else
                if( T = '!MIU' ) then
                begin
                    if( H > 11 ) then
                    begin
                        Res := Res + Default_Time_Context.Parsed_List( LIB_K_MERIDIEM_INDICATOR_U )[ 0 ] ;
                    end else
                    begin
                        Res := Res + Default_Time_Context.Parsed_List( LIB_K_MERIDIEM_INDICATOR_U )[ 1 ] ;
                    end ;
                end else
                if( T = '!MIC' ) then
                begin
                    if( H > 11 ) then
                    begin
                        Res := Res + Default_Time_Context.Parsed_List( LIB_K_MERIDIEM_INDICATOR_C )[ 0 ] ;
                    end else
                    begin
                        Res := Res + Default_Time_Context.Parsed_List( LIB_K_MERIDIEM_INDICATOR_C )[ 1 ] ;
                    end ;
                end else
                if( T = '!MIL' ) then
                begin
                    if( H > 11 ) then
                    begin
                        Res := Res + Default_Time_Context.Parsed_List( LIB_K_MERIDIEM_INDICATOR_L )[ 0 ] ;
                    end else
                    begin
                        Res := Res + Default_Time_Context.Parsed_List( LIB_K_MERIDIEM_INDICATOR_L )[ 1 ] ;
                    end ;
                end ;
            end ;
        end ; // if( copy( T, 1, 1 ) <> '!' )
    end ; // for I := 0 to SL.Count - 1

Note that the previous section of code dealt only with date codes. All of the time codes are handled in an else. This is so we can set the TimePos variable to the current output position if that position is smaller than its current value. In other words, as soon as we encounter a time entry, we set TimePos to that position, so we know where the time specification begins. Like the date codes, we handle the time codes by substituting the appropriate value for the given code. The handling of the "!H02" code is where we use the H12 value that we set above.

    // Trim if too long...
    if( ( Flags and 1 ) = 0 ) then // Wanted both date and time
    begin
        if( length( Res ) > SRB^.Length ) then // Can't fit both in target buffer
        begin
            Res := copy( Res, 1, TimePos - 1 ) ; // Trim off time portion
        end ;
    end ;

Now that we've built the output string, it is time to handle trimming it, if needed. If the flags indicate that both date and time are needed, but the output is longer than the target buffer, we need to trim the output at the end of the date portion. This is where the TimePos variable comes in. We trim the output string to the position just prior to the first time code.

    // Return value...
    if( length( Res ) > SRB^.Length ) then // Can't fit into target buffer
    begin
        setlength( Res, SRB^.Length ) ; // Trim to fit
    end ;
    pint64( LengthA )^ := length( Res ) ;
    move( PChar( Res )[ 0 ], PChar( SRB^.Buffer )[ 0 ], length( Res ) ) ;
end ; // LIB_SYS_ASCTIM

Even with the above possible trimming of the output, the result can still be longer than the target buffer. So, at this point, we trim the output again, if necessary. Then we write the output and it's length back to the calling code's addresses. Although the code is lengthly, it is fairly straight-forward.

In the next article, we'll cover the next lexical function.