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

Handling errors in C

Most functions in the C API return a value that is a return code, and have an optional input parameter that is a handle for an error block. This section describes the respective roles of the return code and the error block.

Related concepts
Error conditions that can be handled at run time

Return codes

The return code from a C function call indicates whether the call was successful. The return code has data type xmsRC. Table 1 shows the possible return codes and their meaning.

Table 1. Return codes from C function calls
Return code Meaning
XMS_OK The call completed successfully.
Any other value The call failed. The error block contains more details about why the call failed. The return code is the same as the exception code that is returned in the error block.

The error block

When an application calls a C function, the application can include a handle for an error block as an input parameter on the call. If the call fails, XMS stores information in the error block about why the call failed. The application can then retrieve this information from the error block.

An error block contains the following information:
Exception code
An integer representing the exception. The exception code provides a high level indication of why the call failed, but does not indicate precisely which error has occurred. The header file xmsc.h defines a named constant for each exception code.

The exception code matches the JMS exception that is thrown by a JMS method in the same circumstances.

Error code
An integer representing the error. The error code provides a more precise indication of which error has occurred. The header file xmsc.h defines a named constant for each error code.
Error string
A null terminated string of characters that describes the error. The characters in the string are the same as those in the named constant that represents the error code.
Error data
A null terminated string of characters that provides additional information about the error. The information is free format.
Linked error
The handle for an linked error block. If XMS needs to report more information about a call that has failed, XMS can create one or more additional error blocks and chain them from the error block provided by the application.

XMS provides a set of helper functions to create an error block and extract information from it. An application must use a helper function to create an error block and obtain a handle for it before calling the first function that can accept the handle as an input parameter. If the function call fails, the application can then use other helper functions to extract information about the error that XMS has stored in the error block. For details of these helper functions, see ErrorBlock.


Concept topic

Terms of Use | Rate this page

Last updated: 7 Dec 2005

© Copyright IBM Corporation 2005. All Rights Reserved.