Script Entry Point Logging Functions

For script based entry points, VCS 4.0 provides functions, or wrappers, to call the VCS halog command for message logging purposes. While the halog command can be called directly within the script to log messages, the following entry point logging functions are easier to use and less error-prone:

VCSAG_SET_ENVS - sets and exports entry point environment variables

VCSAG_LOG_MSG - passes normal agent message strings and parameters to the halog utility

VCSAG_LOGDBG_MSG - passes debug message strings and parameters to the halog utility

VCSAG_SET_ENVS

The VCSAG_SET_ENV function is used in each script-based entry point file. Its purpose is to set and export environment variables that identify the agent's category ID, the agent's name, the resource's name, and the entry point's name. With this information set up in the form of environment variables, the logging functions can handle messages and their arguments in the unified logging format without repetition within the scripts.

The VCSAG_SET_ENV function sets the following environment variables for a resource:

VCSAG_LOG_CATEGORY	Sets the category ID. For custom agents, VERITAS assigns the category ID. See the category ID description in UMI. NOTE: For VCS bundled agents, the category ID is pre-assigned, based on the platform (Solaris, Linux, AIX, HP-UX, or Windows) for which the agent is written.
VCSAG_LOG_AGENT_NAME	The absolute path to the agent. For example:    /opt/VRTSvcs/bin/Application Since the entry points are invoked using their absolute paths, this environment variable is set at invocation. If the agent developer wishes, this agent name can also be hardcoded and passed as an argument to the VCSAG_SET_ENVS function
VCSAG_LOG_SCRIPT_NAME	The absolute path to the entry point script. For example:    /opt/VRTSvcs/bin/Application/online Since the entry points are invoked using their absolute paths, this environment variable is set at invocation. The script name variable is overridable.
VCSAG_LOG_RESOURCE_NAME	The resource is specified in the call within the entry point: VCSAG_SET_ENVS $resource_name

VCSAG_SET_ENVS Examples, Shell Script Entry Points

The VCSAG_SET_ENVS function must be called before any of the other logging functions.

• A minimal call:

VCSAG_SET_ENVS ${resource_name}
• Setting the category ID:

  VCSAG_SET_ENVS ${resource_name} ${category_ID}
  VCSAG_SET_ENVS ${resource_name} 1062
• Overriding the default script name:

  VCSAG_SET_ENVS ${resource_name} ${script_name}
  VCSAG_SET_ENVS ${resource_name} "monitor"
• Setting the category ID and overriding the script name:

  VCSAG_SET_ENVS ${resource_name} ${script_name} ${category_id}
  VCSAG_SET_ENVS ${resource_name} "monitor" 1062

Or,


  VCSAG_SET_ENVS ${resource_name} ${category_id} ${script_name}
  VCSAG_SET_ENVS ${resource_name} 1062 "monitor" 

VCSAG_SET_ENVS Examples, Perl Script Entry Points

• A minimal call:

VCSAG_SET_ENVS ($resource_name);
• Setting the category ID:

  VCSAG_SET_ENVS ($resource_name, $category_ID);
  VCSAG_SET_ENVS ($resource_name, 1062);
• Overriding the script name:

  VCSAG_SET_ENVS ($resource_name, $script_name);
  VCSAG_SET_ENVS ($resource_name, "monitor");
• Setting the category ID and overriding the script name:

  VCSAG_SET_ENVS ($resource_name, $script_name, $category_id);
  VCSAG_SET_ENVS ($resource_name, "monitor", 1062);

Or,


  VCSAG_SET_ENVS ($resource_name, $category_id, $script_name);
  VCSAG_SET_ENVS ($resource_name, 1062, "monitor"); 

VCSAG_LOG_MSG

The VCSAG_LOG_MSG function can be used to pass normal agent messages to the halog utility. At a minimum, the function must include the severity, the message within quotes, and a message ID. Optionally, the function can also include parameters and specify an encoding format.

Severity Levels (sev)	"C" - critical, "E" - error, "W" - warning, "N" - notice, "I" - information; place error code in quotes
Message (msg)	A text message within quotes; for example: "One file copied"
Message ID (msgid)	An integer between 0 and 65535
Encoding Format	UTF-8, ASCII, or UCS-2 in the form: "-encoding format"
Parameters	Parameters (up to six), each within quotes

VCSAG_LOG_MSG Examples, Shell Script Entry Points

• Calling a function without parameters or encoding format:

  VCSAG_LOG_MSG "<sev>" "<msg>" <msgid> 
  VCSAG_LOG_MSG "C" "Two files found" 140
• Calling a function with one parameter, but without encoding format:

  VCSAG_LOG_MSG "<sev>" "<msg>" <msgid> "<param1>"
  VCSAG_LOG_MSG "C" "$count files found" 140 "$count"
• Calling a function with a parameter and encoding format:

VCSAG_LOG_MSG "<sev>" "<msg>" <msgid> "-encoding <format>" "<param1>"
VCSAG_LOG_MSG "C" "$count files found" 140 "-encoding utf8" "$count"

Note that if encoding format and parameters are passed to the functions, the encoding format must be passed before any parameters.

VCSAG_LOG_MSG Examples, Perl Script Entry Points

• Calling a function without parameters or encoding format:

  VCSAG_LOG_MSG ("<sev>", "<msg>", <msgid>);
  VCSAG_LOG_MSG ("C", "Two files found", 140);
• Calling a function with one parameter, but without encoding format:

  VCSAG_LOG_MSG ("<sev>", "<msg>", <msgid>, "<param1>";
  VCSAG_LOG_MSG ("C", "$count files found", 140, "$count");
• Calling a a function with one parameter and encoding format:

VCSAG_LOG_MSG ("<sev>", "<msg>", <msgid>, "-encoding <format>", "<param1>");
VCSAG_LOG_MSG ("C", "$count files found", 140, "-encoding utf8", "$count");

Note that if encoding format and parameters are passed to the functions, the encoding format must be passed before any parameters.

VCSAG_LOGDBG_MSG

This function can be used to pass debug messages to the halog utility. At a minimum, the severity must be indicated along with a message. Optionally, the encoding format and parameters may be specified.

Severity (dbg)	An integer indicating a severity level, 1 to 21.
Message (msg)	A text message in quotes; for example: "One file copied"
Encoding Format	UTF-8, ASCII, or UCS-2 in the form: "-encoding format"
Parameters	Parameters (up to six), each within quotes

VCSAG_LOGDBG_MSG Examples, Shell Script Entry Points

• Calling a function without encoding or parameters:

  VCSAG_LOGDBG_MSG <dbg> "<msg>"
  VCSAG_LOGDBG_MSG 1 "This is string number 1"
• Calling a function with a parameter, but without encoding format:

  VCSAG_LOGDBG_MSG <dbg> "<msg>" "<param1>"
  VCSAG_LOGDBG_MSG 2 "This is string number $count" "$count"
• Calling a function with a parameter and encoding format:

  VCSAG_LOGDBG_MSG <dbg> "<msg>" "-encoding <format>" "$count"
  VCSAG_LOGDBG_MSG 2 "This is string number $count" "$count"

VCSAG_LOGDBG_MSG Examples, Perl Script Entry Points

• Calling a function:

  VCSAG_LOGDBG_MSG (<dbg>, "<msg>");
  VCSAG_LOGDBG_MSG (1 "This is string number 1");
• Calling a function with a parameter, but without encoding format:

  VCSAG_LOGDBG_MSG (<dbg>, "<msg>", "<param1>");
  VCSAG_LOGDBG_MSG (2, "This is string number $count", "$count");
• Calling a function with a parameter and encoding format:

  VCSAG_LOGDBG_MSG <dbg> "<msg>" "-encoding <format>" "<param1>"
  VCSAG_LOGDBG_MSG (2, "This is string number $count", "-encoding
     utf8", "$count");

Using the Functions in Scripts

The script-based entry points require a line that specifies the file defining the logging functions. Include the following line exactly once in each script. The line should precede the use of any of the log functions.

• Shell Script include file

  . ${VCS_HOME:-/opt/VRTSvcs}/bin/ag_i18n_inc.sh
• Perl Script include file

  use ag_i18n_inc;