SQL_BLOB_VAL_STOW - SQLbvst

SQL_BLOB_VAL_STOW writes a new BLOB value sequentially to a BLOB. Contrast this with the CLI call SQL_BLOB_VAL_PUT (see "SQL_BLOB_VAL_PUT - SQLbvpu"), which writes the entire BLOB value in one go. The advantage of SQL_BLOB_VAL_STOW over SQL_BLOB_VAL_PUT is the fact that it allows the buffer to be shorter than the new BLOB value as a whole. The new BLOB value will be transferred in small segments.

To write a BLOB value sequentially using SQL_BLOB_VAL_STOW, 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 writing (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_STOW is called. You must also define the buffer in which the new BLOB value segments are located, and the length of this buffer.

After the BLOB value has been written in its entirety by means of repeated SQL_BLOB_VAL_STOW calls, the access handle must be closed using SQL_BLOB_VAL_CLOSE (see "SQL_BLOB_VAL_CLOSE - SQLbvcl"). Only then will the final segment of the new BLOB value be inserted in the BLOB table.

The entire sequence of operations (SQL_BLOB_VAL_OPEN, repeated
SQL_BLOB_VAL_STOW calls, SQL_BLOB_VAL_CLOSE) must be executed within a transaction.

This CLI call requires the INSERT privilege for the BLOB table.

CLI declaration 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

ID assigned to the access handle in SQL_BLOB_VAL_OPEN. This value must not be modified by the caller.

Buffer

Buffer containing the new value.

ValueLength

Length of the value. ValueLength must be a number >= 0.

SQLda

Diagnostics area.