• Trigger Variables Overview
• Default Internal Variables Available to Trigger Scripts
• Externally Injecting Variables into Job Triggers
• Exporting Variables to Parent Objects
• Requiring Variables in Parent Objects
• Filtering VC Triggers by Namespace

18.5.1 Trigger Variables Overview

Trigger variables can add greater flexibility and power to a site administrator who wants to automate certain tasks and system behaviors. Variables allow triggers to launch based on another trigger's behavior, state, and/or output.

Example

AType=exec,Action="/tmp/trigger1.sh",EType=start,Sets=Var1.Var2 \
AType=exec,Action="/tmp/trigger2.sh $Var1 $Var2",EType=start,Requires=Var1.Var2

AType=exec,Action="/tmp/trigger1.sh",EType=start,
Sets=Var1.Var2 \
AType=exec,Action="/tmp/trigger2.sh $Var1 $Var2",
EType=start,Requires=Var1.Var2

In this example, the first trigger sets two variables (separated by a '.'), which are received in the second. As previously mentioned, those arguments could be accessed in the second trigger through the variables $1 and $2.

It is also possible to have a trigger set a variable when it fails using the '!' symbol:

Example

AType=exec,Action="/tmp/trigger1.sh",EType=start,Sets=!Var1.Var2 \
AType=exec,Action="/tmp/trigger2.sh",EType=start,Requires=Var1 \
AType=exec,Action="/tmp/trigger3.sh",EType=start,Requires=Var2

AType=exec,Action="/tmp/trigger1.sh",EType=start,
Sets=!Var1.Var2 \
AType=exec,Action="/tmp/trigger2.sh",EType=start,
Requires=Var1 \
AType=exec,Action="/tmp/trigger3.sh",EType=start,
Requires=Var2

In this example, the first trigger will set Var1 if it fails and Var2 if it succeeds. The second trigger will launch if Var1 has been set (the first trigger failed). The third trigger will launch if Var2 is set (the first trigger succeeded).

Variable requirements can be further refined to allow for the evaluation and comparison of the variable's value. That is, triggers can have a dependency on a variable having (or not having) a certain value. The format for this is as follows:

[*]<VARID>[:<TYPE>[:<VARVAL>]]

The optional * specifies that the dependencies are satisified by an external source that must be previously registered. A number of valid comparison types exist:

Following is an example of how these comparitive dependencies can be expressed when creating a trigger.

Example

AType=exec,Action="/tmp/trigger2.sh",EType=start,Requires=Var1:eq:45 \
AType=exec,Action="/tmp/trigger3.sh",EType=start,Requires=Var2:ne:failure1

AType=exec,Action="/tmp/trigger2.sh",EType=start,
Requires=Var1:eq:45 \
AType=exec,Action="/tmp/trigger3.sh",EType=start,
Requires=Var2:ne:failure1

In this example, the first trigger will fire if Var1 exists and has a value of 45. The second trigger will only fire if Var2 is not the string failure1.

The following example shows how triggers can set variables as strings:

Example

Var1=arbitrary_value1

Var2=arbitrary_value2

The trigger should be set as follows:

AType=exec,Action="/tmp/trigger2.sh",EType=start,Sets=Var1.Var2"

18.5.2 Default Internal Variables Available to Trigger Scripts

Several internal variables are available for use in trigger scripts. These can be accessed using $<VARNAME>:

• ETYPE is the type of event that signals that the trigger can fire; ETYPE values include cancel, checkpoint, create, end, epoch, fail, hold, migrate, modify, preempt, standing, start, and threshold.
• HOSTLIST is the HostList of the trigger's object (when applicable).
• OID is the name of the object to which the trigger was attached.
• OTYPE is the type of object to which the trigger is attached; can be rsv, job, node, or sched.
• OWNER is the owner of the trigger's object (when applicable).
• OWNERMAIL is a variable that is populated only if the trigger's parent object has a user associated with it and that user has an email address associated with it.
  
• TIME is the time of the trigger launch.
• USER is the user (when applicable).

The TIME variable is returned in the following format: <DAY_OF_WEEK> <MONTH> <DAY> <TIME>. When the TIME variable is passed as an argument to a script, the script must account for the spaces present in the variable's value.

Other unique variables are available to triggers attached to specific objects:

Jobs

• MASTERHOST - The primary node for the job.
• HOSTLIST - The entire hostlist of the job.

Reservations

• GROUPHOSTLIST - The hostlist for the reservation and all of its peers.
• HOSTLIST - The entire hostlist for the reservation.
• OBJECTXML - The XML representation of an object. Output is the same as that generated by mdiag --xml.
• OS - The operating system on the first node of the reservation.

These reserved names cannot be used as variables. For example, if an OS variable is added to a reservation and then accessed, it will contain information reported by the resource manager, not the value that the user inserted.

Example

AType=exec,Action="/tmp/trigger3.sh $OID $HOSTLIST",EType=start

In this example, the object ID ($OID) and hostlist ($HOSTLIST) will be passed to /tmp/trigger3.sh as command line arguments when the trigger executes the script. The script can then process this information as needed.

18.5.3 Externally Injecting Variables into Job Triggers

For triggers that are attached to job objects, another method for supplying variables exists. The trigger is able to see the variables in the job object to which it is attached. Updating the job object's variables effectively updates the variable for the trigger. This can be accomplished through the use of mjobctl using the -m flag.

> mjobctl -m var=Flag1=TRUE 1664

This sets the variable Flag1 to the value TRUE, creating Flag1, if necessary. This will be seen by any trigger attached to job 1664.

18.5.4 Exporting Variables to Parent Objects

Variables used and created by triggers are stored in the namespace of the object to which the trigger is attached. Sometimes it is desirable to make certain variables more accessible to triggers on other objects. When using the Sets trigger attribute, you can specify that a variable, created either by a success or failure, should be exported to the name space of the parent object when the current object is destroyed through a completion event. This is done by placing the caret (^) symbol in front of the variable name when specifying it.

Example

AType=exec,Action="/tmp/trigger1.sh",EType=start,Sets=^Var1.!^Var2 \
AType=exec,Action="/tmp/trigger2.sh",EType=start,Requires=Var1 \
AType=exec,Action="/tmp/trigger3.sh",EType=start,Requires=Var2

AType=exec,Action="/tmp/trigger1.sh",EType=start,Sets=
^Var1.!^Var2 \
AType=exec,Action="/tmp/trigger2.sh",EType=start,
Requires=Var1 \
AType=exec,Action="/tmp/trigger3.sh",EType=start,
Requires=Var2

In this example, both Var1 and Var2 will be exported to the parent object when the trigger has completed. They can also be used by triggers at their own level, just as in previous examples.

The following example shows how triggers can set variables as strings to pass up to parent objects:

Example

AType=exec,Action="/tmp/trigger2.sh",EType=start,Sets=Var1

The trigger sets Var1 to TRUE when it completes successfully. Because AType=exec, the script launched by the trigger can set a string value for Var1. To do this, declare it on its own line in the trigger stdout. For example:

EXITCODE=15
Var1=linux

Var1 has the value linux and if defined with a caret (^) is passed up to the job group or to any parent containers if the trigger is attached to a VM. This is useful for workflows in which a trigger may depend on the value given by a previous trigger.

In order to return multiple variables, simply print out one per line.

18.5.5 Requiring Variables in Parent Objects

By default, triggers will only look for variables to fulfill dependencies in the object to which they are directly attached. In addition, if they are attached to a job object, they will also look in the job group, if defined. However, it is not uncommon for objects to have multiple generations of parent objects. If the desired behavior is to search through all generations of parent objects, the caret (^) symbol must be specified, as in the following example:

Example

AType=exec,Action="/tmp/trigger2.sh",EType=start,Requires=^Var1

AType=exec,Action="/tmp/trigger2.sh",EType=start,Requires=
^Var1

18.5.6 Filtering VC Triggers by Namespace

When a trigger's variable is set with a caret (^) symbol to be passed to the parent object, the parent object inherits the object name as well as the variable. This namespace variable has the following format: <vc_name>.<variable_name>. For example, if virtual container vc2 contains variable var4 and passes it up to vc1, vc1 then contains vc2.var4.

Triggers can request namespaces using the following format: $*.<variable_name>

TRIGGER=Action="$HOME/mytrig.py $*.var4"

Every .var4 VC will receive the mytrig.py script, regardless of the namespace. This means that each applicable namespace is placed in the argument list so that the trigger sent to Moab would execute the script on all namespaces attached to the specified variable (such as vc1.var4, vc2.var4, etc.).

Specifying namespaces in VC triggers allows you to perform an action on multiple VCs based on its variables without inadvertently performing the action on VCs from separate workflows that may happen to have a variable with the same name. To filter the namespaces to be passed down to triggers from a job, use the msub -W command, specify "trigns", and set the value to a comma-delimited list of the desired VC names (namespaces).

msub -l ... -W x="trigns=vc2,vc3"

Variables with namespaces vc2 or vc3, and all non-namespace variables, are acceptable. vc2.var4 and var4 are acceptable, but vc1.var4 is filtered out.

See Also

• Generic Metrics
• Generic Events