This chapter describes the Oracle Communications Billing and Revenue Management (BRM) error logging and handling routines and how to use them in your custom applications.
For information on the log file locations, syntax of error messages, and descriptions of error codes, see "Reference Guide to BRM Error Codes" in BRM System Administrator's Guide.
For additional information on error handling in C++, see "Handling Exceptions".
The BRM APIs include a set of routines to handle and log errors. BRM uses these routines for internal error handling. You must use these routines in your custom applications to allow seamless detection and reporting of errors between your applications and the BRM applications.
The error buffer, pin_errbuf_t, is the basic structure for receiving error status from calls to the BRM Application Programming Interface (API). A pointer to an error buffer, ebufp, is passed into each API call and is filled in by the routine with information about any error condition that occurred.
For details on the structure and fields in an ebufp, see "Error Buffer".
You use the PIN_ERRBUF_IS_ERR macro in your code to test the ebufp for an error condition. This macro returns zero if no error exists in the ebufp and nonzero if an error is recorded.
All higher-level BRM API routines use the ebufp for error detection. These routines check for errors in the following ways:
Check for errors after each API call. See "Individual-Style ebuf".
Check for errors at the end of a series of API calls. See "Series-Style ebuf".
PCM_*() routines log error information in the ebufp after each API call. Since the Portal Communication Module (PCM) API routines affect data, you must detect the errors immediately and test the status of the ebufp after each call to a PCM_*() routine. If you do not detect errors after each call, any error recorded in the ebufp will be overwritten by another API call, and you will lose information about the errors.
For sample code on checking the ebufp for errors after each PCM_*() call, see sample_app.c located in BRM_SDK_Home/source/samples/apps/c.
PIN_*() routines update the error status in the ebufp after each API call. With the series ebufp style, you can perform a series of related API calls, such as creating and populating an flist, and check for errors at the end of the series. The first error is recorded in the ebufp and all subsequent calls are treated as no-ops so that the first error remains recorded in the ebufp. When you check for errors after a series of API calls, you can deal with the errors that have been detected as necessary.
Using series ebufp style makes manipulating flists and Portal object IDs (POIDs) much more efficient, since the entire logical operation can be completed, then tested once for any errors.
Note:
You can check for errors any time using series-style error detection, but series-style ebuf has been designed to reduce the number of error checks required.For sample code on checking the ebufp for errors after a series of PIN_*() routines, see sample_app.c.
Applications that call BRM API routines must follow this general flow for error handling:
Declare an error buffer.
Call PIN_ERRBUF_CLEAR to initialize the error buffer.
Call PIN Library routines to create an input flist.
Check for errors by calling the PIN_ERRBUF_IS_ERR.
Call a PCM API routine.
Check for errors by calling PIN_ERRBUF_IS_ERR().
Call PIN_ERRBUF_RESET to reset the errbuf and cleans up the memory pointed to by the argsp and nextp pointers.
Note:
Previous versions of BRM used the PIN_ERR_CLEAR_ERR macro to initialize the error buffer and to reset its contents to 0. This macro still appears in some BRM code to support backward compatibility. In new code that you write, use PIN_ERRBUF_CLEAR and PIN_ERRBUF_RESET to initialize and reset the error buffer.The following example shows this flow. For a complete sample, see sample_app.c.
... /** Declare error buffer */ pin_errbuf_tebuf; /** Clear the error buffer */ PIN_ERRBUF_RESET(&ebuf); /** PIN Library routines. */ vp = (void *)"test"; PIN_FLIST_FLD_SET(a_flistp, PIN_FLD_BILL_MODE, vp, &ebuf); /* Force CURRENCY to DOLLARS */ dummy = PIN_CURRENCY_DOLLARS; PIN_FLIST_FLD_SET(a_flistp, PIN_FLD_CURRENCY, (void *)&dummy, &ebuf); /* Set BILL_TYPE to internal (no charges). */ btype = PIN_BILL_TYPE_INTERNAL; PIN_FLIST_FLD_SET(a_flistp, PIN_FLD_BILL_TYPE, (void*)&btype, &ebuf); /* Add a nameaddr array element to the plan flist. */ a_flistp = PIN_FLIST_ELEM_ADD(flistp, PIN_FLD_NAMEINFO, PIN_NAMEINFO_BILLING, &ebuf); vp = (void *)"Doe"; PIN_FLIST_FLD_SET(a_flistp, PIN_FLD_LAST_NAME, vp, &ebuf); vp = (void *)"John"; PIN_FLIST_FLD_SET(a_flistp, PIN_FLD_FIRST_NAME, vp, &ebuf); vp = (void *)"1234 Main Street"; PIN_FLIST_FLD_SET(a_flistp, PIN_FLD_ADDRESS, vp, &ebuf); /* Add more PIN library routines to gather all the information needed to register a customer */ /* Check for errors */ if (PIN_ERRBUF_IS_ERR(&ebuf)) { PIN_ERR_LOG_EBUF(PIN_ERR_LEVEL_ERROR, "sample_init_input error", &ebuf); PIN_ERRBUF_RESET(&ebuf); return; } /** Clear the error buffer */ PIN_ERRBUF_RESET(&ebuf); /* PCM operations */ /* Call the COMMIT CUSTOMER opcode */ PCM_OP(ctxp, PCM_OP_CUST_COMMIT_CUSTOMER, 0, flistp, &r_flistp, &ebuf); /* Check for errors */ if (PIN_ERRBUF_IS_ERR(&ebuf)) { PIN_ERR_LOG_EBUF(PIN_ERR_LEVEL_ERROR, "create_customer error"", &ebuf); PIN_ERRBUF_RESET(&ebuf); return; }
When detecting errors using PIN_ERRBUF_IS_ERR, you can call the error- or message-logging macros to record the details of the error in a standard format. For example, you can use the PIN_ERR_LOG_EBUF macro to print the contents of an ebufp along with a custom message to your application's logfile.
To log any messages, including errors unrelated to ebufs and the BRM API, use the PIN_ERR_LOG_MSG macro at any point in your application.
Table 6-1 lists the routines you can use in your application to log status information:
Table 6-1 Routines Used to Log Status Information
| Action | Routine |
|---|---|
|
Specify the path and name of the log file for your application. The default log file is default_pin.log in the application directory. |
PIN_ERR_SET_LOGFILE |
|
Specify your application's name in the log entries to identify the program in which the error occurred. |
PIN_ERR_SET_PROGRAM |
|
Specify what types of messages to log and what to discard. You can enable debugging messages during development and then turn them off by changing the log level setting. |
PIN_ERR_SET_LEVEL |
|
Print the contents of an flist to the error log. |
PIN_ERR_LOG_FLIST |
|
Print the contents of a POID to the error log. |
PIN_ERR_LOG_POID |
For a list and description of all the macros available for logging messages and errors, see "Error-Handling Macros" in BRM Developer's Reference.
For an explanation of the standard log entry format, see "Reference Guide to BRM Error Codes" in BRM System Administrator's Guide.
Use the following methods to debug your applications.
To diagnose application problems:
Check the information in the ebuf for the exact source location of the API call that generated the error. If the error is caused by an incorrect or missing field on the input flist, the ebuf provides the field name.
For details about the error buffer format and contents, see "Error Buffer".
If you can't diagnose an error with the information in the ebuf, use PIN_ERR_SET_LEVEL to enable the application libraries to log debug messages. Errors that occur in the application libraries are printed in detail to the logfile. This helps you locate errors like illegal NULL pointers.
Enable the CMs and DMs to log debug messages to be printed when an operation fails because of bad input. These messages are printed to the CM and DM log files, not to the application's log file. Normally this type of error is not logged because it is not caused by a failure in the BRM system. You can enable and disable debug messages by editing the CM and DM configuration files.
For information on enabling error logging in the CM and DM configuration files, see the configuration files in the CM and DM directories.