Prev Up Home Next

Generally, there are two categories of errors.

  1. Runtime errors. This kind of errors occurs when JagPDF cannot allocate an OS resource or if there are no sufficient permissions to perform an operation, etc. Simply put, these errors are triggered by the environment your application is running in and they are usually outside your control. JagPDF strives for detecting and reporting such errors.
  2. JagPDF incorrect usage. The basic guideline is: do not count on JagPDF detecting this type of errors. Violating preconditions or using JagPDF in an undocumented manner results in undefined behavior.

Any JagPDF function might fail because of a potential runtime error. It is important to check for runtime errors reported by JagPDF. Generally, JagPDF does not attempt to recover from runtime errors so it can be said that any reported error is fatal. If you want to avoid malformed documents then absolutely no error can occur during the whole PDF document composition.

The following sections describe how to handle errors in the supported languages.


You can use either exceptions or error codes. These two variants are mutually exclusive - you can use one or the other but not both at once.

  1. Exceptions. All JagPDF errors are reported by throwing an instance of jag::pdf::Exception which is derived from std::exception.
try {
    // jagpdf usage
catch(pdf::Exception const& exc) {
    exc.what();  // human readable message
    exc.code();  // associated error code
  1. Error codes. It possible to disable exceptions and use error codes instead. Define JAG_DO_NOT_USE_EXCEPTIONS preprocessor symbol when compiling your application and refer to error handling in C for more details. Note that support for error codes in JagPDF for C++ is experimental and is not thoroughly tested.

There are several categories of functions.

The majority of JagPDF functions returns an error code - jag_error. Value 0 indicates that the operation succeeded, non-zero error code signalizes an error.

if (jag_Canvas_line_to(hc, 10.0, 10.0)) {
    /* process the error */

Some functions return an object. If such function fails a null object is returned.

doc = jag_create_file("/path/to/file/", profile);
if (!doc) {
    /* process the error */

If an error occurs it is stored so that it can be accessed later using the following functions:

jag_Char const* jag_error_msg();
jag_error jag_error_code();
void jag_error_reset();

The last non-zero error code can be retrieved from jag_error_code(). jag_error_msg() provides a human readable description of the problem. The information about the last error can be reset by jag_error_reset(). This information is stored in thread local storage so take this fact into the account when using these functions.


All JagPDF errors are reported by raising an instance of jagpdf.Exception which is derived from RuntimeError built-in exception.

    # JagPDF usage
except jagpdf.Exception, why:
    print why              # formatted error message


All JagPDF errors are reported by throwing an instance of com.jagpdf.JagPDFException which is derived from RuntimeException built-in exception.

try {
    // JagPDF usage
} catch(JagPDFException exc) {
    // process the exception
Prev Up Home Next