Command-line generation

Operations

For each parameter, the following operations can be defined:

• Get type="current", used to capture the current value of the parameter.
• Get type="nextboot", used to capture the value the parameter that the parameter will have after a reboot.
• Set type="current", used to set the current value of the parameter. This parameter value is lost upon reboot.
• Set type="nextboot", used to set the value the parameter that the parameter will have after a reboot.
• Set type="permanent", used to set the current value of the parameter, knowing that this value will persist after a reboot.
• diff operation, used to compare two values of the parameter.
• Discover operation, used to find targets for parameters that support them.
• Property, used to capture a property for a parameter.
• Prerequisite, used to condition the execution of a get, set, or discover operation for a given parameter.

Not all operations need to be defined for all parameters. The two get operations and all the set operations supported by the parameters must be defined. The diff operation is optional, and if it is not defined, comparisons between parameter values are done internally based on the parameter type, such as string, and integer. The discover operation must be defined only for parameters that have targets. Properties and prerequisites are only defined when needed.

Command line elements

For each operation supported by a parameter, up to five different elements can be used to define how a command line can be built to perform the operation:

• <Command> element, used to define the base command, for handling parameters.
• <Stdin> element, used to define the data that will be written to the command line standard input.
• <Argument> element, used to insert parameter specific data into a <Command> or <Stdin> element.
• <Filter> element, used to filter the output a command line for the get and diff operations.
• <Mask> element, used to extract data from the output of a command line for the get, diff, and property operations.

When an operation needs to be performed, the <Command>, <Stdin>, <Argument> and <Filter> elements defined for the requested operation are combined together to generate a set of command lines, as explained in the artex_catalog_cmdline_gen.html#artex_catalog_cmdline_gen__CommandLineGenerationAlgorithm topic. The generated command lines are then run by a shell. For the get, diff, and property operations, the <Mask> element is used to extract the requested data (parameter values, comparison results, or property values) from the command output.

Configuration methods

Command line elements can be defined locally inside a <ParameterDef> element, or inherited from a <CfgMethod> element referenced in the <ParameterDef> element using the cfgmethod attribute.

Combination are permitted: the set of command line elements defined for a specific operation of a specific parameter is the union of the command line elements defined locally under the <ParameterDef> element, and the command line elements defined for the same operation in the <CfgMethod> element referenced by the cfgmethod attribute of the <ParameterDef> element. If the same command line element is defined both locally and in a configuration method, then the local definition takes precedence.

For example, in this non-optimized catalog file:

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

  <Set type=”permanent”>
    <Command>/usr/sbin/vmo –p –o%a</Command>
    <Argument> -o %n=%p</Argument>
  </Set>

</CfgMethod>

<ParameterDef name=”lgpg_size” cfgmethod=”vmo”>
  <Get type=”current”>
    <Command>/usr/sbin/vmo -o lgpg_size</Command>
    <Mask name="1" value="2">[[:space:]]*(.*) = (.*)</Mask>
  </Get>

  <Get type=”nextboot”>
    <Argument> -o lgpg_size</Argument>
  </Get>

</ParameterDef>

We can see that:

• The <Get type="current"> operation is entirely defined at the <ParameterDef> level.
• The <Get type="nextboot"> operation has some elements defined at the <CfgMethod> level (<Command> and <Mask>) and some elements defined at the <ParameterDef> level (<Argument>).
• The <Get type="current"> operation is entirely defined at the <CfgMethod> level.

Using a configuration method offers two main advantages:

• It simplifies the catalog. In many cases parameter definitions will inherit all their command line element from a configuration method, and the <ParameterDef> element will be empty.
• It allows different parameters to be grouped together in a single command line, when possible.

Command line generation algorithm

Command lines are generated using an algorithm that allows several parameters to be grouped in a single command.

Parameter grouping is not only desirable from a performance and efficiency standpoint it is also necessary for certain parameters. For example, the vmo parameters lgpg_regions and lgpg_size, which cannot be set independently and need to be set together in a single vmo command invocation.

The command line generation algorithm is functionally equivalent to the following steps:

1. Each parameter in the input profile has its <Command> and <Stdin> elements partially expanded. During this phase, the %a, %v1[name], %v2[name], %f1[name] and %f2[name] sequences are ignored and not expanded.
2. Parameters that verify all five conditions below are grouped together:
   • Parameters use the same <Command> element.
   • Parameters use the same <Stdin> element.
   • Parameters use the same <Filter> element.
   • The expansion of the <Command> element performed during step 1 produced identical strings.
   • The expansion of their <Stdin> element performed during step 1 produced identical strings.

   The group now has its own, partially expanded <Command> and <Stdin> elements and its own <Filter> element, shared by all the parameters in the group.

3. For each group of parameters, the group <Command> and <Stdin> elements have the %v1[name], %v2[name], %f1[name] and %f2[name] sequences expanded. Parameter name is only searched within the group.
4. For each group of parameters, the group <Command> and <Stdin> elements have the %a sequences expanded: each parameter in the group has its <Argument> element expanded, and the concatenation of those expanded <Argument> elements replaces any %a sequence in the <Command> and <Stdin> elements.

The result of this process is a set of command lines, with optionally data to write on their standard input and a command to filter their output.