![developer12 | Embarcadero RAD Studio Delphi C++Builder Blogs](https://i0.wp.com/blogs.embarcadero.com/wp-content/uploads/2020/08/developer12.jpg?resize=1140%2C694&ssl=1)
Author: Jim T1392
This is a continuation of my posts on DataSnap server method parameters and return types. This post is about TStream and TDBXStreamValue. The sample client and server projects that go with this post can be downloaded here: http://cc.embarcadero.com/item/26854
See my earlier posts on “Basic” and “Basic DBXValue” types. I’ve yet to post about TDBXConnection, TDBXConnectionValue, TDBXReader, TParams, and TDataSet. However, TDataSet is demonstrated in the sample projects.
Basic |
---|
Basic DBXValue |
---|
Collection |
---|
Connection |
---|
|
|
|
|
|
|
|
|
The following table summarizes differences between TStream and TDBXStreamValue types:
Supports null values |
---|
Declaration |
---|
Accessing Values |
---|
Proxy generator |
---|
Default parameter direction |
---|
Other parameter directions |
---|
function result type |
---|
Get |
---|
Set |
---|
TStream |
---|
No |
in
|
in/out: use var keyword out: use out keyword
|
Yes
|
lhs := AParameter |
AParameter := rhs |
Yes
|
TDBXStreamValue |
---|
Yes
|
in/out
|
None
|
No
|
AParameter.IsNull lhs:=AParameter.GetStream(InstanceOwner) |
AParameter.SetNull AParameter.SetStream(rhs, InstanceOwner) |
No
|
Supports null values
The TDBXStreamValue type has an IsNull property and a SetNull method. Use this type instead of TStream a parameter value can be null/nil, in some cases.
Declaration
The var and out keywords can’t be used to specify the parameter direction of a TDBXStreamValue parameter. The direction is always in/out. A TDBXStreamValue type can’t be used as a function result.
Proxy Generator
The RAD Studio 2007 client proxy generator does not work properly for server methods with TDBXStreamValue parameters. So you will need to hand code the client code or correct the generated proxy. The sample client has hand corrected proxy methods that look like this.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
function TTestStreamValueClient.Echo(var I: TStream): TStream;<br> begin<br> if FEchoCommand = nil then<br> begin<br> FEchoCommand := FDBXConnection.CreateCommand;<br> FEchoCommand.CommandType := TDBXCommandTypes.DSServerMethod;<br> FEchoCommand.Text := 'TTestStreamValue.Echo';<br> FEchoCommand.Prepare;<br> end;<br> if I = nil then<br> FEchoCommand.Parameters[0].Value.SetNull<br> else<br> FEchoCommand.Parameters[0].Value.SetStream(I, FInstanceOwner);<br> FEchoCommand.ExecuteUpdate;<br> if FEchoCommand.Parameters[0].Value.IsNull then<br> I := nil<br> else<br> I := FEchoCommand.Parameters[0].Value.GetStream(FInstanceOwner);<br> Result := FEchoCommand.Parameters[1].Value.GetStream(FInstanceOwner);<br> end; |
This client method works with a server method declared as follows:
1 |
function Echo(I: TDBXStreamValue): TStream; |
Calling a server method with a TDBXStreamValue parameter is the same as calling a server method with an TStream parameter, except that you can use SetNull and IsNull methods to work with null values.
For example, compare the following server method declaration and client method implementation to the previous example:
1 |
function Echo(I: TStream): TStream; |
1 2 3 4 5 6 7 8 9 10 11 12 13 |
function TTestStreamClient.Echo(I: TStream): TStream;<br> begin<br> if FEchoCommand = nil then<br> begin<br> FEchoCommand := FDBXConnection.CreateCommand;<br> FEchoCommand.CommandType := TDBXCommandTypes.DSServerMethod;<br> FEchoCommand.Text := 'TTestStream.Echo';<br> FEchoCommand.Prepare;<br> end;<br> FEchoCommand.Parameters[0].Value.SetStream(I, FInstanceOwner);<br> FEchoCommand.ExecuteUpdate;<br> Result := FEchoCommand.Parameters[1].Value.GetStream(FInstanceOwner);<br> end; |
Accessing Values
The GetStream and SetStream methods have an InstanceOwner parameter. Passing True indicates that DBX owns the stream and will free it. Passing False indicates that the caller owns the stream. To control how the generated proxy classes call SetStream and GetStream, there is an AInstanceOwner parameter on the proxy class constructor:
1 |
constructor TTestStreamClient.Create(ADBXConnection: TDBXConnection; AInstanceOwner: Boolean); |
The other constructor is equivalent to passing AInstanceOwner as True.
1 |
constructor TTestStreamClient.Create(ADBXConnection: TDBXConnection); |
Sample Client And Server Applications
The sample server has a few simple server methods for passing values (including null).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
{$METHODINFO ON}<br> TTestCollection = class(TComponent)<br> strict protected<br> procedure LogMessage(const AMessage: string);<br> public<br> // Server method to get the parameter type names<br> procedure GetTypeNames(I: T; ADeclaredName, AActualName: TDBXStringValue);<br> end;<br> {$METHODINFO OFF}<br> <br> TTestStream = class(TTestCollection)<br> public<br> function Echo(I: TStream): TStream;<br> procedure Copy(I: TStream; out J: TStream);<br> procedure Swap(var I: TStream; var J: TStream);<br> end;<br> <br> TTestStreamValue = class(TTestCollection)<br> public<br> function Echo(I: TDBXStreamValue): TStream;<br> procedure Copy(I: TDBXStreamValue; J: TDBXStreamValue);<br> procedure Swap(I: TDBXStreamValue; J: TDBXStreamValue);<br> function IsNull(I: TDBXStreamValue): Boolean;<br> procedure SetNull(I: TDBXStreamValue);<br> end; |
The sample client tests the server methods by calling them with sample values and verifying the results (e.g; comparing streams). TMemoryStream is used to pass short streams and TFileStream to pass long streams. Here is a screen shot of the running server and client:
The following table shows the parameter types and return types demonstrated in the sample client and server:
Type |
---|
Direction |
---|
(default) |
---|
var |
---|
out |
---|
Result |
---|
TDBXStreamValue |
X (in/out) |
TStream |
X (in) |
X |
X |
X |
Stream Usage
Check “Log Stream Usage” to show TStream sizes, type names, creates, destroys, and reads. The results from 4 different test cases are displayed after “Call Server Methods” is clicked.
The screen shot below shows the result from a test case with longer streams. I’ve added highlighting to illustrate these points:
- When the server reads a longer stream passed from the client, round trips are made to the client. This makes it possible to send very large streams to the server without consuming lots of memory.
- When the client reads a longer stream passed from the server, round trips are made to the server. This makes it possible to return very large streams to the client without consuming lots of memory.
- The TStream objects that represent longer client and server streams have a Size of –1, meaning the size is unknown. Rely on the return value of TStream.Read to detect the end of the stream. Also note that some DBX streams such as TDBXStreamReaderStream do not fully support Seek.
That’s all for now.
Design. Code. Compile. Deploy.
Start Free Trial Upgrade Today
Free Delphi Community Edition Free C++Builder Community Edition