Understanding CHL file

This topic includes:

What is a CHL file?

A CHL file is script that executes the desired action(s). It is written in Chilli, the BMC Software proprietary programming language.

What is the structure of a CHL file?

A CHL file has the following structure:

Description

Contains information about the script, version, creation date, programmer, and so on.

#####################################################################
# CustomPackagerModuleSetup
# Modify the Custom packager module parameters
#
#####################################################################

Global variables

Similar to other programming languages Chilli uses global variables. You can call any number and type of external variables, however be aware that the following two are mandatory for all step scripts:

StepParamsContainer: contains the values of all parameters defined by the step
RuleParamsContainer: contains general information about the Operational Rule the step is added to. It can be used by the steps to communicate with each other if an Operational Rule contains more than one step.
```
#### The Rule container can be used by steps to communicate with each other.

extern ContainerHandle StepParamsContainer, RuleParamsContainer
```

Local variables

The value of the NAME elements of parameters defined in the XML file need to be defined as local variables in the CHL file.

Following you find the example of the predefined step Custom Package Module Setup which demonstrates how the parameters in the XML and CHL files are linked:

   <PARAMS>
        <PARAM>
            <NAME>PackageExtension</NAME>
            <LABEL>_DB_STEPPARAM_PACKAGEEXTENSION_</LABEL>
            <TYPE>String</TYPE>
            <DEFAULT>.zip</DEFAULT>
        </PARAM>
        <PARAM>
            <NAME>MaxRetry</NAME>
            <LABEL>_DB_STEPPARAM_MAXRETRY_</LABEL>
            <TYPE>Integer</TYPE>
            <DEFAULT>5</DEFAULT>
        </PARAM>
        <PARAM>
            <NAME>RetryInterval</NAME>
            <LABEL>_DB_STEPPARAM_RETRYINTERVAL_</LABEL>
            <TYPE>Integer</TYPE>
            <DEFAULT>300</DEFAULT>
        </PARAM>
    </PARAMS>

custompackagermodulesetup.xml

#### Our parameters to be found in StepParamsContainer:
const PACKAGERCUSTOM_PARAM_PACKAGEEXTENSION   "PackageExtension"
const PACKAGERCUSTOM_PARAM_MAXRETRY           "MaxRetry"
const PACKAGERCUSTOM_PARAM_RETRYINTERVAL      "RetryInterval"
const ERROR_CODE                              "ErrorCode"
    
const PARAM_NAME                              "Name"
const PARAM_PERSISTENT                        "Persistent"
const PARAM_STATE                             "State"
const PARAM_STATE_INITIALISE                  1
const ACTIONDB_ERROR_DUPLICATE                11

custompackagermodulesetup.chl

Notice how the three NAME elements PackageExtension, MaxRetryand RetryIntervalare defined in the CHL file. Additionally you find the five local variables ERROR_CODE, PARAM_NAME, PARAM_PERSISTENT, PARAM_STATE, PARAM_STATE_INITIALISEand ACTIONDB_ERROR_DUPLICATEwhich are used later on in the Main procedure.

Custom defined procedures

code that is defined once in the script and can be executed as often as needed by other parts of the script or program

Main procedure

The main procedure follows the same basic rules as in other programming languages. However, due to the functioning of the operational rules module the Main procedure must be divided into runphases. There are 5 different runphases, of which the RUNPHASE_PLANNEDis mandatory. The operational rules module will not execute step scripts which do not at least contain this runphase. Also all individual operations are required to return either 0 for successful execution or non-zero for failed.The process of executing an operational rule containing three steps for example is as follows:

RUNPHASE_VERIFICATION

The verification phase verifies if all prerequisites for the execution of the steps are given, that is, it verifies for the correct operating system, if the environment variable or the registry key exists, etc. The process verifies the steps in the order in which they are defined. If the verification of all steps returns OK, the script passes on to RUNPHASE_PLANNED. If the verification fails, the Operational Rule is cancelled.

RUNPHASE_PLANNED

This phase is the actual execution phase of the script. It executes one step after the other in the defined order. This phase can have one of the following results:

If all steps are successfully executed, the script passes to RUNPHASE_CLEANUP
If execution failed, the script passes to RUNPHASE_UNDO
If execution is stopped due to a "non-execution" problem such as the CM agent crashing or the computer shutting down, the script passes to RUNPHASE_RESUMEat the next CM agent startup.

RUNPHASE_UNDO

This phase is used to undo all changes executed via the steps if the execution of the Operational Rule fails. After the undo the device will be in exactly the same state and situation as before the execution of the Operational Rule .

RUNPHASE_RESUME

If execution is stopped due to a "non-execution" problem such as the CM agent crashing or the computer shutting down, at the next CM agent this phase will check the Operational Rule and verify which of its steps it finished executing. It will then proceed to re-execute the step at which the execution was interrupted, and run all remaining steps.

RUNPHASE_CLEANUP

This last phase cleans up the device , for example, deleting the MSI file used for a software installation.

How does Chilli work?

Chilli is a procedural programming language, combining the features of BASIC and C as well as some C++ concepts into a flexible computer language. This powerful script language is a self-contained stand-alone language with its own compiler. For in-depth information about Chilli consult the Chilli Reference .