Messaging

During operation, the AgConnect library may produce error and informational messages. For application purposes, it may be necessary to override the default message processing to stderr in some cases. For example, if the Connect library is used by an application that runs in an embedded environment lacking a computer screen, errors encountered by AgConnect won't be reported if the default message processing is used, since stderr won't be valid. Also, the format of the message generated by Connect in that case will be inconsistent with messages provided by code generated in house. To avoid such a situation, AgConnect includes a mechanism to override the default message processing normally used by AgConnect functions. The user application can use the same message functions as are used by Connect.

Connect interface diagram

Two messaging functions are used internally by Connect and STK:

AgUtMsg() and AgUtMsgSetMsgFunc().

Messaging with AgUtMsg()

The AgUtMsg() function generates a message based on the calling arguments. It has the following prototype:

AgTVoid
AgUtMsg (
AgTInt msgType,
AgTBool waitFlag,
AgTInt displayID,
AgTInt errorCode,
AgTChar *sourceFile,
AgTInt lineNo,
AgTChar *msgFormat,
...
);

The following constants represent valid values for the msgType argument:

AgCMsgDebug
AgCMsgInfo
AgCMsgForceInfo
AgCMsgWarning
AgCMsgAlarm

Valid values for the waitFlag argument are listed and described in the following table:

AgUtMsg() function waitFlag constants

Valid values for the displayID argument include any integer value you wish or the constant AgCMsgDispAll, which causes the message to display in all currently defined displayIDs. A displayID of 0 or 1 is associated with writing to standard output by default.

The errorCode argument of AgUtMsg() can be set to any integer error you wish to display, or any of the following constants:

AgCError
AgCNoError
AgCNackReturned
AgCMsgNoErrorCode

The sourceFile and lineNo arguments can both be replaced by a single macro, AgMSourceLine (defined in the AgConnect.h file).

The msgFormat argument is the actual message string to be displayed. AgUtMsg() accepts a variable argument list to handle the creation of the message based on msgFormat, using format strings with the % symbol in the same manner as printf(). Thus, in the following example call to AgUtMsg(), a single additional argument, fileName, specifies the string to be substituted for %s in the msgFormat argument.

AgUtMsg( AgCMsgAlarm, AgCMsgWait, AgCMsgDispDefault,
AgCMsgNoErrorCode, AgMSourceLine, "Couldn't open file: %s",
fileName );

The call to AgUtMsg() in the example following has two additional arguments - one referring to an integer, the other to a string-to specify the contents of %d and %s in the msgFormat argument:

AgUtMsg( AgCMsgForceInfo, AgCMsgNoWait, AgCMsgDispDefault,
AgCMsgNoErrorCode, AgMSourceLine, "Return entry %d:\n%s\n", i+1,
returnInfo.returnList[i]);

Messaging with AgUtMsgSetMsgFunc()

The second messaging function, AgUtMsgSetMsgFunc(), allows you to replace the standard messaging function or add additional messaging functions. Its prototype is:

AgTInt
AgUtMsgSetMsgFunc (
AgTInt setOption,
AgTInt displayID,
AgTMessageFunc messageFunc
);

The first argument, setOption, can be set to any of the constants listed in the following table.

AgUtMsgSetMsgFunc() function setOption constants

The displayID argument can be set to any integer value you wish. The AgUtMsgSetMsgFunc() function uses the setOption argument to replace, add or remove the messaging function currently assigned to the displayID. Because a displayID with a value of 0 or 1 already has a messaging function assigned to it, you can't use the AgCMsgAdd constant to add a function to it, but only to replace existing default functions. Similarly, any displayID without a messaging function reports an error if you attempt to use AgCMsgReplace (i.e., to replace a nonexistent function).

The messageFunc argument to AgUtMsgSetMsgFunc() replaces the old function or is associated with the new displayID. The new function must conform to the following prototype:

void AgTConMsgFunc (int msgType, int waitFlag, int displayID,
int errorCode, char *sourceFile, int lineNo, char *message );