GOSUB (Go to subroutine) - User Guide - PXC4.E16.A - PXC5.E24.A - PXC7.E400.A

Syntax

GOSUBline# (pt1,...,pt15)

or parentheses are optional

GOSUBline# pt1,...,pt15

Use

Subroutines are particularly useful for programs in which the same calculation is carried out several times using different values.

The main subroutine commands, GOSUB and RETURN are required for all subroutines. When this command is executed, the line specified in the GOSUB command is the next line evaluated. When the computer encounters the RETURN command, the next line evaluated is the line following the GOSUB statement.

The variable parameters in a subroutine are designated by the local variables $ARG1 through $ARG15. These variables can be used by PPCL code in the subroutine in the same way that point names and constants are used.

Multiple-Level Subroutines

A multiple-level subroutine is a block of program code that is called from within another subroutine. Each call made within a subroutine constitutes a level. You are limited to a total of eight levels.

When using multi-level subroutines, the rules that govern $ARGn variables and point name declarations for GOSUB commands change as follows:

• $ARGn variables used in multi-level subroutines cannot be shared between subroutine levels. That is, you cannot assign the value of PT1 to $ARG1 in the call to level one and then assign the value of PT2 to $ARG1 in the call to level two.
• When defining a new level in a multi-level subroutine, list the previously-defined $ARGn variables in sequential order to preserve their values.
• Any new points declared in that level must be placed after the $ARGn variables. For example, in the third level of a multi-level subroutine, $ARG1 and $ARG2 would be redefined before the defining the new value of PT3.
• If a previously-defined $ARGn variable is not redefined in the call to a new level, any values introduced in the new level replace the values in $ARGn.

Subroutine Examples

To explain the concept of subroutine program control, two examples of program code are provided in this section:

• Program flow sequence
• Multiple level subroutines

Program Flow Sequence

This example demonstrates how a number of PPCL commands are used in subroutines. Refer to Figure 3-1 as you follow the program flow sequence.

• The variables PT1 and PT2 demonstrate the passing of values between subroutines.
• The $ARG local variable demonstrates how values are passed between subroutines.
• The GOTO command, which is used to bypass subroutines, is also shown in this example.

The program flow through one complete pass is as follows:

1. At line 130, the GOSUB command transfers control to line 1010.
2. At line 1010, the program assigns a value of 10 to PT1 and the value of 20 to PT2. Line 1030 branches back to the line after the GOSUB command (at line 130). After the program returns to the main line code, the values of the two points become: PT1 = 10 PT2 = 20
3. The program continues to sequentially evaluate program lines until it encounters the GOSUB command at line 300. The program branches to line 2010. This command also defines two values that are passed (PT1 and PT2).
4. At line 2010, a $ARGn point is assigned a value. When the program encounters a $ARGn point, it checks the calling GOSUB command for point names. The GOSUB command used to call this subroutine contains two point names. When the program encounters the first $ARGn variable at line 2010, it takes the first point name defined in the GOSUB command (PT1) and stores that value in $ARG1 (10). Line 2010 also adds one (1) to the value of $ARG1. When the program encounters the second $ARGn variable at line 2020, it takes the second point name defined in the GOSUB command (PT2) and stores that value in $ARG2 (20). Line 2020 also adds one (1) to the value of $ARG2. Line 2030 returns control of the program to the line after the GOSUB command (at line 300). At line 400, the program executes the GOTO command to line 3000 that returns control back to mainline code.
5. After one pass of the program, the values of the points after being updated by the $ARGn variables, will be as follows: PT1 = 11 PT2 = 21

100  C MAINLINE PROGRAM FOR LOGICAL FIRMWARE

110  C LEARNING HOW TO USE GOSUB, RETURN, AND

112  C $ARG COMMANDS.***

120

130  GOSUB 1010

     ...

     ...

     ...

300  GOSUB 2010 PT1, PT2

     ...

     ...

     ...

400  GOTO 3000

1000  C   --SUBROUTINE 1

1001  C   THIS SUBROUTINE ASSIGNS NUMBERS

1002  C   TO PT1 AND PT2. IT THEN RETURNS

1004  C   CONTROL TO THE MAIN PROGRAM.

1008  C

1010  PT1 = 10

1020  PT2 = 20

1030  RETURN

2000  C   --SUBROUTINE 2

2001  C   THIS SUBROUTINE PASSES THE VALUE OF

2002  C   PT1 AND PT2 TO THEIR RESPECTIVE $ARG

2003  C   POINTS. IT THEN ADDS ONE TO BOTH $ARG

2004  C   POINTS AND RETURNS THE NEW VALUES TO

2005  C   PT1 AND PT2.

2006  C  

2010  $ARG1 = $ARG1 + 1

2020  $ARG2 = $ARG2 + 1

2030  RETURN

3000  C WHEN THE SUBROUTINE IS FINISHED

3002  C EXECUTING, THE PROGRAM RETURNS TO

3004  C MAINLINE CODE.

Figure 3-1.  Example Program with Two Subroutines.

Multiple-Level Subroutines 

The following example demonstrates the use of $ARGn variables and point declarations used in multiple-level subroutines.

This example demonstrates a method for preserving the values of $ARGn variables as program control is transferred among subroutines. The example program contains a main line section of program code and three subroutines. Refer to Figure 3-2 as you follow the program flow sequence.

The program flow through one complete pass is as follows:

1. At line 1500, the GOSUB command transfers control to line 2030 and passes the value defined in PT1 to $ARG1 in the subroutine.
2. While executing the first subroutine, the program encounters a call to a second subroutine at line 2500.

• Since the GOSUB command at line 2500 is defined within another subroutine, this command must redefine $ARG1 in order to preserve the value from the GOSUB command at line 1500.
• If $ARG1 is not redefined in the call to the second subroutine, any value introduced in the second subroutine replaces the value in $ARG1.
• The new value introduced in the second subroutine (PT2 in the example) is defined after the $ARG1 variable.
• As the program works with the variables $ARG1 and PT2 in the second subroutine, $ARG1 continues to represent the value of PT1, while $ARG2 represents the value of PT2.

1. At line 3200, the second subroutine calls a third subroutine.

• Since the GOSUB command at line 3200 is defined within two other subroutines, this command must redefine both $ARG1 and $ARG2 in order to preserve their values.
• Note that $ARG1 and $ARG2 are placed in the same order in which they were originally defined.
• Line 3200 also defines a new point called PT3. Note that PT3 is placed after the two $ARGn variables.
• As the program branches from the second subroutine to the third subroutine, $ARG1 and $ARG2 continue to represent PT1 and PT2 respectively.

1000  C MAINLINE PROGRAM FOR LOGICAL FIRMWARE

1010  C  

1020  C   THIS PROGRAM TEACHES HOW GOSUBS AND

1030  C   $ARG POINTS WORK IN MULTIPLE

1040  C   LEVEL SUBROUTINES.  

1050  C

1100  ...

1200  ...

1300  ...

1350  C THIS GOSUB CALLS THE FIRST SUBROUTINE

1360  C AND PASSES THE VALUE DEFINED IN PT1 TO

1370  C TO $ARG1.

1380  C

1500  GOSUB 2030 PT1

2000  C  

2010  C SUBROUTINE #1

2020  C  

2030  ...

2040  ...

2050  C IN ORDER TO PRESERVE THE VALUE LOCATED

2060  C IN $ARG1, YOU MUST DEFINE $ARG1 IN THE

2070  C SECOND SUBROUTINE'S CALLING GOSUB. THE

2080  C PROGRAM ALSO PASSES A SECOND POINT

2090  C VALUE NAMED PT2.

2100  C  

2500  GOSUB 3030 $ARG1,PT2

2510  RETURN

3000  C  

3010  C SUBROUTINE #2

3020  C  

3030  ...

3040  ...

3050  C IN ORDER TO PRESERVE THE VALUES

3060  C LOCATED IN $ARG1 AND $ARG2, YOU MUST

3070  C DEFINE BOTH POINTS IN THE THIRD

3080  C SUBROUTINE'S CALLING GOSUB. THE

3090  C PROGRAM ALSO PASSES A THIRD POINT

3100  C VALUE CALLED PT3.

3200  GOSUB 4020 $ARG1,$ARG2,PT3

3210  RETURN

4000  C SUBROUTINE #3

4010  C  

4020  ...

4030  ...

4040  RETURN

Figure 3-2. Multiple Level Subroutines.

Notes

• A GOSUB command can only reference point names or local variables.
• A GOTO command can be used inside of a subroutine only if the command does
• not transfer program control out of that subroutine.
• The last line of a subroutine must be a RETURN command.
• Do not transfer control out of a subroutine without using a RETURN command.
• Do not use time-based commands such as LOOP, SAMPLE, TOD, and WAIT inside a subroutine.
• Do not use an IF/THEN/ELSE command with a GOSUB command.

See also the GOTO and RETURN topics.