SQL_BLOB_VAL_FETCH reads the individual segments of a BLOB value sequentially. Contrast this with the CLI call SQL_BLOB_VAL_GET (see "SQL_BLOB_VAL_GET - SQLbvge"), which reads the entire BLOB value in one go. The advantage of SQL_BLOB_VAL_FETCH over SQL_BLOB_VAL_GET is the fact that it allows the output buffer to be shorter than the BLOB value itself.
To read a BLOB value sequentially using SQL_BLOB_VAL_FETCH, you will need an access handle. This is created using the SQL_BLOB_VAL_OPEN call. With the ForWriteAccess parameter of this call you define that you require this access handle for reading (see "SQL_BLOB_VAL_OPEN - SQLbvop"f). Following the SQL_BLOB_VAL_OPEN call, SESAM/SQL returns a unique ID for the access handle.
This ID must be specified each time SQL_BLOB_VAL_FETCH is called. You must also define a buffer into which the BLOB value segments are to be written, and the length of this buffer.
The first time SQL_BLOB_VAL_FETCH is called within an access handle, the buffer is filled with the first segment of the BLOB value. The next time the call is issued with the same access handle, the buffer is filled with the next segment of the BLOB value, and so on. Once the entire BLOB value has been read, a message (SQLSTATE 02000) to this effect is output.
After the BLOB value has been read in its entirety, it will no longer be possible to call SQL_BLOB_VAL_FETCH with this access handle. The access handle must be closed using SQL_BLOB_VAL_CLOSE (see "SQL_BLOB_VAL_CLOSE - SQLbvcl").
The entire sequence of operations (SQL_BLOB_VAL_OPEN, repeated SQL_BLOB_VAL_FETCH calls, SQL_BLOB_VAL_CLOSE) must be executed within a transaction.
This CLI call does not require any privileges.
CLI declaration in C:
void SQL_BLOB_VAL_FETCH( char *AccessHandle
,char *Buffer
,long int const *BufferLength
,long int *ValueLength
,struct SQLda_t * SQLda);
CLI-Deklaration in Cobol:
IDENTIFICATION DIVISION.
PROGRAM-ID. SQLbvfe IS PROTOTYPE.
DATA DIVISION.
LINKAGE SECTION.
01 AccessHandle PIC X(32).
01 Buffer. *> of any length
02 PIC X(1).
01 BufferLength PIC S9(9) COMP.
01 ValueLength PIC S9(9) COMP.
COPY SQLCA. *> for group item SQLda.
PROCEDURE DIVISION USING AccessHandle, Buffer, BufferLength, ValueLength,
SQLda.
END PROGRAM SQLbvfe.
AccessHandle
ID assigned to the access handle in SQL_BLOB_VAL_OPEN. This value must not be modified by the caller.
Buffer
Buffer to which the BLOB value segment is to be written.
BufferLength
Length of the buffer in bytes. BufferLength must be a number >= 0.
ValueLength
Length of the BLOB value segment written to the buffer. If this is less than the value specified in BufferLength, this indicates that the BLOB value has been read in its entirety.
SQLda
Diagnostics area.