Subject Re: [Firebird-Architect] Re: XSQLDA/XSQLVAR issues
Author Jim Starkey
Roman Rokytskyy wrote:

>> 1. Message oriented. All data is transmitted as a self described
>> byte stream.
>Can you elaborate? Do you mean something like SOAP? Then I am against it.
Sure. A message would start with a version number and field field
count. Each field would start with a type byte, followed, as
appropriate, by a scale or length, then the data itself. We would
probably want a text field that also specified characterset and
encoding. The byte order for numerics would be consistent. There are a
bunch of details to to haggle about, but that is the big picture. When
all is said and done, the message length is sent, a message is the
address and length of block describing a fixed length, ordered,
collection of values.

Right now, the transmission format of data is declared by the receiver
by a blr string describing a fixed length block of memory. It is the
senders responsibility to coerce data into the fixed block. The order
of battle for a DSQL fetch goes something like this:

1. isc_dsql_fetch analyses the XSQLDA, generating a blr_message
string corresponding to the types and length in the XSQLDA and
allocating a fixed length buffer to the hold the data it expects
to receive. isc_dsql_fetch then calls isc_dsql_fetch_m, which
sends the address and length of the blr string and the address and
length of the message buffer on its way.
2. DSQL decodes the blr_message string and allocates another fixed
length message buffer. The it calls isc_receives with the length
and address of its fixed length buffer.
3. isc_receive executes a bunch of blr statements, some of which
copies or converts engine data to the fixed message buffer.
4. isc_receive return to DSQL which copies or converts data field by
field from the fixed format isc_receive buffer to the buffer
allocated in step 2.
5. DSQL returns to isc_dsql_fetch which copies or converts from the
fixed format buffer to the XSQLDA.

The way I'd like to do is:

1. isc_dsql_fetch calls SQL to get a record.
2. Internal SQL calls the moral equivalent of isc_receive, which
executes a bunch of blr statements, some of which assign to a
DataMessage object.
3. isc_receive returns the DataMessage object to internal SQL, which
returns it to isc_dsql_fetch.
4. isc_dsql_fetch copies or converts from the DataMessage object to
the fields described in the XSQLDA.

Almost all data handling is internal to DataMessage. Assignments
preserve their type. If asked politely, DataMessage serializes the data
into a byte stream which, on the other side of the wire, it parses.
Data is maintained in the type/length plucked from an RHD until the
client asks for it by type either through an XSQLDA or a JDBC getXYZ call.

There is no need to the tranmission layers to worry about data. To
them, it's abstract stuff. Squirt, squirt, they're done.

>>I think we have to keep the wire protocol in mind. The API should be
>>designed to minimize number of messages needed to be send over the
>>wire, so people can code the application with almost no overhead on
>>the calls.
Duh! Why didn't I think of that! (please note the heavy use of sarcasm

>Each call should take some kind of payload that describes the expected
>output. For example, if people need to get the number of inserted
>records, something analogous to isc_dsql_execute2 takes something
>analogous to info flags and the response in addition to the statement
>output also returns info information.
For something like an execute call, the client should provide a
structure describing what he wants to hear about, described as an info
request, and get back an info packet containing the data. In our brave
new world, we pass and receive objects, not address and lengths of
buffers, which eliminates the possibility of buffer otherflow and other

But Roman, please, no flags. APIs are like international politics --
the fewer flags the better.


Jim Starkey
Netfrastructure, Inc.
978 526-1376

[Non-text portions of this message have been removed]