Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

func/call - Transfer program execution to a code function

CONTENTS

Synopsis
Description
Function Return Value
Function Arguments
Error Handling
Examples
See Also
Author

func/call write, target
func/call write, target, value <, value ... >

func/bcall write, target
func/bcall write, target, value <, value ... >

The func/call instruction executes a program function identified by target and previously initialised using func/def. The write argument will collect the function return value. One or more optional value arguments pass variables into each formal parameter if defined.

The target argument locates the function code to be executed, and this may be an object reference or a text string. If a text string is provided, the function is located by searching the following locations in order:

local context
	Functions anchored underneath the current executing object.
module root
	Functions anchored to the module root.
.prose.code.sys
	System functions with global scope.

The current program pointer and run state are saved onto the program stack before function execution begins, and restored upon return using func/rtn. The context root is set to point to the function object being executed. Registers are zeroed for the start of the new function, and zeroed again upon return (i.e. they will contain PSUNIT_TYPE_NULL).

The func/bcall instruction is identical in operation, except that it additionally saves (bundles) all used program registers onto the stack, and restores them upon return.

The write argument is the register in which to store a pointer to the function return value. If the function returns a value it will be an encoded attribute value (PSUNIT_TYPE_XVALUE). If the function does not return a value this register will be set to NULL. If the write argument is NULL then the return value, if there is any, will be safely discarded.

If a function has been defined by func/def with formal parameters, then each parameter must be supplied an argument value. When the function code is invoked, each argument will be assigned to a variable automatically as if var/local had been called. The parameter name and type that were declared when the function was defined becomes the variable name and type. The value supplied to func/call or func/bcall is treated exactly as if it were passed to var/local. See var_local(5) for more details.

If value is a register containing the type PSUNIT_TYPE_STRING or PSUNIT_TYPE_XVALUE and the instruction does not generate an error, then the register will be cleared as the data is now referenced elsewhere. This is true regardless of whether func/call or func/bcall was used.

A runtime error is generated if an argument is of the wrong type, if a referenced object does not exist in the nexus, or if the number of supplied arguments does not match the declared formal parameters for the function.

func/bcall NULL, ![set_globals]
	Executes the function called set_globals, located underneath the current context root, saving registers and restoring them upon return from the function. The function has no parameters and returns no value.
func/call NULL, [tools.nxdump]
	Executes the function called nxdump in the tools container located in the function search path. Registers are zeroed before and after the function is called.
func/call P0, [stradd], #5, [53]
	Executes the function called stradd located in the function search path. Passes two arguments and saves the return value in register P0.

pal_intro(5), pal_commands(5), pal_registers(5), pal_indices(5), pal_stack(5), func_def(5), func_rtn(5), func_addr(5), var_local(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2017 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.