Wire Protocol | Blobs

Seek

Seek is only supported for blobs that were created as a stream blob.Seek is not fully supported for blobs longer than 2 GiB (4 GiB?).

Client

Int32 — p_operation

Operation code (op_seek_blob — 61)

Int32 — p_seek_blob

Blob handle

Int32 — p_seek_mode

Seek mode

`blb_seek_from_head` — `0`	absolute seek from start of blob
`blb_seek_relative` — `1`	relative seek from current position
`blb_seek_from_tail` — `2`	absolute seek from end of blob

Int32 — p_seek_offset

Offset

Server

[wireprotocol-responses-generic] — on success, p_resp_object is the current position.

Deviations for protocol version 11

Request flushing and response processing can be deferred.

If ptype_batch_send or higher is used, op_seek_blob can be batched with [wireprotocol-blobs-create] (and other blob operations) by using the invalid object handle (0xFFFF).

Cancel

Cancels and invalidates the blob handle.If this was a newly created blob, the blob is disposed.

Client

Int32 — p_operation: Operation code (op_cancel_blob — 38)
Int32 — p_rlse_object: Blob handle

Server

[wireprotocol-responses-generic]

Deviations for protocol version 11

Request flushing and response processing can be deferred.

If ptype_batch_send or higher is used, op_cancel_blob can be batched with [wireprotocol-blobs-create] (and other blob operations) by using the invalid object handle (0xFFFF).Though doing this probably makes little sense for op_cancel_blob.

Close

Closes and invalidates the blob handle.

Client

Int32 — p_operation: Operation code (op_close_blob — 39)
Int32 — p_rlse_object: Blob handle

Server

[wireprotocol-responses-generic]

Deviations for protocol version 11

Request flushing and response processing can be deferred.

If ptype_batch_send or higher is used, op_close_blob can be batched with [wireprotocol-blobs-create] (and other blob operations) by using the invalid object handle (0xFFFF).

Arrays

Get slice

Client

Int32 — p_operation: Operation code (op_get_slice — 58)
Int32 — p_slc_transaction: Transaction handle
Int64 — p_slc_id: Array handle
Int32 — p_slc_length: Slice length
Buffer — p_slc_sdl: Slice descriptor (SDL)
Buffer — p_slc_parameters: Slice parameters (always empty?, needs verification)
Buffer — p_slc_slice: Slice data (always empty)

Server

Success response: [wireprotocol-responses-slice]

Failure response: [wireprotocol-responses-generic]

Put slice

Client

Int32 — p_operation: Operation code (op_put_slice — 59)
Int32 — p_slc_transaction: transaction handle
Int64 — p_slc_id: Array handle
Int32 — p_slc_length: Slice length
Buffer — p_slc_sdl: Slice descriptor (SDL)
Buffer — p_slc_parameters: Slice parameters (always empty?, needs verification)
Buffer` — p_slc_slice: Slice data

Server

[wireprotocol-responses-generic] — on success, p_resp_blob_id is the array handle.

Batches

Statement batches were introduced in protocol 16 (Firebird 4.0).

Create

Client

Int32 — p_operation: Operation code (op_batch_create — 99)
Int32 — p_batch_statement: Statement handle
Buffer — p_batch_blr: BLR format of batch messages
UInt32 — p_batch_msglen: Message length
Buffer — p_batch_pb: Batch parameters buffer

If ptype_lazy or higher, flushing and response processing can be deferred.

Server

[wireprotocol-responses-generic]

Send messages

Client

Int32 — p_operation: Operation code (op_batch_msg — 100)
Int32 — p_batch_statement: Statement handle
UInt32 — p_batch_messages: Number of messages
Buffer — p_batch_data: Batched values (formatted message repeats 'Number of messages' times)

Server

[wireprotocol-responses-generic]

Execute batch

Client

Int32 — p_operation: Operation code (op_batch_exec — 101)
Int32 — p_batch_statement: Statement handle
Int32 — p_batch_transaction: Transaction handle

Server

Success response:

Int32 — p_operation: Operation code

If operation equals op_batch_cs — 103`:

Batch completion state

Int32 — p_batch_statement: Statement handle
UInt32 — p_batch_reccount: Total records count
UInt32 — p_batch_updates: Number of update counters (records updated per each message)
UInt32 — p_batch_vectors: Number of per-message error blocks (message number in batch and status vector of an error processing it)
UInt32 — p_batch_errors: Number of simplified per-message error blocks (message number in batch without status vector)
Byte[]: Update counters (records updated per each message), array of Int32, length is equal to p_batch_updates

Length is p_batch_updates * 4 bytes long.
Byte[]: Detailed info about errors in batch (for each error server sends number of message (Int32) and status vector in standard way (exactly like in op_response).Number of such pairs is equal to p_batch_vectors.

Length can only be determined by correctly parsing the <Int32><statusvector> pairs.
Byte[]: Simplified error blocks (for each error server sends number of message (Int32) w/o status vector).Used when too many errors took place.Number of elements is equal to p_batch_errors.

Length is p_batch_errors * 4 bytes.

Failure response: [wireprotocol-responses-generic]

Release batch

Client

Int32 — p_operation: Operation code (op_batch_rls — 102)
Int32 — p_batch_statement: Statement handle

Server

[wireprotocol-responses-generic]

Cancel batch

Client

Int32 — p_operation: Operation code (op_batch_cancel — 109)
Int32 — p_batch_statement: Statement handle

Server

[wireprotocol-responses-generic]

Sync batch

Introduced in protocol 17 (Firebird 4.0.1).

Used to force the server to acknowledge previously sent lazy intermediate operations (e.g. op_batch_msg, op_batch_regblob, op_batch_blob_stream and possibly others).

Client

Int32 — p_operation: Operation code (op_batch_sync — 110)

Server

[wireprotocol-responses-generic]

Set default blob parameters

Client

Int32 — p_operation: Operation code (op_batch_set_bpb — 106)
Int32 — p_batch_statement: Statement handle
Buffer — p_batch_blob_bpb: Default BLOB parameter buffer

Server

[wireprotocol-responses-generic]

Register existing blob

Client

Int32 — p_operation: Operation code (op_batch_regblob — 104)
Int32 — p_batch_statement: Statement handle
Int64 — p_batch_exist_id: Existing BLOB ID
Int64 — p_batch_blob_id: Batch temporary BLOB ID

Server

[wireprotocol-responses-generic]

Stream of BLOB data

Caution

This description needs further verification and possibly correction.For example, it seems to mix up Buffer and Byte[].We’re also not able to match some fields to the implementation.For example, the repeated "Record length" seems to be absent, or may actually refer to the p_batch_blob_data buffer length.

Client

Int32 — p_operation

Operation code (op_batch_blob_stream)

Int32 — p_batch_statement

Statement handle

Buffer[] — p_batch_blob_data

BLOB stream

This stream is a sequence of blob records.Each blob records contains:

UInt32: Record length

The following three fields are called BLOB header
Int64: Batch temporary BLOB ID
UInt32: BLOB size
UInt32: BLOB parameters buffer size
Buffer: BLOB parameters buffer
Buffer: BLOB data (length - BLOB size bytes) (what does this mean?)

BLOB headers and records in a stream need not match, i.e. one record may contain many BLOBs and BLOB may stretch from one record to next.

Server

[wireprotocol-responses-generic]

Batch information request

Uses the [wireprotocol-requests-info] message with:

`p_operation`	`op_info_batch` — `111`
`p_info_object`	Statement handle
`p_info_items`	Values of `INF_` constants of `IBatch` (in `IdlFbInterfaces.h`)

Services

Attach

Attach to a service.Use message [wireprotocol-connect-attach] with op_service_attach — 82.

Note on `p_atch_file`:

Current Firebird versions only support one service: service_mgr.Since Firebird 3.0, this can also be an empty string (empty buffer) with the same meaning.

Detach

Send [wireprotocol-connect-detach] with op_service_detach — 83, followed by [wireprotocol-connect-disconnect].

Start

Although the message looks similar to [wireprotocol-requests-info], it has different semantics.

Client

Int32 — p_operation: Operation code (op_service_start — 85)
Int32 — p_info_object: Unused, always use 0
Int32 — p_info_incarnation: Incarnation of object (0)

TODO: Usage and meaning?
Buffer — p_info_items: Service parameter buffer

Server

[wireprotocol-responses-generic]

Query service

Although the message looks similar to [wireprotocol-requests-info], it has different semantics.

Client

Int32 — p_operation: Operation code (op_service_info — 84)
Int32 — p_info_object: Unused, always use 0
Int32 — p_info_incarnation: Incarnation of object (0)

TODO: Usage and meaning?
Buffer — p_info_items: Service parameter buffer
Buffer — p_info_recv_items: Requested information items
Int32 — p_info_buffer_length: Requested information items buffer length

Server

[wireprotocol-responses-generic] — on success, p_resp_data contains the requested information.

Seek

Seek

Client

Server

Deviations for protocol version 11

Cancel

Client

Server

Deviations for protocol version 11

Close

Client

Server

Deviations for protocol version 11

Arrays

Get slice

Client

Server

Put slice

Client

Server

Batches

Create

Client

Server

Send messages

Client

Server

Execute batch

Client

Server

Release batch

Client

Server

Cancel batch

Client

Server

Sync batch

Client

Server

Set default blob parameters

Client

Server

Register existing blob

Client

Server

Stream of BLOB data

Client

Server

Batch information request

Services

Attach

Note on p_atch_file:

Detach

Start

Client

Server

Query service

Client

Server

Note on `p_atch_file`: