Simple Data Operations sample (desktop) (Delphi)

The Simple Data Operations sample uses a console based program to demonstrate the most common interactions you will make to an instance of Relativity Server. It shows how to:

connect to the server
retrieve a table from the server
add a row to the retrieved table and apply that change to the server
update/change the contents of a row and apply that change to the server
delete a row from the table and apply that change to the server

Getting Started

The sample is located in C:\Users\Public\Documents\RemObjects Samples\Data Abstract for Delphi\SimpleDataOperations.

To build it, you will need a version of Delphi RAD Studio, and like all the samples provided with Data Abstract for Delphi you will need to be running Relativity Server with the DASamples Domain and the Simple Schema available.

Running the Sample

When run the sample presents the user interface and sets up the connection to an instance of Relativity Server however the data is not retrieved until the "Load" button is pressed.

The UI is comprised of two sections, the first is a toolbar that contains a combo box that has the address of the server to connect to, which by default is an instance of Relativity Server running on the local machine however it can be changed as needed. Then there are 4 buttons; the "Load" button retrieves a set of data from the "Deps" table in the "Simple" schema, the "Add" button adds a new row to the local table, the "Remove" button will delete the selected row from the table and finally the "Apply" button will send all local changes to the server to be applied to the data there. The other part of the UI is the large area below which will contain the table data after it has been loaded from the server.

After the data has been loaded you can double click on any field to change its content. Note that when you add a new row that its "DepId" is initially a negative number (-1, -2 and so on) until the changes have been applied to the server, at which point the rows will be assigned proper "Id" values and then those values will be returned and the local data updated to reflect those changes.

It should be noted that if you quit the program without applying the local changes to the server then they will be lost.

Examining the Code

This sample is comprised of two source files; fClientDataModule which handles the interaction with Relativity Server and fClientForm which handles the user interface interactions.

The user interface for fClientForm is built using the Delphi form designer. The server connection is defined in the form design for the fClientDataModule that links together a number of Data Abstract controls. When creating a new project the project wizard would define this for you.

The Deps schema table used in this sample has three fields:

DepId is the primary key and use an AutoInc data type.
DepName is a string of up to 50 characters and is required for each new row
DepPhone is also a string of up to 50 characters, the field is optional.

Setting up a connection

Creating the connection through which all communication with the server will typically be created for you by the Data Abstract project wizard provided for Delphi. This will generate a DataModule object for you with the TDARemoteDataAdapter properly configured.

You can manually configure the connection either in code (see the SimpleDataOperations Console for an example of this), or by using the design view and adding components from the "RemObjects Data Abstract" and "RemObjects SDK" sections of the "Tool Palette".

The grid for displaying the table uses the ds_Deps object as its DataSource. The ds_Deps object is an instance of TDADataSource configured with the tbl_Deps (instance of TDAMemDataTable) as its DataTable and DataSet. Any changes then made to the tbl_Deps table are reflected in the grid.

Logging In

To connect to the server and work with the schema data you normally require an authenticated connection before allowing any changes to occur. The sample is configured such that the RemoteDataAdapter control will call the RemoteDataAdapterGenerateLoginString procedure found in fClientDataModule when it requires a login string for authenticating.

The login string is comprised of 4 parts:

User Id the username to attempt to login with
Password the password to use
Domain the name of the domain that the schema is located in
Schema the name of the schema we wish to use

For example, the login string from this sample is

RelativityConnectionString: String = 'User Id="simple";Password="simple";Domain="DASamples";Schema="Simple"';

procedure TClientDataModule.RemoteDataAdapterGenerateLoginString(
  Sender: TObject; var aLoginString: string);
begin
  aLoginString := RelativityConnectionString;
end;

Retrieving a Table

The table used in this sample is defined as a control in the design view of fClientDataModule. It uses TDAMemDataTable which is a concrete form of TDADataTable to store the data retrieved from the server.

To retrieve a copy of a table from the schema we need to use the Open procedure of TDAMemDataTable.

procedure TClientDataModule.SelectDepartment;
begin
  tbl_Deps.Close;
  tbl_Deps.Open;
end;

Inserting a Row

To add a new row to the table first call the Append procedure of the TDAMemDataTable which will set the cursor to the new row. Then you can set the fields of the new row using the FieldByName function. Once the fields have been modified as required, the Post procedure is called to save the changes to the table.

At this point the changes to the row & table are only in the local data. This is why the "DepId" of the new row is assigned a negative number so as not to clash with the server. When you apply the changes to the server a proper value will be assigned to the ID and the updated value returned to the client program.

This is particularly observable in this sample when you add a new row has a DepId of "-1", once the changes have be applied to the server that DepId is updated to reflect what the actual id is on the server.

procedure TClientDataModule.InseptDepartment;
begin
  tbl_Deps.Append;
  tbl_Deps.FieldByName('DepName').AsString := '[New Department]';
  tbl_Deps.FieldByName('DepPhone').AsString := '(000)000-00-00';
  tbl_Deps.Post;
end;

Applying Changes back to the server

To apply the changes made to a data table back to the server we use the ApplyUpdates function of TDAMemDataTable. This will use the remote data adapter to send the data to the server which will then apply the changes.

Any additional changes or new data that are on the server will be sent back to the client program and the local table will be updated to reflect the current state of the server data.

procedure TClientDataModule.ApplyChanges;
begin
  tbl_Deps.ApplyUpdates;
end;

Deleting a Row

Removing or deleting a row from a table is as simple as using the Delete procedure which will delete the record from the table currently marked as current. At this point the changes to the row & table are only in the local data.

procedure TClientDataModule.RemoveDepartment;
begin
  tbl_Deps.Delete;
end;