LOTUSSCRIPT LANGUAGE

Transferring control within the same procedure with the GoSub, On...GoSub, and Return statements
The branching statements GoSub and On...GoSub are nonstandard programming techniques with limited usefulness. They enable running a group of statements by transferring control from any number of other locations within the same procedure. Functionally the statements behave as a subroutine, but they can’t take arguments, don’t establish a separate scope, and aren’t available from other procedures or scripts. It is more common and useful to write the statements as an ordinary sub.

The syntax is:

GoSub label

On expression GoSub label [ , label ]...

Return

The statement GoSub label transfers control to the statement labeled label and executes statements beginning at label, continuing until one of the following occurs:


The group of statements executed after the labeled statement and before the Return statement, including any other transfers of control, acts as a subroutine within the current procedure.

The statement On expression GoSub label, label, ... transfers control similarly to GoSub label, except that the target label is conditioned on the value of expression: control transfers to the first label if expression is 1, to the second label if expression is 2, and so on. (Any of these labels may be the same.) The Return statement returns control to the statement following On...GoSub.

The location of the GoSub statement in the procedure is unrelated to the location of a labeled statement that it transfers control to. The only requirement is that the GoSub and its target labeled statements must be in the same procedure. The actual flow of control is determined at run time.

Execution of a GoSub or an On...GoSub statement defines a point of return. Another GoSub or On...GoSub may be executed before a Return statement is executed. When a Return is executed, control returns to the most recently defined point of return. Then that point of return becomes undefined.

The Return statement doesn’t return from the procedure. It is a run-time error to attempt to execute a Return statement when there is no currently available point of return within the procedure.

These statements differ from the GoTo and On...GoTo statements, which transfer control without establishing a point of return.

This example uses On...GoSub to run one or the other of two simple performance tests on pieces of the LotusScript language. By typing 1 or 2 into an input box, the user chooses whether to time 1000 iterations of a Do loop, or to count the number of Yields executed within one second. Using On...GoSub, the script branches to run one test or the other. A single Print statement reports the result.

Sub RunPerfTest
  Dim directTempV As Variant, directTest As Integer, i As Integer
  Dim startTime As Single, measure As Single, idPace As String
  SpecTest: directTempV = InputBox$ _
    (|Type 1 for iteration time, or 2 for # of yields:|)
  If Not IsNumeric(directTempV) Then Exit Sub
  directTest% = CInt(directTempV)
  If directTest% < 1 Or directTest% > 2 Then _
    Beep : GoTo SpecTest
  i% = 0
  ' Branch on 1 or 2.
  On directTest% GoSub TimeCheck, ItersCheck
  ' Return here to print the performance-test result,
  ' and leave.
  Print idPace$ measure!
  Exit Sub
TimeCheck:
  startTime! = Timer()
  Do While i% <= 1000
     i% = i% + 1
  Loop
  measure! = Timer() - startTime!
  idPace$ = "Time in seconds for 1000 Do iterations: "
  Return
ItersCheck:
  startTime! = Timer()
  Do While Timer() < startTime! + 1
     Yield
     i% = i% + 1
  Loop
  measure! = i%
  idPace$ = "Number of Yields in 1 second: "
  Return
End Sub
Call RunPerfTest()

See Also