SUBROUTINES REFERENCE

SUBROUTINES REFERENCE

Subroutines are identified in a program by a unique subroutine label. The subroutine label is the letter O followed by an integer (with no sign) between 0 and 99999 written with no more than five digits (000009 is not permitted, for example) or a string of characters surrounded by <> symbols.

Examples of valid subroutine labels include:

  • O123
  • O99999
  • O

Subroutine labels may be used in any order but must be unique in a program. Each subroutine label must be followed by a subroutine keyword.

The subroutine keyword defines the action associated with the subroutine label. Valid subroutine keywords and their meanings are as follows:

  • Sub: Begin subroutine definition
  • Endsub: End of subroutine definition
  • Call: Call the subroutine
  • Do/while/endwhile: Execute the subroutine while a condition is true
  • Repeat/endrepeat: Execute the subroutine while a condition is true
  • If/elseif/else/endif: Conditionally execute the subroutine
  • Break: Break out of a while or if/elseif statement
  • Continue: Skip remaining code and restart at top of while or repeat loop
  • Return: Return a value

The sub and endsub keywords are used to define the beginning and end a subroutine. All lines of code between the sub and endsub keywords are considered to be part of the subroutine.

Example of sub, endsub, call:

o100 sub

G53 G00 X0 Y0 Z0 (rapid move to machine home)

o100 endsub

o100 call (call the subroutine here)

M02

Subroutines can either be defined in the program file or in a separate file. If the subroutine is defined in the same file as the main program that calls the subroutine, it must be defined before the call statement. For instance, this is valid:

o100 sub

G53 G00 X0 Y0 Z0 (rapid move to machine home)

o100 endsub

o100 call (call the subroutine here)

M02

But this is not:

o100 call (call the subroutine here)

M02

o100 sub

G53 G00 X0 Y0 Z0 (rapid move to machine home)

o100 endsub

A subroutine can be a separate file, provided the following rules are obeyed:

  • The file must be named the same as your call.
  • The file must include a sub and endsub in the file.
  • The file must be in the directory /subroutines.
  • The file name can include lowercase letters, numbers, dashes, and underscores only.
  • The file can contain only a single subroutine definition.
  • The file must end with the extension .nc.

To execute a subroutine in a program, it must be called. To call a subroutine, program O~ call where ~ is the subroutine name. The subroutine name may be either a named file, a numbered file, or an expression that evaluates to a valid subroutine label.

Expression example: o[#101+2] call

Named file example: o call

Numbered file example: o123 call

O~ call takes up to 30 optional arguments, which are passed to the subroutine as #1, #2 , . . . , #N. Unused parameters from #N+1 to #30 have the same value as in the calling context.

Parameters #1-#30 are local to the subroutine. On return from the subroutine, the values of parameters #1 through #30 (regardless of the number of arguments) are restored to the values they had before the call.

The following calls a subroutine with three arguments: o200 call [1] [2] [3]

Because 1 2 3 is parsed as the number 123, the parameters must be enclosed in square brackets.

Subroutine bodies may be nested. Nested subroutines may only be called after they are defined. They may be called from other functions, and may call themselves recursively if it makes sense to do so. The maximum subroutine nesting level is 10.

Subroutines do not have return values, but they may change the value of parameters above #30 and those changes are visible to the calling G-code. Subroutines may also change the value of global named parameters.

NOTE: File names are lowercase letters only. o is converted to o by the interpreter.
SUBROUTINES REFERENCE