Leica tps1100 User manual

GeoBASIC FOR TPS1100
User Manual
Version 2.10
1997-2001 Leica Geosystems AG
Heerbrugg, Switzerland

GeoBASIC User Manual 1 — Introduction
TPS1100-Version 2.10 1-1
1Introduction ............................................................................................... 1-3
2Installation.................................................................................................. 2-1
2.1 Setup ........................................................................................................... 2-1
3Creating a GeoBASIC Application.......................................................... 3-1
3.1 GBStudio development environment.......................................................... 3-1
3.2 Typical Development Cycle........................................................................ 3-7
3.3 Project Handling ......................................................................................... 3-3
3.4 Common Problems...................................................................................... 3-4
3.5 Compiler Limitations .................................................................................. 3-5
4Executing a GeoBASIC Program on the theodolite................................ 4-6
4.1 Loading a GeoBASIC program................................................................... 4-6
5Executing a GeoBASIC Program on the Simulatior............................... 5-1
5.1 General........................................................................................................ 5-1
5.2 User Interface.............................................................................................. 5-1
5.3 Loading and executing GeoBASIC programs............................................. 5-2
5.4 Configuration of the Simulator.................................................................... 5-3
5.5 GeoCom Mode............................................................................................ 5-4
5.6 SWTheo Mode............................................................................................ 5-4
5.7 Commonly asked questions and answers..................................................... 5-7
6Additional Debugging Functions.............................................................. 6-1
7Multiple Language Support...................................................................... 7-1
7.1 Text Utility.................................................................................................. 7-2
8Typical GeoBASIC Programming............................................................ 8-1

GeoBASIC User Manual 1 — Introduction
1-2 TPS1100-Version 2.10
8.1 The Text Dialog.......................................................................................... 8-1
8.2 The Graphics Dialog................................................................................... 8-5
8.3 Naming conventions.................................................................................... 8-9
9Refined GeoBASIC Concepts ................................................................... 9-1
9.1 Units............................................................................................................ 9-1
9.2 The User Measurement Dialog.................................................................... 9-2
9.3 TPS1100 Configurability............................................................................ 9-5
9.4 Interapplication-Call ................................................................................... 9-8
9.5 System Function Call .................................................................................. 9-9
9.6 System Event Generation.......................................................................... 9-10
10 GeoBASIC Sample Programs................................................................. 10-1
10.1 MeanHz — Mean Value of Horizontal Angle Measurements................... 10-1
10.2 Sample Programs ...................................................................................... 10-8
11 Porting a TPS1000 Originated Program............................................... 11-1
11.1 TPS1100 Hardware Related Changes....................................................... 11-1
11.2 Changes to the Simulator .......................................................................... 11-2
11.3 New constructs in GB_1100 ..................................................................... 11-2
11.4 GeoBASIC Source Changes...................................................................... 11-3
12 GeoBASIC Releases................................................................................. 12-1
12.1 Changes in GeoBASIC Release 1.30 ........................................................ 12-1
12.2 Changes in GeoBASIC Release 2.10 ........................................................ 12-3

GeoBASIC User Manual 1 — Introduction
TPS1100-Version 2.10 1-3
1 INTRODUCTION
GeoBASIC is a programming language for LEICA theodolites and their simulation
on personal computers. The core language appears similar to today's common
Windows BASIC dialects, thereby it is easy to learn and use. However,
GeoBASIC's main power lies in its ability to use many of the existing theodolite
subsystems and dialogs, just by calling an appropriate built-in function: for setting
parameters, measuring, geodesy mathematics, and many things more. These tools
at hand, the programmer can quickly and flexibly build sophisticated geodesy
applications.
The user manual first describes the installation of GeoBASIC on a PC (Chapter 2).
Then, after learning how to create an GeoBASIC application (Chapter 3), it will
be shown how to actually load and execute a program on a LEICA theodolite
(Chapter 4) and on the Windows simulation (Chapter 5).
As these technicalities are mastered, the main topic is programming in GeoBASIC.
This manual will give you several hints on typical GeoBASIC programming
(Chapter 8), and introduces you to the design and programming of the theodolite
user interface and refined GeoBASIC concepts (Chapter 9).
Finally,GeoBASIC example programs are presented (Chapter 10). The reader will
find a sample code for measuring and computing the mean value of several
horizontal angles. Moreover some introductory examples are given to tell how
special problems can be treated.
Note All the details of the GeoBASIC language and system functions are
composed in the "GeoBASIC Reference Manual".

GeoBASIC User Manual 2 — Installation
TPS1100-Version 2.10 2-1
2 INSTALLATION
The requirements for using GeoBASIC are a Personal Computer based on an Intel
486 processor or higher and at least 8MB of main memory. The installation of the
whole development environment occupies about 10 MB of disk space, excluding
the PDF version of the manual. The delivered software needs Microsoft Win95,
Win98 or WinNT to run successfully.
2.1 SETUP
The following directory structure is created during the installation per default.
Notice that the location of this directory tree is user definable. Hence it is not a
granted to be exactly that location. Notice also that the CodeConverter application
is installed in a separate Setup installation procedure.
…+-SurveyOffice
|
+-UserTools
||
| +-TPS1100Tools
|||
| | + - CodeConverter
| | + - GBSamples
|||
Content of the directories (only the main objects are listed):
•TPS1100Tools\
TPS1100.exe TPS Simulator for TPS1100 Series
GBStudio.exe GeoBASIC IDE application
GBI_1100_xxx.prg GeoBASIC Interpreter for TPS1100 series *)
… and maybe several more tools, help files or DLL’s
•CodeConverter\
CGB_Dlg.exe CODE to GeoBASIC converter
Code_ex1.cod CODE sample
GBC_xxx.exe GeoBASIC Compiler for TPS1000 series *)
GBI_xxx.prg GeoBASIC Interpreter for TPS1000 series *)
GBI_1100_xxx.prg GeoBASIC Interpreter for TPS1100 series *)

GeoBASIC User Manual 2 — Installation
2-2 TPS1100-Version 2.10
•…
Several TPS1100Sim specific directories which contain language files, code
lists, configurations and things like that.
* xxx means: i.e. 210 for Release 2.10
Loading the GeoBASIC Interpreter:
The GeoBASIC Interpreter will be loaded automatically with the loading of the
first application into the theodolite using the Software Upload for TPS1100. Hence
you have to copy the GeoBASIC Interpreter (GBI_TPS1100_xxx.prg) into the
same directory as the application before loading it. Otherwise you will get an error
message. (For details, please see Chapter 4.1 Loading a GeoBASIC program or
5.3 Loading and executing GeoBASIC programs)

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
TPS1100-Version 2.10 3-1
3 CREATING A GEOBASIC APPLICATION
Starting from the specification of a GeoBASIC application, several steps have to
be performed until the program can be executed on the theodolite or by simulation:
1. Write the program,
2. compile the program,
3. load the program, either onto the simulation or the theodolite, and
4. start the execution of it.
5. if the execution fails, start a debugging session.
3.1 GBSTUDIO DEVELOPMENT ENVIRONMENT
GBStudio is an integrated development environment and includes a source editor,
compiler, project handling and a source level debugger. It is able to debug
GeoBASIC 2.10 applications for TPS1100 series total stations. Both, the TPS
simulator and the TPS device as the execution platform are supported.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
3-2 TPS1100-Version 2.10
GBStudio contains several views for different purposes. The main source view is
for showing/editing source files. The ‘Open Files’-tab can be used to switch
quickly between different source windows. Toolbars help the user to start actions
with one mouse click. The ‘Build/Output’-window is used to display informative
messages of the compiler and during the debugging session for the user.
Use the integrated help system to get more descriptive explanations of what can be
done with GBStudio. You can invoke the Help documentation by either using the
context-help-cursor (Edit toolbar) or the shortcut F1, which opens the content
page.
3.1.1 The Editor
It establishes a modern programming language editor, which supports syntax and
keyword highlighting, multilevel undo/redo, Intellisense and Tooltip info,
Bookmarks, indent and outdent of a block of source lines, and several other
features.
The ‘Workspace Preferences’-dialog can be used to customize the features, which
should be active during debugging.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
TPS1100-Version 2.10 3-3
To choose a different font use the ‘Font …’-buttons in the ‘Font’-tab, which will
offer a dialog to choose one of the installed fonts on the system. Fonts can be
chosen separately for the Editor window, Build/Debug output window and for the
Watch Variable window.
3.1.2 The Compiler
The source-file has to be compiled before it can be loaded and executed.
Compiling the source file with the GeoBASIC compiler results into 3 files, one for
the executable object itself (file extension “.gba”; i.e. sample.gba), one for
the language data (file extension “.lng”; i.e. sample.lng) and a debug-info
file (file extension “.gbd”; i.e. sample.gbd). The first two files are necessary
to execute the program, either on a LEICA theodolite or with the simulator on a
personal computer. The debug-info file is necessary for debugging a program
using GBStudio. See the following diagram:
sample.gbs
GBStudio
sample.gba sample.lng sample.gbd
Diagram: Compiling a GeoBASIC program
The compiler is fully integrated in the development environment. The compilation
of the source file is just one mouse click away. If an error occurs the editor will
place the cursor automatically at the position of the error in the source window.
Use Ctrl-F1 to get a more descriptive explanation of what caused the failure of the
compilation process.
Depending on the compiler settings also the debug info file is generated which is
necessary for debugging the application.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
3-4 TPS1100-Version 2.10
Depending on the selected project type, use either the ‘Default Project
Preferences’-dialog or the ‘Project Preferences’-dialog to set the build options for
the compiler.
The compiler understands the following options:
Setting Meaning
Language The language on which the resulting application is based
on. The default is ENGLISH, other languages are
FRENCH, GERMAN, etc.
Character Set The character set on which the application is based on.
The default character set is 0.
Output File The name of the resulting applications file name. If it is
empty, the resulting files get the same file base name as
the source code file.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
TPS1100-Version 2.10 3-5
Output Path The path where the compiler places the generated
application files. The default is the source directory,
where the compiler gets the GeoBASIC source file. The
path has to be absolute and has to end with a "\"-
character.
Include Paths Set one or more directory-paths for include files. The
directory path must not have a "\" character at the end.
Generate
Statistics Enable this flag, if you want the compiler to generate some statistical information about the compiled
application.
Generate Debug
Info Enable this flag, if you want the compiler to generate a debug info file, which is necessary to debug the
application
3.1.3 The Debugger
The debugger enables the programmer to debug GeoBASIC applications at source
level. Operations like Step, Step Over, Run, Set breakpoints and watching the
values of variables and some more operations are implemented.
To find errors in the source code an error catcher has been implemented which
stops the execution of the application once the Err-variable changes its value. The
error catching mechanism can be enabled and disabled during the debugging
session at the needs of the developer.
The generated files include time stamp information. With this information
GBStudio is able to check if all involved objects are synchronous to each other.
This feature also enables GBStudio to debug an application, which may be in use
for some time already. The only precondition, which has to be met is, that all files
have to be saved for this purpose. Once the source code file changes debugging
can only be started if the application is compiled anew. This means also that the
application has to be loaded freshly onto hardware, which then initializes all its
values. This feature is very valuable if a tested application shows error only after
weeks or months of usage.
Depending on the selected project, use either the “Default Project Preferences”
dialog or the “Project Preferences” dialog to set the build options for the
debugging session.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
3-6 TPS1100-Version 2.10
For debugging the following values can be set:
Setting Meaning
Connection This setting determines the execution platform and if
TPS over a serial line is served, which COM port
should be used for communication.
Baud Rate Is available only if one of the serial communication
lines has been chosen. Choose an appropriate Baud
rate.
System Idents Determines the location of the system specific symbols
file. Click on the “Browse…” button to get a file
chooser dialog.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
TPS1100-Version 2.10 3-7
Entry Point Since every loadable application on the TPS may have
more than one entry point, one has to select a valid
entry point of the application. This value can be
entered before the debug info has been loaded, or after
the debug info load operation. In the latter case choose
the entry point by selecting an item from the drop
down list.
Catch Runtime
Errors Enable this flag to catch runtime errors.
Number of Watch
Variables Select a value between 1 and 1000 watch variables. The number determines the table size on the server
side. This value heavily influences the performance of
certain debug operations. If you don’t a big number,
then choose a smaller number for better performance.
Size of Shadow
Memory Select a value between 100 and 10000 Bytes. This will be the size of the shadow memory, where the server
will keep a backup copy of the registered variables.
3.1.4 The Interpreter and the Firmware
Both have been adapted to provide all the additional functionality. Hence only
firmware releases 2.10 and newer support GeoBASIC debugging with GBStudio.
Please notice, that GBStudio cannot handle the TPS device state “Sleep Mode”
correctly. Please disable the sleep feature of the TPS firmware if you want to avoid
tedious timeout errors in GBStudio.
3.2 TYPICAL DEVELOPMENT CYCLE
3.2.1 Open or Create a GeoBASIC main source file
Use the Open File command to open an existing GeoBASIC main source file or
create a new file with the document type GBS.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
3-8 TPS1100-Version 2.10
If you choose to open an already existing project, then the defined main source file
should be opened automatically.
3.2.2 Edit the application.
Type in or change an existing GeoBASIC application source code. Please, refer
also to the GeoBASIC reference manual for a complete description of syntax and
semantics of GeoBASIC and how to write applications in GeoBASIC.
The editor is capable of automatically correcting the case of keywords. If one
types a blank after a keyword this features take place automatically. Switch this
feature off in the Workspace Preferences dialog if you don’t want to use this
feature.
CTRL-SPACE opens a drop down list of system-defined functions. This can be
used to quickly select a system function. When the opening parenthesis is typed
the parameter list will be showed as a tool tip and a reminder what the compiler
expects. Use SHIFT-CTRL-SPACE anytime to open up this tool tip again. The
displayed parameter list depends on the cursor position and moreover on the
system function identifier just before the current cursor.
Note: Define also an entry point (GLOBAL SUB definition) of the
application, which you can choose later to debug. This is the only
identifier in a GeoBASIC application, which is case-sensitive. Make
sure this entry point is linked to a menu item on the TPS user interface.
Otherwise it will not be possible to debug the application (with the
exception of the “BasicCodeProgram” type of application).
Save your changes by using CTRL-S or the Save command from the File menu.
3.2.3 Build the application
Press function key F7 or use the Build command from either the Build menu or
Build toolbar.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
TPS1100-Version 2.10 3-9
If an error occurs, then the editor will place the cursor automatically near the
location of the error. Correct the error and recompile it. Repeat these steps until
your application compiles without any errors. Use CTRL-F1 if you want to get
some more information on the last error occurred.
Note The usage of the compiler is protected by a hardware key. Without the
right hardware key it is not possible to execute the compiler
successfully. If the hardware key is not installed properly or it does not
contain the license for the compiler then an error message will be
displayed and execution will be terminated.
3.2.4 Start debugging
To start the debug session, choose the platform (TPS simulator or TPS instrument)
and specific settings, you want to use, in the Project Preferences dialog. Make also
sure the entry point of the application is set properly in the preferences dialog.
1. Switch on the debugging platform.
2. When using the TPS device:
Load the GeoBASIC interpreter.
3. Load the application you want to debug. (For details, please see Chapter
4.1 Loading a GeoBASIC program or 5.3 Loading and executing
GeoBASIC programs)
Note: The application must have been build with ‘’Generate Debug Info’’
enabled.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
TPS1100-Version 2.10 3-1
Note: GBStudio uses the TPS device when the GSI settings are active. The
GeoCOM online mode is not supported during the debugging process.
Make sure the GSI communication settings are:
19200 Baud,
No-Protocol,
8 Data Bits,
No-Parity,
CR/LF as terminator.
GBStudio cannot handle the sleep state of the TPS device correctly.
Make sure the ‘’Sleep after …’’-mode is disabled.
The application source and the generated files must be synchronous, hence a
source file, which has been changed, after the application has been built, cannot be
debugged.
Start debugging by pressing the Start button on the Build toolbar or use the
corresponding menu located command.
Start the application on the platform. The editor should now get a small mark (in
the shape of an right sided arrow) on the left edge of the main source file window,
which points to the very first executable statement of this entry point of the
application.
3.2.5 Debugging
Use the commands of the Debug menu or toolbar to step through the application,
set breakpoints, catch errors and watch variables as they change during the
debugging process.
In the watch variable view you will be able to edit either the identifier of the watch
variable entry or the value itself, if the debugging process is in a HALT state.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
3-2 TPS1100-Version 2.10
Note: Changing the value of a string reference parameter is possible too.
Since the actual, maximum length of the variable (behind the reference)
is unknown, the debugger is unable to protect the memory area
following the string variable. Hence, if you change the value of a string
reference parameter, be sure that the number of added characters is less
than or equal to the declared length.
3.2.6 Stop debugging
Choose the Stop Debugging command to stop the debugging process. Just in case
the application is executing a system function, then the debug server will not be
able to terminate the application immediately. Instead the application will be
terminated after the system call returns. Nevertheless, GBStudio can terminate the
debugging session on the client side.
3.2.7 Watch Variables and Quick Watches
Watch variables can be added to the Watch Variable view by selecting a variable
identifier and pressing the shortcut Ctrl-W.
Use the Quick Watch command if you don’t want to add the variable to the Watch
Variable view. Instead the value will be printed into the Debug Output window.
Once added to the window it is possible to change either the identifier name or the
value of it (if the point of execution is in the scope of the variable). Use a Double-
Click on the identifier or the value to enter the edit mode.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
TPS1100-Version 2.10 3-3
Note: The identifier name is bound to the current context, which is determined
by the selection you made. To choose the same identifier name from a
different context one has to select the identifier in the correct context.
Valid watch variable expressions may be of the following form only:
Variable Expression Example
VariableIdent s, Err, line
StructIdent.Element CurrPt.dHz, GMCircle.Center.dHeight,
ArrayIdent(NumConstant)
arr(2), field(17,3)
All other possible text strings cannot be handled correctly in the current
implementation and will be rejected for registration therefore.
Include exclusively expressions with numerical constants.
3.3 PROJECT HANDLING
GBStudio knows two different categories of projects, which are valid exclusively.
First the default project, which is valid for any valid GBS-file. And second the so-
called ‘named’ projects, which have the application specific information stored in
a file. It should be emphasized that the default project only stores the settings of
one project (similar to one main source file) at a time. Once the user chooses
another main source file, he has to make sure that the default preferences are set
appropriately. E.g., if the two source files have different application entry points,
the user has to set it up accordingly.
The default project is active if the user doesn’t choose a project explicitly. Instead
the user will just open a plain GeoBASIC source code file.

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
3-4 TPS1100-Version 2.10
3.4 COMMON PROBLEMS
The most common problems, which may arise, are:
•GBStudio is not able to establish a connection to the GeoBASIC Debug
Server.
Solution: In the case of debugging with the simulator make sure the TPS
simulator is running and “Switched On”. In the case of the TPS device
make sure the right COM port has been chosen, the cables are connected
and the communication settings are equal on both sides. Notice, that
GBStudio only supports serial settings with 8 Bit, 1 Stop Bit, no Parity
Bit and CR/LF as a packet terminator. Only the Baud Rate may vary.
•The application, which should be debugged, and/or the interpreter are not
loaded.
Solution: Load interpreter and/or application first, before you start
debugging.
•The program source files are out of synchronicity with the compiled
application.
Solution: Recompile and reload the GeoBASIC application.
•The Debug Session cannot be started, because the system predefined
symbol file could not be found.
Solution: Use the “Project Preferences” dialog, Debug-Tab, to specify
path and file name of the system predefined symbols.
•The Debug Session cannot be started, because no valid entry point has
been chosen.
Solution: Use the “Project Preferences” dialog, Debug-Tab, to specify a
valid entry point. Valid entry points are defined in the source code as
“GLOBAL SUB …” procedure names. Notice: the predefined entry
points Install, Init and Stop are not valid entry points.
•During debugging a Step-Into an Include source file doesn’t open the
source file and show the next statement. Or the compiler reports the error
that he can’t open an Include file.
Solution: Make sure that the “Project Preferences” dialog, Build-Tab,
field “Include Directories”, contains the right path, where GBStudio can
find the include source file.
•The second registering of a variable doesn’t show the associated value.
Notice, a variable can be registered only once.
•During debugging the code source cannot be edited. We disabled this
during the debug session to keep the source and the loaded application

GeoBASIC User Manual 3 — Creating a GeoBASIC Application
TPS1100-Version 2.10 3-5
synchronous. Stop the debug session to be able to edit the code source
again.
•The debug session hangs. Conceptually it may happen that a notify
message get lost from the server to the client. Then it might be possible
that the “Stop Debug” and “Break” buttons are enabled only. Since the
debug server has sent the notify message it waits for the next command.
And because the client has missed the notification, it thinks the last
command is still being under execution and waits for the never incoming
notification.
Solution. Use the “Break” button to check the current state. If the last
command has been finished and above situation was the reason then this
initiate a new notification of the current state.
3.5 COMPILER LIMITATIONS
The GeoBASIC programmer has to keep some limitations for his applications:
•One simple procedure or function may not contain more than 10 kB of code.
•The maximum size of an application (including memory space) is limited by
the free memory size of the theodolite only. If no other applications are loaded
there should be free memory up to several hundred kB on a theodolite.
•An application may not have more than 64kB of string literal in total.
•The number of global identifiers is limited to 3000.
•The overall maximum number of identifiers limits the number of local
identifiers, which are about 60000.