Represents one transaction in the underlying database server.
class DBITransaction
| close() | Close the current transaction handle. |
| createBlob() | Creates a new blob entity. |
| openBlob() | Opens an existing blob entity. |
| readBlob() | Reads a whole blob entity. |
| writeBlob() | Overwrites an existing blob entity. |
Represents one transaction in the underlying database server.
You will not instantiate this class directly, instead, you must use the startTransaction method of your DBIHandle.
Close the current transaction handle.
DBITransaction.close( )
Creates a new blob entity.
DBITransaction.createBlob( [data], [options] )
| data | A string or a membuffer to be written. | ||
| options | A string containing driver specific blob creation parameters. | ||
| Returns: | A stream that can be used to read or write from/to the blob, or just the blob ID. | ||
| Raises: |
|
This method creates a Blob entity in the database. If a data member is not given, then a DBIBlobStream class is returned; the returned instance can be used to fill the blob with data and to retreive informations about the blob entity.
If data member is given, it must be either a string or a membuf, and it will be used to fill the blob entity. If a string is given, it will be written through the string oriented Stream.writeText method, while if it's a membuf, it will be written through the byte oriented Stream.write method (although the underlying driver may just treat them the same, or rather use the options parameter to decide how to write the data). After the data is written, the created blob is closed and its ID is returned instead of the blob stream.
The options parameter can be used to send driver specific options that may control the type and creation parameters of the blog entity. Please, refer to the specific DBI driver documentation for details.
Drivers may return instances of the DBIBlobStream class, or provide their own specific sublcasses instead.
Opens an existing blob entity.
DBITransaction.openBlob( blobID )
| blobID | A string containing the blob ID to be opened. | ||
| Returns: | On success, a DBIBlobStream that can be used to read or write from/to the blob. | ||
| Raises: |
|
This method allows to open a stream towards a blob object. The returned stream can be manipulated as any other stream; it can be seeked, it can be truncated, it can be read and written both binary and text oriented.
If the amount of data to be written or read is limited, or if many blobs must be read or written in row, prefer the DBITransaction.readBlob and DBITransaction.createBlob methods.
Drivers may return instances of the DBIBlobStream class, or provide their own specific sublcasses instead.
Reads a whole blob entity.
DBITransaction.readBlob( blobId, [data], [maxlen] )
| blobId | The ID of the blob entity to be read. | ||
| data | A string or a MemBuf to be read. | ||
| maxlen | Maximum length read from the blob. | ||
| Returns: | A string containing the whole blob data, or read length if reading a MemBuf. | ||
| Raises: |
|
This method reads a whole blob in memory. If the parameter data is not given, then a new string, long enough to store all the blob, will be created. If it's given and it's a string, then the string buffer will be used, and it will be eventually expanded if needed. If it's a MemBuf, then the method will read at maximum the size of the MemBuf in bytes.
The maximum size of the input may be also limited by the maxlen parameter. If both maxlen and data(as a MemBuf) are provided, the maximum size actually read will be the minimum of maxlen, the data MemBuf size and the blob entity size.
When a MemBuf is read, then the method returns the amout of data actually imported. If the size of the MemBuf is not enough to contain the whole blob, it will be read as far as possible.
Note: It is possible to give a maximum length to be read and create dynamically the needed space by setting data to nil and passing maxlen.
Overwrites an existing blob entity.
DBITransaction.writeBlob( blobId, data, [start], [length] )
| blobId | The ID of the blob entity to be overwritten. | ||
| data | A string or a MemBuf to be written. | ||
| start | Character (if data is string) or byte (if data is MemBuf) from which to start writing. | ||
| length | Maximum count of Characters (if data is a string) or bytes (if data a is MemBuf) to be written. | ||
| Raises: |
|
This method overwrites a whole existing blob entity. The selection range allows to write a portion of the existing data obviating the need to extract a subpart of it.