isc_get_segment()
Go Up to API Function Reference
Reads a segment from an open Blob.
Syntax
ISC_STATUS isc_get_segment(
ISC_STATUS *status_vector,
isc_blob_handle *blob_handle,
unsigned short *actual_seg_length,
unsigned short seg_buffer_length,
char *seg_buffer);
| Parameter | Type | Description |
|---|---|---|
|
|
|
Pointer to the error status vector |
|
|
|
Pointer to the handle of the Blob you want to read. |
|
|
|
Pointer to the actual segment length that InterBase reads into the buffer; useful if the segment length is shorter than the buffer length. |
|
|
|
Length of the segment buffer |
|
|
|
Pointer to the segment buffer |
Description
isc_get_segment() reads a Blob segment from a previously opened Blob. You can set the seg_buffer_length parameter to a size that is efficient for a particular type of Blob data. For example, if you are reading Blob data from a text file, you might set the segment buffer length to 80, to take advantage of the 72 to 80 character line lengths that are common in text files. By periodically checking the value of the actual segment length in your loop, you can determine an end-of-line or end-of-file condition.
Before reading any part of a Blob, you must open the Blob with a call to isc_open_blob2(). isc_get_segment() behaves differently depending on which call precedes it. If the most recent call is to isc_open_blob2(), then a call to isc_get_segment() reads the first segment in the Blob. If the most recent call is to isc_get_segment(), then it reads the next segment.
If Blob filters are specified when a Blob is opened, then each segment retrieved by isc_get_segment() is filtered on read.
You can read bitmaps and other binary files directly, without filtering, if you do not need to change from one format to another, say from TIF to JPEG. You can also store compressed bitmaps directly in a database in formats such as JPG (JPEG), BMP (Windows native bitmaps), or GIF (CompuServe Graphic Interchange Format). No filtering is required.
You can store bitmaps in a database in row-major or column-major order.
If the buffer is not large enough to hold the entire current segment, the function returns isc_segment, and the next call to isc_get_segment() gets the next chunk of the oversized segment rather than getting the next segment.
When isc_get_segment() reads the last segment of the Blob, the function returns the code isc_segstr_eof.
For more information about reading data from a Blob, see Working with Blob Data.
Example: The following call gets a segment from one Blob and writes it to another:
get_status = isc_get_segment(status, &from_blob, &seg_len, 80, buffer);
if (status[0] == 1 && status[1]) {
isc_print_status(status);
return(1);
}
if (get_status != isc_segstr_eof)
write_status = isc_put_segment(status, &to_blob, seg_len, buffer);
if (status[0] == 1 && status[1]) {
isc_print_status(status);
return(1);
}
Return value
isc_get_segment() returns the second element of the status vector. Zero indicates success. isc_segment indicates the buffer is not large enough to hold the entire current segment; the next call to isc_get_segment() gets the next chunk of the oversized segment rather than getting the next segment. isc_segstr_eof indicates that the last segment of the Blob has been read. Any other nonzero value indicates an error. For InterBase errors, the first element of the status vector is set to 1, and the second element is set to an InterBase error code.
To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.