WebSphere Message Service Clients for C/C++ and .NET, Version 1.2 Operating Systems: Linux, Windows

ErrorBlock

If a C function call fails, XMS can store information about why the call failed in an error block.

For more information about the error block and its contents, see The error block.

Functions in this class return the following return codes:
Return code Meaning
XMS_OK The call completed successfully.
XMS_E_INVALID_ERROR_BLOCK The call failed because the error block that was passed to the function was not valid.
Any other value The call failed for some other reason.

This class is a helper class.

Functions

Summary of functions:
Function Description
xmsErrorClear Clear the contents of the error block.
xmsErrorCreate Create an error block.
xmsErrorDispose Delete the error block.
xmsErrorGetErrorCode Get the error code.
xmsErrorGetErrorData Get the error data.
xmsErrorGetErrorString Get the error string.
xmsErrorGetJMSException Get the exception code.
xmsErrorGetLinkedError Get the handle for the next error block in the chain of error blocks.

xmsErrorClear – Clear Error Block

Interface:
xmsRC xmsErrorClear(xmsHErrorBlock errorBlock);

Clear the contents of the error block.

Note that XMS automatically clears the contents of an error block that is passed by an API function call.

Parameters:
errorBlock (input)
The handle for the error block.
Thread context:
Any

xmsErrorCreate – Create Error Block

Interface:
xmsRC xmsErrorCreate(xmsHErrorBlock *errorBlock);

Create an error block.

In a newly created error block, the exception code is XMS_X_NO_EXCEPTION.

Parameters:
errorBlock (output)
The handle for the error block.
Thread context:
Any

xmsErrorDispose – Delete Error Block

Interface:
xmsRC xmsErrorDispose(xmsHErrorBlock *errorBlock);

Delete the error block.

Only the first error block in a chain of error blocks can be explicitly deleted. By deleting the first error block in a chain, all subsequent error blocks in the chain are also deleted.

If an application tries to delete an error block that is already deleted, the call is ignored.

Parameters:
errorBlock (input/output)
On input, the handle for the error block. On output the function returns a null handle.
Thread context:
Any

xmsErrorGetErrorCode – Get Error Code

Interface:
xmsRC xmsErrorGetErrorCode(xmsHErrorBlock errorBlock,
                           xmsINT *errorCode);

Get the error code.

For more information about the error code, see The error block.

Parameters:
errorBlock (input)
The handle for the error block.
errorCode (output)
The error code.
Thread context:
Any

xmsErrorGetErrorData – Get Error Data

Interface:
xmsRC xmsErrorGetErrorData(xmsHErrorBlock errorBlock,
                           xmsCHAR *buffer,
                           xmsINT bufferLength,
                           xmsINT *actualLength);

Get the error data.

For more information about the error data, see The error block.

For more information about how to use this function, see C functions that return a string by value.

Parameters:
errorBlock (input)
The handle for the error block.
buffer (output)
The buffer to contain the error data.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the error data is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the error data in bytes. If you specify a null pointer on input, the length is not returned.
Thread context:
Any

xmsErrorGetErrorString – Get Error String

Interface:
xmsRC xmsErrorGetErrorString(xmsHErrorBlock errorBlock,
                             xmsCHAR *buffer,
                             xmsINT bufferLength,
                             xmsINT *actualLength);

Get the error string.

For more information about the error string, see The error block.

For more information about how to use this function, see C functions that return a string by value.

Parameters:
errorBlock (input)
The handle for the error block.
buffer (output)
The buffer to contain the error string.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the error string is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the error string in bytes. If you specify a null pointer on input, the length is not returned.
Thread context:
Any

xmsErrorGetJMSException – Get Exception Code

Interface:
xmsRC xmsErrorGetJMSException(xmsHErrorBlock errorBlock,
                              xmsJMSEXP_TYPE *exceptionCode);

Get the exception code.

For more information about the exception code, see The error block.

Parameters:
errorBlock (input)
The handle for the error block.
exceptionCode (output)
The exception code. If the error block is in a chain of error blocks, but is not the first in the chain, the exception code is always XMS_X_GENERAL_EXCEPTION.
Thread context:
Any

xmsErrorGetLinkedError – Get Linked Error

Interface:
xmsRC xmsErrorGetLinkedError(xmsHErrorBlock errorBlock,
                             xmsHErrorBlock *linkedError);

Get the handle for the next error block in the chain of error blocks.

Parameters:
errorBlock (input)
The handle for the error block.
linkedError (output)
The handle for the next error block in the chain. The function returns a null handle if there are no more error blocks in the chain.
Thread context:
Any

Reference topic

Terms of Use | Rate this page

Last updated: 7 Dec 2005

© Copyright IBM Corporation 2005. All Rights Reserved.