cciThrowExceptionW

The cciThrowExceptionW exception is thrown by the integration node interface and uses the specified arguments as exception data.

Using this function

The function, like a C exit call, does not return to the caller. It can throw C++ exceptions. When you use C++ to implement a user-defined extension, you must consider certain caveats. For more information, see Which language to use to implement a user-defined extension.

Syntax

void cciThrowExceptionW(
  int*                returnCode,
  CCI_EXCEPTION_TYPE  type,
  const char*         file,
  int                 line,
  const char*         function,
  const CciChar*      messageSource,
  int                 messageNumber,
  const CciChar*      traceText,
                      ...
);

Parameters

returnCode
The return code from the function (output). If the messageSource parameter is null, the returnCode is set to CCI_INV_DATA_POINTER.
type
The type of exception (input). Valid values are:
  • CCI_FATAL_EXCEPTION
  • CCI_RECOVERABLE_EXCEPTION
  • CCI_CONFIGURATION_EXCEPTION
  • CCI_PARSER_EXCEPTION
  • CCI_CONVERSION_EXCEPTION
  • CCI_DATABASE_EXCEPTION
  • CCI_USER_EXCEPTION
file
The source file name where the exception was generated (input). The value is optional, but it is useful for debugging purposes.
line
The line number in the source file where the exception was generated (input). The value is optional, but it is useful for debugging purposes.
function
The function name that generated the exception (input). The value is optional, but it is useful for debugging purposes.
messageSource
A string that identifies the Windows message source or the Linux® and UNIX message catalog. To use the current integration node message catalog, specify BIPmsgs on all operating systems.
messageNumber
The message number identifying the exception (input). If messageNumber is specified as zero, it is assumed that a message is not available. If messageNumber is non-zero, the specified message is written into the integration node event log with any inserts that are provided in the variable argument list.
traceText
Trace information that is written into the service trace log (input). The information is optional, but it is useful in debugging problems.
...
A C variable argument list that contains any message inserts that accompany the message (input). These inserts are treated as character strings and the variable arguments are assumed to be of type pointer to CciChar.

The last argument in this list must be (Ccichar*)0.

Inserts that are larger than 32,768 bytes (32 KiB) including a null terminator are truncated to this size.

Return values

None. If an error occurs, the returnCode parameter indicates the reason for the error.

Example

void raiseExceptionWithBroker(CciChar* helpfulText, 
                              char* file, /* which source file is broken */
                              int line,   /* line in above file */
                              char* func  /* function in above file */
                              ){
  int rc = CCI_SUCCESS;
  
  /* Set up the message catalog name */
  const char* catalog = "BIPmsgs";
  
  /* Convert the catalog name to wide characters. 
   * BIP_DEF_COMP_CCSID is UTF-8 on distributed and LATIN1 on z/OS 
   */
  int maxChars =  strlen(catalog)+1;
  CciChar* wCatalog =(CciChar*)malloc(maxChars*sizeof(CciChar));
  cciMbsToUcs(&rc, catalog, wCatalog, maxChars, BIP_DEF_COMP_CCSID);

  /* The above might have failed, but we are already throwing an exception,
   * so rc is now set to type success. */
  rc = CCI_SUCCESS;

  /* Throw the exception. The explanation will be added as the traceText and
   *  as an insert to the message 
   */
  cciThrowExceptionW(&rc,
                     CCI_USER_EXCEPTION,
                     file, line, func,
                     wCatalog, BIP2111,  
                     helpfulText,  
                     helpfulText,  
                     (CciChar*)0 
                     );     
  /* The above might have failed, but we are already throwing an exception,
   * so the value of rc is not important. */
}