fb API question

[Andrew Zenz]

Hi everyone.

 

I’m attempting to develop an FB API for Clarion, our dev language, and I am having a bit of trouble.  Not sure if it’s me not understanding the doco or something.

 

Using isc_vax_integer as an example, on reading the old API doco it reverses the order of the bytes.

 

So passing the function (the address of the variable containing) the value 3, and 1 (a single byte), I would expect 192 to be returned.

 

Do I have that right?

 

If I do, in what circumstances would it return the original value, ie 3?  An invalid pointer, an invalid length? 

 

All I seem to get is the value of Buffer returned.

 

I could provide code samples but I don’t expect anyone here plays with Clarion.

 

Andrew Zenz

 

 

 

[Dimitry Sibiryakov]

07.01.2021 07:30, Andrew Zenz wrote:
> Using isc_vax_integer as an example, on reading the old API doco it reverses the order of
> the bytes.

No. It transform bytes from buffer into integer, that's all. Whether order of bytes is
reversed or not depends on your platform.

--
WBR, SD.

[Mark Rotteveel]

Unfortunately, the old documentation (InterBase 6.0 API Guide), page
391/392 does explicitly say that it reverses the byte order. So, what is
the truth?

Mark
--
Mark Rotteveel

[Dimitry Sibiryakov]

07.01.2021 12:45, Mark Rotteveel wrote:
> Unfortunately, the old documentation (InterBase 6.0 API Guide), page 391/392 does
> explicitly say that it reverses the byte order. So, what is the truth?

"The truth is out there."

SLONG API_ROUTINE gds__vax_integer(const UCHAR* ptr, SSHORT length)
{
/**************************************
*
* g d s _ $ v a x _ i n t e g e r
*
**************************************
*
* Functional description
* Pick up (and convert) a VAX style integer of variable length.
*
**************************************/
if (!ptr || length <= 0 || length > 4)
return 0;

SLONG value = 0;
int shift = 0;

while (--length > 0)
{
value += ((SLONG) *ptr++) << shift;
shift += 8;
}

value += ((SLONG)(SCHAR) *ptr) << shift;

return value;
}

BTW, isc_vax_integer is deprecated, isc_portable_integer should be used instead.

--
WBR, SD.

[Andrew Zenz]

Is there a more recent API guide than the Interbase 6 API guide on the FirebirdSQL site?

It has no mention of isc_portable_integer.

Cheers,

Andrew

--
You received this message because you are subscribed to the Google Groups "firebird-support" group.
To unsubscribe from this group and stop receiving emails from it, send an email to firebird-suppo...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/firebird-support/48021be2-c2e0-b62a-620d-5f382be425ad%40ibphoenix.com.

[Dimitry Sibiryakov]

07.01.2021 13:07, Andrew Zenz wrote:
> Is there a more recent API guide than the Interbase 6 API guide on the FirebirdSQL site?

You can get one from any newer Interbase version and fill the gaps with pieces from
Firebird doc folder.

--
WBR, SD.

[Scott Morgan]

Whilst we're on the subject; What's the status of interface.h vs firebird.h?

Which one should a C or C++ dev use for apps?

Scott

[Dimitry Sibiryakov]

07.01.2021 13:47, 'Scott Morgan' via firebird-support wrote:
> Whilst we're on the subject; What's the status of interface.h vs firebird.h?

There is no firebird.h among public headers.

--
WBR, SD.

[Scott Morgan]

Sorry, meant ibase.h

[Dimitry Sibiryakov]

You include "firebird/interface.h" when using OO API and "ibase.h" when using ISC API.
If for some reasons you use both, include both.

--
WBR, SD.

[Scott Morgan]

So, there's no functional difference between the two, and they're both
going to be supported for the foreseeable future?

[Dimitry Sibiryakov]

07.01.2021 16:42, 'Scott Morgan' via firebird-support wrote:
>>   You include "firebird/interface.h" when using OO API and "ibase.h"
>> when using ISC API.
>>   If for some reasons you use both, include both.
>>
> So, there's no functional difference between the two, and they're both
> going to be supported for the foreseeable future?

They describe different APIs. Isn't it a difference?

Though ISC API is declared "legacy" I don't think it is going to be withdrawn.

--
WBR, SD.

[Scott Morgan]

It was just my understanding that one of the reasons for introducing
interface.h was because of limits on the old ISC API[0], which suggests
issues with continuing, or starting, to use ibase.h.

What is the official recommendation?


[0]
https://firebirdsql.org/file/documentation/release_notes/html/en/3_0/rlsnotes30.html#rnfb30-apiods-api-oo

[Dimitry Sibiryakov]

07.01.2021 17:34, 'Scott Morgan' via firebird-support wrote:
> It was just my understanding that one of the reasons for introducing
> interface.h was because of limits on the old ISC API[0], which suggests
> issues with continuing, or starting, to use ibase.h.

That time we were much younger and optimistic.
This new API was aimed to be used in all kind of plugins and other internal stuff in
the first place. Using it for end-user applications as well seemed to be a logical step
but it turned out to be quite inconvenient.
I personally really hate this new API.

> What is the official recommendation?

You must wait for some officials for them.

--
WBR, SD.

[Scott Morgan]

On 07/01/2021 16:44, Dimitry Sibiryakov wrote:
>   That time we were much younger and optimistic.
>   This new API was aimed to be used in all kind of plugins and other
> internal stuff in the first place. Using it for end-user applications as
> well seemed to be a logical step but it turned out to be quite
> inconvenient.
>   I personally really hate this new API.

Can't say I like either of them.

>> What is the official recommendation?
>
>   You must wait for some officials for them.
>

I'll pester fb-dev

[Mark Rotteveel]

That is I think the wrong attitude. If someone thinks documentation is
missing or lacking, they should consider volunteering to
write/contribute to documentation.

This is an open-source project after all, and contributions are welcome.

Mark
--
Mark Rotteveel

[Andrew Zenz]

Dimitry,

I am working my way, slowly, through the Embarcadero InterBase 2020, Update 1, Api Guide and on page 18 at the end of section 1.2. Creating and Populating a DPB is an important notification (and though I haven't looked further I expect it to be mentioned in more locations):


All numbers in the database parameter buffer must be represented in a generic format, with the least significant byte
first, and the most significant byte last. Signed numbers should have the sign in the last byte. The API function isc_
portable_integer() can be used to reverse the byte order of a number. For more information, see Isc portable integer().


Which part of the above notification is correct?

Do numbers have to be presented in a generic format with the least significant byte first?

If so, your assertion and code example that isc_portable_integer does not reverse the byte order is in contradiction to this most important message.

Is the documentation wrong?

What function, if any, does reverse the byte order?


I have been following this group for some time and have read many of your brief posts, and I understand your belief that 'if you teach a man to fish ...', but sometimes that requires a little more than a 'No, that's not the way'.

I'm not interested in a flame war, I'm not necessarily interested in the exact answer (what would I learn from that), I just want some clarification to figure out what is right (or wrong) with conflicting information and/or my understanding of the doco.

Cheers,

Andrew


-----Original Message-----
From: firebird...@googlegroups.com [mailto:firebird...@googlegroups.com] On Behalf Of Dimitry Sibiryakov
Sent: Thursday, 7 January 2021 10:50 PM
To: firebird...@googlegroups.com
Subject: Re: [firebird-support] fb API question

[Mark Rotteveel]

On 11-01-2021 05:45, Andrew Zenz wrote:
> Dimitry,
>
> I am working my way, slowly, through the Embarcadero InterBase 2020, Update 1, Api Guide and on page 18 at the end of section 1.2. Creating and Populating a DPB is an important notification (and though I haven't looked further I expect it to be mentioned in more locations):
>
>
> All numbers in the database parameter buffer must be represented in a generic format, with the least significant byte
> first, and the most significant byte last. Signed numbers should have the sign in the last byte. The API function isc_
> portable_integer() can be used to reverse the byte order of a number. For more information, see Isc portable integer().
>
>
> Which part of the above notification is correct?

Please keep in mind that documentation for InterBase 2020 is not
documentation for Firebird, Firebird was forked from InterBase 6 20
years ago, and although there is a common ancestry, documentation for
InterBase does not necessarily apply for Firebird.
Mark

--
Mark Rotteveel

[Dimitry Sibiryakov]

11.01.2021 05:45, Andrew Zenz wrote:
> I am working my way, slowly, through the Embarcadero InterBase 2020, Update 1, Api Guide and on page 18 at the end of section 1.2. Creating and Populating a DPB is an important notification (and though I haven't looked further I expect it to be mentioned in more locations):
>
>
> All numbers in the database parameter buffer must be represented in a generic format, with the least significant byte
> first, and the most significant byte last. Signed numbers should have the sign in the last byte. The API function isc_
> portable_integer() can be used to reverse the byte order of a number. For more information, see Isc portable integer().
>
>
> Which part of the above notification is correct?

Every part is correct, but together they are wrong.
isc_portable_integer() should not be used for creating and populating parameters
blocks. Its purpose is gathering integers from server responses of isc_XXX_info() functions.

My messages are short to be clear because my English is bad.

--
WBR, SD.

[Andrew Zenz]

Mark, I appreciate that Firebird and Interbase diverged some time ago but in the absence of documentation, a la an API Guide specific to Firebird, what alternative is there?

Masses of frustration.

I would also expect that once forked, there were no wholesale changes to the Firebird API - why make extra work and there is already a document in place.

I know very little (nothing) of C/C++ and am still toeing the water with Firebird so am unable to help.

I suppose that's what this group is for.

Cheers,

Andrew


-----Original Message-----
From: firebird...@googlegroups.com [mailto:firebird...@googlegroups.com] On Behalf Of Mark Rotteveel
Sent: Tuesday, 12 January 2021 12:57 AM
To: firebird...@googlegroups.com
Subject: Re: [firebird-support] fb API question

--
You received this message because you are subscribed to the Google Groups "firebird-support" group.
To unsubscribe from this group and stop receiving emails from it, send an email to firebird-suppo...@googlegroups.com.

To view this discussion on the web, visit https://groups.google.com/d/msgid/firebird-support/d65402b3-4153-65d2-c6a0-e8a5d4525b0f%40lawinegevaar.nl.

[Vlad Khorsun]

On Thursday, 7 January 2021 at 13:28:52 UTC+2 Andrew Zenz wrote:

Hi everyone.

 

I’m attempting to develop an FB API for Clarion, our dev language, and I am having a bit of trouble.  Not sure if it’s me not understanding the doco or something.

Using isc_vax_integer as an example, on reading the old API doco it reverses the order of the bytes.

So passing the function (the address of the variable containing) the value 3, and 1 (a single byte), I would expect 192 to be returned.

Do I have that right?

  Why do you expect to get 192 ?

If I do, in what circumstances would it return the original value, ie 3?  An invalid pointer, an invalid length? 

  isc_vax_integer reverts order of one byte (as you instruct it, passing 1 as second parameter). One byte have exactly

the same value after such a reverse :) Probably you expect that it reverse *bits* order as well ?

 

Hope it helps,

Vlad