Legato
Legato

GoFiler Legato Script Reference

 

Legato v 1.5b

Application v 5.24b

  

 

Chapter Five — General Functions (continued)

5.12 Date and Time Functions

5.12.1 Overview

This section covers the date formatting functions that can be used within Legato. Many systems use different formats of structured data for date and time. Legato employs two basic types: date-time as a 64-bit numeric format (based on the FILETIME format described in the Windows SDK) and strings in ISO-8601. The date-time value represents the number of 100 nanosecond intervals since January 1, 1601 (Coordinated Universal Time, or UTC. UTC time is also referred to as GMT or Zulu). Since it is a 64-bit value, it must be carried in a qword variable type. In the Windows SDK, the FILETIME structure is actually the combination of two 32-bit values.

There are other time formats used by UNIX and Windows. Basic functions are provided to convert UNIX time; however, Windows cannot be processed directly.

5.12.2 File Times and File Systems

Windows records dates and times when applications create, access, and write to files. These times are also used in Legato because they are easy to translate and transport. The NTFS (New Technology File System) file system stores time values in UTC format so they are not affected by changes in time zone or daylight savings time. FAT (File Allocation Table) file systems (used on many SD cards, USB thumb drives, and older disk drives) store time values based on the local time of the computer. For example, a file that is saved at 3:00 pm PST in Washington is seen as 6:00 pm EST in New York on an NTFS volume, but it is seen as 3:00 pm EST in New York on a FAT volume. As required, the operating system automatically translates the UTC version of the FILETIME to local time for presentation. Localization can be rather complex and is based on the system’s time zone and the time of year of the original UTC timestamp. For example, the system may adjust the UTC time +/- an hour for daylight savings time based on the date of the timestamp.

Not all file systems can record creation and last access times, and not all file systems record them in the same manner. For example, the resolution of create time on FAT is ten milliseconds, while write time has a resolution of two seconds and access time has a resolution of one day so it is really the access date. The NTFS file system delays updates to the last access time for a file by up to one hour after the last access.

Most Legato functions deal with conversion of date/time data to and from string and a 64-bit (qword) date-time format. When using Legato functions to read times for files, all date-times are automatically converted to UTC. The GetFileCreateTime and GetFileModifiedTime functions copy the creation, last access, and last write times to individual file-time values and return that information to the script. Date-times of files can also be retrieved using the GetFirstFile and GetNextFile functions. It should be noted that when writing to a file, the last write time is not fully updated until all handles that are used for writing are closed. To set the date-times for a file, use the SetFileModifiedTime function. This function permits modification of creation, last access, and last write times without changing the content of the file.

5.12.3 Comparing Times and Dates

Legato offers numerous functions to compare date-time values. Date-time values are large counts of 100 nanosecond intervals and are therefore in and of themselves difficult to interpret. Date-times are qword data types and thus also can be directly compared using comparison operators. However, use caution when judging for equality since the time resolution is much finer than might be expected and beyond what is necessary by most standards.

The Windows FILETIME structure is essentially two dword data types linked together to form a 64-bit container for date-time data; it is therefore possible to extract the high or low 32 bits using the GetHighWord and GetLowWord functions respectively. This may have its uses when attempting to determine differences between two date-time values, but note again that Legato provides functions to better interpret and report these differences in a more usable manner.

It is up to the script programmer to make these distinctions and compensate accordingly.

5.12.4 Formatting Codes

There are two types of date structuring codes: bitwise attributes and string formatting (similar to PHP). Date conversion functions that result in a string value can use Date String (DS_) formatting codes. These are bitwise values that are as follows:

Definition   Bitwise   Description   Example
Date Modes    
  DS_MMDDYY   0x00000000   mm/dd/yy   06/30/13
  DS_MMDDYYYY   0x00000001   mm/dd/yyyy   06/30/2013
  DS_DDMMYY   0x00000002   dd/mm/yy   30/06/13
  DS_DDMMYYYY   0x00000003   dd/mm/yyyy   30/06/2013
  DS_MMMDDYY   0x00000004   mmm/dd/yy   JUN 30 13
  DS_MMMDDYYYY   0x00000005   mmm/dd/yyyy   JUN 30 2013
  DS_DDMMMYY   0x00000006   dd/mmm/yy   30 JUN 13
  DS_DDMMMYYYY   0x00000007   dd/mmm/yyyy   30 JUN 2013
  DS_YYYYMMDD   0x00000008   yyyy/mm/dd   2013/06/30
  DS_MON_DAY_YEAR   0x00000009   Mon. Day, Year   Jun. 30, 2013
  DS_MONTH_DAY_YEAR   0x0000000A   Month Day, Year   June 30, 2013
  DS_WEEKDAY_MONTH_DAY_YEAR   0x0000000B   Weekday, Month Day, Year
  Sunday, June 30, 2013
Time Mode    
  DS_HHMM_24   0x00000000   hh:mm (24-hour)   23:55
  DS_HHMM_12   0x00000010   hh:mm (12-hour)   11:55 PM
  DS_HHMMSS_24   0x00000020   hh:mm:ss (24-hour)   23:55:30
  DS_HHMMSS_12   0x00000030   hh:mm:ss (12-hour)   11:55:30 PM
  DS_HHMMSS_ND_24   0x00000040   hhmmss (24-hour)   235500
Date Delimiters    
  DS_SLASH   0x00000000   Slashes   06/30/2013
  DS_DASH   0x00010000   Dashes   06-30-2013
  DS_SPACES   0x00020000   Spaces   06 30 2013
  DS_SPACESCOMMA   0x00030000   Spaces and Commas   June 30, 2013
  DS_PERIODS   0x00040000   Periods   06.30.2013
Output Mode    
  DS_DATE   0x00000000   Date only   06/30/2013
  DS_TIME   0x01000000   Time only   23:55
  DS_DATE_TIME   0x02000000   Date then time   06/30/2013 23:55
  DS_DATE_AT_TIME   0x03000000   Date at time   06/30/2013 at 23:55
  DS_TIME_DATE   0x04000000   Time then date   23:55 06/30/2013
  DS_DATE_T_TIME   0x05000000   ISO-8601 ‘T’ connector   dateTtime
Case    
  DS_DEFAULT_CASE   0x00000000   Default (all lower case)   june 30 2013
  DS_LOWER   0x10000000   Lower   june 30 2013
  DS_UPPER   0x20000000   Upper   JUNE 30 2013
  DS_INITIAL   0x30000000   Initial capitalization   June 30 2013
Other    
  DS_ISO_8601   0x05010028   ISO-8601 combination   2013-06-30T23:55:30
  DS_NO_ZERO_FILL   0x80000000   No zero filling   6/30/2013
  DS_FILETIME_UTC    0x00000100   Converts as raw UTC   —

 

5.12.5 Locale

For functions based on the local time, the host application may have its locale overridden in the application settings (ini) file. For example:

[Locale Override]

Time Zone=Pacific Standard Time

This will impact any function that relies on local time such as GetLocalTime.

5.12.6 Functions

Date Formatting and Translation

DateToUnix — Converts a date/time to Unix (aka POSIX or Epoch) time.

FormatDate — Formats time value (file time) to a date string.

GetDateTimeComponents — Returns an array of date and time component values.

GetDayOfWeek — Returns the day of the week as an index from Sunday.

GetLocalTime — Gets local time and date in file time (default) or specified string format.

GetUTCTime — Gets current UTC time and date in file time (default) or specified string format.

MS1900ToDate — Converts a Microsoft 1900 format date to a qword.

MS1900ToString — Converts a Microsoft 1900 format date to ISO-8601.

MS1904ToDate — Converts a Microsoft 1904 format date to a qword.

MS1904ToString — Converts a Microsoft 1904 format date to ISO-8601.

StringToDate — Converts a string to file time format as a qword.

UnixToDate — Converts Unix date/time (aka POSIX or Epoch time) to date/time format.

Date Math

AddDays — Adds (or subtracts) days to an ISO-8601 formatted date and returns an ISO-8601 date.

LocalToUTC — Converts local time (current time zone) to UTC in file time or string format.

SecondsToTime — Converts seconds to hours, minutes and seconds.

SubtractDates — Subtracts ISO-8601 style date ‘b’ from ‘a’ and returns the number of days.

UTCToLocal — Converts UTC file time to local time (current time zone) in file time or string format.

ISO 8501 Duration

AddDuration — Adds an ISO duration code to an ISO date-time string.

DurationToComponents — Parses an ISO Duration into Components.

DurationToDays — Parses an ISO Duration into components and returns number of days.

DurationToString — Converts an array of duration items to an ISO/XML duration string.

DurationToTimeComponents — Converts an ISO Duration to Standard Windows Time Components.

StringToDuration — Interprets a natural language string and converts to an XML duration.

SubtractDuration — Subtracts an ISO duration code from an ISO date-time string.

Time Zone and Locale

EnumerateTimeZones — Returns a list of all known time zones for the system.

GetLocalTimeForZone — Gets the local time and date for a specific zone.

GetTimeZoneBias — Returns the difference between the locale and UTC in minutes.

GetTimeZoneInformation — Returns time zone information for the system locale.

GetTimeZoneOverride — Returns Time Zone Override.

IsDaylightSavingsTime — Tests whether the current locale is operating under daylight savings time.

StringToTimeZone — Converts ISO-8601 to formatted time zone data.

StringToTimeZoneBias — Converts ISO-8601 to UTC bias.

Page revised 2024-10-21

 

GoFiler Legato Script Reference — Generated on 10/21/2024

© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.