User-Defined Routine/Function (UDR)
- Jonathan Muse
- Shane Smith
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:
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
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
Constant Parameters
Parameters of user-defined functions can be made read-only in the scope of the function by adding the keyword "const" before the parameter definition in the signature of the function.
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.
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.
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.
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 function). You can use issue fields and custom fields anywhere in your code (including in the UDR body) without having to declare them.
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
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).
You can return simply from a function without specifying a value. However, you should always remember that by design functions return a value, even if it is undefined. The following code is therefore valid:
Of course, the above code will print the text 'S IS NULL' in the log.
Contents