Mit SQL_BLOB_VAL_FETCH wird ein BLOB-Wert sequenziell gelesen. Im Gegensatz dazu wird bei dem CLI-Aufruf SQL_BLOB_VAL_GET (siehe "SQL_BLOB_VAL_GET - SQLbvge") der gesamte Wert in einem Stück gelesen. SQL_BLOB_VAL_FETCH besitzt daher gegenüber SQL_BLOB_VAL_GET den Vorteil, dass die Größe des Puffers, in den ausgelesen wird, kleiner sein kann als der BLOB-Wert.
Um einen BLOB-Wert mit SQL_BLOB_VAL_FETCH sequenziell zu lesen, benötigen Sie ein Access-Handle zum Lesen. Dieses Access-Handle erzeugen Sie mit SQL_BLOB_VAL_OPEN. Dabei legen Sie mit dem Parameter ForWriteAccess dieses Aufrufs fest, dass Sie dieses Access-Handle zum Lesen benötigen (siehe "SQL_BLOB_VAL_OPEN - SQLbvop"f).
SESAM/SQL liefert nach dem Aufruf von SQL_BLOB_VAL_OPEN eine eindeutige Identifikation für das Access-Handle zurück.
Diese Identifikation müssen Sie bei jedem Aufruf von SQL_BLOB_VAL_FETCH angeben. Zusätzlich übergeben Sie noch den Puffer, in den das gelesene Stück übertragen werden soll, und die Länge dieses Puffers.
Beim ersten Aufruf von SQL_BLOB_VAL_FETCH innerhalb eines Access-Handles wird der Puffer mit dem ersten Teil des BLOB-Werts gefüllt. Beim nächsten Aufruf mit demselben Access-Handle wird der Puffer mit dem nächsten Teil des BLOB-Werts gefüllt, usw.. Wurde der gesamte BLOB-Wert gelesen, wird dies mit einer Meldung (SQLSTATE 02000) angezeigt.
Nach dem vollständigen Lesen des BLOB-Werts ist es nicht mehr möglich, mit dem verwendeten Access-Handle SQL_BLOB_VAL_FETCH aufzurufen. Das Access-Handle muss mit SQL_BLOB_VAL_CLOSE geschlossen werden (siehe "SQL_BLOB_VAL_CLOSE - SQLbvcl").
Die gesamte Folge von Operationen (SQL_BLOB_VAL_OPEN, wiederholtes SQL_BLOB_VAL_FETCH und SQL_BLOB_VAL_CLOSE) muss innerhalb einer Transaktion stattfinden.
Dieser CLI-Aufruf erfordert keine Privilegien.
CLI-Deklaration 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
Der bei SQL_BLOB_VAL_OPEN gelieferte Wert für das Access-Handle muss hier eingegeben werden. Dieser Wert darf vom Aufrufer nicht modifiziert werden.
Buffer
Puffer, in den der Wert übertragen werden soll.
BufferLength
Größe des Puffers in Byte. BufferLength muss eine Zahl >= 0 sein.
ValueLength
Größe des in den Puffer geschriebenen Teils des BLOB-Werts. Ist der Wert von ValueLength kleiner als der Wert von BufferLength, so ist der BLOB-Wert komplett gelesen worden.
SQLda
Diagnosebereich.