9 Operational Utilities

This chapter describes the following operational utilities of RPAS:

• Finding Alerts Using alertmgr

• Copying Domains Using copyDomain

• Moving a Domain Using moveDomain

• Setting Miscellaneous Domain Properties Using domainprop

• Using the mace Calculation Engine

• Managing the Workbook Batch Queue Using wbbatch

• Managing Workbooks Using wbmgr

• Registering Measures Using regmeasure

• Registering Token Measures Using regTokenMeasure

• Batch Plug-In Tasks: execPluginTask.sh

Finding Alerts Using alertmgr

Alerts are an exception management tool for users. An alert is a measure that evaluates a business rule (returning a value of true or false). RPAS then notifies users of the true conditions and allows users to build workbooks to resolve the scenario that drove the alert.

Alert measures are first defined in the domain using the RPAS Configuration Tools. These measures are of type Boolean, which means they have a value of true or false. Next, rules (expressions) are registered in the domain for the alert measures to define the business rules used to evaluate the alert.

After the registration process is complete, the alert utility is run to find the alerts in the domain. After the alert finder has been run, the identified alerts can be viewed in the Alert Manager window in the RPAS Classic Client.

The following is a summary of the process for defining and finding an alert:

1. Create an alert measure. This must be a Boolean measure (values are true-false or yes-no) and must be defined in the RPAS Configuration Tools. Its aggregation state and base state must be read-only.

2. Create the alert (the expression) for which the alert should be evaluated using the Configuration Tools. Using alertmgr, register the alert with a category, categoryLabel, and the above expression. This flags the registered measure as an alert so that it is recognized when the alert finder is run.

3. Repeat steps 1 and 2 for any additional alerts to be registered in the domain.

4. Run the alert finder on the domain to evaluate the number of instances in which one or more alert expressions are true. This operation is completed using the RPAS utility alertmgr.

alertmgr Usage

alertmgr -d domainPath [COMMAND [parameters]]
alertmgr -d pathtodomain -findAlerts {-navigationThresholdhits} {-alerts "a1 a2 …" | -categories "cat1 cat2 …"}

Note: This utility includes arguments that are not documented in this guide as it is recommended that those operations be configured using the Configuration Tools to ensure consistency between the configuration and the domain.

Table 9-1 provides descriptions of the arguments used by the alertmgr utility.

Table 9-1 Arguments Used by the alertmgr Utility

Argument	Description
-d pathToDomain	Specifies the directory in which to run the utility. All commands except -version require -d domainPath.
-findAlerts	Finds alerts in the specified domain. The utility will find all alerts in the domain if neither the -alerts or -categories arguments are specified. If the -alerts or -categories list are not specified, findAlerts is run on all alerts. findAlerts can be run from either Master or Local Domains.
-alerts a1 a2…	Evaluates specific alerts in the domain. a1 a2 … must be valid names of alerts that are defined in the domain.
-categories cat1 cat2 …	Evaluates all alerts in the domain that are associated with specific categories of alerts. cat1 cat2 … must be valid names of alert categories that are defined in the domain.
-sumAlerts	Sums up the hit counts of alerts across local domains. It can be run based on a list of alerts or alert categories. If none are provided, then the respective hit count of each alert across all local domains is summed. -sumAlerts can be used only from Master Domain. Note: -findAlerts must be run first to generate hit counts of alerts.
-navigationThreshold hits	Defines the maximum number of alert hits for the Find Next/Previous Alert functionality to remain operational in a workbook. If over that threshold, the Find Alert functionality will only work up to that number. The default value is 5000.

Note: The alertmgr utility can be run on the local domains individually. The administrator may spawn several processes in parallel and, when needed, run alertmgr -sumAlerts again to aggregate the results to the global domain. If parallelization is desired, the administrator should create a script to spawn the parallel processes.

Copying Domains Using copyDomain

The copyDomain utility is used to copy a simple domain, all domains included in a global domain environment, or a subset of domains in a global domain environment. Domains are often copied before the domains are upgraded after receiving a patch to RPAS.

For a standard, simple domain (in other words, not a global domain environment), copyDomain copies the domain directory recursively from one location to another.

For a global domain environment, copyDomain copies the master domain to the specified destination and then copies each local domain into the corresponding subdirectories of the new location. As part of this particular replication process, the utility also updates all relevant data structures so that the domains are properly connected together.

Relative paths are supported with this utility and are used when creating the new copies of all the underlying data structures (arrays). Relative paths are based on the full pathname of the domain's root directory.

copyDomain Usage

copyDomain -xmlConfigFile filename {OPTIONS}
copyDomain -d pathToSrc {OPTIONS}
copyDomain -version 

Table 9-2 provides descriptions of the arguments used by the copyDomain utility.

Table 9-2 Arguments Used by the copyDomain Utility

Argument	Description
-d pathToSrcDomain	Specifies the path of the domain to be copied. This argument and -dest should not be used with -xmlConfigFile.
-xmlConfigFile pathToXmlConfigFile.xml	Allows copyDomain to copy each subdomain into user-instructed specific locations. This argument should not be used with -d OR -dest. See "copyDomain: Format of the XML Configuration File" for the file format.
The following arguments are valid for -xmlConfigFile and -d:
-force	Deletes the existing domain at the specified destination path before copying the source domain.
-clone dimposlist	Copies a subset of a domain environment. Copies only positions specified in a format as dim1,pos1,...,posn:dim2,pos1,...,posn where the sequence dim1,pos1,...,posn specifies the selected positions along dim1. Multiple dimensions may be specified, but only one dimension per each hierarchy is allowed.
-partitionPositions positions	Deprecated. Use -clone instead.
-copyWorkbooks workbookList	Copies only the specified workbooks to the destination location. workbookList is either a comma-separated list of the workbooks to copy, or the value none such that no workbooks are copied. If this argument is not specified all workbooks in the environment are copied.
-skipInput	Do not copy the input directory located in the source domain.
-skipConfig	Do not copy the configuration directory located in the source domains.
-skipEmptyDir	Do not copy the empty directory located in the source domain.
-maxProcesses count	If this argument is specified, some parts of copyDomain run in parallel, utilizing up to the given number of processes.
-noSubDomains	Do not copy any local domains in the source domain.
The following arguments are valid only with -d:
-dest pathToDestDomain	Specifies the path to where the domain is to be copied. The copied domain can also be renamed in this step by providing a name different than the source domain.This argument must be provided when using any other option (other than -xmlConfigFile or -relativizePaths) of the utility. If this argument is not provided, the domain is updated to have relative paths.
-export	Exports each database from the source domain into a format that can be used on a UNIX platform. This argument cannot be used when specifying an -xmlConfigFile.
-gzip	Compresses the copied domain into a gzip format. This argument cannot be used when specifying an -xmlConfigFile.
-dimDictOnly	Copies only the source domain structure, metadata, and hierarchy data. Running copyDomain with this option result in a non-functional domain. Therefore, this argument should be used for diagnostic purposes only.
-relativizePaths	Updates the existing master and subdomain path references to relative paths. If the current absolute path references are invalid paths, subdomains are searched for in the same location as the master and within the master domain directory. When this argument is used, no domain copy is made. Note: When using this argument, do not provide a destination with the -dest argument. For example, if you build a domain, this is what it looks like at first: (PGRP100 INFO): "C:\Oracle\Domains\1323\mfprtl\ldom3" (PGRP200 INFO): "C:\Oracle\Domains\1323\mfprtl\ldom3" (PGRP21 INFO) : "C:\Oracle\Domains\1323\mfprtl\ldom0" (PGRP22 INFO) : "C:\Oracle\Domains\1323\mfprtl\ldom1" (PGRP300 INFO): "C:\Oracle\Domains\1323\mfprtl\ldom3" (PGRP31 INFO) : "C:\Oracle\Domains\1323\mfprtl\ldom2" (PGRP32 INFO) : "C:\Oracle\Domains\1323\mfprtl\ldom2" This tells you, by partition dimension, the path to the local domain. You can see that it is a full path and that the domains are subdirectories of the master domain. If you then run copyDomain with the -relativizePaths option, the paths look like the following: (PGRP100 INFO) : "ldom3" (PGRP200 INFO) : "ldom3" (PGRP21 INFO) : "ldom0" (PGRP22 INFO) : "ldom1" (PGRP31 INFO) : "ldom2" (PGRP300 INFO) : "ldom3" (PGRP32 INFO) : "ldom2"

Notes for copyDomain

Note the following:

• If the -dest or -pathToDestDomain arguments are not provided, the utility no longer makes the paths to the subdomains relative paths. Instead, use the -relativizePaths argument.

• When used with -clone or -noSubDomains, copyDomain does not affect workbook metadata or hierarchies.

• Workbooks that are not included in the list used with the -copyWorkbooks option are not included in the new domain.

• Any existing workbooks in a domain copied with the -clone or -noSubDomains options may not be able to be committed back to the new domain.

• When used with -dimDictOnly, the -clone or -noSubDomains options cannot be specified.

• The -dimDictOnly switch implies -copyWorkbooks none.

• Use -xmlConfigFile to specify destination locations for individual subdomains.

• To get the usage text, use -?, -help, or -usage.

• To get the version of this utility, use -version.

• To set the logger verbosity level, use -loglevel with the following values: all, profile, debug, audit, information, warning, error, or none.

• To disable timestamp header, use -noheader.

copyDomain: Format of the XML Configuration File

The XML configuration file contains source and destination fields for the location of the master domain and each of the subdomains. Here is a basic example:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rpas>
    <globaldomain>
        <srcPath>C:\usr\Rpas\Domains\GlobalDomain</srcPath>
        <dstPath>C:\usr\Rpas\Domains\GlobalDomain2</dstPath>
        <subdomain>
            <srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom0</srcPath>
            <dstPath>C:\usr\Rpas\Domains\GlobalDomain2\ldom0</dstPath>
        </subdomain>
        <subdomain>
            <srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom1</srcPath>
            <dstPath>C:\usr\Rpas\Domains\GlobalDomain2\ldom1</dstPath>
        </subdomain>
        <subdomain>
            <srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom2</srcPath>
            <dstPath>C:\usr\Rpas\Domains\ldom2</dstPath>
        </subdomain>
        <subdomain>
            <srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom3</srcPath>
            <dstPath>C:\usr\Rpas\Domains\ldom3</dstPath>
        </subdomain>
    </globaldomain>
</rpas>

The globaldomain tag should contain one srcPath tag, one stPath tag, and a subdomain tag for each subdomain. Each subdomain tag should contain one srcPath tag and one dstpath tag. Each srcPath tag should be a path to either the master or subdomain begins copied. Each matching dstPath tag should be a path to where to copy that part of the domain.

The copyDomain utility validates the configuration xml file first before any files are copied. If any of the subdomain source paths do not match a subdomain path of the global domain being copied, a "can't find source subdomain 'subdomain' ” error will be report. If the global domain being copied contains any subdomain that does not have a matching srcPath tag, a ”subdomain 'subdomain' doesn't have a subdomain xml tag" error will be reported. If the global domain srcPath tag does not contain the path of a valid global domain then an "invalid source path 'srcPath' to global domain" will be reported.

The destination paths in all cases is validated when that part of the global domain is being copied. Unless the switch -force is provided, the destination must not exist and must be writable.

There are two options that control the number of subdomains to be copied. These options still limit the number of subdomains that are copied; however, the configuration file must still contain entries for all domains.

Moving a Domain Using moveDomain

The moveDomain utility provides the flexibility to move elements of global domains such as individual local domains and the master domain to pre-specified locations based on a given XML configuration file. The utility automatically updates RPAS metadata to reflect the modified directory paths in local and master domains. This utility also ensures that the globalDomainConfig.xml file is updated as domains are moved.

The XML configuration being used is simple and designed to fit the required task. It contains fields for the locations of the source master domain and destination master domain as well as source and destination fields for each of the subdomains that need to be moved.

moveDomain Usage

moveDomain -version
moveDomain -xmlConfigFile filename
moveDomain -d master -srcSubDomain src -dstSubDomain dst

Table 9-3 provides descriptions of the arguments used by the moveDomain utility.

Table 9-3 Arguments Used by the moveDomain Utility

Argument	Description
-xmlConfigFile pathToXmlConfigFile.xml	Allows moveDomain to move a subdomain into user-instructed specific locations based paths specified in an XML file. This argument should not be used with the -d, the -srcSubDomain, and the -dstSubDomain parameters. See "moveDomain: Format of the XML Configuration File" for the file format.
-d pathTomaster	Allows moveDomain to move each subdomain based on the user-specified paths. Enter the path to the master domain.
-srcSubDomain src	Indicates the path of the subdomain to be moved.
-destSubDomain src	Indicates the path where the subdomain is to be moved.

moveDomain: Format of the XML Configuration File

The XML configuration being used is simple and designed to fit the required task. It contains fields for the locations of the source master domain and destination master domain as well as source and destination fields for each of the subdomains that need to be moved. Here is a basic example of the XML configuration file.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rpas>
    <globaldomain>
        <srcPath>C:\usr\Rpas\Domains\GlobalDomain</srcPath>
        <dstPath>C:\usr\Rpas\Domains\GlobalDomain2</dstPath>
        <subdomain>
            <srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom2</srcPath>
            <dstPath>C:\usr\Rpas\Domains\ldom2</dstPath>
        </subdomain>
        <subdomain>
            <srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom3</srcPath>
            <dstPath>C:\usr\Rpas\Domains\ldom3</dstPath>
        </subdomain>
    </globaldomain>
</rpas>

The globaldomain tag must contain a srcPath tag and dstPath tag for the master domain. The master domain is not moved if srcPath and dstPath are the same. It is essential to specify srcPath and dstPath for the master domain even if the master is not intended to be moved; otherwise an error condition will be incurred.

The srcPath and dstPath tags for local domains are required only if the local domain is intended to be moved; otherwise, the lack of tags for a specific local domain indicates that the local domain will not be relocated. If srcPath and dstPath are identical for a given local domain, it will not be moved.

When global domain srcPath and dstPath are different, that is, when moving global domains, all local domains that reside under the global domain folder and are not included in the XML file, will be moved to the destination global domain folder. Other local domains with a specified destination location will be moved according to the configuration.

Assumptions and Requirements

The following rules apply to the XML configuration settings:

• All source and destination paths must be absolute.

• All source paths must correspond to existing directories.

• All destination paths must be valid, in the sense that:

  • The parent of the destination directory must exist.

  • The parent directory must be writable by the user.

  • The destination directory itself must not exist.

  • The source and destination master domain paths are required.

• The source and destination subdomain paths are required only for the domains that must be moved.

• The subdomains that must be moved can be specified or those subdomains that will remain under the master domain can be left out. If a subdomain is not specified, it will be moved along with the master domain.

• If the xmlConfigFile contents do not abide by the above mentioned rules, the utility does not clear the validation phase and terminates with the appropriate error message.

Minimum Space Requirement

Minimum space requirement for moving a global domain is the size of (only) the master domain plus the size of the largest local domain.

Setting Miscellaneous Domain Properties Using domainprop

Use the domainprop utility to manipulate the properties of a domain. Specify password properties, lock user accounts, and determine whether or not a daemon is currently managing a domain. The domainprop utility can be run on a global domain master to set values in all subdomains.

domainprop Usage

domainprop -d pathToDomain {-property propertyname=value}  

Table 9-4 provides descriptions of the arguments used by the domainprop utility.

Table 9-4 Arguments Used by the domainprop Utility

Argument	Description
-d pathToDomain	Specifies the domain path.
-property propertyname=value	Specifies the property to be changed. See Table 9-5 for a list of properties that can be set with this utility. To view the current property setting, use the property command with no value.
-reportSubDomains	Shows property values for subdomains (should all match).

Available Properties

Table 9-5 Available Properties for the domainprop Utility

Domain Property Name	Type	Description
disable_commit_asap	Boolean	If this property is set to TRUE, the ability to use "Commit ASAP" in the File menu of the RPAS Client is disabled. Furthermore, the "Commit ASAP" radio button on the workbook close dialog is disabled. By default, this property is set to FALSE.
disable_commit_later	Boolean	If this property is set to TRUE, the ability to use "Commit Later" in the File menu of the RPAS Client is disabled. Furthermore, the "Commit Later" radio button on the workbook close dialog is disabled. By default, this property is set to FALSE.
domain_name	String	If this property is set, the domain name is displayed on the "About" page of the RPAS Client (menu Help > About).
insert_measure_disabled	Boolean	If this property is set to TRUE, the "insert measure…" item under the Edit menu is disabled. By default, this property is set to FALSE.
help_path	String	This property defines the path to the help files. It is set when using custom help files for the RPAS Client instead of the default help files that are provided with the RPAS Client installation. These files must be in WebHelp format. This path is normally a path to a network folder where the common help files are located. The folder must have a file named "Start.htm". This file is the starting point for the custom help. The default RPAS help has several pages for context-sensitive help. Help searches for these folders in the preset relative location from the root folder of WebHelp. If an implementation uses custom help, it must locate the context help files in the expected default locations relative to that folder. Otherwise, context-sensitive help will not be available and an error will occur every time the user tries to invoke context- sensitive help for a particular function. If this property is not set, the path specified in the foundation.ini file of the Client machine is used. If a path is not specified in that file, help looks in the default location in the RPAS Client installation for help files. If the default files have been removed, help is not available. For the location of the foundation.ini file, see "Translation Administration".
meas_fillclr_precedence	Boolean	By default, when deciding which color to fill a particular cell with, the RPAS grid uses the following order of formatting settings: Read-only, Measure, Hierarchical, and then Read/Write. That is, if the cell is in a read-only state, it will use the read-only formatting setting. However, if that is not the case, the grid will check if there is any Measure level formatting. Failing to find it will fall through to checking for the hierarchical setting and then the read-write setting. However, some customers want RPAS to follow a different priority order for fill color formatting decision making. They may want it to try Measure, then Read-only, then Hierarchical, and finally Read/Write. This change from default can be made by setting this domain property to TRUE. To reset behavior, this domain property can be reset to FALSE.
measure_locking_disabled	Boolean	If this property is set to FALSE, the user can lock a measure on a work sheet. By default, this property is set to FALSE. To disable measure locking, set this property to TRUE.
ovr_def_admin_privileges	Boolean	Using the Security Administration workbook, administrators can set workbook template access for every user in the system. Non-administrative users cannot access the workbook templates to which they have not explicitly been given access. However, if a user is an administrator, by default that user can see all the workbooks in the system. Some retailers want to prevent this from happening. Reasons for this include reducing clutter and having different kind of administrators who manage different administrative tasks in their RPAS systems. Ability to control template access for administrators from the Security Administration workbook is made possible by setting this domain property to TRUE. By default, this property is FALSE.
r_upgrade_hash_alg	Integer	Sets the value for r_crypt_hash_alg in the upgraded domain. Because the list of algorithms can change with each release, it is not feasible to provide a list here. To get the list of values that can be used here, go to the rpasHome of the version to which you are upgrading and run: usermgr -listHashAlgs
r_upgrade_has_iter	Integer	This property sets the value for r_crypto_hash_iter in the upgrade process. It is the number of iterations of hashing to perform on the password.

Using the mace Calculation Engine

The mace utility (Multi-dimensional Array Calculation Engine) allows the administrator to evaluate rule groups or expressions in order to manipulate measures. The mace utility supports the use of the RPAS calculation engine in batch.

The mace utility is most commonly used to run a rule group or an expression, but can also be used to:

• create rules and rule groups

• add rules to rule groups

• add expressions to rules

• delete rules not contained in a rule group

• remove any or all rule groups

• validate expressions

• print a list of rules or rule groups

Parallelization

The mace utility can execute in parallel under the following circumstances:

• The utility must be invoked on a master domain.

• Parallelization is only applicable to single-expression evaluation (-run -expression argument). Parallelization does not apply to rule group evaluation.

• The evaluated expression cannot be a SpecialExpression.

• All of the measures appearing on the left-hand side of the expression must be non-HBI; that is, the base intersection of the measures must be below the partition level.

The mace utility creates multiple child processes based on the -processes argument, and each child mace process evaluates the expression in one local domain. This functionality enables mace to achieve higher levels of CPU utilization using parallelization on systems with multiple CPUs. It also simplifies the user script when the same expression must be evaluated in all local domains.

Centralization

When mace is run on a master domain, the following command line options apply to the master as well as all local domains. For example, running mace -d domain -newRule … creates a new rule in the master and all local domains.

• -newRule: create a new rule in the domain

• -delRule: delete an existing rule from the domain

• -addRule: add a new rule to a specific rule group

• -removeRule: remove an existing rule from a specific rule group

• -newGroup: create a new rule group in the domain

• -remove Group: remove an existing rule group from the domain

• -addExpression: add an expression to a specific rule

• -purgeRules: remove all rules not contained in any rule group from the domain

• -removeAllRuleData: remove all rule and rule group data from the domain

The behavior and usage of the following commands is unchanged:

• -find: search all expressions for the specific measure and print all rules and rule groups that use it

• -check: validate the specific expression

• -resolve: order but do not evaluate expressions within the rule group

• -transit: rule calc engine by transitting over a list of rule groups

• -print: print all specific rules and groups

• -validate: validate rule groups

mace Usage

mace -version
mace -d domainPath -find string
mace -d domainPath -newRule {-ruleName ruleName} {-label ruleLabel}{-processes numProcesses}
mace -d domainPath -delRule ruleName (-processes numProcesses}
mace -d domainPath -addRule     groupName:ruleName {-processes numProcesses}
mace -d domainPath -removeRule  groupName:ruleName {-processes numProcesses}
mace -d domainPath -newGroup    groupName {-label groupLabel}{-processes numProcesses}
mace -d domainPath -removeGroup groupName {-processes numProcesses}
mace -d domainPath -addExpression ruleName -expression exprString{-processes numProcesses}
mace -d domainPath -check -expression exprString
mace -d domainPath -run -group groupName      {-debugRuleEngine}
mace -d domainPath -run -expression expString {-processes numProcesses}{-debugRuleEngine}
mace -d domainPath -resolve groupName -measures measList {-debugRuleEngine}
mace -d domainPath -transit workbookName -group groupList {-debugRuleEngine}
mace -d domainPath -print -rule  ruleList
mace -d domainPath -print -group groupList
mace -d domainPath -print -allGroups
mace -d domainPath -purgeRules {-processes numProcesses}
mace -d domainPath -removeAllRuleData {-processes numProcesses}
mace -d domainPath -validate calc    -ruleGroup groupName
mace -d domainPath -validate general -ruleGroup groupName
mace -d domainPath -validate refresh -ruleGroup groupName -calcRuleGroup calc
 

Table 9-6 provides descriptions of the arguments used by the mace utility.

Table 9-6 Arguments Used by the mace Utility

Argument	Description
-d domainPath	Specifies the domain in which to load the measure.
-find string	Searches all expressions for the specified string and prints all the rules and rule groups that have these expressions.
-newRule {-ruleName ruleName}	Creates a new empty rule. If desired, use the -ruleName argument to specify a name for the rule.
-label {ruleLabel | groupLabel	Specifies the label of the rule with the -newRule argument or label of the group with the -newGroup argument.
-processes numProcesses	Specifies the number of child processes to be run in parallel.
-delRule ruleName	Removes the specified rule.
-addRule groupName:ruleName	Adds the specified rule to the group specified by groupName.
-removeRule groupName:ruleName	Removes the specified ruleName from the group specified by groupName.
-newGroup groupName	Creates a new rule group with the specified name.
-removeGroup groupName	Removes the specified group and non-shared rules in it.
-addExpression ruleName	Adds an expression to the specified rule. The -expression should be used with this argument.
-check	Validates the specified expression. The -expression should be used with this argument.
-run	Evaluates the specified expression or rule group. The -expression should be used with this argument.
-resolve groupName	Orders (does not evaluate) expressions within rule group. Requires a comma-separated list of edited measures.
-transit workbookName	Runs a calc engine by transitioning over a list of rule groups. Requires the name of an existing workbook and a comma-separated list of rule-group names.
-print {ruleList | groupList | true}	Prints all the specified rules and rule groups. The ruleList is a comma-separated list of rule names. The groupList is a comma-separated list of group names. If "true" is supplied for either ruleList or groupList, all rules or rule groups are printed.
-purgeRules	Removes all rules not contained in any rule groups.
-removeAllRuleData	Removes all rule groups and all rules.
-validate {calc | general | refresh}	Validates rule groups. Use calc to validate a calc rule group. To validate a refresh rule group, use the refresh parameter along with -calcRuleGroup to specify the corresponding calc rule group. For all other types of rule groups, use general.
-debugRuleEngine	Generates a file mace.log in the working directory for logging RuleEngine specific debug information.
-expression exprString	Specifies the expression. This argument is used in conjunction with the -addExpression, -check, and -run arguments.
-group groupName	Specifies the rule group to evaluate using the -run argument.
-measures measureList	Specifies the measures to resolve.
-group groupList	Specifies a list of group names, separated by commas. Use this argument in conjunction with the -transit and -print arguments.
-rule ruleList	Specifies a list of rule names, separated by commas. Use this argument in conjunction with the -print argument.
-allGroups	Use this argument in conjunction with the -print argument to print all rule groups.
-addGroup	Creates a new rule group with the specified name
-beginBatch	Instructs mace to set the batch status flag for domains integrated with an RPAS Data Mart.
-endBatch	Instructs mace to perform the end-of-batch data synchronization and clean-up operations associated with the conclusion of a batch process for a domain integration with an RPAS Data Mart.
-abortBatch	Instructs mace to perform the clean-up operations associated with the early termination of a batch process in a domain integrated with an RPAS Data Mart.

mace Restrictions in Global Domains

Problems were found when running simple rule groups using the mace utility. Mace did not allow executing a rule group consisting of non-HBI measures from the master domain for the following reasons:

1. Even though the rule group contains only non-HBI measures, mace was not designed to run it from the master domain and spawn it across local domain as it required too many checks to make it work differently for special expressions as sometimes the special expressions could take more than one left-hand side measure and some of them could be HBI and some non-HBI.

2. It is not a properly configured rule group if the expressions in the rule group have both HBI and non-HBI measures which need to be evaluated. RPAS may not be able to detect this at the time of configuring the solution as the partition dimension can be changed in the globalDomainConfig.xml.

3. The rule group may contain special expressions and regular RPAS expressions (as in 1 and 2) and that adds to the complexity to the rule engine to properly evaluate these expressions when run from the master domain.

4. The above restrictions do not apply when mace is run on a single expression where the LHS can be a HBI or non-HBI measure.

There is only one situation where a rule group can be run from the master domain and that is when all the LHS measures of the expressions in the rule group are HBI measures. This type of rule group cannot be run from local domains and needs to be run from the master domain.

Proper validation is added to the mace utility to identify these conditions and flag them to the user and exit gracefully. The Oracle Retail Predictive Application Server Administration Guide will be updated with these additional validation points in future release. The following validations are added:

1. If mace is executed against a master domain and the executing expressions within the rule group contain non-HBI measures on the left-hand side of expressions, excluding special expressions, mace exits with an exception.

2. If mace is executed against a local domain and the executing expressions within the rule group contain an HBI measure on the left-hand side, excluding special expressions, mace outputs a warning message but the execution continues.

The end result is that mace cannot execute a rule group that contains non-HBI measures on the LHS against the master domain and provides a warning when running a rule group with HBI measures on the LHS against a local domain.

Executing mace in an Integrated Environment

When operating on a domain that shares data through an RPAS Data Mart, mace may encounter situations in which one or more of the measures involved in a calculation are shared measures whose data is stored within the RDM. To support this situation, users can make use of the -beginBatch and -endBatch operations to cause mace to interact with the RPAS Data Mart associated with a domain during calculation.

The use of -beginBatch sets a status flag within the domain. When this status is active, mace evaluates all rule groups for the presence of shared measures prior to execution. In the case where shared measures are present in the calculation, mace makes use of the transferFactData utility to fetch the measure data for the shared fact from the RPAS Data Mart.

For the duration of the batch operation, shared measures whose data are updated by mace hold their data within the domain. At the conclusion of the batch, if mace is called with the -endBatch operation, mace determines the set of shared measures whose data has been modified and writes those measures back to the RPAS Data Mart.

Upon successful completion of the write-back operation, mace deletes the temporary measure copies within the domain and clears the status flag set by -beginBatch. If an error results in the need for a batch process to end prior to the point where -endBatch would normally complete the batch process, the -abortBatch operation will clear the status flag set by -beginBatch without performing the write-back of data to the RPAS Data Mart. This prevents partially or incorrectly updated data from entering the RDM.

The following error and warning conditions exist in association with -beginBatch ,-endBatch and -abortBatch:

• A second call to -beginBatch without either -endBatch or -abortBatch having been called.

• A call to -endBatch without -beginBatch having first been called.

• Any mace call that evaluates an expression (-run -group or -run -expression), if any included measure is an RDM-shared measure, and -beginBatch has not first been called.

• Any call to -beginBatch, -endBatch, or -abortBatch with the -d parameter referencing a subdomain.

The following conditions are reported by mace as a warning, with a successful (zero) return code:

• A call to -abortBatch or -printBatchStatus when -beginBatch was not first called.

• A call to -beginBatch, -endBatch, or -printBatchStatus on a domain that is not HSA-integrated.

Managing the Workbook Batch Queue Using wbbatch

The wbbatch utility is used to manage workbook batch categories and workbooks in the workbook batch queue. The workbook batch queue is updated by using the standard RPAS wizard Auto Workbook Build or using various options of the wbbatch utility.

The most common use of this utility is to build workbooks that have been scheduled to be automatically built using the Auto Workbook Build wizard in the RPAS clients. It is also used to add, update, and delete batch categories, update assignments of workbook build entries to workbook batch categories, provide workbook batch categories when adding workbooks to the refresh queue, and update the assignments to workbooks already in the refresh queue.

When a user defers a workbook commit (using Commit Later), that workbook commit process is added to the Commit Later queue, which is committed using this utility. An administrator can also add a workbook to the commit later queue with this utility.

RPAS provides the ability to update workbook data with domain data without having to rebuild the workbook; this refreshing process is completed using a workbook's default refresh rule group. Workbooks are added to the queue to be refreshed and refreshed using this utility.

The build and refresh operations can be executed in multiple, parallel processes using the -processes argument.

wbbatch Usage

wbbatch -version
wbbatch -d pathToDomain -build queueIndex
wbbatch -d pathToDomain -refresh workbookName
wbbatch -d pathToDomain -commit workbookName
wbbatch -d pathToDomain -scheduleRefresh workbookName [-category categoryName]
wbbatch -d pathToDomain -unscheduleRefresh workbookName
wbbatch -d pathToDomain -scheduleCommit workbookName
wbbatch -d pathToDomain -unscheduleCommit workbookName
wbbatch -d pathToDomain -startQueue [all|build|refresh|commit] [-processes max][-categories catName1,catName2]
wbbatch -d pathToDomain -printQueue [all|build|refresh|commit]
wbbatch -d pathToDomain -listCategories
wbbatch -d pathToDomain -addCategories catName1:Label1,catName2:Label2
wbbatch -d pathToDomain -deleteCategories catName1,catName2
wbbatch -d pathToDomain -changeCategoryLabels catName1:NewLabel1, catName2:NewLabel2
wbbatch -d pathToDomain -queue build -updateCategories queueIndex1:newCatName1, queueIndex2:newCatName2
wbbatch -d pathToDomain -queue refresh -updateCategories workbookName1:newCatName1, workbookName2:newCatName2

Table 9-7 describes the arguments used by the wbbatch utility.

Table 9-7 Arguments Used by the wbbatch Utility

Argument	Description
-d pathToDomain	Specifies the domain containing the workbooks.
-build queueIndex	Runs workbook build for provided queueIndex.
-refresh workbookName	Refreshes workbooks scheduled to be refreshed using this utility. To refresh a single workbook in the queue, specify the name of the workbook. If no name is provided, all workbooks scheduled to be refreshed will be completed.
-commit workbookName	Commits workbooks with deferred commits. To commit a single workbook in the commit later queue, specify the name of a workbook. If no name is provided, all workbooks in the commit later queue will be committed.
-processes count	Used with either -build or -refresh to build or refresh workbooks in the auto-workbook queue in parallel using the specified number of parallel processes.
-scheduleRefresh	Schedules a workbook to be refreshed later by adding it to the workbook refresh batch queue. If the -category option is specified, the scheduled workbook will be in that category. Otherwise, it will be in the default category.
-unscheduleRefresh workbookName	Removes a workbook from the workbook refresh batch queue.
-scheduleCommit workbookName	Schedules a workbook to be committed later by adding it to the workbook commit batch queue.
-unscheduleCommit workbookName	Removes a workbook from the workbook commit batch queue.
-startQueue	Runs all workbooks in provided queue. The queue options are build, refresh, and commit. If the -category option is used and one or more categories are specified, only the workbooks in those categories are built or refreshed. Categories do not apply to committing.
-printQueue	Prints the contents of the queue argument. The queue indexes for auto workbooks in the build queue are shown when printing the build queue. If ”all” is specified, all three queues (build, refresh, and commit) are displayed.
-listCategories	Lists both the name and label for all categories.
-addCategories Name1:Label1, Name2:Label2, Name3:Label3	Adds a new category by providing a name and label, separated by a colon. Multiple categories can be specified on the same command line if separated by a comma. If the users use a different language other than the one typed in the command line, the administrator should use the Workbook Batch Category Management wizard to create new categories.
-deleteCategories catName1, catName2	Deletes a category by specifying the name of that category. Multiple categories can be deleted if separated by a comma.
-changeCategoryLabels Name1:NewLabel1, Name2:NewLabel2	Changes the label of an existing category by specifying the category name and providing a new category label. If the users use a different language other than the one typed in the command line, the administrator should use the Workbook Batch Category Management wizard to change category labels.
-updateCategories queueIndex1:newCatName1, queueIndex2:newCatName2 Or: -updateCategories wbName1:newCatName1, wbName2:newCatName2	Updates the category for an entry in the build queue or to change the workbook category of an existing entry in the refresh queue. Multiple category assignment for workbook auto build queue entries and refresh entries can be updated. If using the -build option, list the queue index. If using the -refresh option, list the workbook name. Build example: wbbatch -d pathToDomain -queue build -updateCategories queueIndex1:newCatName1, queueIndex2:newCatName2 Refresh example: wbbatch -d pathToDomain -queue refresh -updateCategories workbookName1:newCatName1, workbookName2:newCatName2

Managing Workbooks Using wbmgr

Use the Workbook Manager utility to inspect or remove the existing workbooks. It is recommended that administrators use this utility to remove workbooks rather than doing so manually.

wbmgr Usage

wbmgr -version
wbmgr -d pathToDomain -list -all
wbmgr -d pathToDomain -list -user userName
wbmgr -d pathToDomain -print  -wbList wb1,wb2,...
wbmgr -d pathToDomain -remove -all
wbmgr -d pathToDomain -remove -user userName
wbmgr -d pathToDomain -remove -user userName -wbList wb1,wb2,...

Table 9-8 provides descriptions of the arguments used by the wbmgr utility.

Table 9-8 Arguments Used by the wbmgr Utility

Argument	Description
-d pathToDomain	Specifies the domain that contains the workbooks.
-list -all	Lists all workbooks in the domain.
-list -user userName	Lists all workbooks belonging to the user.
-print -wbList wb1,wb2,...	Prints detailed information about workbooks in the list.
-remove -all	Removes all workbooks from the domain.
-remove -user userName	Removes all workbooks from the domain belonging to the specified user.
-remove -user userName -wbList wb1,wb2	Removes all the workbooks in the specified list for the specified user.

Registering Measures Using regmeasure

The regmeasure utility is used for batch measure registration. The following functionality is included:

• Register a new measure in the user-specified domain with the user-specified measure properties. If the domain specified by the user is a global domain, this measure will be registered in the master domain and all its local domains. The user must provide a minimum set of measure properties, type, and base intersection. Other measure properties are optional, such as default aggregation and spreading method. If the user omits an optional measure property, the measure will be registered with default value of that property.

• Unregister an existing measure identified by its name from the user-specified domain. If the specified domain is a global domain, this measure will be removed from the master domain and all local domains. Unregistering a measure from a domain causes the measure definition and all the related measure data arrays and supporting arrays to be removed from the domain.

• Modify measure properties of an existing measure. Not all measure values can be modified, such as type, base intersection, NV value, and database name. These properties cannot be changed once the measure is registered. Measure properties such as default aggregation method, default spread method, base state, agg state, and so on can be modified after the measure is registered.

regmeasure Usage

regmeasure -version
regmeasure -d pathToDomain -add measureName -type typeName(-baseint baseIntersection|-scalar) {-label labelString} {-db dataDbPath}{-navalue naValue} {-defagg aggType} {-defspread spreadType}{-allowedaggs "aggType1 aggType2"}{-refreshable (true|false)} {-insertable (true|false)}{-basestate (read|write)} {-aggstate (read|write)}{-stageonly (true|false)} {-filename fileName}{-loadint loadIntersectionString} {-clearint clearIntersectionString}{-loadstokeep loadsToKeep} {-start fieldStart} {-width fieldWidth}{-loadagg loadAgg} {-range range} {-purgeage purgeAge} {-viewtype viewType}{-syncwith syncWith} {-description descriptionString} {-picklist}{-materialized (persistent|display)}{-lowerbound measurename} {-upperbound measurename}{-attr attrName -attrpos attrPosName} {-scriptname scriptName}{-specialval action:specval:behavior,action:specval:behavior,...} {-fnhbi}{-hybridaggspec hiername:aggop,hiername:aggop,...}{-periodstartvalue (true|false)}

regmeasure -d pathToDomain -modify measureName {-label labelString}{-defagg aggType} {-defspread spreadType} {-allowedaggs "aggType1 aggType2..."}{-refreshable (true|false)} {-insertable (true|false)}{-basestate (read|write)} {-aggstate (read|write)}{-stageonly (true|false)} {-filename fileName}{-clearint clearIntersectionString}{-loadstokeep loadsToKeep} {-start fieldStart} {-width fieldWidth}{-loadagg loadAgg} {-range rangeString} {-purgeage purgeAge|-clearPurgeAge}{-viewtype viewType} {-syncwith syncWith} {-description descriptionString}{-picklist|-nopicklist} {-materialized (persistent|display)}{-lowerbound measureName} {-upperbound measureName}{-attr attrName -attrpos attrPosName} {-scriptname scriptName}{-specialval action:specval:behavior,action:specval:behavior,...}{-hybridaggspec hiername:aggOp,hiername:aggOp,...}{-periodstartvalue (true|false)}
regmeasure -d pathToDomain -remove measureName

Table 9-9 provides descriptions of the arguments used by the regmeasure utility.

Table 9-9 Arguments Used by the regmeasure Utility

Argument	Description
-d pathToDomain	Specifies the path to the domain. A valid domain path must be specified.
-add measureName	Adds a measure with the specified name. Set the values for the measure by using the required arguments and any of the optional arguments. Measure names can be up to 30 characters long.
-type typeName	Specifies the measure data type. It can be set to int, real, string, date, or boolean. Required with the -add option. Not available with the -modify option.
-baseint baseIntersection|-scalar	Specifies the base intersection of the measure. Non-scalar measures must use the -baseint option. Scalar measures must use the -scalar option. Required with the -add option. Not available with the -modify option.
-label labelString	Specifies the measure label. If not specified, it defaults to the measure name specified for the -add option.
-db dataDbPath	Specifies the database path for the measure's data arrays. A valid database path name must be specified. If not specified, the measure will be registered without a database. As a result, the measure will not be able to store any data in the domain. However, if the measure is not a Display only type, it will still be assigned a database in the workbook. Not available with the -modify option.
-navalue naValue	Specifies the na value for the measure's base level data array. The navalue must be the same type as the measure. For date, the navalue must be formatted as 'YYYYmmddHHMMSSsss'. If not specified, it defaults to the type's default value: 0 for numeric type, false for boolean type, an empty string for string type, and 0001/01/01 for date type. Not available with the -modify option.
-defagg aggType	Specifies the default aggregation method for the measure. It must be an aggregation name valid for the type of measure. For a list of valid aggregation type names, see the RPAS Configuration Tools User Guide. If not specified, it defaults to the measure type's default aggregation method: Total for int and real, Ambig for string and date, and OR for boolean.
-defspread spreadType	Specifies the default spread method for the measure. It must be a spread method valid for the type of measure. For a list of valid spread methods, see the RPAS Configuration Tools User Guide. If not specified, it defaults to the measure type's default spread method: Ratio for int and real, and Replicate for string, date, and boolean.
-allowedaggs "aggType1 aggType2..."	Specifies a list of aggregation methods that are allowed for this measure. The aggregation methods must be valid for the type of measure. If not specified, it defaults to the default allowed aggs for the type of measure. For numeric (int or real type) measures: total, total_pop, first, first_pop, last, last_pop, min, min_pop, max, max_pop, average, average_pop, popcount, nobcount, ambig, ambig_pop, none, period_start_total, period_end_total, period_start_average, period_end_average, median, median_pop, recalc, hybrid. For string type measures: ambig, ambig_pop, none, popcount, nobcount, first, first_pop, last, last_pop, recalc, hybrid. For date type measure: ambig, ambig_pop, pop_count, nob_count, first, first_pop, last, last_pop, min, min_pop, max, max_pop, non, recalc, hybrid. For boolean measure: boolean_and, boolean_or, pop_count, nob_count, ambig, ambig_pop, none, first, first_pop, last, last_pop, recalc, hybrid.
-refreshable (true|false)	Note: This option is no longer supported but is kept for compatibility.
-insertable (true|false)	Specifies whether the measure can be dynamically inserted into the workbook. If not specified, it defaults to true.
-basestate (read|write)	Specifies the workbook access right for the base array of the measure. If not specified, it defaults to read. The access rights of this measure will be further restricted by the RPAS security features. As a result, write access specified by this option does not guarantee write access of this measure in a specific workbook.
-aggstate (read|write)	Specifies the workbook access right for the aggregated level of the measure. If not specified, it defaults to read. The access rights of this measure are further restricted by the RPAS security features. As a result, write access specified by this option does not guarantee write access of this measure in a specific workbook.
-stageonly (true|false)	Specifies whether the measure is a stage only measure. If not specified, it defaults to false. Measure data loaded by loadmeasure for stage only measures are not automatically applied to the measure's base data array. User intervention is usually required to manually approve the loaded measure data and apply the approved loads to the measure's base data array.
-filename fileName	Specifies the file name of this measure's loading file. It should not include any extensions. If not specified, it defaults to the measure name in lower case.
-loadint loadIntersectionString	Specifies the intersection to load data for this measure. It must be a valid intersection string that is either the same or lower than the base intersection of this measure. If loadint is lower than the base intersection of the measure, the aggregation method specified by the -loadagg option will be used to aggregate the loaded data to the base array of the measure. Not available with the -modify option.
-clearint clearIntersectionString	Specifies the clear intersection for the clear load of this measure. For more information on the various loading methods including clear load, refer to the Loading Measure Data - loadmeasure section in this guide.
-loadstokeep loadsToKeep	Specifies the number of temporary measure load arrays to be kept in the staging database. If not specified, it defaults to 1.
-start fieldStart	Specifies the starting column of this measure's data in the measure loading file. If not specified, it is calculated based on the loadint of the measure.
-width fieldWidth	Specifies the number of characters this measure's data occupies in the measure loading file. If not specified, it defaults to the default width of the measure type: 8 for integer, real, and date, 24 for string, and 1 for boolean.
-loadagg loadAgg	Specifies the aggregation method used to aggregate the temporary load array to the measure's base array if the measure's loadint is lower than its baseint. If not specified, it defaults to the measure type's default aggregation method: Total for int and real, Ambig for string and date, and OR for Boolean.
-range rangeString	Specifies the valid range for the measure. The value of the range parameter depends on the measure type. For int or real types, the format is min:max, where min is the lowest possible value of the measure and max is the highest possible value of the measure. For picklist measures, to give the allowed options, the format of the string argument is 'a(Label A),b(Label B),c,d', where a, b, c, and d are allowed measure values and Label A and Label B are optional labels for the values. In addition, the list of allowed options can be changed dynamically with the cell the user is clicking in. For this functionality, the measure's range is specified as 'measurerange=measurename' where measure name is the name of the measure that contains strings in the above format of value/label pairs. For date types, the range must be in the format MMddyyyyhhmmss:MMddyyyyhhmmss, where the first string is the starting date and time of the range and the second date is the ending date and time of the range. If you omit the time portion of the string (hhmmss), the default time is used. The default lower bound is 000000 (12:00:00AM), which is used for the beginning of the day. The default upper bound is 235959 (11:59:59PM), which is used for the end of the day. If the range begins with a negative number (which may confuse the command-line argument parser), enclose the entire range string in square brackets, such as -range [-10:10].
-purgeage (purgeAge)	Specifies the number of days (or whatever the base dimension of the calendar hierarchy is) of measure data that should be kept in the measure's base data array after the measure load. This is used to keep the measure's data size small. If not specified, it defaults to -1, in which case the measure data will never be purged. When using the -modify option, -purgeage or -clearPurgeAge can be specified.
-clearPurgeAge	Resets the number of days (or whatever the base dimension of the calendar hierarchy is) of measure data that should be kept in the measure's base data array after measure load to -1. This means that the measure data is never purged. clearPurgeAge is only available with the -modify option. When using the -modify option, -purgeage or -clearPurgeAge can be specified.
-viewtype viewtype	Specifies the view type of this measure on the RPAS Client. The valid values are: 0 for none, 1 for view_only, 2 for sync_first_lag, 3 for sync_lead_last, 4 for sync_first, and 5 for sync_last. If not specified, it defaults to none. If the view type starts with "sync", the measure is called a 'Virtual Measure'. A measure of sync_first_lag type must have two sync measure names specified by the -syncwith option. The first syncwith measure name is a 'Period Start Value' type of measure, like opening stock. Measure data at the beginning period of the calendar is synchronized with this period start value kind of measure. The subsequent measure data is synchronized with the other measure data but lagged one period. A measure of sync_lead_last type must have two sync measure names specified by the -syncwith option. The first measure is a 'Period End Value' type of measure. Measure data at the last period of the calendar is synchronized with this period end value. Measure data of previous periods is synchronized with the other measure lead one period data. A measure of sync_first type must have one measure name specified by the -syncwith option. The data of the beginning period is synchronized with this syncwith measure. A measure of sync_last type must have one measure name specified by the -syncwith option. The data of the ending period is synchronized with this syncwith measure. Measures of view_only type are non-persistent. View only measures can only be used in workbooks. Their measure data is calculated during the Fetch process using a calc expression usually specified in the workbook's calc rule group.
-syncwith syncWith	Specifies the measures that the measure must be synchronized with. This option must be specified if the measure is not a virtual measure. For sync_first_lag and sync_lead_last measures, the syncwith option must have two measure names separated by a comma. The first measure is used to synchronize the data at the first or the last calendar period. The second measure is used to synchronize data at other periods. For sync_first and sync_last measures, the syncwith option must be specified with a single measure name that will be used to synchronize the first or last calendar period.
-description descriptionString	Specifies the description of the measure.
-picklist|-nopicklist	Specifies whether the measure is displayed as a picklist in the Client. The actual value of the picklist is specified by the -range option of the measure. -nopicklist is only available with the -modify option. It means the measure should not be displayed as a picklist measure in the RPAS Client.
-materialized (persistent|display)	Specifies whether the measure is persistent or display only on the RPAS Server side. Persistent measures must have a valid database and arrays to store the measure data. Display only measures do not have permanent data arrays associated with it. The data for a display only measure must be calculated on the fly. As a result, display only measures can not be used on the RHS of any expression. Display only measures can still be used on the LHS of a calc expression used in a workbook, in which case a temporary array will be created in the workbook to hold the temporary data for the display measure.
-lowerbound measureName	Specifies a measure name that defines the lower bound for each cell of the measure. The difference between the -lowerbound and -range options is that the -range option specifies a single scalar as the lower bound for all cells of the measure, but the lower bound value specified by the -lowerbound option can be different from cell to cell.
-upperbound measureName	Specifies a measure name that defines the upper bound for each cell of the measure. The difference between the -upperbound and -range options is that the -range option specifies a single scalar as the upper bound for all cells of the measure, but the upper bound value specified by the -upperbound option can be different cell to cell.
-attr attrName	Specifies the measure attribute name. If not specified, it defaults to no attribute is assigned to the measure. Note: If this option is specified, the -attrpos option must also be specified.
-attrpos attrPosName	Specifies the measure attribute position name. Combined with the -attr option, the measure attribute provides a way to group measures together based on measure attributes. Note: If this option is specified, the -attr option must also be specified.
-scriptname scriptname	Specifies a shell script that must be executed as part of a specific event. Currently, the only script that is handled is to give the option of selecting a hierarchy position name as the content of a string measure. In other words, when a user clicks in a cell, the user is presented with a hierarchy dimension single-tree pop-up. The format for this is 'SingleSelect(HIER="<HIER>", DIM="<DIM>") where <HIER> and <DIM> should be replaced with the actual names of the hierarchy and dimension for which the single-tree pop-up should be created.
-specialval action:specval:behavior, action:specval:behavior,...	Specifies a list of measure special values in the form of "Action:SpecialValue:Behavior,…". The special values are stored in the domain's meta data database. For Action, the only action supported is: "DISPLAY". The only SpecialValue supported is "NAVAL". For Behavior, "NULL" means translate any na cell to a blank cell for display. "CELLVALUE" means no translation, just display the navalue as a regular value.
-fnhbi	Specifies that this measure is a "Forced non=HBI" measure, which means that although the base intersection of this measure is above the partition dimension, the measure data must still be stored in each local domain. Not available with the -modify option.
-hybridaggspec hiername:aggOp,hiername:aggOp,...	Specifies the aggregation method to be used for each hierarchy in the base intersection. This option is only valid when the default aggregation method for the measure is hybrid.
-periodstatevalue (true|false)	Specifies that this measure stores a "Period Start" type of data, like beginning inventory. PeriodStart measures usually use Period Start Total or Period Start Average for the default aggregation method. It also has different behavior in elapsed lock. At the aggregated calendar level, if the starting period is elapse locked, then the whole aggregated period is locked.
-modify measureName	Modifies the measure with the specified name. Set the updated values for the measure by using any of the optional arguments.
-remove measureName	Removes the measure with the specified name.

Registering Token Measures Using regTokenMeasure

The regTokenMeasure utility is used to register, list, and remove RPAS Token Measures.

RPAS Token Measure provides placeholder functionality for measure names in RPAS expressions. An RPAS Token Measure is a special RPAS measure.

An RPAS Token Measure is always registered as a scalar measure of string type, with the measure property called tokenmeas set to true. Its measure data holds a valid value measure name as a single string. The data arrays for all token measures are stored in one database called token under the data directory in the RPAS domain.

Token measure can be used in RPAS expressions by prefixing @ in front of the token measure name, either on the LHS or RHS of the expression. Before evaluation, @TokenMeasName in the expression is replaced with the value measure name that is associated with the token measure. As a result, the expression is evaluated against the value measure. A token measure name cannot be used in expression without the prefixing @.

In the following example, TM1 is a token measure registered with the value measure name VM1.

The following expression:

@TM1 = a + b

Is evaluated as:

VM1 = a + b

The following expression is not valid, because TM1 is used without prefixing it with @:

TM1 = "sth"

If mace is used to evaluate, it will throw a ParserException with the message that the token measure "TM1" is used without prefixing @. This functionality prevents the modification of the token measure's data, which is actually the value measure's measure name.

The regTokenMeasure utility cannot be used to create a token measure which is a measure shared through an RPAS Data Mart. If regTokenMeasure is called to register a shared measure as a token measure, regTokenMeasure will exit with an error identifying the shared measure.

regTokenMeasure Usage

regTokenMeasure -version
regTokenMeasure -d pathToDomain -add tokenMeasure=valueMeasure {-fnhbi}
regTokenMeasure -d pathToDomain -list
regTokenMeasure -d pathToDomain -remove tokenMeasure=valueMeasure

Table 9-10 provides descriptions of the arguments used by the regTokenMeasure utility.

Table 9-10 Arguments Used by the regTokenMeasure Utility

Argument	Description
-d pathToDomain	Specifies the path to the domain. A valid domain path must be specified.
-add tokenMeasure=valueMeasure	Adds a token measure with the specified token measure name and value measure that the token measure points to.
-fnhbi	If specified, the token measure will be registered as an fnhbi measure in the global domain. Its data is stored in each local domain rather than the global domain, although by definition the token measure should be always be HBI measure since it is scalar type.
-list	Prints all token measure names and the value measure names associated with the token measure, which are registered in the domain specified by the -d option.
-remove tokenMeasure=valueMeasure	Removes the token measure with the specified token measure name and value measure. The token measure is unregistered from the domain specified by -d option. Unregistering the token measure has no side effect to the value measure that the token measure is associated with.

Batch Plug-In Tasks: execPluginTask.sh

Many RPAS applications can be used to extend the functionality of the RPAS Configuration Tools and the rpasInstall process. Theses extensions are provided by plug-ins included as part of the solution. Most plug-in extensions execute either within the RPAS Configuration Tools or within the rpasInstall process. However, some applications may include plug-in extensions that can be executed from a command prompt.

The execPluginTask.sh utility is the method by which these command line plug-in tasks can be performed. When execPluginTask.sh is executed, it loads a configuration, locates the desired plug-in extension, and executes that extension on the loaded configuration. Then, depending on the task being executed, the configuration may or may not be saved. Extensions that do not modify the configuration, for example, ones that generate resources based on the contents of the configuration, do not require saving the configuration at the conclusion of the automation.

Individual applications document the command line extensions they support, if any, along with information on how those extensions may be used.

execPluginTask.sh usage

In addition to the standard arguments described below, it is possible to pass any number of additional arguments to execPluginTask.sh. These additional arguments are passed to the extension being executed to allow control over its operation. Details on the arguments any given command line extension accept and their function are located in the application-specific documentation of the extension.

execPluginTask.sh plug-inName:taskName pathToConfiguration {plug-inTaskArguments}
execPluginTask.sh -version
execPluginTask.sh -help

Table 9-11 Arguments Used by the execPluginTask.sh Utility

Argument	Description
plug-inName	Indicates the name of the plug-in containing the extension to be executed.
taskName	Indicates the name of the extension to be executed.
pathToConfiguration	The path to the configuration execPluginTask.sh should load to execute the extension. As with the rpasInstall process, paths passed as arguments should be absolute paths and not relative paths.
plug-inArguments	Indicates additional arguments that are passed to the extension.
-version	Prints the version information for execPluginTask.sh.
-help	Prints the usage statement for execPluginTask.sh.