callwithin( function

callwithin(

DATABASE

PROCEDURE

LABEL

PARAMETERS

)

The callwithin( function allows a “mini-procedure” to be called as a subroutine within a formula and return a result.

Parameters

This function has four parameters:

database – is the database containing the procedure you want to run, or "" to use a procedure within the current database.

procedure – is the name of the procedure you want to run, or "" to call within the current procedure.

label – identifies the beginning of the mini-subroutine. (The end of the mini-subroutine is defined by a return statement or the end of the procedure.) A label is a unique series of letters and numbers that identifies a location within the procedure. The label must start with a letter, may not contain any spaces or punctuation except for ., _ and %, and must always end with a colon. The colon is not actually part of the label, it simply identifies the series of letters and numbers as a label instead of a field or variable..

parameters – is a list of parameters to be passed to the subroutine. This list is optional, you don’t have to pass any parameters if you don’t need to. See parameter( and setparameter for more information on accessing parameters within a subroutine.

Description

The callwithin( function allows a “mini-procedure” within a procedure to be called as a subroutine within a formula and return a result. It’s basically a combination of the call( function and shortcall statement. The “mini-procedure” must contain a functionvalue statement that tells Panorama what value to return from the function. (The “mini-procedure” may contain multiple functionvalue statements, in which case the function will return the value of the last functionvalue statement executed.)

The callwithin( function allow you to perform procedure statements anywhere a formula is allowed, including in form objects, formulafill, etc. There are some significant restrictions that the procedure called by this function must follow, see the call( function for details.

Parameters

The callwithin( function allows you to supply one or more parameters to be passed to the subroutine (each parameter must be separated by a comma). When using the callwithin( function the parameters are listed after the database, procedure name and label name, like this:

callwithin(database,procedure,label,parameter1,parameter2,parameter3, ... parameterN)

The specified procedure (subroutine) can access the parameters with the parameter( function, or change the value of a parameter with the setparameter statement.

Handling Errors

If there is a syntax error in the subroutine (misspelled command, unexpected formula operator, etc.) the function will return an error message describing the problem instead of the calculated value (since there is a syntax error, it cannot even try to run the program.

If there is a run-time error in the subroutine (for example a missing variable, incorrect data type, etc.) the function will also return an error message describing the problem. Or you can also use the if error, try/catch or onerror statements (see Error Handling) to trap the error yourself and take appropriate action without returning an error. You can even combine the functionvalue statement with the error( function to return your own custom error message.

Error Messages

Procedure called by callwithin( function does not return a value (you must add the functionvalue statement) – The procedure that is called must include a functionvalue statement. If there is a functionvalue statement and you still see this error, the functionvalue is not being executed – check the logic of the procedure.

See Also

call -- allows a procedure to call a separate procedure within the current database as a subroutine.
call( -- allows a procedure to be called as a subroutine within a formula and return a result.
calledby( -- returns true if this function is in code called by the specified database, the specified procedure, or both.
callingdatabase( -- returns the name of the database that called this procedure as a subroutine, if any.
callingprocedure( -- returns the name of the procedure that called this procedure as a subroutine, if any.
callwithin -- allows a procedure to call a mini-procedure within a separate procedure within the current database as a subroutine.
callwithindatabase( -- returns true if the current procedure was called by another procedure in the same database, false if it was called by a procedure in another database.
Custom Statements -- creating your own custom statements that can be used in your code.
execute -- allows a procedure to call a sequence of statements within the current procedure as a "mini-subroutine".
execute( -- allows a formula to execute a sequence of statements and return a result.
executeasap -- executes the specified code at the first possible opportunity, non-atomically.
executecatcherrors -- is the same as the execute statement, except for the fact that if an error occurs while running, it can be trapped by an if error statement immediately following the executecatcherrors statement.
executelocal -- is the same as the execute statement, but it shares local variables with the procedure that called it.
farcall -- allows a procedure to call a separate procedure within a different database as a subroutine.
farcallwithin -- allows a procedure to call a mini-procedure within a separate procedure in a different database as a subroutine.
getproceduretext( -- gets the contents (source code) of a procedure.
info("parameters") -- returns the number of parameters passed to a subroutine.
info("procedurestack") -- returns the contents of Panorama's procedure call stack.
parameter( -- is used to transfer data between a main procedure and a subroutine.
parameterentity( -- returns the entity (field or variable) associated with a subroutine parameter, if any.
return -- ends a subroutine.
returnerror -- passes an error back to the current subroutines calling procedure.
setparameter -- is used to transfer data from a subroutine back to the main procedure that called it.
shortcall -- allows a procedure to call a sequence of statements within the current procedure as a "mini-subroutine".

History

Version	Status	Notes
10.0	New	New in this version.