Using the Monitoring Archive Utility

The monitoring archive, MAR file, contains one or more monitoring configurations. A monitoring configuration is a TIBCO Hawk rulebase template.

The MAR utility converts TIBCO Hawk rulebases into templates so that they can be deployed to any target within any TIBCO Administrator domain. A rulebase template, in a MAR file, has the extension .hrt.

The rulebases can contain the following types of rules:

Application-specific

These rules use the data source of the microagents belonging to TIBCO applications, such as TIBCO BusinessWorks or TIBCO Adapters. Each of these applications have a unique type.

Agent-specific or non-application specific

These rules do not use the data source of the microagents belonging to TIBCO applications.

If a rulebase contains multiple application-specific rules, the MAR utility splits a single rulebase into multiple rulebases where each rulebase contains rules with the data source from the same adapter type. The name of the templatized rulebase is suffixed with the type of the TIBCO application. For example, if the rulebase myRulebase.hrb contains rules using the microagents belonging to TIBCO ActiveMatrix BusinessWorks (of type bwengine) and TIBCO Adapter for Active Database (of type adb), then the resulting rulebases will be myRulebase-bwengine.hrt and myRulebase-adb.hrt.

If a rulebase contains only the agent-specific rules, the rulebase is not split into separate rulebases and neither is the rulebase name suffixed with any type. If you want the name of such a rulebase to be assigned a specific type, use the -Xtype option when creating the monitoring archive file.

If the rulebase contains one or more agent-specific rules and one or more application-specific rules, the rulebases are split into agent-specific and application-specific rulebases. For example, if the rulebase myMixedRulebases.hrb contains rules using the Logfile microagent and microagents belonging to TIBCO ActiveMatrix BusinessWorks (of type bwengine) and TIBCO Adapter for Active Database (of type adb). The resulting rulebases will be myMixedRulebases.hrt, myMixedRulebases-bwengine.hrt, and myMixedRulebases-adb.hrt.

The MAR utility will convert any six part data source to a seven part data source in the input rulebases.

For Example, if the data source in a rulebase is: COM.TIBCO.ADAPTER.<NAME>.<TIBCO_DEPLOYMENT>.<TIBCO_COMPONENT_INSTANCE>, the MAR utility will convert this data source to the following:

COM.TIBCO.ADAPTER.<NAME>.<TIBCO_DOMAIN>.<TIBCO_DEPLOYMENT>.<TIBCO_COMPONENT_INSTANCE>.

Note: If a rulebase contains a rule that contains an action that invokes a method from a TIBCO application which is different from the TIBCO application used in the data source, the rulebase will not be templatized and an error is generated. To allow other rules in the rulebase to be templatized, separate the rule that caused the error and run the mar tool again.
Note: Rulebases that use posted conditions will not work as expected if the posted condition is referred by the rules with different adapter types in the same rulebase. This is because the referred rulebase will be split into multiple rulebases.
Note: While creating or updating a MAR file (using the MAR utility), an incorrect rulebase type is assigned to the rulebase if the rulebase contains one application-specific and one or more agent-specific rules. This problem occurs only if an agent-specific rule is created first in the rulebase and the application-specific rule created later. If this happens, the Domain, Deployment, ComponentInstance values are not substituted. It is recommended that when creating or updating a MAR file, the –Xtype option is used to specify the type of the rulebase.

The MAR utility, mar, is located in the CONFIG_FOLDER/hawk/bin directory. The MAR utility requires TIBCO Runtime Agent 5.5.4 to be installed. Using the MAR utility you can:

Create a MAR file

To create a MAR file, use the command:

mar c[v]f <marfilename> <inputfiles> [-Xoptions] 
mar c[v]df <description> <marfilename> <inputfiles>     [-Xoptions]

Examples:

mar cvf myMarFile.mar ./

This command creates a MAR file myMarFile.mar that contains all rulebases in the current directory.

mar cdf "My test MAR file" myMarFile.mar ./

This command creates a MAR file myMarFile.mar that contains all rulebases in the current directory and includes the provided description.

mar cvf myMarFile.mar bw.hrb agent.hrb -Xtype adb

This command creates a MAR file myMarFile.mar of type adb and contains two rulebases adb.hrb and agent.hrb.

mar cvf myMarFile.mar ./ -Xasis

This command creates a MAR file myMarFile.mar that contains all rulebases in the current directory but without converting them into rulebase templates.

Update a MAR file

To update a MAR file, use the command

mar u[v]f <marfilename> <inputfiles> [-Xoptions] 
mar u[v]df <description> <marfilename> <inputfiles>     [-Xoptions]

Example:

mar uf myMarFile.mar newRB.hrb

This command add the rulebase newRB.hrb to the existing MAR file, myMarFile.mar.

Extract MAR file

To extract a MAR file, use the command

mar x[v]f <marfilename> <inputfiles> [-Xoptions] 
mar x[v]pf <propertiesfile> <marfilename> <inputfiles>     [-Xoptions]

Example:

mar xf myMarFile.mar testRB.hrb

This command extracts the rulebase testRB.hrb from the specified MAR file. Any other rulebase contained in the MAR file is not extracted.

mar xpf myprop.properties myMarFile.mar testRB.hrb

This command extracts the rulebase testRB.hrb from the specified MAR file and substitutes the variables in the rulebase using the key-value pair specified in myprop.properties file.

Any other rulebase contained in the MAR file is not extracted.

Following are the contents of a sample properties file used for variable substitution:

      TIBCO_DOMAIN=MyHawkdomain
      TIBCO_DEPLOYMENT=myDeployment
      TIBCO_COMPONENT_INSTANCE=myComponentInstance
List a MAR file

To extract a MAR file, use the command

    mar t[v]f <marfilename> 

Example:

mar tf myMarFile.mar

This command lists all rulebases contained in the specified file.

The following table describes the input parameters and options for the MAR utility.

MAR Utility: Input parameters and Options

Input

Description and Usage

marfilename

The name of the MAR file.

inputfiles

The files or directories (separated by spaces) that are combined into or extracted from the MAR file.

All directories are processed at the top level only. Only files with .hrb extensions are processed.

description

The description for the MAR file. If specified, the description must be placed within quotes (").

If the d option is specified, you have to provide a description. In the command, the options d and f must appear in the same order as the description and MAR file.

propertiesfile

The properties file contains the name-value pairs which is to be used for substituting variables in the rulebase template after the rulebase is extracted.

If the p option is specified, you have to specify the properties file. In the command, the options p and f must appear in the same order as the properties file and MAR file.

c

Creates a new archive file

u

Updates an existing MAR file by adding to it the files and directories specified by <inputfiles> parameter.

If the MAR file does not exist and the command results in adding a file, the MAR file is created.

x

Extracts files from a MAR file. If input files are specified, only those files are extracted; otherwise, all files are extracted.

If a properties file is specified, the values in the properties file are used for substituting variables when the rulebases are extracted. When a rulebase is extracted, the file extension changes to .hrb from .hrt.

t

Lists the rulebases in the MAR file.

v

Generates verbose output to standard output.

p

Specifies the properties file that contains name-value pairs that is used for substituting variables in the rulebase template.

f

Specifies the name of the MAR file.

-Xtype <type>,

where type is the unique identifier assigned to TIBCO applications.

This option is only valid for rulebase that contain agent-specific rules.

For rulebases that contain application-specific rules, this option will not apply.

For rulebases that contain agent-specific rules and an application-specific rule, option will have no effect on this rulebase.

This option will never override known type (where the type is determined from the data source of the rule).

See Types Assigned to TIBCO Applications for the list of valid types.

-Xasis

Do not templatize the rulebases.

Normally all the rulebases are templatized before adding to the mar file. This option will add the rulebase to the MAR file as is without parsing the rulebase for the data source type.

This option is useful for deploying rulebases created for a specific deployment or a component instance.

The MAR utility recognizes the datatype of any rule in a rulebase whose datasource name is in the following format: COM.TIBCO.ADAPTER.<NAME>.<TIBCO_DEPLOYMENT>.<TIBCO_COMPONENT_INSTANCE> or COM.TIBCO.ADAPTER.<NAME>.<TIBCO_DOMAIN>.<TIBCO_DEPLOYMENT>.<TIBCO_COMPONENT_INSTANCE>.

The following table lists valid values for some TIBCO applications that you can use when assigning a type to the MAR file.

Types Assigned to TIBCO Applications

TIBCO Application

Type

TIBCO Businessworks

bwengine

TIBCO Adapter for Active Database

adb

TIBCO Adapter for Siebel

adsbl

TIBCO Adapter for Files

adfiles

TIBCO Adapter for Oracle Applications

adorapps

TIBCO Adapter for SWIFT

adswift

TIBCO Adapter for EJB

adejb

TIBCO Adapter for COM

adcom

TIBCO Adapter for CORBA

adcorba

TIBCO Adapter for Teradata

adtera

TIBCO Adapter for Tuxedo

adtuxedo

TIBCO Adapter for Infranet

adinfra

TIBCO Adapter for PeopleSoft8

adpsft8