Error handling

Log macros

Log macros can be used for displaying vital information about the state of a script during debugging. These macros have the benefit of being removed by the preprocessor in the finished product, but they can be enabled on demand by the developer. They also automatically log the component, file path and line number they are used in.

Usage

The following log macros are available:

    INFO(<message>);
    LOG(<message>);
    WARNING(<message>);
    ERROR(<message>);
    ERROR_MSG(<message>);
    MESSAGE_WITH_TITLE(<title>,<message>);
    ERROR_WITH_TITLE(<title>,<message>);

<title> and <message> must be strings.

The log macros can be used by including the CBA macro library at the top of the script file:

#include "\x\cba\addons\main\script_macros_common.hpp"

Which messages can be displayed and which get removed by the preprocessor depends on the current debug mode. The following modes are available:

#define DEBUG_MODE_FULL
#define DEBUG_MODE_NORMAL
#define DEBUG_MODE_MINIMAL

If you want to specify a debug mode, you have to define it before including the CBA macro library:

#define DEBUG_MODE_FULL
#include "\x\cba\addons\main\script_macros_common.hpp"

• If DEBUG_MODE_FULL is defined, all debugging macros are kept and will be printed into the RPT-logfile.
• DEBUG_MODE_NORMAL is the default mode. In this mode, ERROR() and WARNING() messages will be logged, but LOG() (as well as TRACE_n) messages are removed.
• In DEBUG_MODE_MINIMAL only ERROR() messages are displayed and logged, but WARNING() is removed during preprocessing.

All messages will be displayed in the following format:
[<PREFIX>] (<COMPONENT>) <LEVEL>: <MESSAGE> File: <FILE_PATH> Line: <LINE_NUMBER>

If PREFIX and COMPONENT are undefined, they default to [CBA] (diagnostic).

The macros LOG(), WARNING(), ERROR(), ERROR_MSG() and INFO() also have "format"-versions. These can be used to display the values of variables. They behave exactly like the format scripting command:

ERROR_2("%1 count: %2!", "banana", 5);
->
[CBA] (diagnostic) ERROR: banana count: 5! File: x\cba\addons\diagnostic\XEH_preStart.sqf Line: 5

In LOG_n, n must be the exact number of additional arguments. n can range from 1 to 8.

Examples

When using ERROR_MSG or ERROR_WITH_TITLE lines can be seperated by using \n.

    INFO("my info message");
    LOG("my log message");
    WARNING("my warning message");
    ERROR("my error message");
    ERROR_MSG("my on screen and RPT error message");
    MESSAGE_WITH_TITLE("CUSTOM","my custom message");
    ERROR_WITH_TITLE("my error","line1\nline2\nline3");

output:

[CBA] (diagnostic) INFO: my info message
[CBA] (diagnostic) LOG: my log message File: x\cba\addons\diagnostic\XEH_preInit.sqf Line: 39
[CBA] (diagnostic) WARNING: my warning message File: x\cba\addons\diagnostic\XEH_preInit.sqf Line: 40
[CBA] (diagnostic) ERROR: my error message File: x\cba\addons\diagnostic\XEH_preInit.sqf Line: 41
[CBA] (diagnostic) CUSTOM: my custom message File: x\cba\addons\diagnostic\XEH_preInit.sqf Line: 42
[CBA] (diagnostic) ERROR: my error File: x\cba\addons\diagnostic\XEH_preInit.sqf Line: 42
            line1
            line2
            line3

ERROR_MSG() and ERROR_WITH_TITLE() will aditionally create the following ui pop up message:

INFO() will not log the file path and line number.

DEBUG_SYNCHRONOUS

By default LOG(), WARNING(), INFO() and their derivates, but not ERROR() are logged using their own thread. This is made so the game does not slow down when writing to the hard drive if many lines would be logged at once. This will cause them to be delayed (at least by one frame) in the RPT-logfile, which can mean that they appear after custom diag_log or vanilla error messages that happened later. Despite that they are still written in order they are called.

To disable this behaviour and have the log macros written at the moment they are called, one can define DEBUG_SYNCHRONOUS before including the CBA macro library.

#define DEBUG_SYNCHRONOUS
#include "\x\cba\addons\main\script_macros_common.hpp"

LOG("this is logged in the same frame this line is evaluated!");