DebugMessage

Sends the KINGSTAR log messages to KINGSTAR Analysis Console.

Syntax

KsError DebugMessage(
     int Category,
     KsLogSeverity Severity,
     wchar_t* Message,
     BOOL AppendValues,
     long long Value0,
     long long Value1,
     double Value2,
     double Value3
);

Parameters

Category: the ID of a log. It is user-defined. A string can be associated with each Category using the SetCategoryName method. The ID doesn't have to start from zero or in sequence.

Severity: the severity level of a log. See the KsLogSeverity type.

Message: a message that describes the log data. The maximum length is 128 characters.

AppendValues: TRUE: the values are added at the end of the Message. FALSE: the values are not added at the end of the Message.

Value0: the first value to be displayed in your log.

Value1: the second value to be displayed in your log.

Value2: the third value to be displayed in your log.

Value3: the fourth value to be displayed in your log.

Return value

If the function succeeds, it returns errNoError, otherwise an error code. For more information about the error code, see the KsError list.

Remarks

• Category and Severity can be used to filter the log you want to see. The filter is done in KINGSTAR Analysis Console.
• The Message string uses UTF-16 encoding.
• If AppendValues is enabled, the output is like this: Message: value0, value1, value2, value3.
• The values can be formatted and inserted inside the message using the same format as the C# String.Format Method.

Usable EtherCAT states

ecatOffline, ecatInit, ecatBoot, ecatPreOP, ecatSafeOP, ecatOP

Example

/*
*    Assume an user-defined enumeration:
*
*    typedef enum
*    {
*        userMain = 0,
*        userCommander,
*        userObserver,
*        END_USERMODULE
*    } userModule;
*/

long long errorCode = KsError::errWrongParameter;
double watchValue1 = 360.0, watchValue2 = 720.0;
// Scenario 1: Print plain messages
// Expected message: "Fatal error in the main loop"
nRet = DebugMessage(userMain, logFatal, L"Fatal error in the main loop", FALSE,
                    0, 0, 0.0, 0.0);

// Scenario 2: Append values behind
// Expected message: "Calling JogAxis() failed, error code returned: 4097, 0, 0.0, 0.0"
nRet = DebugMessage(userCommander, logError, L"Calling JogAxis() failed, error code returned",
                    TRUE, errorCode, 0, 0.0, 0.0);

// Scenario 3: Insert values in the message
// Expected message: "Before: watchValue1: 360.0, watchValue2: 720.0"
nRet = DebugMessage(userObserver, logDebug, L"Before: watchValue1: {2}, watchValue2: {3},",
                    FALSE, 0, 0, watchValue1, watchValue2);
watchValue2 = watchValue1;
// Expected message: "After: watchValue1: 360.0, watchValue2: 360.0"
nRet = DebugMessage(userObserver, logDebug, L"After: watchValue1: {2}, watchValue2: {3},",
                    FALSE, 0, 0, watchValue1, watchValue2);

Requirements

See also

GetCategoryName

SetCategoryName