ThDB_Client

The ThDB_Client is the central and most critical component for handling all client-server communication with the SYE framework's proprietary database server.
It encapsulates the entire data access layer, allowing the application to load, save, query, and delete records on the remote server.
It is intended to be used as a singleton, typically accessed through the global Server variable.

Key Features

  • High-Level Operations: Provides a rich set of methods that represent database commands, such as Load, Save, Query, and Delete.
  • Communication Protocol: It automatically constructs requests in a custom XML format, which are then compressed and encrypted before being sent over a TCP/IP socket.
  • Fluent Query Builder: Includes a fluent API for building complex server-side queries by chaining Where_* methods (e.g., Where_SameVal, Where_In_Range).
  • Real-time Messaging: Manages a background thread to receive asynchronous push messages from the server, firing a New_Message event for real-time updates.

Reset

Safely resets the `ThDB_Client` component to a clean state, preparing it for a new transaction.
It clears any previously added requests but will fail if a transaction is already in progress.
This is the recommended method for resetting the client under normal circumstances.
Function Reset: Boolean;

Return Value

Returns `True` if the reset was successful and the client is ready for a new transaction.
Returns `False` if the client is currently busy and cannot be reset.

Hard_Reset_After_Thread_Break

Forcefully resets the `ThDB_Client` component's state, abandoning any pending requests.
This function initializes a new transaction packet, including writing the XML header and user information.
It is intended for recovery situations, such as after a network error or a broken thread.
Function Hard_Reset_After_Thread_Break: Boolean;

Return Value

Returns `True` if the client is connected to the server and ready for a new transaction after the reset.
Returns `False` if a connection to the server could not be established.

Request_Size_In_MB

Calculates the current size of the pending request packet that is being constructed in memory.
This can be useful for monitoring the size of a transaction before it is sent to the server.
Function Request_Size_In_MB: Double;

Return Value

Returns a `Double` representing the size of the request packet in megabytes, rounded to two decimal places.

Execute

Finalizes and sends the entire batch of queued database requests to the server.
This function handles the complete transaction lifecycle: it compresses and encrypts the request, sends it over the network, waits for the server's response, and then decodes and processes the returned data.
This is the final command that must be called to perform any server-side operations.
Function Execute: Boolean;

Return Value

Returns `True` if the entire transaction was sent and a valid response was successfully received and processed.
Returns `False` if any part of the communication or data processing fails.

Load

Adds a command to the current transaction to load a record or a set of related records from the server by its primary key.
This is an overloaded procedure that accepts either a `String` or a `ThNumeric` primary key.
This action is not executed immediately; it is queued and sent to the server when the `Execute` method is called.

Procedure Load(HTable: ThTable; PrimaryKey: String; Attrib: String = 'N'); Overload;
Procedure Load(HTable: ThTable; PrimaryKey: ThNumeric; Attrib: String = 'N'); Overload;

Parameters

  • HTable: ThTable; The table component that will receive the loaded data.
  • PrimaryKey: String or ThNumeric; The primary key of the record to load.
  • Attrib: String; An optional storage attribute, such as 'A' for archive, that tells the server which data store to load from.

The Attrib parameter specifies the data storage area for a server command. The possible values are:

Attribute Description
'N' (Default) Target / Source the Normal data store, which contains primary, active records.
'A' Target / Source the Archive data store, which contains older, archived records.
'NA' Target / Source both the Normal and Archive data stores. This is typically used for queries that span a date range covering both active and archived data.
'D' Target / Source Deleted items, often used when listing or undeleting files from object storage.
'T' Target / Source the Trash or temporary storage, used as a destination when moving records.

Save

Queues a request to save the data from one or more `ThTable` components to the server.
This procedure can save a single primary table or a main table along with an array of related sub-tables in a single transaction.
It performs several checks, such as verifying primary keys, before adding the save command to the request queue.
The actual save operation is performed when the `Execute` method is called.

procedure Save(MainTable: ThTable; Attrib: String = 'N'); Overload;
procedure Save(MainTable: ThTable; SubTables: Array OF ThTable; Attrib: String = 'N'; Only_When_Modified_By_User: Boolean = False); Overload;

Parameters

  • MainTable: ThTable; The primary table containing the record or records to be saved.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').
  • SubTables: Array OF ThTable; An optional array of related sub-tables to be saved along with the main table.
  • Only_When_Modified_By_User: Boolean; If `True`, a table will only be queued for saving if its `Modified_By_User` property is also `True` (default is `False`).

Combine_SubTable

Queues a request to save data to a sub-table, which is identified by a secondary key.
The server performs an "upsert" operation, either updating an existing record if the key is found, or inserting a new one if it is not.
This procedure must be used only with sub-tables, not primary tables.
procedure Combine_SubTable(HTable: ThTable; Attrib: String = 'N');

Parameters

  • HTable: ThTable; The sub-table component containing the data to be saved or updated.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Append_Blindly

Queues a request to perform a bulk insert of all records from the specified `HTable` into the database.
The server appends these records directly without checking for duplicates or existing records.
procedure Append_Blindly(HTable: ThTable; Attrib: String = 'N');

Parameters

  • HTable: ThTable; The table containing the new records to be appended to the database.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Number

Queues a request to create a new primary record and have the server generate a unique numeric primary key for it.
This is the standard procedure for inserting new main records into the database.
It can also save records from related sub-tables within the same transaction.
procedure Number(MainTable: ThTable; SubTables: Array OF ThTable; RangeMin: Cardinal = 0; RangeMax: Cardinal = 0);

Parameters

  • MainTable: ThTable; The main table containing the new record for which the server will generate a key.
  • SubTables: Array OF ThTable; An optional array of related sub-tables to be saved along with the new main record.
  • RangeMin: Cardinal; An optional value suggesting a lower bound for the server-generated key.
  • RangeMax: Cardinal; An optional value suggesting an upper bound for the server-generated key.

Save_Flagged_Rows

Queues a request to save only the rows in a given `ThTable` that have their flag set to `True`.
This is useful for efficiently saving only a subset of records, such as those modified in a data grid.
procedure Save_Flagged_Rows(MainTable: ThTable; ByColumn: Integer = 0; Attrib: String = 'N');

Parameters

  • MainTable: ThTable; The table containing the data to be saved.
  • ByColumn: Integer; The index of the column whose boolean flag will be checked to determine if a row should be saved (default is 0).
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Delete

Adds a request to the transaction queue to delete a single record from the server.
This procedure can identify the record to be deleted by either a string-based or a numeric primary key.
The actual deletion occurs when the `Execute` method is called.

procedure Delete(TableName: String; PrimaryKey: String; Attrib: String = 'N'); Overload;
procedure Delete(TableName: String; PrimaryKey: ThNumeric; Attrib: String = 'N'); Overload;

Parameters

  • TableName: String; The name of the table from which the record will be deleted.
  • PrimaryKey: String or ThNumeric; The value of the primary key that identifies the record to delete.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Delete (by table array)

Queues requests to delete a primary record and its related detail records across multiple tables.
It reads the primary key from the current row of the first table in the array (`Tables[0]`).
It then issues a separate delete command for each table provided in the array, using that same primary key.
This is useful for deleting a complete data entity that is spread across several tables.
procedure Delete(Tables: Array OF ThTable; ClearTables: Boolean; Attrib: String = 'N'); Overload;

Parameters

  • Tables: Array OF ThTable; An array of table components from which records with the matching primary key will be deleted.
  • ClearTables: Boolean; If `True`, the client-side `ThTable` components in the array will be cleared after the server confirms the deletion.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

VLock

Sends a request to the server to place a virtual lock on a specific data record. This is used to prevent concurrent editing of the same record by multiple users.
The lock is identified by the module that requests it and the primary key of the record.
procedure VLock(ModuleName: String; PrimaryKey: String);

Parameters

  • ModuleName: String; The name of the application module or screen that is requesting the lock.
  • PrimaryKey: String; The string-based primary key of the record that needs to be locked.

VRelease

Sends a request to the server to release a virtual lock that was previously placed on a data record.
This makes the record available for editing by other users. The lock is identified by the same module name and primary key used to create it.
procedure VRelease(ModuleName: String; PrimaryKey: String);

Parameters

  • ModuleName: String; The name of the application module that initially requested the lock.
  • PrimaryKey: String; The string-based primary key of the record whose lock is to be released.

Get_Online_Users_List

Requests a list of all currently connected users from the server.
After the transaction is executed, the results are populated in the `Last_Online_Users_List` property of the `ThDB_Client` component.
procedure Get_Online_Users_List(UsersList: String);

Parameters

  • UsersList: String; A parameter for the server request, which may be used for filtering or other purposes.

Update_Exist_Record (by arrays)

Updates a single existing record on the server using data provided in arrays.
This procedure is useful for updating a record without needing a complete `ThTable` object.
The first field in the `FldNames` array should be the primary key to identify the record.

procedure Update_Exist_Record(TableName: String; FldNames: ThFlds_Name_Array; DataStr: ThFlds_Name_Array; DataExt: Array OF ThNumeric; Attrib: String = 'N'); Overload;

Parameters

  • TableName: String; The name of the database table where the record will be updated.
  • FldNames: ThFlds_Name_Array; An array of strings containing the names of the fields to update.
  • DataStr: ThFlds_Name_Array; An array of strings with the new values for string-based fields.
  • DataExt: Array OF ThNumeric; An array of numbers with the new values for numeric fields.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Update_Exist_Record (by single row)

Updates a single existing record on the server using data from a specific row in a `ThTable`.
This version is ideal for performing partial updates on a record, as it only sends the data for the fields specified.

procedure Update_Exist_Record(SourceTb: ThTable; Srow: Integer; FldNames: ThFlds_Name_Array; Attrib: String = 'N'); Overload;

Parameters

  • SourceTb: ThTable; The source `ThTable` component containing the record to be updated.
  • Srow: Integer; The index of the row within the `SourceTb` that contains the data for the update.
  • FldNames: ThFlds_Name_Array; An array of strings specifying which fields from the row should be included in the update.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Update_Exist_Records

Updates multiple existing records on the server using all the rows from a source `ThTable`.
This is a convenience method that processes every row in the provided table.
For each row, it sends an update request containing only the data from the fields specified in `FldNames`.
procedure Update_Exist_Records(SourceTb: ThTable; FldNames: ThFlds_Name_Array; Attrib: String = 'N');

Parameters

  • SourceTb: ThTable; The source `ThTable` component containing the records to be updated.
  • FldNames: ThFlds_Name_Array; An array of strings specifying which fields from each row should be included in the update.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Query

Initiates a server-side query request to retrieve data into a `ThTable`. This procedure begins the query-building process.
After calling `Query`, you must add one or more filter conditions using the `Where_*` methods, followed by a call to `Close_Query` and finally `Execute` to run the transaction.
procedure Query(HTable: ThTable; Clear_On_Init: Boolean; Remember_Nickname: String = ''; Attrib: String = 'N');

Parameters

  • HTable: ThTable; The table component that will receive the results of the query.
  • Clear_On_Init: Boolean; If `True`, the `HTable` will be cleared before the request is sent to the server.
  • Remember_Nickname: String; An optional name for the server to cache the query results under, allowing them to be referenced in subsequent queries.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Move_Records_By_Query

Initiates a server-side operation to move records from one storage attribute to another based on a set of query conditions.
This procedure begins the query-building process.
After calling it, you must add filter conditions using the `Where_*` methods, followed by `Close_Query` and `Execute` to perform the move on the server.
procedure Move_Records_By_Query(TableName: String; FromAttrib, ToAttrib: Char);

Parameters

  • TableName: String; The name of the table in which the records will be moved.
  • FromAttrib: Char; The source storage attribute character (e.g., 'N', 'A', 'D').
  • ToAttrib: Char; The destination storage attribute character (e.g., 'N', 'A', 'D', 'T').

QuerySpecificFile

Initiates a query to retrieve records from a sub-table that are associated with a single primary key value.
This procedure is specifically designed for loading detail records related to a master record.
It supports both numeric and string-based primary keys.
After calling this procedure, you can add further `Where_*` conditions to filter the results before calling `Close_Query` and `Execute`.

procedure QuerySpecificFile(HTable: ThTable; PrimaryKey: ThNumeric; Attrib: String = 'N'); Overload;
procedure QuerySpecificFile(HTable: ThTable; PrimaryKey: String; Attrib: String = 'N'); Overload;

Parameters

  • HTable: ThTable; The sub-table component that will receive the query results.
  • PrimaryKey: ThNumeric or String; The primary key value of the parent record whose sub-table records are being queried.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Query_And_Remember

Initiates a server-side query and instructs the server to store the results in a temporary, named cache instead of sending them back to the client.
This is a powerful optimization for complex, multi-step queries, as the cached result set can be referenced in subsequent requests using its `Remember_Nickname`.
Like other query methods, this procedure must be followed by `Where_*` conditions, `Close_Query`, and `Execute`.
procedure Query_And_Remember(TableName, Remember_Nickname: String; SelectFields: ThFlds_Name_Array; Attrib: String = 'N');

Parameters

  • TableName: String; The name of the table to query on the server.
  • Remember_Nickname: String; A unique name under which the server will cache the query results.
  • SelectFields: ThFlds_Name_Array; An array of strings specifying which fields to include in the cached result set.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Set_Field_Value_By_Query

Initiates a server-side bulk update operation. It updates specified fields to new values for all records that match a set of query conditions.
This procedure must be followed by one or more `Where_*` conditions to define the target records, then `Close_Query`, and finally `Execute` to perform the update.
procedure Set_Field_Value_By_Query(TableName: String; FldNames: ThFlds_Name_Array; DataStr: ThFlds_Name_Array; DataExt: Array OF ThNumeric; Attrib: String = 'N');

Parameters

  • TableName: String; The name of the table to update on the server.
  • FldNames: ThFlds_Name_Array; An array of field names to be updated in the matching records.
  • DataStr: ThFlds_Name_Array; An array containing the new string values for the corresponding string-based fields.
  • DataExt: Array OF ThNumeric; An array containing the new numeric values for the corresponding numeric fields.
  • Attrib: String; An optional storage attribute character for the server transaction (default is 'N').

Where_Above

Adds a filter condition to a pending server query, selecting records where a numeric field's value is greater than the specified value.
This method must be called after a `Query` initiator and before `Close_Query`.
procedure Where_Above(CONST FieldName: String; CONST AboveValue: ThNumeric; CONST LogicGate: Thds_Logic = he_AND);

Parameters

  • FieldName: String; The name of the numeric or date/time field to be filtered.
  • AboveValue: ThNumeric; The lower bound for the comparison; records with values greater than this will be included.
  • LogicGate: Thds_Logic; The logical operator (e.g., `he_AND`, `he_OR`) used to combine this condition with the previous one.

The Thds_Logic type is an enumeration, that specifies the logical operator for combining filter conditions in a server-side query.
Value Description
he_AND Combines the current filter condition with the previous one.
Both conditions must be true for a record to be selected.
he_OR Combines the current filter condition with the previous one.
Either condition can be true for a record to be selected.
he_AND_NOT Combines the current filter condition with the previous one, but negates the current condition.
A record is selected if the previous condition is true AND the current condition is false.
he_OR_NOT Combines the current filter condition with the previous one, but negates the current condition.
A record is selected if the previous condition is true OR the current condition is false.

Where_Below

Adds a filter condition to a pending server query, selecting records where a numeric field's value is less than the specified value.
This method must be called after a `Query` initiator and before `Close_Query`.
procedure Where_Below(CONST FieldName: String; CONST BelowValue: ThNumeric; CONST LogicGate: Thds_Logic = he_AND);

Parameters

  • FieldName: String; The name of the numeric or date/time field to be filtered.
  • BelowValue: ThNumeric; The upper bound for the comparison; records with values less than this will be included.
  • LogicGate: Thds_Logic; The logical operator used to combine this condition with the previous one.

Where_In_Range

Adds a filter condition to a pending server query, selecting records where a numeric or date/time field's value falls between a minimum and maximum value (inclusive).
This method must be called after a `Query` initiator and before `Close_Query`.

procedure Where_In_Range(FieldName: String; Min, Max: ThNumeric; LogicGate: Thds_Logic = he_AND; DateTimeLogic: Thds_Where_In_Range_FixDT = he_As_Is);

Parameters

  • FieldName: String; The name of the numeric or date/time field to be filtered.
  • Min: ThNumeric; The minimum value of the range (inclusive).
  • Max: ThNumeric; The maximum value of the range (inclusive).
  • LogicGate: Thds_Logic; The logical operator used to combine this condition with the previous one.
  • DateTimeLogic: Thds_Where_In_Range_FixDT; A special flag to control how date/time values are handled, such as treating a date as the entire 24-hour period.

The Thds_Where_In_Range_FixDT type is an enumeration used specifically with the Where_In_Range procedure to control how it handles date and time ranges.
It provides options to either use the exact time values provided or to automatically adjust the range to ensure entire days are included in the filter, which is particularly useful when users only input dates without specific times.

Value Description
he_As_Is The range condition uses the provided date and time values exactly as they are without any modification.
he_Whole_Days_Anyway Always ignores the time portion of the range boundaries.
It expands the filter to cover the full 24-hour period for both the start and end dates of the range.
he_Only_On_Integer Expands the range to cover whole days, but only if the provided `TDateTime` values for the range have no time component (i.e., they are integer values).

Where_SameVal

Adds a filter condition to a pending server query, selecting records where a field's value exactly matches a specified value.
This method has overloads to support comparisons for both string and numeric data types.
It must be called after a `Query` initiator and before `Close_Query`.

procedure Where_SameVal(CONST FieldName: String; CONST SameVal: String; CONST LogicGate: Thds_Logic = he_AND); Overload;
procedure Where_SameVal(CONST FieldName: String; CONST SameVal: ThNumeric; CONST LogicGate: Thds_Logic = he_AND); Overload;

Parameters

  • FieldName: String; The name of the field to be filtered.
  • SameVal: String or ThNumeric; The value to compare against; records with a field value equal to this will be selected.
  • LogicGate: Thds_Logic; The logical operator (e.g., `he_AND`, `he_OR`) used to combine this condition with the previous one.

Where_String_Search

Adds a fuzzy, sound-based search condition to a pending server query.
This is an advanced search that finds records based on phonetic similarity, making it resilient to spelling errors.
It must be called after a `Query` initiator and before `Close_Query`.
procedure Where_String_Search(CONST FieldName: String; CONST SearchString: String; CONST LogicGate: Thds_Logic = he_AND);

Parameters

  • FieldName: String; The name of the string field to be searched.
  • SearchString: String; The text to search for phonetically.
  • LogicGate: Thds_Logic; The logical operator used to combine this condition with the previous one.

Where_Contain_String

Adds a simple substring search condition to a pending server query. It selects records where the specified field's value contains the provided text.
This method must be called after a `Query` initiator and before `Close_Query`.
procedure Where_Contain_String(CONST FieldName: String; CONST ContString: String; CONST LogicGate: Thds_Logic = he_AND);

Parameters

  • FieldName: String; The name of the string field to be searched.
  • ContString: String; The substring to search for within the field's value.
  • LogicGate: Thds_Logic; The logical operator used to combine this condition with the previous one.

Where_Included_In_Remembered_Query

Adds a powerful subquery-like condition to a pending server query.
It filters for records where a field's value exists within a result set that was previously cached on the server using `Query_And_Remember`.
This allows for efficient, multi-step filtering without transferring intermediate data to the client.
procedure Where_Included_In_Remembered_Query(FieldName, From_Table_Nickname, From_Field_Name: String; LogicGate: Thds_Logic = he_AND);

Parameters

  • FieldName: String; The name of the field in the current query whose value will be checked.
  • From_Table_Nickname: String; The nickname of the server-cached result set (created with `Query_And_Remember`) to search within.
  • From_Field_Name: String; The name of the field within the cached result set to compare against.
  • LogicGate: Thds_Logic; The logical operator used to combine this condition with the previous one.

Where_Date_In_Period

Adds a filter condition to a pending server query for a date/time field based on a predefined period string.
This allows for easy filtering using human-readable ranges like 'Today', 'ThisWeek', 'LastMonth', etc., which are interpreted by the server.
procedure Where_Date_In_Period(CONST FieldName, Period_Range: String; CONST LogicGate: Thds_Logic = he_AND);

Parameters

  • FieldName: String; The name of the date/time field to be filtered.
  • Period_Range: String; A predefined string representing the desired date range (e.g., 'Today', 'ThisMonth').
  • LogicGate: Thds_Logic; The logical operator used to combine this condition with the previous one.

Period_Range Value Description
'Today' Filters for records from the beginning to the end of the current day.
'Yesterday' Filters for records from the beginning to the end of the previous day.
'ThisWeek' Filters for records from the start of the current week until the current time.
'LastWeek' Filters for records spanning the entire previous week.
'ThisMonth' Filters for records from the first day of the current month until the current time.
'LastMonth' Filters for records spanning the entire previous month.
'ThisYear' Filters for records from the first day of the current year until the current time.
'LastYear' Filters for records spanning the entire previous year.

Where_Cont_Group_Items

Adds a filter condition to a pending server query for fields that contain a delimited list of values.
It selects records if the field contains any of the items specified in the `Group_Item_List`.
This is useful for searching in fields that store multiple tags or categories as a single string.
procedure Where_Cont_Group_Items(CONST FieldName: String; CONST Group_Item_List: String; CONST LogicGate: Thds_Logic = he_AND);

Parameters

  • FieldName: String; The name of the field containing the delimited list to search within.
  • Group_Item_List: String; A delimited string of items to search for within the field.
  • LogicGate: Thds_Logic; The logical operator used to combine this condition with the previous one.

Where_Compare_Between

Adds a filter condition to a pending server query that compares the value of one field against the value of another field in the same record.
This allows for dynamic, row-by-row comparisons as part of the server-side query.
procedure Where_Compare_Between(Field1: String; Equation: Thds_Equation; Field2: String; LogicGate: Thds_Logic = he_AND);

Parameters

  • Field1: String; The name of the first field in the comparison.
  • Equation: Thds_Equation; The comparison operator to use (e.g., `he_Equal_To`, `he_Less_Then`, `he_More_Then_Equal_To`).
  • Field2: String; The name of the second field in the comparison.
  • LogicGate: Thds_Logic; The logical operator used to combine this condition with the previous one.

The Thds_Equation type is an enumeration that defines the comparison operator used in a Where_Compare_Between query condition.
It allows you to specify how the values of two different fields within the same record should be compared on the server.

Value Description
he_Equal_To Selects records where the value of the first field is equal to the value of the second field.
he_Different_Then Selects records where the value of the first field is not equal to the value of the second field.
he_Less_Then Selects records where the value of the first field is less than the value of the second field.
he_More_Then Selects records where the value of the first field is greater than the value of the second field.
he_Less_Then_Equal_To Selects records where the value of the first field is less than or equal to the value of the second field.
he_More_Then_Equal_To Selects records where the value of the first field is greater than or equal to the value of the second field.

Close_Group_And_Start_A_New_Group

Allows for the creation of complex, nested query logic by grouping conditions together.
This procedure closes the current block of `Where_*` conditions and starts a new one.
It is used to build queries with logic equivalent to using parentheses, such as `(ConditionA AND ConditionB) OR (ConditionC)`.
procedure Close_Group_And_Start_A_New_Group(LogicGate: Thds_Logic);

Parameters

  • LogicGate: Thds_Logic; The logical operator used to combine the entire previous group of conditions with the new group that is about to be started.

Close_Query

Finalizes the construction of a server-side query request.
This procedure must be called after a query initiator (like `Query` or `QuerySpecificFile`) and after all `Where_*` conditions have been added.
After calling `Close_Query`, you can add other requests to the transaction or call `Execute` to send it to the server.
procedure Close_Query;

LoadFile

Queues a request to download a file from the server's secure DB Object storage.
The file will be saved to the local application cache.
It includes an optimization to avoid re-downloading the file if the local version is already up-to-date.
procedure LoadFile(Folder, FileName: String; Alternative_Target_FN: String = '');

Parameters

  • Folder: String; The name of the DB Object folder on the server where the file is located.
  • FileName: String; The name of the file to download from the server.
  • Alternative_Target_FN: String; An optional full local path and filename to save the file to, overriding the default cache location.

SaveFile

Queues a request to upload a local file to the server's secure DB Object storage.
The file's content is read from a local source and sent to the server to be stored.
procedure SaveFile(Folder, FileName: String; Alternative_Source_FN: String = '');

Parameters

  • Folder: String; The name of the DB Object folder on the server to save the file into.
  • FileName: String; The name to give the file on the server.
  • Alternative_Source_FN: String; An optional full local path and filename of the source file, used if it differs from the default cache location.

DeleteFile

Queues a request to delete a file from the server's secure DB Object storage.
The `FileName` parameter can include wildcards (*) to delete multiple files at once.
procedure DeleteFile(Folder, FileName: String);

Parameters

  • Folder: String; The name of the DB Object folder on the server where the file is located.
  • FileName: String; The name of the file to delete. Wildcards are supported.

RenameFile

Queues a request to rename a file within the server's secure DB Object storage.
The operation occurs entirely on the server.
procedure RenameFile(Folder, FileName, RenameTo: String);

Parameters

  • Folder: String; The name of the DB Object folder on the server where the file is located.
  • FileName: String; The current name of the file to be renamed.
  • RenameTo: String; The new name for the file.

UnDeleteFile

Queues a request to the server to restore a previously deleted file from the secure DB Object storage.
The `FileName` parameter can include wildcards (*) to restore multiple files at once.
procedure UnDeleteFile(Folder, FileName: String);

Parameters

  • Folder: String; The name of the DB Object folder on the server where the file was originally located.
  • FileName: String; The name of the file to restore. Wildcards are supported.

FilesList

Queues a request to the server to get a list of files from a secure DB Object storage folder.
The server returns a list of files matching the specified criteria, which is then populated into the provided `HTable`.
The `HTable` should be based on the 'SYE_FilesList_Header' table schema to correctly receive the file information.
procedure FilesList(HTable: ThTable; Folder, FilesMask: String; Deleted_SubFolder: Boolean = False; SearchString: String = '');

Parameters

  • HTable: ThTable; The table component that will be populated with the list of files returned by the server.
  • Folder: String; The name of the DB Object folder on the server to search within.
  • FilesMask: String; The file mask used to filter the results (e.g., '*.jpg', 'document_*.pdf').
  • Deleted_SubFolder: Boolean; If `True`, the search will be performed in the folder containing deleted items instead of the main folder.
  • SearchString: String; An optional string to perform a full-text search on the files' content or metadata.

Explore_Lic_Details

Reads and decodes a `.lic` license file from the disk.
This function populates the internal properties of the client component with the license information, such as the database folder name and feature flags, but does not initiate a network connection.
function Explore_Lic_Details(VAR License_FileName: String): Boolean;

Parameters

  • License_FileName: VAR String; The path to the license file. If an empty string is passed, the function will automatically search for the first `.lic` file in the application's directory.
    Upon successful execution, this parameter will contain the full path of the file that was loaded.

Return Value

Returns `True` if the license file was found and successfully decoded, otherwise returns `False`.

Login

Establishes an authenticated connection to the database server. This procedure uses the provided license file and user credentials to connect and log in.
If no `ServerIP` is provided, it may attempt to look up the IP from a supervisor server.
Upon success, it starts a background thread for receiving real-time messages.
function Login(License_FileName, UserName, ServerIP: String): Boolean;

Parameters

  • License_FileName: String; The path to the `.lic` license file.
  • UserName: String; The username for the session.
  • ServerIP: String; The IP address of the server. If left empty, the client may attempt to resolve it automatically.

Return Value

Returns `True` if the connection and login were successful, otherwise returns `False`.

LogOUT

Disconnects from the server and clears the current session's authentication and license information.
It terminates the background messenger thread and resets the client component to a disconnected state.
procedure LogOUT;

Connected_To_Server

Checks the current connection status of the client component.
function Connected_To_Server: Boolean;

Return Value

Returns `True` if the client has an active and authenticated connection to the server, otherwise returns `False`.

Assign_Login

Clones the connection and session details from an existing, connected `ThDB_Client` instance to the current one.
This is useful for creating multiple client instances for concurrent operations without performing a full login for each.
It copies all necessary details, including IP address, port, username, and encryption keys.
function Assign_Login(FromClient: ThDB_Client): Boolean;

Parameters

  • FromClient: ThDB_Client; The source `ThDB_Client` component that is already logged in. If NIL, it defaults to the global `Server` instance.

Return Value

Returns `True` if the login details were successfully copied and the source client was connected, otherwise returns `False`.

Login_To_Supervisor_Server

A specialized procedure to connect the client component to the central SYE Supervisor Server.
This connection does not use a local license file and is a prerequisite for looking up customer database server IP addresses.
procedure Login_To_Supervisor_Server;

Get_DB_IP_From_Supervisor_Server

Retrieves the IP address of a specific customer's database server from the Supervisor Server.
This function must be called after a successful connection has been established using `Login_To_Supervisor_Server`.
function Get_DB_IP_From_Supervisor_Server(Query_Lic_DB_Folder_Name: String): String;

Parameters

  • Query_Lic_DB_Folder_Name: String; The unique database folder name from the customer's license file, used to identify their server.

Return Value

Returns the IP address of the requested database server as a string, or '127.0.0.1' if not found.

Lic_Feature

Checks if a specific feature is enabled in the currently loaded license file.
This is the standard method for performing run-time checks for licensed application features.
function Lic_Feature(_FName: String): Boolean;

Parameters

  • _FName: String; The case-insensitive name of the feature to check (e.g., 'Hyper Full ERP').

Return Value

Returns `True` if the feature is enabled in the license, otherwise returns `False`.

Get_Http_Link

Constructs a direct HTTP URL for a file stored in the server's DB Object storage.
This is used to create web-accessible links to files managed by the framework.
function Get_Http_Link(Folder, FN: String; UTF8: Boolean): String;

Parameters

  • Folder: String; The name of the DB Object folder on the server where the file is located.
  • FN: String; The name of the file on the server.
  • UTF8: Boolean; If `True`, the resulting URL will be UTF-8 encoded.

Return Value

Returns a full, direct HTTP URL to the specified file as a string.

Get_DB_FN

Constructs the full local path for a cached file from the DB Object storage.
This function determines the correct local directory where files are stored after being downloaded from the server and ensures the path exists.
function Get_DB_FN(Folder, FileName: String): String;

Parameters

  • Folder: String; The name of the DB Object folder that corresponds to the local cache subdirectory.
  • FileName: String; The name of the file.

Return Value

Returns a full local file path, including the filename, as a string.

NOW_UTC

Gets the current Coordinated Universal Time (UTC), synchronized with the server's clock.
It adjusts the client's system time by an offset calculated during the login process to correct for local clock inaccuracies.
function NOW_UTC: TDateTime;

Return Value

Returns a `TDateTime` value representing the current server-synchronized UTC.

NOW

Gets the current local time, synchronized with the server and correctly adjusted for the application's default timezone.
It calls `NOW_UTC` internally and then applies the appropriate timezone conversion.
function NOW: TDateTime;

Return Value

Returns a `TDateTime` value representing the current server-synchronized local time.

Today

Gets the date part of the current server-synchronized local time.
It calls `NOW` internally and removes the time portion.
function Today: Integer;

Return Value

Returns an `Integer` representing the date value for the current day, synchronized with the server.

SendMessageAnsiText

Sends a real-time message containing an Ansi string (`RawByteString`) to a specific user connected to the server.
This is a convenience wrapper for the core `SendMessage` procedure.
procedure SendMessageAnsiText(ToUser: String; MsgType: Byte; Text: RawByteString);

Parameters

  • ToUser: String; The username of the recipient.
  • MsgType: Byte; A user-defined message type identifier, allowing the recipient to handle different kinds of messages.
  • Text: RawByteString; The Ansi string content of the message to be sent.

SendMessageWideText

Sends a real-time message containing a Unicode string to a specific user connected to the server.
This is a convenience wrapper for the core `SendMessage` procedure.
procedure SendMessageWideText(ToUser: String; MsgType: Byte; Text: String);

Parameters

  • ToUser: String; The username of the recipient.
  • MsgType: Byte; A user-defined message type identifier.
  • Text: String; The Unicode string content of the message to be sent.

SendMessage_MS

Sends a real-time message containing the content of a `ThMemoryStream` to a specific user connected to the server.
This is a convenience wrapper for the core `SendMessage` procedure, useful for sending binary data.
procedure SendMessage_MS(ToUser: String; MsgType: Byte; Content: ThMemoryStream);

Parameters

  • ToUser: String; The username of the recipient.
  • MsgType: Byte; A user-defined message type identifier.
  • Content: ThMemoryStream; The stream whose content will be sent as the message.

SendMessage

Sends a real-time message with content from an untyped buffer to a specific user connected to the server.
This is the core, low-level procedure that handles the packaging, encryption, and transmission of the message.
procedure SendMessage(ToUser: String; MsgType: Byte; VAR Content; SizeinBytes: Integer);

Parameters

  • ToUser: String; The username of the recipient.
  • MsgType: Byte; A user-defined message type identifier.
  • Content: VAR; An untyped buffer containing the message data to be sent.
  • SizeinBytes: Integer; The size of the content buffer in bytes.

Encode_String

Encrypts and encodes a string for secure storage or transmission.
The process involves converting the string to UTF-8, encrypting it with the internal SYE Sapphire algorithm, and then encoding the binary result into a Base64 string.
function Encode_String(InputStr: String): String;

Parameters

  • InputStr: String; The original string to be encrypted.

Return Value

Returns the encrypted and Base64-encoded string.

Decode_String

Decrypts a string that was previously encrypted using the `Encode_String` function.
It performs the reverse operations: Base64 decoding, SYE Sapphire decryption, and conversion from UTF-8 back to a standard string.
function Decode_String(InputStr: String): String;

Parameters

  • InputStr: String; The encrypted, Base64-encoded string to be decrypted.

Return Value

Returns the original, decrypted string.

EncDec_String_Test

A utility function to test the encryption and decryption process for a given string and validate the length of the encrypted result.
It encrypts the string, checks if the result's length is within the specified maximum, then decrypts it and verifies that it matches the original.
function EncDec_String_Test(InputStr: String; MaxLength: Integer): Boolean;

Parameters

  • InputStr: String; The string to use for the test.
  • MaxLength: Integer; The maximum allowed length for the encrypted string.

Return Value

Returns `True` if the encrypted string length is within the limit and the decrypted string matches the original; otherwise, returns `False`.

Decode_WideString

Decrypts a string that was encrypted from a source that was originally UCS-2 (WideString) without being converted to UTF-8.
This is a special-case function, typically used for backward compatibility with older data.
function Decode_WideString(InputStr: String): String;

Parameters

  • InputStr: String; The encrypted, Base64-encoded string to be decrypted.

Return Value

Returns the original, decrypted WideString.

rt_SB_Msg_Ptr

A procedure pointer used to link the client component to a status bar message handler in the user interface.
When assigned, the `ThDB_Client` will send progress updates, status messages, and errors to this handler during transactions, allowing the UI to reflect the component's activity.
property rt_SB_Msg_Ptr: ThTable_Statusbar_Msg;

Description

This property acts as a callback mechanism to decouple the data layer from the UI layer.
Assign a method that matches the `ThTable_Statusbar_Msg` signature to this property to receive real-time feedback from the client component's operations.

    ThTable_Statusbar_Msg

    This is a procedural type that defines the signature for a method used as a callback to receive status updates.
    Data components like `ThTable` and `ThDB_Client` use a pointer of this type (`rt_SB_Msg_Ptr`) to send status information to the user interface, typically to a status bar component.
    This allows the data layer to report progress, errors, and messages without being directly coupled to UI controls.
    ThTable_Statusbar_Msg = procedure(Purpose: ThTable_Statusbar_Msg_Purpose; Note: String; CurrPos, TotalScope: Double; Icon: String) of object;

    Parameters

    • Purpose: ThTable_Statusbar_Msg_Purpose; An enumeration (`he_Msg`, `he_ErrorMsg`, `he_Progress`, `he_Progress_And_Note`) that specifies the kind of status update being sent.
    • Note: String; The text message to be displayed in the status bar.
    • CurrPos: Double; The current value for a progress bar calculation (e.g., rows processed).
    • TotalScope: Double; The maximum value for a progress bar calculation (e.g., total rows to process).
    • Icon: String; The name of an icon to display in the status bar panel.

rt_Bind_NIC_IP

Specifies a local IP address to which the client's outgoing socket connection should be bound.
This is useful for machines with multiple Network Interface Cards (NICs), allowing the developer to force communication over a specific network.
property rt_Bind_NIC_IP: String;

Description

Set this property to the string representation of a local IP address before connecting.
If the string is empty, the operating system will choose the outgoing network interface automatically.

Read_Only_Mode

A flag that puts the `ThDB_Client` instance into a read-only mode.
When set to `True`, all procedures that modify data on the server (e.g., `Save`, `Delete`, `Combine_SubTable`) will be blocked from executing.
property Read_Only_Mode: Boolean;

Description

Set this property to `True` to prevent any data modification requests from being sent to the server through this client instance.

Last_Transaction

A record that contains status information and metadata about the most recently completed server transaction.
This property is populated after each successful call to the `Execute` method.
property Last_Transaction: ThDB_Last_Transaction;

Description

After a transaction, you can inspect the fields of this record to get valuable feedback from the server, including:
  • Object_Is_Locked: Boolean; Indicates if a requested record was locked by another user.
  • Object_Is_Locked_By: String; The name of the user holding the lock.
  • IP_Reflection: String; The client's public IP address as seen by the server.
  • Bandwidth_KB_Per_Sec: Double; The calculated network speed of the transaction in kilobytes per second.

Lic_Licenced_To

A read-only property that holds the name of the license holder.
This value is read from the `.lic` file after a successful call to `Login` or `Explore_Lic_Details`.
property Lic_Licenced_To: String;

Lic_Db_Folder

A read-only property that holds the unique name of the database folder on the server.
This value is a crucial identifier read from the `.lic` file and is used in server communications.
property Lic_Db_Folder: String;

Lic_Filename

A read-only property that contains the full path and filename of the license file used for the current session.
This property is populated after a successful call to the `Login` function.
property Lic_Filename: String;

IP_Address

A read-only property that returns the IP address of the server to which the client is currently connected.
property IP_Address: String;

Last_Online_Users_List

A read-only property that provides a list of users currently connected to the server.
This `ThStringList` is populated after a successful call to `Get_Online_Users_List` is executed.
property Last_Online_Users_List: ThStringList;

Request_Count

A read-only property that returns the number of individual requests currently queued in the pending transaction.
property Request_Count: Integer;

Description

The count starts at 1 for the first request and increments for each subsequent request (e.g., `Load`, `Save`, `Query`) added to the transaction before `Execute` is called.

Last_Query_Had_Wheres

A read-only property that indicates whether the most recently defined query included at least one `Where_*` condition.
property Last_Query_Had_Wheres: Boolean;

Description

This flag is set to `True` if any `Where_*` method was called within a `Query...Close_Query` block. It allows you to check if the last query was filtered.

Busy

A read-only property that indicates if the client component is currently executing a transaction.
It is set to `True` when the `Execute` method is called and remains `True` until the entire server communication is complete.
property Busy: Boolean;

Connected_UserName

A read-only property that returns the username for the current, authenticated session.
This value is set after a successful call to the `Login` method.
property Connected_UserName: String;

Last_Login_Answer

A read-only property containing the raw response string from the server after the last login attempt.
This is useful for debugging login failures.
property Last_Login_Answer: String;

Description

A successful login will typically result in the string 'SYE_OK'.
Failed attempts may return codes such as 'Suspnd' (suspended user) or 'TooMny' (too many users).

Usage_Notes

A design-time string property for developer comments.
This property has no effect on the component's run-time behavior and can be used to document the purpose of the component instance within a project.
property Usage_Notes: String;

New_Message

An event that fires when a real-time message is received from the server.
The background messenger thread listens for incoming data and triggers this event on the main application thread for safe UI interaction.
This is the primary event for handling asynchronous, server-pushed notifications or client-to-client messages.
property New_Message: ThDB_Client_Message_Event;

Event Signature

ThDB_Client_Message_Event = procedure(MsgType: Byte; Source: ThMemoryStream) of object;
  • MsgType: A user-defined byte that identifies the type of message being received.
  • Source: A `ThMemoryStream` containing the raw content of the message.

Server_DisConnected

An event that fires when the connection to the server is lost.
The background messenger thread detects the disconnection and triggers this event on the main application thread.
This allows the application to respond appropriately, such as by updating the UI to a "disconnected" state.
property Server_DisConnected: TNotifyEvent;

Server_ReConnected

An event that fires after the client has successfully re-established a connection to the server following a disconnection.
The background messenger thread automatically attempts to reconnect. Upon success, this event is triggered on the main application thread.
This allows the application to restore its UI and resume normal operations.
property Server_ReConnected: TNotifyEvent;