RETURN clause
RETURN clause is optional and must be included into a FUNCTION program block only if a function returns some values to the calling routine.
|
Argument list |
The list of values returned by the function |
The RETURN statement usually appears at the end of the FUNCTION program block, before END FUNCTION keywords, because it returns control from the function to the calling routine and all the statements placed between the RETURN statement and the END FUNCTION keywords will be ignored. It can be also used in a conditional statement within the FUNCTION program block in order to return control from the function to the calling routine under some conditions.
The RETURN statement can be used either with or without values:
- Without values the RETURN statement is used to control the course of the program execution (to leave the function and to return the program control to the calling routine under some conditions)
- With a list of values The RETURN statement is used to pass the values to the calling routine. It also returns the program control to the calling routine
The values specified in the RETURN clause must match the values specified in the RETURNING clause of the CALL statement in order and number, they must also be of compatible data types. If the RETURN clause contains no arguments, it transfers program control back to the calling routine without returning any values.
A programmer defined or a built-in function that does not have the same name as a built-in operator, and that returns a single value, can be used as an operand in a 4GL expression.
MAIN
…
IF func2() < 0 THEN
EXIT PROGRAM
END IF
…
END MAIN
FUNCTION func2()
DEFINE var1 INT
PROMPT "Enter your number " FOR var1
RETURN var1
END FUNCTION
A function calling used as an operand can include formal arguments, if they are required.
The RETURN statement is optional and it can be absent from a function. If there is no RETURN statement, a function will be terminated, when 4GL encounters the END FUNCTION keywords and the program control will be passed to the calling routine.
If you use the RETURN statement within a program block other that FUNCTION program block (MAIN or REPORT), an error will occur.
Returned values
RETURN statement can be used with the list of returned values. The values must immediately follow the RETURN keyword, they must be separated by commas. The THRU/THROUGH keyword and the .* notation can be used to specify a part of a program record or a whole record.
To invoke a function, do this:
- specify the function name in the CALL statement (if the function does not return anything)
- specify the function name in the CALL statement with the RETURNING clause (if a function returns more than one value)
- use the function as an operand within a 4GL expression (if a function returns a single value)
Returned data types
If a function returns values, the number and order of the arguments in the RETURNING clause of the CALL statement must match the returned values in the RETURN statement in number and order. Their data types must be the same or compatible.
If a function returns exactly one value and is invoked implicitly as an operand of a 4GL expression, the data type of the returned value is checked against the data type expected by the expression. A value of ARRAY data type cannot be returned by a function as well as a RECORD that contains arrays as members.
Below is an example of a function that returns a whole record. The values returned by the function match the members of the record in number order and data type, so though in the RETURN clause all the variables are listed, the RETURNING clause can contain only the record name with the .* notation:
MAIN
DEFINE my_rec RECORD
var1, var2, INT,
var4, var5 CHAR (15)
END RECORD
…
CALL my_function() RETURNING my_rec.*
…
END MAIN
FUNCTION my_function()
DEFINE
r_var1, r_var2 INT,
r_var4, r_var5 CHAR (15)
…
RETURN r_var1, r_var2, r_var4, r_var5
END FUNCTION
The second example is an example of the implicit function invocation for a function that returns only one value:
MAIN
DEFINE cl_fullname VARCHAR(25)
…
LET cl_fullname = get_fname(), 1 SPACE, get_lname()
…
END MAIN
FUNCTION get_fname()
DEFINE
r_name VARCHAR (10)
PROMPT "Enter the first name: " FOR r_fname
RETURN r_fname
END FUNCTION
FUNCTION get_lname()
DEFINE
r_lname VARCHAR (15)
PROMPT "Enter the last name: " FOR r_lname
RETURN r_lname
END FUNCTION
The values of large data types (BYTE or TEXT) cannot be returned by a function, because the returned variables should be referenced by values and the variable of large data types can only be passed by reference. If some changes have been made in values of large data types within a function, they will be visible in the calling routine without being returned by the function.
A returned value of character data type cannot be longer than 511 bytes. No more than 10 lines 511 bytes each can be returned by a function. The actual size of the returned character strings is limited to 512 bytes, but they require the terminating symbols (ASCII 0) at the ends. To pass longer values by reference, use the variables of TEXT data type.