Introduction
User-defined routines (UDR) are functions that perform specific actions that you can define in your SIL™ programs for a later use. These can considerably improve the readability and maintainability of your code.
Syntax
function <name>(<type> param1, <type> param2, ...) {
Instruction1;
...
InstructionN;
return <value>;
}
The name of the UDR cannot contain spaces.
Example
function zero(){
return 0;
}
number a = zero();
Definition of UDRs must be done before the code, even though it is not used anywhere up to that point. Therefore, the following code is invalid.
number i;
const number pi = 3.14;
i = 0; //this is the error line, i is initialized to a constant and this is extra code, not allowed
function circleArea(number r) {
return r * r * pi;
}
However, you are allowed to declare global variables and constants before function definitions:
number i = 0; //global var with initialization, ok
const number pi = 3.14; //constant, ok
function circleArea(number r) {
return (i + r) * (i + r) * pi;
}
number r = 10;
runnerLog("Area of radius " + r + " is " + circleArea(r));
i++;
runnerLog("Area of radius " + (r + i) + " is " + circleArea(r));
Running the above code in the Power Scripts for JIRA (formerly known as JJUPIN) Runner gadget:
Parameters
The list of parameters in the definition of a UDR can be of any length (including 0) and their respective types can be any valid SIL™ type.
Example
function zero(){
return 0;
}
function doSomething(string s, number n1, number [] n2, boolean flag, string [] oneMore){
....
}
UDRs use a "pass-by-value" policy. This means that even though you modify the value of a parameter in your function, on exit the value will be lost.
Example
function increment(number a){
a = a + 1; // the value of a is only modified locally
return a;
}
number b = 0;
number c = increment(b); // the value of b does not change
print(b); // this prints 0
print(c); // this prints 1
Constant Parameters
Parameters of user-defined routines can be made read-only in the scope of the routine by adding the keyword "const" before the parameter definition in the signature of the routine.
function f(const string s) {
...
}
Default Parameters
Parameters may have defaults. This feature was introduced in 5.8.0.0.
Default parameters should not be followed by another param without a default value.
function f(int i, string arg = "this is default") {
return "[" + i + "]" + arg;
}
//function f(int i = 1001, string arg) - incorrect, because 'arg' does not have a default
//function f(int i = 1001, string arg = "default") - correct, we can call it now by f() and receive the default params.
return f(0, "first string") + " >>>" + f(1); //f(1) will provide argument 'arg' the default value
Variable Visibility
There are three categories of variables that can be used in a UDR:
Local variables
These are the variables you define in the body of the UDR. These can be used throughout the body of the UDR. On exit, the values of these variables are lost.
function example(){
number a = 3;
number b = a + 10;
// use here variables a and b
}
Parameter Variables
These are the values passed to the UDR in the list of parameters. Because SIL™ uses a "pass-by-value" policy, even though you modify the value of these variables in the body of the function, on exit, their original values will be restored.
function increment(number a){
a = a + 1; // the value of a is only modified locally
return a;
}
number b = 0;
number c = increment(b); // the value of b does not change
print(b); // this prints 0
print(c); // this prints 1
Global Variables
These are the variables that are already defined and can be used right away (issue fields, customfields and any variables defined before the routine). You can use issue fields and custom fields anywhere in your code (including in the UDR body) without having to declare them.
function printKey(){
print(key);
}
Notice that the key variable is a standard issue field that you could otherwise use anywhere in your SIL™ program without having to declare it.
Return Value
Return values can be used to communicate with the context that called the UDR or to halt its execution.
Examples
function isEven(number a){
return (a % 2 == 0);
}
function increment(number a){
return a + 1;
}
number b = increment(2);
Notice that there is no need to declare the type of the return value; this will be evaluated at runtime. Therefore, even though the check on the following program will be ok, at runtime the value of d will NOT be modified because of the incompatibility between date (on the right-hand-side) and number (on the left-hand-side).
function increment(number a){
return a + 1;
}
date d = increment(2);
There can be only one return value (at most). If you would like to return more values of the same type, consider using an array or a struct.
You can return simply from a routine without specifying a value. However, you should always remember that by design routines return a value, even if it is undefined. The following code is therefore valid:
function f(number a) {
if(a > 0) {
print("positive");
return;
}
if(a == 0) { print("ZERO"); }
}
//[...................]
string s =f(4); //s is still undefined, no value was returned
if(isNull(s)) {
print("S IS NULL!"); //this will be printed
} else {
print("S IS NOT NULL!");
}
Of course, the above code will print the text 'S IS NULL' in the log.
Contents