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>;
}

Example

function zero(){
    return 0;
}
number a = zero();

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;
}

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);

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.