Logging in C++ and Script-based Entry Points

For VCS 4.0, developers creating C++ agent entry points can use a set of macros to log application or debug messages. Developers of script-based entry points can use a set of functions, or "wrappers," that call the VCS halog utility to generate application or debug messages.

VCS Agent Messages: Format

An agent log message consists of five fields. The format of the message is:

<Timestamp> <Mnemonic> <Severity> <UMI> <MessageText>

The following is an example message, of severity ERROR, generated by the VCS FileOnOff agent's online entry point when attempting to online the resource, a file named "MyFile":

The first four fields of the message above is composed of the timestamp, an uppercase mnemonic that represents the product (VCS, in this case), the severity, and the UMI (unique message ID). The subsequent lines contain the message text.

Timestamp

The timestamp indicates when the message was generated. It is formatted according to the locale.

Mnemonic

The mnemonic field is used to indicate the product. The mnemonic, such as "VCS," must use all capital letters. All VCS bundled agents, enterprise agents, and custom agents use the mnemonic: "VCS."

Severity

The severity of each message is displayed in the third field of the message (Critical, Error, Warning, Notice, or Information for normal messages; 1-21 for debug messages). All C++ logging macros and script-based logging functions provide a means to define the severity of messages, both normal and debugging.

UMI

The UMI (unique message identifier) includes an originator ID, a category ID, and a message ID.

• The originator ID is a decimal number preceded by a "V-" assigned by VERITAS.
• The category ID is a number in the range of 0 to 65536 assigned by VERITAS. For each custom agent, VERITAS must be contacted so that a unique category ID can be registered for the agent.
• For C++ messages, the category ID is defined in the VCSAgStartup entry point (see Log Category).
• For script-based entry points, the category is set within the VCSAG_SET_ENVS function (see VCSAG_SET_ENVS).
• For debug messages, the category ID, which is 50 by default, need not be defined within logging functions.
• Message IDs can range from 0 to 65536 for a category. Each normal message (that is, non-debug message) generated by an agent must be assigned a message ID. For C++ entry points, the msgid is set as part of the VCSAG_LOG_MSG and VCSAG_CONSOLE_LOG_MSG macros. For script-based entry points, the msgid is set using the VCSAG_LOG_MSG function. The msgid field is not used by debug functions or required in debug messages.

Message Text

The message text is a formatted message string preceded by a dynamically generated header consisting of three colon-separated fields. namely, <name of the agent>:<resource>:<name of the entry point>:<message>. For example:

In the case of C++ entry points, the header information is generated

In the case of script-based entry points, the header information is set within the VCSAG_SET_ENVS function (see VCSAG_SET_ENVS).