CALL, ENTER

CALL, ENTER

Top  Previous  Next

 

The CALL statement calls a catalogued subroutine. The ENTER statement is a synonym for CALL unless the PICK.ENTER option of the $MODE directive is used.

 

 

Format

 

CALL name {(arg.list)}

CALL @var {(arg.list)}

CALL "file name" {(arg.list)}

 

where

 

nameis the name of the subroutine to be called.

 

@varis the name of a variable holding the name of the subroutine to be called.

 

arg.listis the list of arguments to the subroutine.

 

fileis the name of the file containing the subroutine to be called.

 

A subroutine with no arguments is equivalent to a program. A whole matrix can be passed as an argument by prefixing it with MAT.

 

 

Direct Calls

 

Placing the subroutine name in the CALL statement as in the first syntax shown above is referred to as a direct call. QM will search for the subroutine as described below when any CALL statement referencing the subroutine is first executed in the program or subroutine. For CALL statements which occur within catalogued subroutines the search will take place every time the calling subroutine itself is called. QM includes an object code caching mechanism to minimise the performance impact of this repeated search.

 

 

Indirect Calls

 

The second syntax executes a CALL statement using a variable to hold the subroutine name and is referred to as an indirect call. In this case, QM will search for the subroutine as described below when the first CALL statement is executed. Indirect calls allow an application to call a subroutine where the name of the routine was not known at compile time. This might be of use, for example, in menu systems.

 

When an indirect call is executed, the variable containing the subroutine name is modified to become a subroutine reference. This can still be used as a string in the program but also contains a pointer to the memory resident copy of the subroutine. The subroutine will remain in memory so long as one or more subroutine references point to it. Overwriting the variable will destroy the subroutine link and may make the subroutine a candidate for removal from the object code cache.

 

One advantage of indirect calls is that, by placing the variable in a common block where it is accessible by all modules of the application and will not be discarded, the catalogue search need only be performed once even when the CALL is in a subroutine which itself may be called many times. A direct call works in a similar way but the variable in which the subroutine reference is placed is local to the program containing the CALL and is thus lost when the program terminates.

 

If the string stored in the variable used in an indirect call contains a space, this is taken as being a Pick style subroutine reference described below.

 

 

Searching for the Subroutine

 

Subroutines to be executed using CALL must be placed in the catalogue using the CATALOGUE command or the equivalent automated cataloguing from within the QMBasic compiler.

 

Subroutine names must conform to the QMBasic name formats except that two special prefix characters are allow. An exclamation mark prefix character is used on all standard globally catalogued subroutines provided as part of QM that are intended for user use. An asterisk prefix may be used on user written globally catalogued subroutines for compatibility with other products.

 

Unless the subroutine name commences with one of the global catalogue prefix characters, QM goes through a series of steps when a CALL statement searches for a subroutine:

The local catalogue is checked. This consists of a VOC record of the form

Field 1        V

Field 2        CS

Field 3        Runfile pathname

The private catalogue file is checked.

The global catalogue is checked.

 

Note that subsequent calls to the same subroutine where the subroutine reference has not been reset will continue to use the original catalogued routine even if it has been deleted from the catalogue or replaced.

 

 

Pick Style Call with a File Name

 

The third syntax of CALL,

CALL "file name" {(arg.list)}

allows a program to specify subroutine to be called by its file and program name. The file element of this syntax is the case sensitive name of the file containing the compiled program. A suffix of .OUT is added to this name automatically. Extended file name syntaxes are supported where permitted by the value of the FILERULE configuration parameter. The name element is the name of the program within the specified file. On platforms with case sensitive file systems, the casing of this name must match that of the stored program. The program is loaded directly from the specified location instead of following the catalogue search process described above.

 

 

Arguments

 

The argument list may contain up to 255 items. If a subroutine has no arguments, the brackets may be omitted.

 

Each argument is

A constantCALL SUB("MY.FILE")
An expressionCALL SUB(X + 7)
A variable nameCALL SUB(X)
An indexed matrix element nameCALL SUB(A(5,2))
A matrix name prefixed by MATCALL SUB(MAT A)

 

Where the argument is a reference to a variable, a matrix element or a whole matrix, the subroutine may update the values in these variables. Except when passing a whole matrix, the calling program can effectively prevent this by forcing the argument to be passed by value rather than by reference by enclosing it in brackets, thus making the argument into an expression.

 

 

Forced Reload of Object Code

 

Whenever a program is compiled or catalogued, an event is signalled to all QM processes to cause them to unload any inactive programs from the object code cache. In this context, an inactive program is one that is not the currently executing program, an earlier one in the hierarchy of subroutine calls, or one that has a subroutine reference variable pointing to it.

 

If the FORCE.RELOAD mode of the OPTION command is in effect, this mechanism is extended such that all subroutine link variables are reset. The next call to the subroutine will reload the object code. This allows dynamic modification of an application in a production environment but carries the risk that a simple loop such as

FOR I = 1 TO 5

  CALL MYSUB

NEXT I

might call a different version of MYSUB from one iteration of the loop to the next.

 

Note that the event causes all subroutine links to be reset, not just those for the program that has been compiled or catalogued, however, it does not apply to instantiated objects. Note also that the FORCE.RELOAD option must be set in the QM session that is to perform the reload, not necessarily in the session that compiles or catalogues the program.

 

Pick Style ENTER

 

By default, the ENTER statement is a synonym for CALL. Use of the PICK.ENTER option of the $MODE compiler directive causes ENTER to behave in the same way as its equivalent in Pick style multivalue database products.

 

In this mode, use of ENTER terminates the current program and replaces it with the named program. This new program may not take arguments. If the ENTER statement is performed in a program that was started using the EXECUTE statement, or a subroutine called from such a program, the ENTER does not discard the program containing the EXECUTE.

 

 

Examples

 

COMMON /COM1/ INITIALISED, SUB1

IF NOT(INITIALISED) THEN

 SUB1 = "SUBR1"

 INITIALISED = @TRUE

END

 

This program fragment declares a common block to hold subroutine call references. When the program is first executed, the conditional statements will be performed as common block variables are initially zero. This path sets the name of the subroutine SUBR1 into common variable SUB1.

 

Later in the program, perhaps in a different subroutine from that in which the common was initialised, a statement of the form

 

CALL @SUB1(ARG1, ARG2)

 

will call the SUBR1, changing the common variable to be a subroutine reference for fast access on subsequent calls.

 

A statement of the form

 

CALL SUBR1(ARG1, ARG2)

 

would call the same subroutine but does not use the common block variable. If this call was in a subroutine, the catalogue search would be performed for the first call each time the calling subroutine is entered.

 

 

See also:

CATALOGUE