TAPIDataset Reference

TAPIDataset bridges TMS WEB Core applications to XData server endpoints. It wraps HTTP calls to PostgreSQL stored procedures, handling:

• Automatic JSON parsing and field creation
• Parameter binding (input and output)
• Async operation with callback events
• Connection pooling via TXDataWebConnection

Location: Framework/Components/API/SOURCE/Obj.API.Dataset.pas

Load / Open

PROCEDURE Load;                          /// Opens dataset, fires AfterOpen
PROCEDURE Load(Callback: TProc);         /// Opens with completion callback
PROCEDURE Open;                          /// Same as Load
PROCEDURE Close;                         /// Closes dataset, clears data

Refresh

PROCEDURE Refresh;                       /// Reloads data with current params
PROCEDURE RefreshAsync(Callback: TProc); /// Async refresh with callback

Parameter Access

FUNCTION ParamByName(Name: STRING): TParam;
FUNCTION OutputParamByName(Name: STRING): TParam;

Field Access

FUNCTION FieldByName(Name: STRING): TField;
FUNCTION FindField(Name: STRING): TField;  /// Returns NIL if not found

Basic Load

/// Design time: Set Connection, EntitySetName = 'dashboard.getcards'
/// Set ParamByName('fkuserid_').AsInteger in code

PROCEDURE TfrmDashboard.WebFormShow(Sender: TObject);
BEGIN
   dsCards.ParamByName('fkuserid_').AsInteger := CurrentUserID;
   dsCards.Load;
END;

PROCEDURE TfrmDashboard.dsCardsAfterOpen(Dataset: TDataset);
BEGIN
   /// Data is now available
   WHILE NOT dsCards.EOF DO
      BEGIN
         ProcessCard(dsCards.FieldByName('cardid').AsInteger);
         dsCards.Next;
      END;
END;

Async with Callback

dsCards.Load(
   PROCEDURE
   BEGIN
      /// Executes after load completes
      ShowMessage('Loaded ' + IntToStr(dsCards.RecordCount) + ' cards');
   END);

Output Parameters

/// PostgreSQL function returns OUT parameters
/// e.g.: CREATE FUNCTION getuser(userid_ INT, OUT username_ TEXT, OUT email_ TEXT)

dsUser.ParamByName('userid_').AsInteger := 123;
dsUser.Load(
   PROCEDURE
   BEGIN
      UserName := dsUser.OutputParamByName('username_').AsString;
      Email := dsUser.OutputParamByName('email_').AsString;
   END);

PostgreSQL Naming Convention

Parameters follow the PostgreSQL function signature with trailing underscore:

/// PostgreSQL: dashboard.getcards(fkuserid_, startdate_, enddate_)
dsCards.ParamByName('fkuserid_').AsInteger := UserID;
dsCards.ParamByName('startdate_').AsDateTime := StartDate;
dsCards.ParamByName('enddate_').AsDateTime := EndDate;

NULL Handling

/// Set parameter to NULL
dsCards.ParamByName('optionalfilter_').Clear;

/// Check if field is NULL
IF dsCards.FieldByName('description').IsNull THEN
   Description := '(none)'
ELSE
   Description := dsCards.FieldByName('description').AsString;

JSON Array Parameters

/// For PostgreSQL JSONB array parameters
dsCards.ParamByName('cardids_').AsString := '[1,2,3,4,5]';