Retrieves the contents of a character large object. (UTF-8 version.)
A character large object may be retrieved in one or more chunks.
If the character large object is to be retrieved in multiple chunks, chunks are retrieved in sequence, where the length of each chunk is specified by the length parameter of each call to this routine. Chunks may only be retrieved sequentially through the character large object.
Parameters
size_t *returned,
MimerLob clobhandle,
char *data,
size_t size)
|
returned |
out |
The number of bytes, excluding terminating zero, returned as a result of the operation. |
|
clobhandle |
in |
A handle to a character large object returned by a call to MimerGetLob. |
|
data |
out |
Where to place the entire or a part of the character large object. |
|
size |
in |
The number of bytes to retrieve, including terminating null. |
Returns
A negative value indicating error, or a non-negative value indicating the number of characters available to return. This includes the number of characters returned in this call (excluding terminating null) and all data that are left in the character object. When the returned value is less than the length input parameter, all data of the character object has been returned.
This value may be used to calculate how many characters (excluding terminating null) that were returned using this formula:
returned_characters = min(length_input_parameter-1,return_value)
The following formula may be used to calculate the number of characters left to return:
left_to_return = return_value-length_input_parameter+1
|
Return value |
Description |
|---|---|
|
>= 0 |
Success. The number of characters to return. (See description above.) |
|
MIMER_HANDLE_INVALID |
The clobhandle parameter was not recognized as a handle. |
|
MIMER_OUTOFMEMORY |
If not enough memory could be allocated. |
|
Other value < 0 |
Any of the server error codes listed in Return Codes. |
Notes
This routine interacts with the database server.
Not Micro API compatible.
UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.