Mit SQL_BLOB_VAL_STOW wird ein neuer BLOB-Wert sequenziell in ein BLOB-Objekt geschrieben. Im Gegensatz dazu wird bei dem CLI-Aufruf SQL_BLOB_VAL_PUT (siehe "SQL_BLOB_VAL_PUT - SQLbvpu") der gesamte Wert in einem Stück geschrieben. SQL_BLOB_VAL_STOW besitzt daher gegenüber SQL_BLOB_VAL_PUT den Vorteil, dass der Puffer nicht die Größe des gesamten neuen BLOB-Werts haben muss. Der neue BLOB-Wert kann in kleinen Teilstücken übergeben werden.
Um einen BLOB-Wert mit SQL_BLOB_VAL_STOW sequenziell zu schreiben, benötigen Sie ein Access-Handle zum Schreiben. 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 Schreiben 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_STOW angeben. Zusätzlich übergeben Sie noch den Puffer, in dem das neue Stück des BLOB-Werts steht, und die Länge dieses Puffers.
Nachdem durch mehrmaliges Aufrufen von SQL_BLOB_VAL_STOW alle Stücke des BLOB-Werts geschrieben wurden, muss das verwendete Access-Handle mit SQL_BLOB_VAL_CLOSE geschlossen werden (siehe "SQL_BLOB_VAL_CLOSE - SQLbvcl"). Erst dabei wird das letzte Stück des neuen BLOB-Werts in die BLOB-Tabelle eingefügt.
Die gesamte Folge von Operationen (SQL_BLOB_VAL_OPEN, wiederholtes SQL_BLOB_VAL_STOW und SQL_BLOB_VAL_CLOSE) muss innerhalb einer Transaktion stattfinden.
Dieser CLI-Aufruf erfordert das INSERT-Privileg für die BLOB-Tabelle.
CLI-Deklaration in C:
void SQL_BLOB_VAL_STOW( char *AccessHandle
,char *Buffer
,long int const *ValueLength
,struct SQLda_t *SQLda);
CLI-Deklaration in Cobol:
IDENTIFICATION DIVISION.
PROGRAM-ID. SQLbvst IS PROTOTYPE.
DATA DIVISION.
LINKAGE SECTION.
01 AccessHandle PIC X(32).
01 Buffer. *> of any length
02 PIC X(1).
01 ValueLength PIC S9(9) COMP.
COPY SQLCA. *> for group item SQLda.
PROCEDURE DIVISION USING AccessHandle, Buffer, ValueLength, SQLda.
END PROGRAM SQLbvst.
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, der den neuen Wert enthält.
ValueLength
Länge des Werts. ValueLength muss eine Zahl >= 0 sein.
SQLda
Diagnosebereich.