2 Preface

Documentation Conventions
This guide uses the following documentation conventions.

Text and Programming Code

Example Description Explanation

ready() evenly Programming code. In syntax

grip_close() spaced sections, required characters that
finish() computer must be included.
font

gripdist_set(distance) italics User supplied item. Can be simple

motor(axis,pulses,c) (integer, variable) or complex
if expression (expression, statements)

align_X|align_Y vertical pipe A choice between two or more

M_READ|M_WRITE or bar items. One must be chosen unless
X|Y|Z it is optional (in square brackets).

place[3] square Required characters of array

message[2,2] brackets syntax. Must be included.
data[10,4,7] in arrays

grip_close([force]) square Optional items in code. Can be

home([axis][,axis]) brackets included or omitted depending on
...[flags] [x|X]... in any other the needs of the program.
part of code

lock(7) three dots Omitted code of the example. A

... on one line place for additional material which
unlock(7) or is not specified.
on three
lines

\ (backslash) character(s) Characters referred to in the text

_ (underscore) with which need to be clearly identified.
" (double quote) description(s)
in
parentheses.

use with bold Names of commands, functions,

to end keywords, etc. used in the text
when here which could be confused.
 RAPL-3 Reference Guide 3

Commands and Keywords

The following documentation conventions are used for
• all subroutines, functions, and commands in libraries
• all flow control statements
• other keywords (main, return, comment, sizeof)

name_of_command/keyword
Description A description of the functionality of this subroutine, function, command, control
statement, or keyword.
Details of usage.
Caution Any characteristics that could create a problem.
Syntax Required characters are in non-italic monospace font. Programmer-
supplied identifiers and constructs are in italics. Optional items are in [square
brackets]. Long lines may carry over onto a second line on the printed page, but
in a program must be written either on one line or with a \ (backslash) line
continuation character.
Subroutines, functions, and commands are given in declaration form.
Parameters A list with explanations and types.
Arguments
Where a parameter is a standard-library defined enum or struct, the members
are listed.
Returns The return value of the function or command which also indicates success or
error.
Example An example of use in a program.
Result The example’s result, if applicable.
See Also Any related RAPL-3 commands, functions, subroutines, statements, keywords, or
topics, described in this Reference Guide.
System Shell An equivalent command in the CROS/RAPL-3 system shell or application shell,
Application Shell described in the Application Development Guide.
RAPL-II Any similar RAPL-II commands.
Category The category of this and related commands which are listed in the category
section.
4 Preface

Related Resources
Related material can be found in these documents.
• Release notes on the diskettes.
• Application Development Guide
A guide for developing your robotic application using all components of your
robot system: arm, controller, teach pendant, personal computer, Robcomm3,
RAPL-3 programs, application shell, and system shell.
• F3 Robot System Installation Guide
• A465 Arm and C500 Controller User Guides
• A255 Arm and C500 Controller User Guides
CHAPTER 1

General Program Format

All RAPL-3 programs follow the same general format. Some elements are
required. Other elements are optional depending on the complexity of the
program.
6 General Program Format

Example 1: Basic Program in RAPL-II Style

A basic program can contain
• only a main function
and follow a style similar to RAPL-II
• implicit declarations of variables
• familiar RAPL-II command names
main function main ;; begin program

fast = 50 ;; implicitly declare and initialize integers

slow = 25
z = 1

speed(fast) ;; set speed

move(_safe) ;; move and implicitly declare cartesian location

do ;; begin do loop

appro(_a,5) ;; pick from location a, implicitly declare location

grip_open(100)
grip_finish()
move(_a)
finish()
grip_close(100)
grip_finish()
depart(5)

move(_safe) ;; move to safe location between pick and place

appro(_b,5) ;; place at location b, implicitly declare location

move(_b)
finish()
grip_open(100)
grip_finish()
depart(5)

move(_safe) ;; move to safe location between place and pick

z = z + 1 ;; increment counter in loop

until z == 10 ;; condition to end do loop

end main ;; end program

 RAPL-3 Reference Guide 7

Example 2: Basic Program in Preferred RAPL-3 Style

A basic program can contain
• a main function
• a subroutine
and follow the preferred style of RAPL-3
• explicit declarations of variables, including teachables
subroutine sub io(int out_channel, int out_state, int in_channel)
int in_state
output(out_channel, out_state)
do
delay(250)
input(in_channel, in_state)
until (in_state) == 1
end sub

main function main

int i ;; explicitly declare variables

teachable int fast, slow, cycles ;; explicitly declare teachable variables
teachable cloc safe, a, b ;; explicitly declare teachable locations

move(safe)
speed(fast)

for i = 1 to cycles ;; use a for loop

;; cycles is teachable, set outside
appro(a,5)
grip_open(100)
io(1,1,2)
speed(slow)
move(a)
grip_close(100)
depart(5)

speed(fast)
move(safe)

appro(b,5)
io(3,1,4)
speed(slow)
move(b)
grip_open(100)
depart(5)

speed(fast)
move(safe)

end for

end main
8 General Program Format

The Main Program

Every RAPL-3 program contains a main function.

main
Description A required function for each program. Requires main and end main to indicate
the beginning and the end of the main function.
main is the place in the program where execution begins.
The main function may not call itself.
Syntax main
statement(s)
end main
Returns Main does not have to explicitly return a value. By default, 0 (zero) is returned.
Any integer could be returned.
Example main
teachable cloc pick, place
move(pick)
grip_close()
move(place)
grip_open()
end main
RAPL-II RAPL-II did not have a function or structure similar to main. RAPL-II’s STOP
command had a purpose similar to end main.
 RAPL-3 Reference Guide 9

Lines of a Program
A RAPL-3 program consists of a number of lines of ASCII text. Statements and
declarations are terminated by the line end.

Line Continuation
To continue on the next line, end a line with the \ (backslash) character. For
example
a = b + c + d \
+ e + f
is read as one statement.
Without the continuation character
a = b + c + d
+ e + f
the first part of the statement ends at the end of the first line and is read as a
statement. The second part is a fragment which causes a syntax error when
compiling.
Lines that end with , (a comma) are automatically considered to be continued.
For example,
printf(“The coordinates are {}, {}, {}\n”,
x, y, z)
10 General Program Format

Comments
A comment starts with ;; (two semicolons) and extends to the end of the line. A
comment can start at the beginning of a line or after some program code. For
example:
;; calculate the position error:
x_error = x_pos - desired_x_pos ;; for the x-axis
y_error = y_pos - desired_y_pos ;; for the y-axis
z_error = z_pos - desired_z_pos ;; for the z axis
 RAPL-3 Reference Guide 11

Labels
A statement can be marked with a special identifier called a label. The label has ::
(two colons) after the identifier. A labels is used as the target of a goto statement.

Syntax
label_identifier:: statement
where
label_identifier is the name of the label and follows the rules for identifiers,
and
statement is the statement line being labelled.
The statement can be an empty line.

Examples
my_label:: current_location = num

start_again::
12 General Program Format

Keywords
The following identifiers are keywords of RAPL-3. They are reserved for the RAPL-
3 language and cannot be redefined. In particular, the following keywords
cannot be used as the name of any variable, subroutine, function, or command:
and gloc sizeof
break goto static
_builtin if step
case ignore string
cloc import struct
command int sub
comment libversion teachable
const loop then
continue main to
do mod try
else not typedef
elseif of union
end or unteachable
enum ploc until
except private var
export proto void
float raise volatile
for resume while
func return with
global retry
CHAPTER 2

Data Types and Variables

RAPL-3 programs can work with many different types of data and also permits
user-defined data types. This chapter presents the basic data types supported by
RAPL-3, and goes on to look at the kinds of user-defined types that can be
constructed.
14 Data Types and Variables

Basic Data Types

RAPL-3 supports the following basic data types.

Name Description Size (bytes)

int 32-bit signed integer 4

(Range: -2147483648 to +2147483647)

float IEEE single precision floating point 4

–38
(Range: –1.7 x 10 )

string variable length string 4 + number of

(Range: 0 to 65535 8-bit characters) characters

cloc cartesian location 36

ploc precision location 36

void used for forming generic pointers

int
An int, or integer, is a signed number without any decimal or fractional part.
Examples: 0, 1, 23, 456, -7, -89

float
A float, or floating point number, is a number with a decimal or fractional part
and an optional exponent. A float has up to seven significant digits.
Examples: 4.75, -99.99, 1.0, 3.141593, 1.0e10

string
A string is a set of characters: uppercase or lowercase letters, digits,
punctuation and other graphic characters, and the blank space. In a string, a
digit is a character and does not have numeric value as it does in a number (int
or float). RAPL-3 does not have a character data type.

cloc
A cloc, or cartesian location, represents a point in the robot arm workspace
defined by cartesian co-ordinates. Coordinates have three translational elements
(along axes) x, y, and z, and three rotational elements (around axes) z, y, and x.
The values of a cloc are independent of arm position and arm type.

ploc
A ploc, or precision location, represents a point in the robot arm workspace
defined by increments of rotational movement, specifically encoder counts, of
each joint of the arm and any additional axes (j1, j2, j3, j4, j5, j6, j7, j8). The
values of a ploc are dependent on the robot.
RAPL-3 Reference Guide 15

void
The void type is used to form void pointers (pointers that can point to any type).
void@ x
Void pointers are assignment compatible with all other types of pointers.
16 Data Types and Variables

Identifiers
An identifier is used for the name of a variable, type, subroutine, function, or
command.

Character Set
An identifier begins with a letter. This may be followed by zero or more letters,
digits, or _ (underscore) characters.
a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9
_

Case
Letters may be either uppercase (ABCDE), lowercase (abcde), or mixed (AbCdE).
RAPL-3 is case-sensitive with identifiers. For example, the following are all
different identifiers.
x ;; lowercase
X ;; uppercase
symbol ;; lowercase
SYMBOL ;; uppercase
sYmBoL ;; mixed
SyMbOl ;; mixed

Length
An identifier may be any length, but only the first 32 characters are significant.
For example, the following are not different identifiers.
location_sensor_data_collection_1
location_sensor_data_collection_2

Examples
There are many possibilities of valid identifiers.

Valid
a ;; a single letter
num ;; several letters
my_symbol ;; letters with underscore
MySymbol ;; letters of different cases
x3 ;; letter with digit
rack_loc_12 ;; letters, underscores, digits

Invalid
3a ;; begins with a digit, not a letter
my$symbol ;; uses a character not in the valid character set
&num ;; uses a character not in the valid character set
;; and does not begin with a letter
 RAPL-3 Reference Guide 17

Declarations
This section details the declaration of: int, float, string, cloc, and ploc. For the
declaration of arrays of these types, see the Arrays section. For const, see the
Initializers section.
Each variable must be declared as one specific type of variable (int, float, string,
cloc, ploc, const). A declaration states the type of variable and the name of the
variable.
You can declare a variable explicitly or implicitly. It is good programming practice
to explicitly declare all variables.

Explicit Declarations
When you declare a variable explicitly, you list it in a declaration statement
before you use it in the program.
Variables being declared as the same type can be listed in the same declaration,
separated by commas.

Syntax
type identifier
type identifier, identifier, identifier ...
where
type is the data type, and
identifier is the name of the variable and follows the rules for identifiers.

Examples

Type Example Description

int int i i is an integer

float float a,b a and b are floats

string string[10] message message is a string that can hold 10 or fewer

characters

cloc cloc pick_1, pick_1 and place_1 are cartesian locations

place_1

ploc ploc pick_2, pick_2 and place_2 are precision locations

place_2

Implicit Declarations
When you declare a variable implicitly, you indicate the variable’s type with a
prefix before its name when you use it in the program for the first time.
If a variable is used without having been explicitly declared, the compiler looks
for an implicit declaration prefix character on the variable name to determine the
type of variable. If there is no prefix character, the compiler defines the variable
as the default type, an int, and issues a warning.
In general, implicit declarations should be avoided. You should always explicitly
declare variables.
18 Data Types and Variables

Syntax
[prefix_character]identifier
where
prefix_character is the character indicating the data type, and
identifier is the name of the variable and follows the rules for identifiers.

Implicit Declaration Prefix Characters

Prefix Character Type Example
none int a = 2
% percent sign float %b = 10.25
$ dollar sign string[64] $m = "Robot working.\n"
_ underscore cloc here _z
# number sign ploc here #y

Examples
Type Example Description
int e = c + d e is defined as an int, if it has not been seen before.
float %h = f * g h is defined as a float.
string $notice9 = notice9 is defined as a string[64].
"stop"
cloc here(_place22) place22 is defined as a cloc.
ploc here(#material3 material33 is defined as a ploc.
3)

Implicit with Explicit

If an implicit declaration prefix is used in an explicit declaration statement, the
implicit prefix is ignored by the compiler. For example,
float %b ;; the variable b is declared as a float
float $c ;; the variable c is declared as a float
float #d ;; the variable d is declared as a float

Identifiers
The prefix character indicates the type of declaration. It is not part of the
identifier, the variable’s name. For example, if _m was used in a statement, a cloc
with the name m was defined. A later statement with #m causes an error, the
same way that cloc m followed by ploc m causes an error.

Scope
Two variables with the same scope cannot have the same name. For definitions of
scope, see the Scope section of the Subprogram chapter.

Teachables
Teachable variables that are declared inside a sub, func, or command must not
have the same name as any teachable outer-frame variable.
 RAPL-3 Reference Guide 19

Strings
The string type is essentially a character array with a fixed size.
The string type must always have a subscript, indicated by [ ] (square brackets).

String[number]
Usually, the subscript contains a number to specify the maximum length of
string that can be stored in it, such as string[10] or string[64].

Syntax
string[number] identifier
where
string and the square brackets are required,
number is the character size of the string, and
identifier is the name of the variable and follows the rules for identifiers.

String[ ]
In some circumstances, the subscript can be empty.
string[]
This undimensioned string declaration can be used only in the following
circumstances.
• A simple single string being initialized. When string[] is used, the compiler
determines the size of the string. In this example, the compiler makes notice9
a string[18].
string[] notice9 = “End of work cycle.”
• A function formal parameter or var parameter.
func int strlen(string[])
sub str_append(var string[] dst, string[] src)
• The target of a pointer.
string[]@ sptr
For a table of pointers to strings of unknown length, use
string[]@[5] greek = {“alpha”, “beta”, “gamma”, “delta”,
“epsilon”}

Notes:
A RAPL-3 string is actually stored as a length, a limit, and an array of
characters. The length value indicates how many characters are actually valid.
Strings can be created with at most space for 65,532 characters. The limit value
indicates how many characters there is actually room for. For example, if we
have a variable:
string[10] s
then s is initially created with its length set to 0 (no characters; the empty string)
and its limit set to 12. The limit is 12 because RAPL-3 always allocates storage in
units of 1 word (or 4 characters); string[10] actually needs 1 word for the length
and limit, and an additional 3 words for the characters (which actually is 3 * 4 or
12 characters in size.) After this statement:
s = hello!
20 Data Types and Variables

the length of s is set to 6, and the characters h , e , l , l , o and ! have be

stored in the character part of the string.

Termination
RAPL-3 does not use any string termination character. The variable is declared
and the string of characters is packed into the variable.

Concatenation
To concatenate (link together to form a longer string), use the str_append
subroutine with string variables. The + (plus) operator can be used to
concatenate string constants.
 RAPL-3 Reference Guide 21

Arrays
An array is a collection of data objects where all are the same data type and all
use the same identifier but each has a unique subscript.
Syntax
base_type[ subscript_list ] identifier
where
base_type is the data type of each element in the array,
subscript_list is a comma-separated list of one or more constant expressions
defining each dimension, and
identifier is the name of the variable and follows the rules for identifiers.

A subscript must be a constant expression, such as a simple integer constant.

The compiler must be able to compute the value of each constant expression at
compile time.
Types
You can have an array of any type or an arrays of arrays.
Dimensions
There is no limit on the number of dimensions allowed, except for teachable
arrays. See Teachables.
Numbering
In RAPL-3, numbering begins with 0.
Declaration Number of Numbering
Elements
int[4] a 4 a[0], a[1], a[2], a[3]

int[10] a 10 a[0], a[1], a[2], a[3], a[4], a[5], a[6], a[7], a[8], a[9]

int[20] a 20 a[0], a[1], a[2], a[3], a[4], a[5], a[6], a[7], a[8], a[9],
a[10], a[11], a[12], a[13], a[14], a[15], a[16], a[17], a[18], a[19]

int[100] 100 a[0], a[1], a[2], a[3], a[4], a[5], a[6], a[7], a[8], a[9],
a through to
a[90], a[91], a[92], a[93], a[94], a[95], a[96], a[97], a[98], a[99]

Review of Strings

Example Description
string[30] z a string that can hold 30 or fewer characters

One Dimensional Arrays

Example Description
int[5] a an array of 5 integers
a[0], a[1], a[2], a[3], a[4]
float[10] b an array of 10 floats
b[0], b[1], b[2], ... b[9]
ploc[20] c an array of 20 precision locations
c[0], c[1], c[2], ... c[19]
string[30] [10] d an array of 10 strings
d[0], d[1], d[2], ... d[9]
each can hold 30 or fewer characters
22 Data Types and Variables

Two Dimensional Arrays

Example Description
int[5,10] e a 2-dimensional array of 50 integers
e[0,0] ... e[0,9]
... ...
e[4,0] ... e[4,9]
float[10,20] f a 2-dimensional array of 200 floats
f[0,0] ... f[0,19]
... ...
f[9,0] ... f[9,19]
ploc[5,10] g a 2-dimensional array of 50 precision locations
g[0,0] ... g[0,9]
... ...
g[4,0] ... g[4,9]
string[20][5,10] a 2-dimensional array of 50 strings
h h[0,0] ... h[0,9]
... ...
h[4,0] ... h[4,9]
each can hold 20 or fewer characters
int[10] [5] i a 2-dimensional array of 50 integers
same as int[5,10] e
brackets are applied from left to right
float[20][10] j a 2-dimensional array of 200 floats
same as float[10,20] f
brackets are applied from left to right
string[20] [10] a 2-dimensional array of 50 strings
[5] k same as string[20] [5,10] h
string[50][23 + an array of 30 strings,
7] m each can hold 50 or fewer characters

Multi Dimensional Arrays

Example Description
int[2,2,2] n a 3-dimensional array of integers
n[0,0,0], n[0,0,1],
n[0,1,0], n[0,1,1],
n[1,0,0], n[1,0,1],
n[1,1,0], n[1,1,1]

float[5,5,5,5] p a 4-dimensional array of integers

p[0,0,0,0] to p[4,4,4,4]

Declarations
You cannot implicitly declare an array.
However, if you use the implicit declaration syntax in a statement with an array,
you will not cause a problem, if the array is previously declared and the implicit
declaration character matches the base type of the array. For example,
ploc[16,16] a
...
here(#a[1,1])
 RAPL-3 Reference Guide 23

Teachables
A variable that is teachable is accessible from outside the program.

Use
Teachables provide an easy way, outside the program, to modify a value for a
variable, store that value, and use the value in a program. Using this feature
avoids writing (hard-coding) values in the program and having to re-write the
program to change the values. It also avoids storing the values in a custom user-
designed file and having to carefully edit the file to change values and include a
routine in the program to read that custom data file.
Data about teachable variables and their values are stored in the variable file.
When you run a program, the operating system takes the program s variable file
and uses its values to initialize the variables in the program just before running.

Variable (v3) File

Data about teachable variables are stored in the variable file (also known as a v3
file). You modify data, or teach locations and other variables, using the teach
pendant or the application shell.
You can create a variable file in a number of ways.
• Refreshing from the Program. When your program file is in a CROS directory
(in CROS-500 or CROSnt), ash s refresh command reviews the program and
adds any teachable variables of the program to ash s database. After
assigning values (including teaching locations) to the teachables in the
database, this new data is saved to the variable file. This method is used if
you write your program before teaching your locations.
• Building Independently. You can build a variable file completely in a CROS
directory (in CROS-500 or CROSnt) using ash or the teach pendant. With
ash s or the teach pendant s database, you create variables and assign values
to them. When you are finished this data is saved to in the variable file. This
method is used if you teach your locations before writing your program.
See the Application Development Guide chapters on the application shell.

Declarations
You make a variable teachable by adding the keyword teachable before the data
type at declaration. Teachables are not initialized.

Syntax
teachable type identifier
teachable type identifier, identifier, identifier ...
where
teachable is a necessary keyword
type is the data type, and
identifier is the name of the variable and follows the rules for identifiers.
24 Data Types and Variables

Examples

Example Description

teachable int cycles cycles is an teachable integer

teachable float a, b, c a, b, and c are teachable floats

teachable string[10] note note is a teachable string that can hold 10 or fewer
characters

teachable cloc pick_1, pick_1 and place_1 are teachable cartesian

place_1 locations

teachable ploc pick_2, pick_2 and place_2 are teachable precision

place_2 locations

teachable int[3] step step is a teachable array of 3 integers: step[0],

step[1], step[2]

teachable float[5,5] delta is a teachable two-dimensional array of

delta floats: delta[0,0] ... delta[4,4]

teachable ploc[2,10] spot spot is a teachable two-dimensional array of

precision locations: spot[0,0] . . . spot[1,9]

Limitations
Data Types
There are limits on which data types are teachable. Simple, scalar variables can
be teachable. One-dimensional arrays of variables can be teachable. Two-
dimensional arrays, except string[n], can be teachable. Three-dimensional and
higher dimensional arrays cannot be teachable. The void type cannot be
teachable.

= can be teachable

= cannot be teachable

int float string[n] cloc ploc gloc void

simple

one-dimensional

array
two-dimensional


array
three-dimensional







or higher array

Not Initialized
A variable cannot be both teachable and initialized. You cannot write
teachable int a = 5
teachable string[64] message_12 = “Error recovery underway.“.
RAPL-3 Reference Guide 25

Storage Class: Static

Variables which are declared as teachable are static. They should not be used in
recursive routines except as read only.

Defaults and Unteachables

Scope and Declaration Defaults
The following variables are teachable by default.
Local (within a subprogram or main) and Implicitly Declared
• clocs, and plocs
sub
...
here(_point)
end sub

main
...
here(_place)
end main
Outer-Frame (outside all subprograms and main) and Explicitly Declared
• clocs, and plocs
• 1-dimensional and 2-dimensional arrays of clocs, and plocs
ploc start_point
cloc[10] point

sub
...
end sub

main
...
end main
All other variable types are unteachable by default.

Unteachable Declaration
A variable can be declared as unteachable with the unteachable keyword. This
can be used to make an outer frame location that is not teachable, for example
unteachable cloc[10] point

sub
...
end sub

main
...
end main
 RAPL-3 Reference Guide 45

Location Constants
You can initialize cloc and ploc variables. The RAPL-3 compiler has built-in
functions: cloc{} for generating cloc constants, and ploc{} for generating ploc
constants. All of the arguments to cloc{} or ploc{} must be constant expressions
and the result is a constant expression that can be used in a variable
initialization.
The format of cloc{} is:
cloc{ flags, x, y, z, zrot, yrot, xrot, e1, e2 }
Where flags specifies extra information about the location, x, y, and z are the
translational coordinates along the world axes, zrot, yrot, and xrot are
orientational coordinates around world axes, and e1 and e2 are the coordinates
for extra axes such as track. The argument flags must be an int constant
expression and all other arguments are float constants.
An example of cloc{} is the following definition:
cloc my_tool = cloc{0, 0.0, 0.0, 10.0, 0.0, 0.0, 0.0, 0.0, 0.0}
;; tool transform for use with the tool_set() command.
The format of ploc{} is:
ploc{ machtype, flags, a1, a2, a3, a4, a5, a6, a7, a8 }
Where machtype is the machine type (each type of machine, F3, A465, A255, ...,
has a different geometry and configuration resulting in different encoder counts
for a given location), flags specifies extra information about the location, and a1
to a8 specify the number of encoder pulses from zero of the desired position for
each axis. The arguments machtype, flags, and a1 to a8 are integer constant
expressions.
An example of ploc{} is:
ploc start_point = ploc{mc_a465, 0, 3500, 2800, 1000, 4000,
2500, 1500}
;; initialized precision location
A word of warning: initialized clocs are useful for specifying tool transforms and
related information. It is, however, very dangerous to hand-construct plocs and
command to robot to move to them. This is because the robot cannot physically
move to any arbitrary joint configuration, and may collide with itself or objects in
the workspace. If you must hand-construct locations, use extreme care.
46 Control Flow
CHAPTER 5

Control Flow

When a program executes, generally the computer executes one line, then the
next, then the next. In order to make a program do useful things for example,
to repeat a particular task 10 times we must be able to alter the way in which
control passes from line to line of the program.
This section deals with statements that alter the sequence in which the
statements in a program execute, allowing loops and conditional statements.
48 Control Flow

break
Description Exit from a looping construct to the statement immediately following the looping
construct (the statement immediately following until, end while, end for, or end
loop).
Can be used to exit from the following looping constructs: do, while, for, or loop.
Often used with a condition such as an if or if-else statement.
If loops are nested, break exits from only the innermost do, while, for, or loop
statement that encloses the break.
Syntax break
Context while ( expression_1 )
...
if ( expression_2 )
break
end if
...
end while
Example A loop that counts to 10.
int i
i = 0
loop
if i == 10
break
end if
i++
end loop
Break exits from the loop when i equals 10.
See Also continue, do, for, loop, while

case
Description Executes one of several statements, depending on the value of an integer
expression. Note that you can implement any case statement with a series of if
statements; the case statement just provides a compact way to select between
several statements based on a value.
Syntax case expression
[ of constant_1 : ]
[ statement(s) ]
[ of constant_2 to constant_3 : ]
[ statement(s) ]
[ of constant_4,constant_5 : ]
[ statement(s) ]
...
[else
[ statement(s) ]]
end case
Example 1 An example with a single value, a list of values, a range of values, a mixed list,
and an else value.
int tracking
string[64] message_1
...
case tracking
of 1:
 RAPL-3 Reference Guide 49

message_1 = "success"
of 2, 3, 5:
message_1 = "at maximum limits"
of 6 to 10:
message_1 = "beyond maximum limits"
of 10 to 15, 20 to 23, 99:
message_1 = "failure"
else
message_1 = "unknown"
end case
Example 2 When this code is executed, if z = 1, 2, 3, or 6, then $y is set to hello . If z is 4 or
5, then $y is set to goodbye . If z is 7, then $y is set to right . If z is not equal to
any of these values, then $y is set to unknown .
case z
of 1 to 3, 6:
$y[] = “hello”
of 4, 5:
$y[] = “goodbye”
of 7:
$y[] = “right”
else
$y[] = “unknown”
end case
RAPL-II No equivalent in RAPL-II.
See Also if

continue
Description By-passes the remainder of the body of a loop and goes to the next iteration of
the loop: the condition in do or while, the step increment in for, or the beginning
of the next iteration in loop.
Can be used to by-pass the body of the following looping constructs: do, while,
for, or loop.
Often used with a condition such as an if or if-else statement.
If loops are nested, continue by-passes the body of the innermost do, while, for,
or loop statement that encloses continue.
Syntax continue
Context while ( expression_1 )
...
if ( expression_2 )
continue
end if
...
end while
Example Print only odd numbers.
for i= 1 to 10
if (i/2)*2==i ;; integer division
continue ;; it is even
end if
print i, “\n”
end for
Result 1
3
5
7
9
50 Control Flow

See Also break, do, for, loop, while

do
Description A looping construct that tests a condition at the end of the loop.

Flow enters the loop and the statements are executed down to the just before the
until. The control expression following the until (a condition) is tested. If the
expression is true (non-zero), flow goes back to the first statement after do. If the
expression is false (zero), flow proceeds to the statement following the until.

Since the controlling expression is executed after the body of the loop, the loop
body is always executed at least once, even if the first test of the control
expression is false (zero).

A break can be used to exit a do loop and proceed to the line following the until.
A continue can be used to by-pass the remainder of the body of a do loop. A
goto can be used to jump to another position in the subprogram.

do statements can be nested.

Syntax do
statement(s)
until expression

Example A simple do loop.

i = 0
do
move #safe_path[i]
i = i + 1
until i > 4

The loop body executes 5 times, with i having the values 0, 1, 2, 3, and 4. On exit
from the loop, i has the value 5.

See Also while, for, loop, break, continue, goto

for
Description A looping construct that executes a loop for a defined number of times.

The for construct controls the number of times the loop is executed by using an
integer variable (a counter) with an initial value, a final value, and the size of step
(increment) from initial to final.

Defining the step is optional. If step is not specified, it is assumed to be +1.

Step can be negative for a decrementing counter. In any event, the specified step
must be a constant expression.

For executes in the following way. The counter variable is initialized to the value
of expression_1. The counter is then tested to see if it is greater than (if step
expression_3 is positive) or less than (if step expression_3 is negative)
 RAPL-3 Reference Guide 51

expression_2. If so, execution proceeds at the first statement after the end of the
loop (after end for). The statements in the body of the loop are executed. At the
end of these statements the step (expression_3) is added into the counter.
Control then loops back to the condition test and we repeat.

One implication of the way in which the for loop is implemented is that it is
possible that the body of the loop might never be executed. Consider the
following for loop:

for x = 1 to 0
printf(“This is never printed\n”)
end for

The loop does nothing, since the test (is x > 0) is true initially, causing the body
of the loop to be skipped.
Syntax for variable = expression_1 to expression_2 [step expression_3 ]
statement(s)
end for

Example With an increment of 1.

for x = 1 to 10
move #safe[x]
end for

Step is not specified and is assumed to be + 1. The function move is executed

10 times, with x = 1, 2, 3, ... 10. The arm moves from safe location 1 to 2 to 3 ...
to 10.

With a decrement of 1.

for x = 10 to 1 step -1
move #safe[x]
end for

Step is defined as 1. The functionmove is executed 10 times, with x = 10, 9,

8, ... 1. The arm moves from safe location 10 to 9 to 8 ... to 1.

With an increment of 3.

for x = 1 to 11 step 3
move #safe[x]
end for

Step is defined as + 3. The function move is executed 4 times, with x = 1, 4, 7,

and 10. The arm moves from safe location 1 to 4 to 7 to 10. Note that even
though the limit expression_2 is 11, this value is never seen by the body of the
loop, since the next value after 10 (13) is in fact beyond the limit.
See Also do, while, loop

goto
Description Jumps to a statement marked with a label.

A label is named with an identifier and follows the rules for identifiers. The label
can be before or after the goto.
52 Control Flow

A goto can jump only to statements within the main program or within the
current subprogram (sub, func, or command). A goto can neither jump between
the main program and a subprogram, nor between subprograms.

Caution Gotos should be used with caution. Overuse of the goto statement can make
code extremely difficult to read and debug. Good use of conditionals, loops,
break, or continue can almost always eliminate the need for a goto.

Syntax The label identifier is followed by two colons. The immediately following statement
may be on the same line or the next line.

identifier:: statement
...
goto identifier

identifier::
statement
...
goto identifier

Example A simple goto.

...
label_1::
...
if(query_another_loc()==‘Y’)
goto label_1
end if
...

The earlier statement declares the label label_1. If the condition in the if
statement is true, the goto directs control to the statement following label_1.

See Also identifiers, break, continue

if
Description A conditional construct which causes a statement to be executed only if a specific
condition is true (non-zero). Optional else and elseif clauses allow 2-way or
multi-way branching.
Begins with if and ends with end if. The use of then is optional. Can be used
with else and with elseif.
You can use if with else, to execute one set of statements if the condition is true,
and execute a different set of statements if the condition is false. This
construction is a two-way branching (see syntax (b)). The elseif keyword allows
an if statement to evaluate several possible conditions in turn creating a multi-
way branch like a case statement (see syntax (c).)
If statements can be arbitrarily nested.
Syntax (a) a simple if statement:

if expression [then]
statement(s)
end if
 RAPL-3 Reference Guide 53

(b) if with an else clause

if expression [then]
statement(s)
else
statement(s)
end if

(c) if-elseif construction

if expression [then]
statement(s)
elseif expression
statement(s)
elseif expression
statement(s)
else
statement(s)
end if

Example (a) This is a simple if statement.

if (curr_locnum <= num_safe_path_locs) then

move #safe_path[curr_path_locnum]
end if

If the condition is true (curr_locnum is less than or equal to num_locs), the move
statement executes. If the condition is false, the program flow proceeds to the line
following end if.

(b) This is an if and else construction.

if (curr_locnum <= num_locs)

move #safe_path[curr_locnum]
else
curr_locnum = curr_locnum - 1
end if

If the condition is true (curr_locnum is less than or equal to num_locs), the move
statement executes. If the condition is false, the statements following else
execute (curr_locnum is decremented by 1).

(c) This is one example of nested statements. Inner statements must end before
outer statements.

if (num==num_locs+1)
print_msg_screen(“Teach new power loc.”)
teach(#power_loc[num])
num_locs++

if(num_locs<10)

if(query_another_power_loc()==‘Y’)
goto labl
else
num_locs=0
end if

end if

end if
54 Control Flow

(d) An elseif construction.

if(t==123)

elseif(t<10)

elseif(t>200)

else

end if
See Also case

loop
Description A looping construct with no condition.
Begins with loop and ends with end loop.
Since there is no control expression, the loop continues forever until a break or
if necessary, a goto, causes flow to proceed out of the loop.
loop statements can be nested.
Syntax loop
statement(s)
end loop
Example In this example, the program prompts and gets a number to identify a location.
The prompting and getting continues indefinitely until the user enters a valid
number.
[1] loop
[2] printf(“Enter location number >”)
[3] readline($str, 10)
[4] if str_to_int(num, $str) < 0
[5] print(“Invalid number\n”)
[6] continue
[7] end if
[8] if((num<0)or(num>20))
[9] printf(“Number is out of range\n”)
[10] continue
[11] end if
[12] break ;; if we get here, we are DONE
[13] end loop

Line 2 displays a prompt asking the user to enter the number of the desired
location. Lines 3 to 7 read in a string typed by the user and try to convert the
string to an integer. If this fails, an error message is printed and a contine
sends control back to the start of the loop. Lines 8 to 11 verify that the number
is in the expected range, displaying an error message and sending control back to
the start of the look if it is not. Lastly, line 12, which is reached only if the
number is valid and in range, exits the loop.
See Also do, while, for, break, continue, goto

while
Description A looping construct that tests a condition at the beginning of the loop.
Begins with while and ends with end while.
The control expression (a condition) is tested. If the control expression is true
(non-zero), then flow enters the loop and the statements are executed. At the
end, flow goes back to the control expression for the next test. If the expression is
 RAPL-3 Reference Guide 55

false (equals zero), flow proceeds to the statement following end while.

If the initial test is false (zero), flow never enters the body of the loop and the
statements are never executed.

If the control expression never evaluates to zero, or is a non-zero constant, for

example while(1), the loop continues indefinitely.

A break can be used to exit a while loop and proceed to the line following the end
while. A continue can be used to by-pass the remainder of the body of a while
loop. A goto can be used to jump to another position in the program.

While statements may be arbitrarily nested.

Syntax while expression
statement(s)
end while
Example A simple while statement.
i = 0
while i < 5
move #safe_path[i]
i = i + 1
end while

The loop body executes 5 times, with i having the values 0, 1, 2, 3, and 4. On exit
from the loop, i has the value 5.

See Also do, for, loop, break, continue, goto

56 Control Flow
CHAPTER 6

Subroutines, Functions and

Commands

RAPL-3 has three distinct kinds of executable objects: subroutines (subs),

functions (funcs), and commands (commands). Collectively, subs, funcs, and
commands are referred to as subprograms. main itself is a special case of a
command subprogram.
58 Subroutines, Functions and Commands

Subprograms
One way to understand the concept of subprograms is to look at a brief example:
[1] sub sayhello()
[2] int x
[3] x = 0
[4] printf(“Hello!\n”)
[5] end sub
[6]
[7] sub say_n_plus_1(int n)
[8] printf(“n + 1 = {}\n”, n + 1)
[9] end sub
[10]
[11] func int a_plus_b(int a, int b)
[12] return a + b
[13] end func
[14]
[15] main
[16] int x, y
[17] x = 10
[18] sayhello()
[19] say_n_plus_1(x)
[20] y = a_plus_b(1, x)
[21] printf(“x + 1 = {}\n”, y)
[22] end main
This example defines two subs (called sayhello() and say_n_plus_1()) and one func
called a_plus_b().
Program execution starts in main. Line 16 declares two variables that belong only
to main (local variables) called x and y; in line 17, x is set to have the value 10.
When line 18 is reached, the subroutine sayhello() is executed. sayhello() has its
own local variable x, which it sets to have a value of 0 in line 3. sayhello() then
executes line 4 which prints a message out on the console. When the end of
sayhello() is reached, control returns to main to line 19.
The fact that sayhello() has set its variable x to be 0 does not change the value of
main s variable x at all. Any variable declared inside a subprogram islocal to
that subprogram and cannot be changed by any outside means. Variables that
are declared outside of any subprogram are accessible to all subprogram and are
called program scope or simply program variables. This concept of local and
program variables is part of variable scope.
After sayhello() is executed (called) by main, main calls the sub say_n_plus_1().
One difference between the call to sayhello() and the call to say_n_plus_1() is that
the latter has an expression (x) inside the brackets next to the sub name. This is
an argument (or actual parameter) to say_n_plus_1(). The value of x is given (or
passed) to the subprogram.
Subprogram say_n_plus_1() then executes with its variable n initially set to 10,
since that was the value passed to it by main. n is a special local variable of
say_n_plus_one() called a formal parameter. formal parameters get initial values
that are given by the caller of the subprogram, in this case, main.
At line 8, say_n_plus_one now prints out the value of n + 1, which is 11 in this
case. Control returns to main at line 20.
In line 20, main sets y equal to a_plus_b(1, x). This is an example of a function
call; the func a_plus_b() is called with the two arguments (1 and 10 (x)) just like a
sub is called. Line 12 is the only line in a_plus_b(), and is a return statement.
For a function, the return statement indicates that a value (in this case a + b or
11) is to be returned to the calling subprogram. The effect in this example is that
y gets set to the value that a_plus_b() returns, or 11.
This result is printed out at line 21, and the program ends. The rest of this
chapter explains in detail the elements of RAPL-3 that deal with subprograms.
 RAPL-3 Reference Guide 59

Kinds of Subprograms
subs
A sub (subroutine) is the simplest kind of RAPL-3 subprogram. A sub can take
any number of arguments (including none), but does not return any value to the
calling subprogram. As a result, a sub cannot appear inside an expression.

Declaration Syntax
sub sub_identifier ( parameter_list )
[ declarations and statements... ]
end sub

Calling Syntax
sub_identifier(actual_parameter_list)
Note that the actual_parameter_list must match the parameter list in the sub
declaration. That is, there must be the same number of parameters as those
declared, and the types of the expressions must be compatible.

funcs
A func is similar to a sub in that it can accept any number of arguments.
However, a func returns a value to the calling subprogram. In RAPL-3, funcs
can return any int, float, cloc, ploc, gloc or pointer type of value (a func cannot
return a string or structure, but can return a pointer to a string or structure.)
For example, a = sin(x) + cos(y) calls the sin() function to compute the value
of the sine of variable x, calls the cos() function to compute the cosine of variable
y, adds the two and then stores the result in variable a.

Declaration Syntax
func type func_identifier ( parameter_list )
[ declarations and statements... ]
return value
end func
Note that there must be at least one return statement that returns the value of
the correct type somewhere in the body of the function. Functions can return
only int, float, location, or pointer types.

Calling Syntax
There are two ways to call a function. As part of an expression:
... func_identifier(actual_parameter_list)...
or by itself as a statement:
func_identifier(actual_parameter_list)
In the latter form, the compiler will warn that the return value of the function is
being ignored (unless warnings are disabled.)
Once again, the actual_parameter_list must match the parameter list in the func
declaration.
60 Subroutines, Functions and Commands

commands
A command is in many respects identical to a func int. Commands must return
an integer value, and can appear in expressions just like a func. The difference
lies in the way that a command behaves when it is called as a statement by
itself. In this case, the compiler generates code that checks the return value of
the command, and if that value is less than zero (negative) it causes an exception
to be raised with the error code equal to the returned value. This provides a
default way of handling errors; commands that fail should return a negative
number describing the error (and error descriptor). The system can then handle
the error, even if only by aborting the program and issuing an error message.
The section on structured exception handling deals with exceptions, and with how
to handle them, in more detail.
Note that this automatic error check is not performed when the command is used
as a function in an expression. This allows the code to look for and handle errors
explicitly.

Declaration Syntax
command cmd_identifier ( parameter_list )
[ declarations and statements... ]
return value
end command
Note that there must be at least one return statement that returns an integer in
the body of the command.

Calling Syntax
There are two ways to call a command. As part of an expression:
... cmd_identifier(actual_parameter_list)...
or by itself as a statement:
cmd_identifier(actual_parameter_list)
The latter form is the more usual. Unlike functions, the compiler does not warn
about the return value being ignored, since code is automatically generated to
check the return value and act upon it if it is negative.
Once again, the actual_parameter_list must match the parameter list in the
command declaration.

Example
Most of the robot and CROS operations are, in fact, commands. A program can
move the robot to a given location using the move() command like this:
move(#this_loc)
In this case the system handles any errors that move() reports (by means of its
return value.) In the following example, we examine and act on the error
explicitly:
r = move(#this_loc)
if (r < 0)
;; take action...
...
end if
RAPL-3 Reference Guide 61

Where main fits in

The main part of a RAPL-3 program is actually a special type of command. It
differs from a normal command in three respects:
(1) It is declared with main and end main
(2) It need not contain a return statement; the compiler automatically
inserts a return 0 at the end ofmain. The user is free, however, to
return some other value instead.
(3) When the program is run, the main section is called by the startup code.
62 Subroutines, Functions and Commands

Parameters
In func, sub and command declarations, the parameter_list part is a comma
separated list of individual parameter_declarations, possibly empty. Each
parameter_ declaration takes the form:
[var] [ type_declaration ] identifier
If type_declaration is omitted then int is the default.
To the subprogram, the parameter looks like an ordinary local variable. However,
its value is set to the actual parameter value provided by the caller.
The special optional keyword var indicates whether or not changes to the
parameter value inside the subprogram change the value of the parameter in the
calling subprogram. The default (var keyword omitted) does not change the
variable outside the subprogram. For example:
sub this_routine(float x)
x = 2.71828 ;; will have no effect on the
;; calling subprogram
end sub

sub that_routine(var float y)

y = 1.0
end sub

... ;; in the calling subprogram

this_routine(t) ;; t is unchanged after this call
that_routine(t) ;; t is 1.0 after this call

Restrictions on Parameters
Function formal parameters (appearing in declarations) that are complex entities
like strings, arrays, or structs are treated by the compiler exactly as if they had
been declared var. (Internally, this is done by passing where the object is
instead of the passing the value of the object itself.)
If this kind of complex parameter is not actually declared var, then the compiler
will generate warnings about any code in the subprogram that modifies the
variable. This protects the programmer from inadvertently changing the
variable s value in the calling routine.
The compiler also generates a warning if a string constant is used as the actual
parameter of a formal var string[] parameter.
Var parameters can be of any type, but non-var parameters may be only int,
float, cloc, ploc, gloc, or any pointer type. Furthermore, when calling a
subprogram, var actual parameters must be expressions that might reasonably
occur on the left-hand-side of an assignment. For example:
sub alpha(var float x) ;; note the var parameter
...
end sub

... ;; in another subprogram

alpha(a[j*i+1]) ;; this is OK
alpha(q) ;; this is OK
alpha(q+1) ;; but this is not OK
...
RAPL-3 Reference Guide 63

sub beta(int[10] a) ;; this is taken to be

... ;; var int[10] a
end sub

sub gamma(int[10]@ a) ;; this is OK

...
end sub

sub delta(var int[10] a) ;; this is OK

...
end sub