<Mask> element

Syntax

Parent element: <Get>, <Diff>, <Discover> (only under a <SeedDef>),<PropertyDef>, <Property>

The following attributes are supported when used in a <Get> or <Diff> element:

Table 1. Attributes
Attribute	Required	Type	Description
name	no	integer	Specifies the index of the subexpression that matches the name of the parameter. Valid values are 1 and 2.
value	no	integer	Specifies the index of the subexpression that matches the value of the parameter. Valid values are 1 and 2.

The following attributes are supported when used under the <Discover> subelement of a <SeedDef> element:

Table 2. Attributes
Attribute	Required	Type	Description
catalog	yes	integer	Specifies the index of the subexpression that matches the name of the catalog. Valid values are 1, 2, and 3.
name	yes	integer	Specifies the index of the subexpression that matches the name of the parameter. Valid values are 1, 2, and 3.
target	no	integer	Specifies the index of the subexpression that matches the target of the parameter. Valid values are 1, 2, and 3.

The following attribute is supported when used under the <PropertyDef> or <Property> element:

Table 3. Attribute
Attribute	Required	Type	Description
value	no	integer	Specifies the index of the subexpression that matches the name of the parameter. Must be set to “1” if specified.

Usage

The <Mask> element defines a regular expression that is applied on each line of command output to extract data from those lines. The data that is extracted depends on where the <Mask> element is used.

If no attributes are specified, the last line in the command output that matches the regular expression is used to extract the data. The extracted data is the part of the line that matches the regular expression. When used under a <Get> or <Diff> element, the extracted data is used as the parameter value. When used under a <PropertyDef> or <Property> element, the extracted data is used as the property value.

If only the value attribute is specified, it must be set to 1, and the regular expression must contain only one subexpression. The last line in the command output that matches the regular expression is used to extract the data. The extracted data is the part of the line that matches the first (and only) subexpression. When used under a <Get> or <Diff> element, the extracted data is used as the parameter value. When used under a <PropertyDef> or <Property> element, the extracted data is used as the property value.

If the name and value attributes are specified, one of those attributes must be set to 1 and the other must be set to 2, and the regular expression must contain two subexpressions. A name and a value are extracted from each line of the command output that matches the regular expression. When used in a <Get> element, the name is used as the parameter name and the value as the parameter value. When used in a <Diff>element, the name is used as the parameter name and the value is used as the comparison result. Using this function, the values of several parameters can be extracted by using a single get command, and several parameters can be compared by using a single diff command.

When used in the <Discover> subelement of a <SeedDef> element, the catalog and name attributes must be specified. A catalog name and a parameter name are extracted from each line of the command output that matches the regular expression. If a catalog that matches the extracted catalog name is found on the system, and if it contains a definition for a parameter that matches the extracted parameter name, a parameter is inserted into the profile. The optional target argument can be added to extract a target definition for each discovered parameter. The target definition must follow the semicolon-separated list of “class=instance” pairs format, such as class1=instance1;class2=instance2;... format.

Examples

The vmoParam.xml catalog uses the <Mask> element with the name and value attributes to extract all parameter values from a single vmo –a command:

<CfgMethod id="vmo">
  <Get type="current">
    <Command>/usr/sbin/vmo -a</Command>
    <Mask name="1" value="2">[[:space:]]*(.*) = (.*)</Mask>
  </Get>
</CfgMethod>

Had the vmoParam.xml catalog been written in a way that one separate command was used to capture the value of each parameter, then the <Mask> element could have been used with just the value attribute set and no name attribute:
```
<CfgMethod id="vmo">
  <Get type="current">
    <Command>/usr/sbin/vmo -o %n</Command>
    <Mask value="1"> = (.*)</Mask>
  </Get>
</CfgMethod>
```
Or, by using a regular expression that matches only the value:
```
<CfgMethod id="vmo">
  <Get type="current">
    <Command>/usr/sbin/vmo –o %n</Command>
    <Mask>[^ ]*$</Mask>
  </Get>
</CfgMethod>
```
From the three examples above, the first is the most efficient, since it requires only a single command to capture all the vmo command parameters. Examples 2 and 3 would generate a separate command for each vmo command parameter, since the parameter name is used in the <Command> element.

The following <SeedDef> element defines a seed that can be used to discover all attributes of all devices. It uses a target to designate the device they operate on:

<SeedDef name="devAttr">
  <Discover>
    <Command>
      /usr/sbin/lsdev -F 'name class subclass type' |
      while read DEV CLASS SUBCLASS TYPE
      do
        /usr/sbin/lsattr -F attribute -l $DEV |
        while read PAR
        do
          echo device=$DEV devParam.$CLASS.$SUBCLASS.$TYPE $PAR
        done
      done
    </Command>
    <Mask target="1" catalog="2" name="3">(.*) (.*) (.*) <Mark>
  </Discover> 
</SeedDef>

The discovery command prints each discovered device attribute on a separate line, by using the following format:

device=DeviceName devParam.Class.Subclass.Type AttributeName

For example,

device=en0 devParam.if.EN.en tcp_recvspace
device=en0 devParam.if.EN.en tcp_sendspace
device=ent0 devParam.adapter.vdevice.IBM,l-lan alt_addr
device=ent0 devParam.adapter.vdevice.IBM,l-lan chksum_offload

Related information

Command line generation