Purpose
Returns the message text associated with the error index provided. An index
value of 1 will retrieve the lowest-level (for example, the oldest) message
that is associated with the error handle. An index value of "cwbSV_GetErrCount()'s
returned errorCount" will retrieve the top-level (for example, the most recent)
message associated with the error handle.
Syntax
unsigned int CWB_ENTRY cwbSV_GetErrTextIndexed(
cwbSV_ErrHandle errorHandle,
unsigned long errorIndex,
char *errorText,
unsigned long errorTextLength,
unsigned long *returnLength);
Parameters
- cwbSV_ErrHandle errorHandle - input
- Handle that was returned by a previous call to the cwbSV_CreateErrHandle()
function.
- unsigned long errorIndex - input
- Index value that indicates which error text to return if multiple errors
are associated with the error handle.
- char * errorText - input/output
- Pointer to a buffer that will receive the error message text that is
stored in the error that is identified by the index.
- unsigned long errorTextLength - input
- Length of the receive buffer passed in. It should include space for
the ending null character. If the buffer is too small, the value will be truncated,
and CWB_BUFFER_OVERFLOW and returnLength will be set.
- unsigned long * returnLength - input/output
- Optional, may be NULL. A return address to store the number of bytes
needed to hold the output string if the receive buffer is too small.
Return Codes
The following list shows common return values.
- CWB_OK
- Successful completion.
- CWB_BUFFER_OVERFLOW
- Output buffer too small, data truncated.
- CWB_INVALID_POINTER
- NULL passed on output parameter.
- CWB_INVALID_HANDLE
- Handle is not valid.
- CWBSV_NO_ERROR_MESSAGES
- No error messages associated with error handle.
Usage
Valid index values are from 1 to cwbSV_GetErrCount()'s return value. Index
values less than 1 act as if 1 was passed. Index values greater than cwbSV_GetErrCount()
act as if errorCount was passed.