Flat Functions

Wrong_Input_Lang

Validates an input string against a specified language enforcement rule.
If the input is invalid and a control is provided, it can display a popup message to the user.
This function is typically used in UI event handlers to block invalid keyboard input.
function Wrong_Input_Lang(CONST InText: String; CONST Enforce_Input_Lang: ThEnforce_Input_Lang; Control: TSYE_Control): Boolean;

Parameters

  • InText: String; The input text to be validated.
  • Enforce_Input_Lang: ThEnforce_Input_Lang; The language rule to apply.
  • Control: TSYE_Control; An optional control to associate with the validation popup message.
    • The ThEnforce_Input_Lang type is an enumeration used to define the language validation rule for an input field.
    It is used by functions like Wrong_Input_Lang to ensure that user input conforms to the required language settings for string-based fields.

    Value Description
    he_No_Filter No language validation is performed. Any character input is allowed. This is the default for numeric fields.
    he_Acceptable Input is validated against the global `he_Acceptable_Input_Lang` set, which defines the languages permitted for the application.
    he_EnglishOnly Input is restricted to only allow characters belonging to the English language.

Return Value

Returns `True` if the input language is invalid and the input should be blocked.
Returns `False` if the input language is valid.

Check_Range_Fields

Validates a pair of fields that represent a numeric or date range (e.g., StartDate and EndDate).
If the 'from' value is greater than the 'until' value, indicating an invalid range, it clears both fields.
procedure Check_Range_Fields(Tbl: ThTable; FromFN, UntilFN: String; CompareInteger: Boolean = True; Row: Integer = 0);

Parameters

  • Tbl: ThTable; The table containing the fields to check.
  • FromFN: String; The name of the field representing the start of the range.
  • UntilFN: String; The name of the field representing the end of the range.
  • CompareInteger: Boolean; If `True`, the fields are compared as integers; otherwise, they are compared as real numbers.
  • Row: Integer; The row index to check. If not specified, it defaults to the first row (0).

Create_Table

A factory function that creates and initializes a `ThTable` component at run-time.
It requires the specified table name to be defined in the global `Schema` component.
The created table is fully initialized with its field definitions and ready for use.
function Create_Table(TableName: String; AOwner: TComponent = NIL): ThTable;

Parameters

  • TableName: String; The name of the table as defined in the application's `Schema`.
  • AOwner: TComponent; The owner of the newly created component (optional).

Return Value

Returns the newly created and initialized `ThTable` instance.
Returns `NIL` if the specified `TableName` does not exist in the `Schema`.

Create_PrivateQry

A factory function that creates and initializes a `ThPrvTable` component at run-time.
This is used to dynamically create a custom, private view of a schema table with a specific subset of fields.
function Create_PrivateQry(TableName: String; Fields: ThFlds_Name_Array; AOwner: TComponent = NIL): ThPrvTable;

Parameters

  • TableName: String; The name of the base schema table from which the private query will be created.
  • Fields: ThFlds_Name_Array; An array of strings containing the names of the fields to include in the `ThPrvTable`.
  • AOwner: TComponent; The owner of the newly created component (optional).

Return Value

Returns the newly created and initialized `ThPrvTable` instance.
Returns `NIL` if the specified `TableName` does not exist in the `Schema`.

Calc_Table_Storage_Attrib

Calculates the appropriate storage attribute ('N', 'A', or 'NA') for a server query based on a given date range.
This function is used in systems with data archiving to determine whether a query should target the normal storage, the archive storage, or both.
function Calc_Table_Storage_Attrib(FromDate, UntilDate: Tdatetime; Stored_On_Archive_Until_Date: Integer): String;

Parameters

  • FromDate: Tdatetime; The starting date of the query range.
  • UntilDate: Tdatetime; The ending date of the query range.
  • Stored_On_Archive_Until_Date: Integer; The cut-off date for the archive. Records on or before this date are considered archived.

Return Value

Returns a string: 'A' if the entire range is in the archive, 'N' if the entire range is in normal storage, or 'NA' if the range spans both.

Init_Clear_Table_Sort_Array

Initializes or clears a `ThTable_Sort_Array` structure to its default, empty state.
This procedure is used internally by the `ThTable` component to reset any existing sorting criteria.
procedure Init_Clear_Table_Sort_Array(VAR _SortCols: ThTable_Sort_Array);

Parameters

  • _SortCols: VAR ThTable_Sort_Array; The sort array structure to be cleared.

SYE_Monitor_Error

A convenience function that sends a critical failure status to the SYE Monitor system for a specific module.
This is a shortcut for calling the main `SYE_Monitor` function with a `Task_ID` of 2 (Task Failed).
function SYE_Monitor_Error(Module_Unique_Name: String): Boolean;

Parameters

  • Module_Unique_Name: String; A unique name that identifies the application module or process reporting the error.

Return Value

Returns `True` if the error status was successfully sent to the server.

SYE_Monitor

The core function for sending a status heartbeat to the SYE Monitor system.
It updates or creates an entry on the server that reports the status of a specific module or automated task.

function SYE_Monitor(Module_Unique_Name: String; Task_ID: Word; CycleEveryMinutes: Double = 0; Manual_Time: TDateTime = 0): Boolean; Overload;
function SYE_Monitor(Module_Unique_Name: String; Task_ID: Word; Error_Failed: Boolean; CycleEveryMinutes: Double = 0): Boolean; Overload;

Parameters

  • Module_Unique_Name: String; A unique name that identifies the application module or process.
  • Task_ID: Word; A code that represents the current status of the task (e.g., 0 for General, 1 for Critical).
  • CycleEveryMinutes: Double; Specifies how often, in minutes, this module is expected to send a heartbeat. The monitoring system can use this to detect if a task is stalled.
  • Manual_Time: TDateTime; An optional UTC timestamp for the status report. If not provided, the current server UTC time is used.
  • Error_Failed: Boolean; In the second overload, a simple flag to report success (`False`) or failure (`True`). If `True`, it sends a `Task_ID` of 2.

Return Value

Returns `True` if the status was successfully sent to the server.

SYE_Monitor_Delete

Sends a request to the server to remove a module's entry from the SYE Monitor system.
This should be called when a monitored task or module is shut down cleanly to stop it from appearing in the monitoring dashboard.
function SYE_Monitor_Delete(Module_Unique_Name: String): Boolean;

Parameters

  • Module_Unique_Name: String; The unique name of the module whose monitoring entry should be removed.

Return Value

Returns `True` if the deletion request was successfully sent to the server.

Write_App_Log

Writes a log entry to both the local log file and a central logging table on the server.
It can also optionally report a failure to the SYE Monitor system at the same time.
procedure Write_App_Log(From_Module: TComponent; Description: String; _Monitor_Failed_UniqueName: String = '');

Parameters

  • From_Module: TComponent; The component or module from which the log message is originating.
  • Description: String; The text of the log message.
  • _Monitor_Failed_UniqueName: String; If provided, this procedure will also send a failure status to the SYE Monitor system using this string as the unique module name.

UTC_To_LocalTime_By_TZ

Converts a `TDateTime` value from Coordinated Universal Time (UTC) to a local time based on a specific timezone index.
This function relies on the application's timezone cache, which must be populated beforehand by calling `ThScm.Build_App_TimeZone_Cache`.
It correctly accounts for Daylight Saving Time (DST) for the given year.
function UTC_To_LocalTime_By_TZ(UTC_Input: TDateTime; Schema_TZ_Index: Integer): TDateTime;

Parameters

  • UTC_Input: TDateTime; The date and time value in UTC to be converted.
  • Schema_TZ_Index: Integer; The index of the target timezone within the `Schema` component's internal cache. This index is typically obtained by calling `ThScm.Find_TimeZone_Index`.

Return Value

Returns the converted `TDateTime` value in the specified local timezone.

LocalTime_To_UTC_By_TZ

Converts a local `TDateTime` value from a specific timezone to Coordinated Universal Time (UTC).
This function is the inverse of `UTC_To_LocalTime_By_TZ` and uses the same pre-loaded application timezone cache.
It correctly accounts for Daylight Saving Time (DST) for the given year.
function LocalTime_To_UTC_By_TZ(Local_Input: TDateTime; Schema_TZ_Index: Integer): TDateTime;

Parameters

  • Local_Input: TDateTime; The local date and time value to be converted.
  • Schema_TZ_Index: Integer; The index of the source timezone within the `Schema` component's internal cache.

Return Value

Returns the converted `TDateTime` value in UTC.

UTC_To_LocalTime

A convenience function that converts a UTC `TDateTime` value to the application's default local time.
It uses the default timezone that has been set globally for the application by calling `ThScm.Set_Default_App_TZ`.
function UTC_To_LocalTime(UTC_Input: TDateTime): TDateTime;

Parameters

  • UTC_Input: TDateTime; The date and time value in UTC to be converted.

Return Value

Returns the converted `TDateTime` value in the application's default local timezone.

LocalTime_To_UTC

A convenience function that converts a `TDateTime` value from the application's default local time to UTC.
It uses the default timezone that has been set globally for the application by calling `ThScm.Set_Default_App_TZ`.
function LocalTime_To_UTC(Local_Input: TDateTime): TDateTime;

Parameters

  • Local_Input: TDateTime; The local date and time value to be converted.

Return Value

Returns the converted `TDateTime` value in UTC.

LocalTime_Offset_In_Hours

Calculates the current timezone offset in hours between UTC and the application's default local time for a given moment.
This function correctly accounts for Daylight Saving Time (DST), returning the appropriate offset based on the specific date and time provided.
function LocalTime_Offset_In_Hours(UTC_Input: TDateTime): Double;

Parameters

  • UTC_Input: TDateTime; The UTC date and time for which to calculate the offset.

Return Value

Returns a `Double` representing the offset in hours from UTC (e.g., +2.0, +3.0).

Gen_Next_Daily_Process_DT

Calculates the next scheduled run time for a daily recurring process, returning the result in UTC.
It determines the next occurrence based on a specific time of day provided as a `TDateTime` fractional value.
If the calculated time for today has already passed, it schedules the process for the following day.
function Gen_Next_Daily_Process_DT(Daily_Cycle_Hour_Field: Double; LogAstr: String = ''): Double;

Parameters

  • Daily_Cycle_Hour_Field: Double; The time of day for the process to run, expressed as the fractional part of a `TDateTime` value (e.g., the result of `Frac(MyTime)`).
  • LogAstr: String; If not empty, a descriptive string that will be written to the application log along with the calculated run time.

Return Value

Returns a `TDateTime` value in UTC representing the next scheduled run time.

Gen_Next_Daily_Process_To_UTC

Calculates the next scheduled run time for a daily process that needs to run at a specific local time in a given timezone.
This function is timezone-aware; it takes a local time (HH:MM) and a timezone name, calculates the next local run time, and then converts that time to its UTC equivalent.
function Gen_Next_Daily_Process_To_UTC(HH, MM: Byte; TimeZone: String; LogAstr: String = ''): Double;

Parameters

  • HH: Byte; The hour (0-23) of the day for the process to run in the specified local timezone.
  • MM: Byte; The minute (0-59) of the hour for the process to run.
  • TimeZone: String; The name of the timezone in which the HH:MM applies (e.g., 'Israel', 'America/New_York').
  • LogAstr: String; If not empty, a descriptive string that will be written to the application log.

Return Value

Returns a `TDateTime` value in UTC representing the next scheduled run time.

Get_Timezones_Difference

Calculates the time difference between two specified timezones at a particular moment in time.
The function requires a specific UTC timestamp because the difference can change depending on Daylight Saving Time rules for one or both timezones.
function Get_Timezones_Difference(From_TZ_Index, TO_TZ_Index: Integer; About_UTC: TDateTime): Double;

Parameters

  • From_TZ_Index: Integer; The index of the source timezone in the application's timezone cache.
  • TO_TZ_Index: Integer; The index of the destination timezone in the application's timezone cache.
  • About_UTC: TDateTime; The specific moment in UTC for which to calculate the difference.

Return Value

Returns a `Double` representing the time difference, expressed as a `TDateTime` fraction (which can be converted to hours).

Get_TimeZone_Name

Retrieves the clean, human-readable name of a timezone from the application's cache using its index.
This function requires the timezone cache to be built first via `ThScm.Build_App_TimeZone_Cache`.
function Get_TimeZone_Name(Schema_TZ_Index: Integer): String;

Parameters

  • Schema_TZ_Index: Integer; The index of the timezone within the `Schema` component's cache.

Return Value

Returns the name of the timezone as a string.
If the index is invalid, it returns 'GMT / UTC'.

Convert_TimeZone

Converts a `TDateTime` value from a source timezone to a destination timezone.
This function correctly handles the conversion by first translating the source time to UTC and then to the destination timezone, accounting for any DST differences.
function Convert_TimeZone(DateTime: TDateTime; From_TZ_Index, TO_TZ_Index: Integer): TDateTime;

Parameters

  • DateTime: TDateTime; The date and time value in the source timezone.
  • From_TZ_Index: Integer; The index of the source timezone in the application's cache.
  • TO_TZ_Index: Integer; The index of the destination timezone in the application's cache.

Return Value

Returns a new `TDateTime` value representing the same moment in time, expressed in the destination timezone.