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.

GetNodeByHostName("ORA_HOST_01");

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.

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

Funcname([param1, param2 ...])

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

// 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

// 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