Subroutine CALLs

The CALL element is quite similar to a simple instruction. The difference is that the executed instruction is the invocation of a user-defined subroutine (also see Type) represented by another diagram, i.e. the execution control is delegated to that other diagram, which then (after having done its job) returns control hitherto where it gets passed to the next element..

Subroutines may be classified into procedures, which do not return a result and are used as command, and functions, which return a value and are to be used as expression. Hence, the calls to procedures and functions differ slightly in their syntax. Generally, in a programming language, functions could be called at arbitrary nesting levels in expressions (as is possible with the built-in functions of Structorizer). With the CALL elements in Structorizer referring to other (customer-defined) diagrams it's different, however:

If you want to allow the Executor to perform such a CALL element or if you want the code export working then the CALL should contain just a single line, either of the form

procedureName(value1, value2, ..., valueN)

or

variable <- functionName(value1, value2, ..., valueN)

The argument list may be empty, but the parentheses must not be omitted. The arguments (value1 through valueN in the templates above) may not only be represented by literals or variable names but by arbitrary valid expressions with operators and built-in functions. The only restriction is that the expressions may not contain further custom-routine CALLs. The argument expressions are to be separated with commas.

A call must provide as many argument values as the called routine has parameter names in its header. They are mapped one by one in the order of the parameter list. If there are overloaded subroutines (i.e. several subroutines with same name but different numbers of parameters) then the argument number of the call decides which of the routines gets invoked.

Since version 3.29-05, subroutines may have optional parameters at the end of the parameter list. In this case, the call may omit as many argument values (from right to left) as parameters in the routine header are equipped with default values. These default values will be used instead of the omitted arguments. If an argument is given then the default value will no be used.

Version 3.32-11 introduced an autocompletion mechanism in the element editor that offers the signatures of all matching subroutine diagrams that are held in Arranger at the moment of editing. Its further functionality is described on page Content Assist.

Example

Here is a simple example of a CALL element (yellow) within a function diagram:

The called function is defined by another diagram (see Executor guide and Arranger page to learn how calls can be executed in Structorizer):

The calling two-parameter function diagram daysInMonth above is of course also meant to be called by another algorithm.

On the Runtime Analysis manual page you will find an example of a pretty complex bunch of routines co-operating in the task of sorting an array; the core algorithm there (quickSortRecursive) is a recursion example.

Recursion

If you want to write a recursive algorithm, you ought to place the recursive call into a CALL element as described above. Example:

Though this diagram shows a fundamentally correct recursion, it will not be executable in Structorizer because the CALL element (red) does not only consist of target variable, assignment symbol, and function invokation but embeds the function call in a multiplication.	This version of a recursive factorial algorithm decomposes the recursive branch into the assignment with the pure call on the right-hand side and a separate multiplication instruction. This way, Structorizer can execute it. (The expression n-1 as function argument is no problem.)

Instruction transmutation, routine outsourcing and editing

There are some very helpful features to facilitate the creation of CALL elements or their corresponding subroutine diagrams.

1. If you happened to write a subroutine call into a simple Instruction element by mistake, then you don't need to delete the element, to insert a Call element and to enter the entire statement text again. Instead, by clicking the magic wand button  (with the Instruction element selected) you may transmute it into a Call element (with same content). This can also serve as an easy test whether the statement complies with the syntax rules stated above. (Otherwise the transmutation button simply won't work.)
2. If you realize that a designed algorithm has grown too large and should better be decomposed then you may "outsource" parts of the diagram into subroutine diagrams. Simply select the logically consistent element subsequence you want to make a subroutine from and click the menu item " Outsource". This will move the selected elements to a new subroutine and fill the gap with a Call to that subroutine diagram. See Outsourcing for details.
3. You may summon the called routine for editing or inspection (since version 3.29-04). Another Structorizer instance, related via Arranger, would open to show the summoned routine. There are respective items in both the "Edit" menu and the context menu:
   
   
   If the referenced routine cannot be retrieved from Arranger, then you will be asked whether you want to create a new subroutine diagram for the referred signature:
   
   You may decline here, or continue, in which case Structorizer will set up a new empty diagram with a routine header vaguely inferred from the call, ready for editing:
   
   As you can see, the new routine diagram will automatically be added to the group of the parent diagram, possibly a new group may have been generated for this relation.

Method declaration reference

Diagrams resulting by source code import from an object-oriented language like Java or Processing (since Structorizer release 3.31) may contain special CALL elements that were deliberately misapplied as mere method reference declarations — they will permanently be disabled (see the green elements with hatched side-bars at the end of the diagram shown below) but allow to summon the related diagram into an additional Structorizer window via the menu item "Edit Sub-routine ..." in either the "Edit" or the context menu or via key binding <Ctrl><Enter>:

On COBOL import, the same misapplication is used to place unsatisfied section or paragraph labels from the source code, in a way that they can't cause harm, into the diagrams at the corresponding places:

A special benefit of these misapplied CALL elements is that series of them (together with neighbouring genuine declarations) can be collapsed with the display mode Hide mere declarations:

In contrast to the method declaration reference elements as used for Java, Processoing, and Delphi import, for the CALLs misapplied as COBOL label markers, the "Edit Sub-routine ..." action is not enabled.

Note that such specifically diverted CALL elements cannot be inserted or generated manually, they will only occur as product of source code import. Since version 3.32-20 they differ visually from disabled ordinary CALL elements by their hatching: whereas disabled ordinary CALL elements are completely hatched, the hatching on these method / label reference elements is restricted to the side bars (which also helps legibility of the element text and comment).