From RTSC-Pedia

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC

Using xdc.runtime Errors/Example 4

How to create and use custom Error IDs

Creating Custom Error IDs

The example below is identical to Error Example 1 except that we replace the use of the predefined error ID, Error.E_generic, with an error ID of our own. As before, the function half() raises an error when its argument is not an even number and main() initializes an Error_Block, calls half(), and checks for an error. The only difference is that the error raised is now defined in a new module, named examples.runtime.errors.Errors, and the output now includes the value of current value of the offending argument.

Since we are using an error defined in a new module (examples.runtime.errors.Errors), we mustn't forget to add this to our application's configuration script; otherwise, when we build the application we will get "undefined reference to ..." errors from the linker.

#include <xdc/std.h>
 
#include <xdc/runtime/Error.h>
#include <xdc/runtime/System.h>
 
#include <examples/runtime/errors/Errors.h>
 
/* ======== half ======== */
static Int half(Int num, Error_Block *eb)
{
    /* raise an error if num is not even */
    if ((num & 0x1) != 0) {
        Error_raise(eb, Errors_PARAMETER, num, 
            "num must be even");
    }
    return (num / 2);
}
 
/*  ======== main ======== */
Int main(Int argc, String argv[])
{
    Error_Block eb;
 
    /* must initialize prior to first use */
    Error_init(&eb);
 
    /* call a function that raises an error */
    System_printf("half returned %d\n", half(17, &eb));
 
    /* return 1 if an error occured, 0 otherwise */
    return (Error_check(&eb) ? 1 : 0);
}

var System = xdc.useModule("xdc.runtime.System");
var Error = xdc.useModule("xdc.runtime.Error");
 
var Errors = xdc.useModule(
     "examples.runtime.errors.Errors");

xdc.runtime.Main: "main.c", line 10: parameter value (= 0x11) is not valid: num must be even
half returned 8

The Errors Module

This section shows the complete set of files necessary to create a new module that specifies a set of custom error IDs. The module specification below couldn't be simpler: it declares the name of the new module, Errors, and defines a new Error.Id named PARAMETER that accepts two arguments, a value and a message.

import xdc.runtime.Error;
 
module Errors {
    config Error.Id PARAMETER = {
        msg: "parameter value (= 0x%x) is not valid: %s"
    };
}

The Package Files

Since all modules must live in a package we also need to create a two other files:

1. package.xdc - a file that define the package's name and identifies the modules it contains, and
2. package.bld - a file that specifies everything that needs to be included in the package.

Since this package does not contain any source files that need to be compiled or included in the this package, the package.bld file can be empty. Why is it needed at all if it can be empty? The existence of package.bld tells RTSC tooling that this package is "buildable" while the contents specify what should be built.

package examples.runtime.errors { 
    module Errors; 
}

/* nothing more to say (package.xdc said it all) */

The package.xdc file is largely self explanatory; it defines the name of the package, examples.runtime.errors, and it specifies the modules contained in the package, ErrorID.

The package.bld file, on the other hand, requires some explanation. The existence of package.bld indicates that the package is (re)buildable and, because the RTSC build engine's default behavior is sufficient for this package, the package.bld file can be empty.

See also

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC