SQL_BLOB_VAL_OPEN opens an access handle. Access handles are used in the sequential processing of BLOB values. In SESAM/SQL you can read BLOB values sequentially with SQL_BLOB_VAL_FETCH (see "SQL_BLOB_VAL_FETCH - SQLbvfe") and write them sequentially with SQL_BLOB_VAL_STOW (see "SQL_BLOB_VAL_STOW - SQLbvst").
Once you have finished processing BLOB values sequentially using an access handle, you must close the access handle by calling SQL_BLOB_VAL_CLOSE (see "SQL_BLOB_VAL_CLOSE - SQLbvcl"). An access handle must be opened and closed within the same transaction.
By repeating the CLI calls SQL_BLOB_VAL_FETCH and SQL_BLOB_VAL_STOW, you can read or write BLOB values sequentially. To ensure that this is carried out correctly, you will require an access handle which manages the following information internally:
the BLOB value to be addressed
the progress of the read or write operation (which segment is to be read or written next)
The input parameters include the REF value of the BLOB, the database name and the ForWriteAccess parameter.
With ForWriteAccess you define whether the access handle is to be used for reading or writing purposes.
Each access handle is assigned a unique ID by SESAM/SQL, which must be specified each time SQL_BLOB_VAL_FETCH or SQL_BLOB_VAL_STOW is called.
It is possible to have up to 10 access handles open at any one time, i.e. to have up to 10 sequential processes involving BLOBs running in parallel. If you attempt to initiate an 11th sequential process, this will be rejected with a corresponding message.
If you fail to issue an SQL_BLOB_VAL_CLOSE call once sequential processing is complete, the access handle remains reserved. This makes it impossible to optimize the utilization of the 10 possible access handles.
If you open an access handle for writing purposes and the BLOB to be processed already has a BLOB value, the old BLOB value will be deleted by the SQL_BLOB_VAL_OPEN call, i.e. it will have the length 0. The BLOB itself will be retained.
You should avoid subjecting a particular BLOB to several parallel writing sequences, since these may have conflicting effects on the BLOB value.
If the SQL_BLOB_VAL_OPEN call is issued for reading purposes, you will require the SELECT privilege for the BLOB table. If it is issued for writing purposes, you will require the SELECT and DELETE privileges for the BLOB table, as well as the UPDATE privilege for the slice_val column of the BLOB table.
CLI-Deklaration in C:
void SQL_BLOB_VAL_OPEN( char const *REFvalue
,char const *CatalogId
,long int *ForWriteAccess
,char *AccessHandle
,struct SQLda_t *SQLda);
CLI declaration in COBOL:
IDENTIFICATION DIVISION.
PROGRAM-ID. SQLbvop IS PROTOTYPE.
DATA DIVISION.
LINKAGE SECTION.
01 REFvalue PIC X(237).
01 CatalogId PIC X(31).
01 ForWriteAccess PIC S9(9) COMP.
01 AccessHandle PIC X(32).
COPY SQLCA. *> for group item SQLda.
PROCEDURE DIVISION USING REFvalue, CatalogId, ForWriteAccess, AccessHandle,
SQLda.
END PROGRAM SQLbvop.
REFvalue
The REF value of the BLOB. The exact structure of REF values is described on "Column definitions".
CatalogId
Unqualified name of the database in which the table is located. CatalogId is an unqualified name (see section "Unqualified names"). If necessary, this name must be padded with blanks up to a length of 31 characters or terminated with a null byte. If you wish to use the default database name, simply enter a null byte or a string of blanks instead of the database name.
ForWriteAccess
This can be set to the value 1 (=TRUE) or 0 (=FALSE). The values have the following meaning:
0: | The access handle is intended for reading purposes (with SQL_BLOB_VAL_FETCH). |
1: | The access handle is intended for writing purposes (with SQL_BLOB_VAL_STOW). |
AccessHandle
ID of the access handle. This value must not be modified, as it will be used in all subsequent operations up to the concluding SQL_BLOB_VAL_CLOSE call.
SQLda
Diagnostics area.