From a676d61b726b11fcb094ef4e353e621798cbd1b5 Mon Sep 17 00:00:00 2001 From: AlexPeshkoff Date: Mon, 10 Dec 2018 17:42:22 +0300 Subject: [PATCH] Improved batch example and interfaces documentation --- doc/Using_OO_API.html | 110 ++++++++++++++++++++++++++----- examples/interfaces/11.batch.cpp | 18 ++++- 2 files changed, 109 insertions(+), 19 deletions(-) diff --git a/doc/Using_OO_API.html b/doc/Using_OO_API.html index e4c50b7a70..6fe868effb 100644 --- a/doc/Using_OO_API.html +++ b/doc/Using_OO_API.html @@ -3,10 +3,10 @@ - + - + @@ -1099,7 +1099,7 @@ alignment = batch->getBlobAlignment(&status);

It’s supposed that all components of blob stream in a batch should be aligned at least at alignment boundary, including size of stream -potions passed to addBlobStream() which should be a multiple of this +portions passed to addBlobStream() which should be a multiple of this alignment. Header contains 3 fields – 8-byte blob ID (must be non-zero), 4-byte total blob size and 4 byte BPB size. Total blob size includes BPB inside, i.e. one will always find next blob in the @@ -1145,6 +1145,17 @@ correct (from batch POV) ID to msg->desc.

Almost all mentioned methods are used in 11.batch.cpp – please use it to see an alive sample of batching in firebird.

+

+
+ +

+

+Two words about access to +batches from ISC API - one can execute prepared ISC statement in +batch mode. Main support for it is present in Util interface, namely +getTransactionByHandle & getStatementByHandle methods, which make +it possible to access appropriate interfaces identical to existing +ISC handles. An example of it is present in 12.batch_isc.cpp.


@@ -2144,14 +2155,36 @@ sub-entries) in firebird configuration file:


-


- -

-

Dtc -interface – distributed transactions coordinator. Used to start -distributed (working with 2 or more attachments) transaction. Unlike -pre-FB3 approach where distributed transaction must be started in -this way from the most beginning FB3's distributed transactions +

+DecFloat16 / DecFloat34 – +interfaces that help to work with DECFLOAT (16 & 34 respectively) +datatypes. They have almost same set of methods with FB_DEC16 +parameter replaced by FB_DEC34 for DecFloat34:

+
    +
  1. +

    void + toBcd(const FB_DEC16* from, int* sign, unsigned char* bcd, int* exp) + – convert decimal float value to BCD.

    +
  2. +

    void + toString(StatusType* status, const FB_DEC16* from, unsigned + bufferLength, char* buffer) – convert decimal float value to + string.

    +
  3. +

    void + fromBcd(int sign, const unsigned char* bcd, int exp, FB_DEC16* to) – + make decimal float value from BCD.

    +
  4. +

    void + fromString(StatusType* status, const char* from, FB_DEC16* to) – + make decimal float value from string.

    +

    +
+

Dtc +interface – distributed transactions coordinator. Used to +start distributed (working with 2 or more attachments) transaction. +Unlike pre-FB3 approach where distributed transaction must be started +in this way from the most beginning FB3's distributed transactions coordinator makes it also possible to join already started transactions into single distributed transaction.

    @@ -3107,18 +3140,60 @@ interface – various helper methods required here or there.

    getClientVersion() – returns integer, containing major version in byte 0 and minor version in byte 1.

  1. -

    IXpbBuilder* +

    IXpbBuilder* getXpbBuilder(StatusType* status, unsigned kind, const unsigned char* buf, unsigned len) – returns XpbBuilder interface. Valid kinds are - enumerated in XpbBuilder.

    + enumerated in XpbBuilder.

  2. -

    unsigned +

    unsigned setOffsets(StatusType* status, IMessageMetadata* metadata, IOffsetsCallback* callback) – sets valid offsets in MessageMetadata. Performs calls to callback in OffsetsCallback for each - field/parameter.

    + field/parameter.

    +
  3. +

    IDecFloat16* + getDecFloat16(StatusType* status) – access DecFloat16 + interface.

    +
  4. +

    IDecFloat34* + getDecFloat34(StatusType* status) – access DecFloat34 + interface.

    +
  5. +

    ITransaction* + getTransactionByHandle(StatusType* status, isc_tr_handle* hndlPtr) – + access Transaction interface by ISC API + hndl.

    +
  6. +

    IStatement* + getStatementByHandle(StatusType* status, isc_stmt_handle* hndlPtr) – + access Statement interface by ISC API hndl.

    +
  7. +

    void + decodeTimeTz(StatusType* status, const ISC_TIME_TZ* timeTz, + unsigned* hours, unsigned* minutes, unsigned* seconds, unsigned*

    +

    fractions, + unsigned timeZoneBufferLength, char* timeZoneBuffer) + – decode time taking time zone into an account.

    +
  8. +

    void + decodeTimeStampTz(StatusType* status, const ISC_TIMESTAMP_TZ* + timeStampTz, unsigned* year, unsigned* month, unsigned* day, + unsigned* hours, unsigned* minutes, unsigned* seconds, unsigned* + fractions, unsigned timeZoneBufferLength, char* timeZoneBuffer) - + decode timestamp taking time zone into an account.

    +
  9. +

    void + encodeTimeTz(StatusType* status, ISC_TIME_TZ* timeTz, unsigned + hours, unsigned minutes, unsigned seconds, unsigned fractions, const + char* timeZone) – encode time taking time zone into an account.

    +
  10. +

    void + encodeTimeStampTz(StatusType* status, ISC_TIMESTAMP_TZ* timeStampTz, + unsigned year, unsigned month, unsigned day, unsigned hours, + unsigned minutes, unsigned seconds, unsigned fractions, const char* + timeZone) – encode timestamp taking time zone into an account.


@@ -3756,9 +3831,8 @@ interface is main interface of database crypt key holder plugin.

interface (if provided by user with Provider::setDbCryptCallback() call). This call is always performed at database attach moment, and some holders may reject attachment if satisfactory key was not - provided. Return value - of 0 means that key holder can not provide a key to crypt plugin, - non-zero – can.

+ provided. Return value of 0 means that key holder can not provide a + key to crypt plugin, non-zero – can.

  • ICryptKeyCallback* keyHandle(StatusType* status, const char* keyName) – is intended diff --git a/examples/interfaces/11.batch.cpp b/examples/interfaces/11.batch.cpp index 47667b463e..741ac5e807 100644 --- a/examples/interfaces/11.batch.cpp +++ b/examples/interfaces/11.batch.cpp @@ -418,6 +418,22 @@ int main() batch->addBlobStream(&status, stream - streamStart, streamStart); + // Continue last blob + stream = streamStart; + ISC_QUAD nullId = {0,0}; + unsigned* size = putBlobHdr(stream, blobAlign, &nullId, 0, NULL); + + const char* d4 = " 444444444444444444444444"; + unsigned ld4 = strlen(d4); + + memcpy(stream, d4, ld4); + *size += ld4; + stream += ld4; + stream = align(stream, blobAlign); + + stream = align(stream, blobAlign); + batch->addBlobStream(&status, stream - streamStart, streamStart); + // Put segmented Blob in the stream // add message @@ -435,7 +451,7 @@ int main() // make stream stream = streamStart; - unsigned* size = putBlobHdr(stream, blobAlign, &vSeg, pb->getBufferLength(&status), pb->getBuffer(&status)); + size = putBlobHdr(stream, blobAlign, &vSeg, pb->getBufferLength(&status), pb->getBuffer(&status)); *size += putSegment(stream, d1); *size += putSegment(stream, "\n"); *size += putSegment(stream, d2);