farcall
farcall
DATABASE
,
PROCEDURE
,
PARAMETERS

The farcall statement allows a procedure to call a separate procedure within a different database as a subroutine.

Parameters

This statement has three parameters:

database – is the database that contains the procedure to call. This database must be open. If the database name does not have any spaces or punctuation, no quotes are required. You can also use a formula to calculate the database name “on the fly.”

procedure – is the name of the procedure to call. If the procedure name does not have any spaces or punctuation, no quotes are required. You can also use a formula to calculate the procedure name “on the fly.”

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

This statement allows a procedure programmer to execute a second procedure in a different database (which must be open) as a subroutine to the first procedure. Subroutines become important when you wish to use the same code at different times within the same procedure or from within multiple procedures. Creating a subroutine allows you to write the code once and use it again and again rather than duplicating the same code over and over again.

Subroutines normally finish when the end of the procedure is reached. To stop the subroutine before the end of the procedure, use the return statement. The return statement makes Panorama return control to the original procedure.

This simple example shows how to call a procedure called Summarize in the MySubroutines database.

    farcall MySubroutines,Summarize

This example calls a subroutine named Calculate % in the Business Percentages database. The subroutine’s name is more than one word and contains symbol characters.

    farcall "Business Percentages","Calculate %"

#### Parameters

When you call a subroutine, you can supply one or more parameters to be passed to the subroutine (each parameter must be separated by a comma). When using the farcall statement, the parameters are listed after the procedure name, like this:

    farcall database,procedure parameter1,parameter2,parameter3, ... parameterN

Within the procedure’s source code, you can access the parameters with the parameter( function, or change the value of a parameter with the setparameter statement. This is especially useful for accessing the main program’s local variables within the subroutine procedure. Normally the local variables in the calling procedure cannot be accessed within the subroutine, but parameters provide a way to do this. For example, you could create a procedure called AddMultipleRecords in a database named MySubroutines to add several records at once:

    for i,1,parameter(1)
        addrecord
    endloop

In any other procedure in the main database, you can call this procedure to add multiple records. Here’s how you would add a dozen records:

    farcall MySubroutines,AddMultipleRecords,12

You can also use the setparameter statement to modify the value of a parameter passed to the subroutine.

#### Keeping track of the active database

The call statement works only within the currently active database. That isn’t necessarily the database that contains the call statement. If you use a statement that changes the active database, the call statement will be trying to call a procedure in the database that is associated with the currently active window, not the database that contains the call statement. A similar situation occurs if the calling procedure is itself the subject of a farcall from another database, as described below.

Consider the case where database A issues a farcall to procedure X in database B and procedure X then issues a call to procedure Y, also in database B. Throughout the whole of this process, database A remains the active database and a call from procedure X to procedure Y will fail. In this case, the call to procedure Y must be a farcall.

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.
- callwithin( -- allows a "mini-procedure" to be called as a subroutine within a formula and return a result.
- 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.
- 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.
- 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 | No Change | Carried over from Panorama 6.0