CWBSO_GetErrMsgText

Purpose

Retrieves the message text from an error handle. This API should only be called when CWBSO_ERROR_OCCURRED is the return value from a call to another API. In this case there is an error message associated with the error handle.

Syntax

 
unsigned int CWB_ENTRY CWBSO_GetErrMsgText(
                CWBSO_ERR_HANDLE errorHandle ,          
                char far* lpszMsgBuffer ,               
                unsigned long ulBufferLength,           
                unsigned long far* lpulBytesNeeded);

Parameters

CWBSO_ERR_HANDLE errorHandle - input: A handle to an error object. If an error occurs that there is error text for, this handle may be used to retreive the error message and message help.
char far* lpszMsgBuffer - output: A long pointer to the output buffer where the message text will be placed. The message text that is returned by this API will be translated text. The output buffer is not changed when the return code is not set to CWBSO_NO_ERROR.
unsigned long ulBufferLength - input: The size, in bytes, of the output buffer argument.
unsigned long far* lpulBytesNeeded - output: A long pointer to an unsigned long that will be set to the number of bytes needed to place the entire message text in the output buffer. When this value is less than or equal to the size of output buffer that is specified, the entire message text is placed in the output buffer. When this value is greater than the size of output buffer that is specified, the output buffer contains a null string. The output buffer is not changed beyond the bytes that are needed for the message text. This value is set to zero when the return code is not set to CWBSO_NO_ERROR.

Return Codes

The following list shows common return values.

CWBSO_NO_ERROR: No error occurred.
CWBSO_BAD_ERR_HANDLE: The error handle that is specified is not valid.
CWBSO_NO_ERROR_MESSAGE: The error handle that is specified contains no error message.
CWBSO_GET_MSG_FAILED: The error message text could not be retrieved.

Usage

CWBSO_CreateErrorHandle must be called prior to calling this API. The error handle that is returned by CWBSO_CreateErrorHandle must be passed as input to this API. For errors which occurred on the iSeries™ server, the message text will be in the language that is specified for the user's execution environment. All other message text will be in the language that is specified in the Windows^® Control Panel on the user's personal computer.