IBM Tivoli Netcool/Impact, Version

User-defined functions

User-defined functions are functions that you use to organize your code in the body of a policy.

Once you define a function, you can call it in the same way as the built-in action and parser functions. Variables that are passed to a function are passed by reference, rather than by value. This means that changing the value of a variable within a function also changes the value of the variable in the general scope of the policy.

User-defined functions cannot return a value as a return parameter. You can return a value by defining an output parameter in the function declaration and then assigning a value to the variable in the body of the function. Output parameters are specified in the same way as any other parameter.

You can also declare your own functions and call them within a policy. User-defined functions help you encapsulate and reuse functionality in your policy.

The syntax for a function declaration is the Function keyword followed by the name of the function and a comma-separated list of runtime parameters. The list of runtime parameters is followed by a statement block that is enclosed in curly braces.

Unlike action and parser functions, you cannot specify a return value for a user-defined function. However, because the scope of variables in IPL policy is global, you can approximate this functionality by setting the value of a return variable inside the function.

Function declarations must appear in a policy before any instance where the function is called. The best practice is to declare all functions at the beginning of a policy.

The following example shows how to declare a user-defined function called GetNodeByHostname. This function looks up a node in an external data source by using the supplied host name.

Function GetNodeByHostName(Hostname) {
	DataType = "Node";
	Filter = "Hostname ='" + Hostname + "'";
	CountOnly = False;
	MyNodes = GetByFilter(DataType, Filter, CountOnly);
	MyNode = MyNodes[0];

You call user-defined functions in the same way that you call other types of functions. The following example shows how to call the function.


Here, the name of the node that you want to look up is ORA_HOST_01. The function looks up the node in the external data source and returns a corresponding data item named MyNode. For more information about looking up data and on data items, see the next chapter in this book.


When you write an Impact function, check that you do not call the function within the function body as this might cause a recursive loop and cause a stack overflow error.

Function declarations

Function declarations are similar to those in scripting languages like JavaScript. Valid function names can include numbers, characters, and underscores, but cannot start with a number.

The following is an example of a user-defined function:

Function MyFunc(DataType, Filter, MyArray) {
    MyArray = GetByFilter(DataType, Filter, False);

Calling user-defined functions

You can call a user-defined function as follows:

Funcname([param1, param2 ...])

The following example shows a user-defined function call:

MyFunc("User", "Location = 'New York'", Users);

Examples of user-defined functions

The following example show how variables are passed to a function by reference:

// Example of vars by reference
Function IncrementByA(NumberA, NumberB) {
    NumberB = NumberB + NumberA;
SomeInteger = 10;
SomeFloat = 100.001;
IncrementByA(SomeInteger, SomeFloat);
Log("SomeInteger is now: " + SomeInteger);
// will return: IntegerA is now 10
Log("SomeFloat is now: " + SomeFloat);
// will return: FloatB is now 110.001

The following example shows how policies handle return values in user-defined functions:

// Example of no return output
Function LogTime(TimeToLog) {
    If (TimeToLog == NULL) {
        TimeToLog = getdate();
    Log("At the tone the time will be: "+ localtime(TimeToLog));
LoggedTime = LogTime(getdate());
Log("LoggedTime = "+LoggedTime);
// will return: "LoggedTime = NULL" as nothing can be
// returned from user functions