GetRowBySerialAsync

Part of the IQSDataTable interface, this method retrieves a single row as an IQSDataTableRow using a unique decimal serial number. Combined with a BatchId, it returns a fully initialised row that includes all metadata and row fields.

the (BatchId) is used to associate the retrieved row with a logical group of operations, which is useful for tracking the fields modifications and used later when calling SaveBatchAsync(BatchId) or SaveBatchOnlyAsync(BatchId) to determine which fields have been modified and apply the corresponding updates to the data source.

Asynchronously returns an IQSDataTableRow for the given serial, or null when no matching record exists. You can limit the retrieved columns by supplying a comma‑separated list of target fields.

Data retrieved from this method can be modified and saved back to the data source using the appropriate save methods. The returned IQSDataTableRow is designed for edit operations, allowing you to change field values and track those changes within the context of the provided BatchId.

Signature

public async Task<IQSDataTableRow> GetRowBySerialAsync(decimal serial, Guid BatchId, string TargetFields = "")

Parameters

NameTypeDescription
serialdecimalThe unique serial number of the row to fetch.
BatchIdGuid A batch identifier used to associate the retrieved row with a logical group of operations and track the row field changes in the resulting IQSDataTableRow.
TargetFieldsstring (optional) Comma‑separated column names to include in the underlying query. When empty (default), all columns are fetched.

Returns

A Task<IQSDataTableRow> that represents the asynchronous operation. On success, the result is a fully constructed IQSDataTableRow containing:

  • The table name and metadata (OwnerTableName, OwnerTableInfo)
  • The fetched DataRow
  • The provided BatchId

If no record matches the serial, the method returns null.

Example Usage

// Define the data table
IQSDataTable invoicesTable = QSAppContext.Tables["Invoices"];

// Serial number and batch context
decimal serialNumber = 5001;
Guid batchId = Guid.NewGuid();

// Retrieve a full row (all columns)
IQSDataTableRow row = await invoicesTable.GetRowBySerialAsync(serialNumber, batchId);

// Retrieve only selected columns
IQSDataTableRow limitedRow = await invoicesTable.GetRowBySerialAsync(
  serialNumber, batchId, "InvoiceID,CustomerName,Amount"
);

if (row != null)
{
  string customer = row["CustomerName"].ToString();

  // Modify and track changes to fields
  row["Email"] = "new.email@example.com";
  row["Name"] = "New Name";

  // Save changes for the batch
  await QSAppContext.SaveBatchAsync(batchId);

  // Or save only a single batch without affecting other pending changes
  await QSAppContext.SaveBatchOnlyAsync(batchId);
}