DEV Community

Peter + AI
Peter + AI

Posted on

🕰️ Mastering Uniface $datim Function: Complete Guide to Date and Time Handling

This blog post was created with AI assistance to provide clear explanations and practical examples.

Working with dates and times is essential in business applications. The Uniface $datim function is a powerful tool that handles both current system time retrieval and string-to-datetime conversion. Let me show you how to use it effectively! 🚀

🎯 What is $datim?

The $datim function serves two main purposes:

  • Without parameters: Returns the current system date and time
  • With a string parameter: Converts a formatted string into a Datetime data type

The function is accurate to one hundredth of a second (called a "tick" in Uniface) 📏

🔧 Basic Syntax 

$datim { ( Source ) }
Enter fullscreen mode Exit fullscreen mode

Where Source is an optional string parameter that must follow the format:

dd-mm-yyhh:nn:ss.tt
Enter fullscreen mode Exit fullscreen mode
  • dd = day
  • mm = month
  • yy = year
  • hh = hour
  • nn = minute
  • ss = second
  • tt = tick (hundredth of a second)

💡 Practical Examples

Getting Current Date and Time 

; Get current system time
currentTime = $datim
; Returns format: ccyymmddhhnnsstt
; Example: 20250928093045.78
Enter fullscreen mode Exit fullscreen mode

Converting String to DateTime 

; Convert formatted string to datetime
myDateTime = $datim("01-05-0723:30:43")
; Returns properly formatted datetime based on locale
Enter fullscreen mode Exit fullscreen mode

Real-World Example: Timestamping Records 

trigger getFocus ; of entity HEADER.USYS
    DATE.HEADER = $datim
end
Enter fullscreen mode Exit fullscreen mode

This example automatically sets a timestamp when a user focuses on a header field ✨

📊 Return Value Examples

The output format depends on your field layout definition:

Field Layout Example Output
hh:nn:ss.tt 12:32:24.78
hh:nn:ss 12:32:24
dd-MMM-yyyy hh:nn:ss.tt 01-MAY-2007 23:30:43.67

⚠️ Error Handling

When $datim encounters invalid input, it handles errors gracefully:

  • $datim("abc") returns an empty string ""
  • Check $procerror for error codes (value -1006 indicates invalid datetime) 
; Safe datetime conversion with error checking
myDate = $datim("invalid-date")
if ($procerror < 0)
    ; Handle the error appropriately
    putmess "Invalid date format provided"
endif
Enter fullscreen mode Exit fullscreen mode

🌍 Internationalization Support

The $datim function respects your application's locale settings:

  • Uses $nlslocale and $nlsformat for formatting
  • Falls back to dd-mmm-yy hh:nn:ss:tt if no default format is defined
  • Considers $language and $variation settings

🏢 Client-Server Considerations

Important: In distributed environments, $datim returns the server's system time, not the client's time. This ensures consistency across your application when multiple users are working simultaneously 🔄

💪 Best Practices

  • Always validate input: Use error checking when converting strings
  • Consider locale: Account for different date formats in international applications
  • Use for timestamps: Perfect for audit trails and record tracking
  • Test edge cases: Verify behavior with invalid dates and format mismatches

🔗 Related Functions

Enhance your date handling with these complementary Uniface functions:

  • $date - Date-only operations
  • $clock - Time-only operations
  • addmonths - Date arithmetic
  • $nlslocale - Locale management

🎉 Conclusion

The $datim function is essential for any Uniface developer working with temporal data. Whether you're creating audit trails, calculating deadlines, or handling user input, mastering this function will make your applications more robust and reliable.

Start experimenting with $datim in your next Uniface project, and you'll quickly see how it simplifies date and time operations! 🎯

Keywords: uniface datetime procscript timestamp

Top comments (0)