Difference between revisions of "Recital Functions"
Yvonnemilne (Talk | contribs) |
Yvonnemilne (Talk | contribs) (→Declaring Parameters in a Recital Function) |
||
| (3 intermediate revisions by one user not shown) | |||
| Line 14: | Line 14: | ||
===Returning a Value from a Recital Function=== | ===Returning a Value from a Recital Function=== | ||
The [[RETURN|return]] statement can optionally return a value. | The [[RETURN|return]] statement can optionally return a value. | ||
| − | |||
| − | |||
| − | |||
| − | |||
<pre> | <pre> | ||
| − | + | return <value> | |
</pre> | </pre> | ||
| + | ===Declaring Parameters in a Recital Function=== | ||
| + | A UDF can have a variable number of parameters passed to it. These are assigned to private variables in the the <parameters list> declaration or [[PARAMETERS|parameters]] statement. The [[PARAMETERS()|parameters()]] function can be used to determine how many actual parameters were specified. | ||
| + | |||
| + | ===Calling Recital Functions=== | ||
Functions can be called like built-in functions: postfixing the name of the function with brackets containing any arguments, e.g. | Functions can be called like built-in functions: postfixing the name of the function with brackets containing any arguments, e.g. | ||
| Line 28: | Line 28: | ||
myudf(m_var,"Hello World",123.45,{12/03/2010}) | myudf(m_var,"Hello World",123.45,{12/03/2010}) | ||
</code> | </code> | ||
| − | |||
| − | |||
Alternatively, the function can be called using the [[DO|do]] command and specifying the arguments in the [[DO|with]] clause, e.g. | Alternatively, the function can be called using the [[DO|do]] command and specifying the arguments in the [[DO|with]] clause, e.g. | ||
| Line 37: | Line 35: | ||
</code> | </code> | ||
| + | Functions can be included in program files, as well as in procedure library files. The functions in a procedure library file are made known to the Recital process by using the [[SET PROCEDURE|set procedure]] command. | ||
| + | <pre> | ||
| + | set procedure to [<filename as character> [ADDITIVE]] | ||
| + | </pre> | ||
===Passing Parameters by Reference=== | ===Passing Parameters by Reference=== | ||
| − | + | Using the [[DO|do]] command, parameters are passed by ''reference'' by default: the called module is given the address of the memory variable so the memory variable itself can be altered. | |
| + | Using function-calling syntax, parameters are passed by ''value'' by default: a copy of the memory variable is passed to the module and the original memory variable is not accessible within the called module. To pass a parameter by ''reference'', the parameter should be preceded by an ''@'' sign. | ||
| + | |||
| + | <code lang="recital"> | ||
| + | myudf(@m_var) | ||
| + | </code> | ||
| + | |||
===Returning Values by Reference=== | ===Returning Values by Reference=== | ||
===Variable Scope=== | ===Variable Scope=== | ||
| + | [[PUBLIC|Public]] variables are globally visible, they are accessible and can be changed from any part of an application. If the application is run from the Interactive Prompt, then any public variables can still be accessed even after the application ends. Any variables created at the Interactive Prompt are automatically created as public variables. | ||
| + | |||
| + | [[PRIVATE|Private]] variables are only visible within the declaring module (program, procedure, User Defined Function) and any modules called by that declaring module. Any variables accessed within a module that are not pre-declared are automatically created as private variables. When the module returns, then all of the memory variables and arrays that were declared by the private command are released. | ||
| + | |||
| + | [[LOCAL|Local]] variables are only visible within the declaring module and are released when the module returns. Local variables differ from private variables in that a local variable is not visible to lower level procedures or functions. | ||
| + | |||
===Built-in Functions=== | ===Built-in Functions=== | ||
===Extending with Functions Developed in C/C++=== | ===Extending with Functions Developed in C/C++=== | ||
===Summary=== | ===Summary=== | ||
Latest revision as of 11:56, 15 March 2010
Contents
- 1 Recital Functions
- 1.1 What is a Recital Function
- 1.2 How to Write a Recital Function
- 1.3 Returning a Value from a Recital Function
- 1.4 Declaring Parameters in a Recital Function
- 1.5 Calling Recital Functions
- 1.6 Passing Parameters by Reference
- 1.7 Returning Values by Reference
- 1.8 Variable Scope
- 1.9 Built-in Functions
- 1.10 Extending with Functions Developed in C/C++
- 1.11 Summary
Recital Functions
What is a Recital Function
Recital User Defined Functions (UDFs) are blocks of reuseable code which can be used in expressions or as individual commands.
How to Write a Recital Function
The function command is used to declare a User Defined Function (UDF) and is terminated with an endfunc or return statement.
function <name as character>[(<parameters as list>)] [parameters <parameters as list>] [return <value as expression> | endfunc]
Returning a Value from a Recital Function
The return statement can optionally return a value.
return <value>
Declaring Parameters in a Recital Function
A UDF can have a variable number of parameters passed to it. These are assigned to private variables in the the <parameters list> declaration or parameters statement. The parameters() function can be used to determine how many actual parameters were specified.
Calling Recital Functions
Functions can be called like built-in functions: postfixing the name of the function with brackets containing any arguments, e.g.
myudf(m_var,"Hello World",123.45,{12/03/2010})
Alternatively, the function can be called using the do command and specifying the arguments in the with clause, e.g.
do myudf with m_var,"Hello World",123.45,{12/03/2010}
Functions can be included in program files, as well as in procedure library files. The functions in a procedure library file are made known to the Recital process by using the set procedure command.
set procedure to [<filename as character> [ADDITIVE]]
Passing Parameters by Reference
Using the do command, parameters are passed by reference by default: the called module is given the address of the memory variable so the memory variable itself can be altered. Using function-calling syntax, parameters are passed by value by default: a copy of the memory variable is passed to the module and the original memory variable is not accessible within the called module. To pass a parameter by reference, the parameter should be preceded by an @ sign.
myudf(@m_var)
Returning Values by Reference
Variable Scope
Public variables are globally visible, they are accessible and can be changed from any part of an application. If the application is run from the Interactive Prompt, then any public variables can still be accessed even after the application ends. Any variables created at the Interactive Prompt are automatically created as public variables.
Private variables are only visible within the declaring module (program, procedure, User Defined Function) and any modules called by that declaring module. Any variables accessed within a module that are not pre-declared are automatically created as private variables. When the module returns, then all of the memory variables and arrays that were declared by the private command are released.
Local variables are only visible within the declaring module and are released when the module returns. Local variables differ from private variables in that a local variable is not visible to lower level procedures or functions.
