Leica TPS1200 series User manual

Leica TPS1200+
Leica TS30 / TM30
GeoCOM Reference
Manual
Version 1.50
English

GeoCOM Reference Manual Contents
1..................................................................................................................................................................5GEOCOM
1.1 INTRODUCTION....................................................................................................................................................5
1.2 TPS1200 SYSTEM SOFTWARE .............................................................................................................................5
1.3 PRINCIPLES OF GEOCOM OPERATION.................................................................................................................6
2GENERAL CONCEPTS OF USING GEOCOM..................................................................................................7
2.1 INTRODUCTION ....................................................................................................................................................7
2.2 GENERAL CONCEPT OF OPERATION.....................................................................................................................7
2.3 ASCII PROTOCOL................................................................................................................................................7
2.4 FUNCTION CALL PROTOCOL -C/C++ ..................................................................................................................8
2.5 FUNCTION CALL PROTOCOL -VBA.....................................................................................................................9
3FUNDAMENTALS OF PROGRAMMING GEOCOM .....................................................................................10
3.1 INTRODUCTION ..................................................................................................................................................10
3.2 ASCII PROTOCOL PROGRAMMING ....................................................................................................................10
3.3 C/C++ -PROGRAMMING....................................................................................................................................12
3.4 VBA -PROGRAMMING ......................................................................................................................................14
3.5 UNITS OF VALUES .............................................................................................................................................16
3.6 TPS1200 INSTRUMENT MODES OF OPERATION .................................................................................................16
3.7 COMMON COMMUNICATION ERRORS ................................................................................................................16
4REMARKS ON THE DESCRIPTION.................................................................................................................19
4.1 STRUCTURE OF DESCRIPTIONS...........................................................................................................................19
5COMMUNICATION SETTINGS.........................................................................................................................21
5.1 USAGE.............................................................................................................................................................21
5.2 CONSTANTS AND TYPES ....................................................................................................................................21
5.3 GENERAL GEOCOM FUNCTIONS.......................................................................................................................22
5.4 CLIENT SPECIFIC GEOCOM FUNCTIONS............................................................................................................24
6ALT USER - AUS...................................................................................................................................................38
6.1 USAGE...............................................................................................................................................................38
6.2 CONSTANTS AND TYPES ....................................................................................................................................38
6.3 FUNCTIONS........................................................................................................................................................39
7AUTOMATION - AUT..........................................................................................................................................43
7.1 USAGE...............................................................................................................................................................43
7.2 CANCELLING /ABORTING CURRENT FUNCTIONS...............................................................................................43
7.3 CONSTANTS AND TYPES ....................................................................................................................................43
7.4 FUNCTIONS........................................................................................................................................................45
8BASIC APPLICATIONS – BAP...........................................................................................................................69
8.1 USAGE.............................................................................................................................................................69
8.2 CONSTANTS AND TYPES ....................................................................................................................................69
8.3 FUNCTIONS........................................................................................................................................................71
9BASIC MAN MACHINE INTERFACE – BMM ................................................................................................89
9.1 USAGE................................................................................................................................................................89
9.2 CONSTANTS AND TYPES ....................................................................................................................................89
9.3 FUNCTIONS........................................................................................................................................................90
10 COMMUNICATIONS – COM..........................................................................................................................94
10.1 USAGE.............................................................................................................................................................94
10.2 CONSTANTS AND TYPES ....................................................................................................................................94
10.3 FUNCTIONS........................................................................................................................................................95
11 CENTRAL SERVICES – CSV........................................................................................................................101
11.1 INTRODUCTION ................................................................................................................................................101
11.2 USAGE.............................................................................................................................................................101
11.3 CONSTANTS AND TYPES ..................................................................................................................................101
11.4 FUNCTIONS......................................................................................................................................................103
Leica TPS1200 / TS30 / TM30 – Version 1.50 2

GeoCOM Reference Manual Contents
12 ELECTRONIC DISTANCE MEASUREMENT – EDM..............................................................................113
12.1 INTRODUCTION ................................................................................................................................................113
12.2 USAGE.............................................................................................................................................................113
12.3 CONSTANTS AND TYPES ..................................................................................................................................113
12.4 FUNCTIONS......................................................................................................................................................114
13 FILE TRANSFER - FTR.................................................................................................................................117
13.1 USAGE.............................................................................................................................................................117
13.2 CONSTANTS AND TYPES ..................................................................................................................................117
13.3 FUNCTIONS......................................................................................................................................................118
14 IMAGE PROCESSING – IMG.......................................................................................................................127
14.1 INTRODUCTION ................................................................................................................................................127
14.2 USAGE.............................................................................................................................................................127
14.3 CONSTANTS AND TYPES ..................................................................................................................................127
14.4 FUNCTIONS......................................................................................................................................................128
15 MOTORISATION – MOT ..............................................................................................................................131
15.1 INTRODUCTION ................................................................................................................................................131
15.2 USAGE.............................................................................................................................................................131
15.3 CONSTANTS AND TYPES ..................................................................................................................................131
15.4 FUNCTIONS......................................................................................................................................................132
16 SUPERVISOR – SUP.......................................................................................................................................137
16.1 USAGE..............................................................................................................................................................137
16.2 CONSTANTS AND TYPES ..................................................................................................................................137
16.3 FUNCTIONS......................................................................................................................................................138
17 THEODOLITE MEASUREMENT AND CALCULATION – TMC...........................................................140
17.1 INTRODUCTION ................................................................................................................................................140
17.2 USAGE.............................................................................................................................................................140
17.3 CONSTANTS AND TYPES ..................................................................................................................................141
17.4 MEASUREMENT FUNCTIONS.............................................................................................................................144
17.5 MEASUREMENT CONTROL FUNCTIONS............................................................................................................157
17.6 DATA SETUP FUNCTIONS.................................................................................................................................160
17.7 INFORMATION FUNCTIONS...............................................................................................................................177
17.8 CONFIGURATION FUNCTIONS ..........................................................................................................................179
18 PORTING A TPS1100 APPLICATION.........................................................................................................191
18.1 INTRODUCTION ................................................................................................................................................191
18.2 RPC CHANGES ................................................................................................................................................191
18.3 DATA TYPES AND CONSTANTS CHANGES........................................................................................................193
18.4 RETURN-CODES ...............................................................................................................................................193
19 GEOCOM RELEASES....................................................................................................................................194
19.1 RELEASE 1.00..................................................................................................................................................194
19.2 RELEASE 1.10 ..................................................................................................................................................194
19.3 RELEASE 1.20 ..................................................................................................................................................194
19.4 RELEASE 1.50 ..................................................................................................................................................194
20 APPENDIX........................................................................................................................................................195
AReturn-Code names and return-code values...................................................................................................195
BHardware interface.........................................................................................................................................201
B-1 Serial Interface........................................................................................................................................201
B-2 Debugging Utility...................................................................................................................................202
CProvided Samples ...........................................................................................................................................203
C-1 Program Frames......................................................................................................................................203
C-1.1 VBA Sample Program ....................................................................................................................203
C-1.2 C/C++ Sample Programs................................................................................................................203
C-1.3 TCC Image Grabber Sample Program............................................................................................204
DList of Remote Procedure Calls (RPC).......................................................................................................D-205
D-1 rpc in Alphabetical order ....................................................................................................................D-205
Leica TPS1200 / TS30 / TM30 – Version 1.50 3

GeoCOM Reference Manual Contents
Microsoft, MS, MS-DOS, Windows, Windows NT, Win32, Visual C++ and Visual Basic
are either registered trademarks or trademarks of Microsoft Corporation in the USA and other countries
Leica TPS1200 / TS30 / TM30 – Version 1.50 4

GeoCOM Reference Manual GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 5
1GEOCOM
1.1 INTRODUCTION
TPS1200 series Theodolites are modern geodetic measurement instruments. Most of the main tasks can be fulfilled with
these instruments implicitly by their integrated applications. Now, to fulfil a broader spectrum of tasks and applications
an interface to the TPS1200 series sensor functions has been defined and will be published with this document.
With this interface it will be possible to write client applications based on MS-Windows and/or for any other platform,
which supports ASCII, based communications.
Note: The TS30/TM30 and TPS1200 share the same GeoCOM interface. If not otherwise stated, the implementation
for TM30 and TS30 instruments is the same as that for theTPS1200 instruments.
1.2 TPS1200 SYSTEM SOFTWARE
The TPS1200 system software organises and controls the interplay of several sensor elements. Furthermore, it builds up
a frame for applications, which can be executed on the TPS1200 Theodolite.
This document concentrates on the main interface to the sensor elements of the TPS1200 Theodolite. This main
interface can be used to implement solutions for special customer problems if the already existing solution does not
provide the needed functionality or just to enhance it.
1.2.1Organisation of Subsystems
The TPS1200 system software is built around the sensor elements, which are parts and/or optional add-ons of the
TPS1200 Theodolite instrument. It provides a set of functions to access sensors and calculated values. These functions
are organised as subsystems. We will keep this segmentation in this document.
These functions can be grouped in the following sections:
AUS The subsystem ‘Alt User’ mainly contains functions behind the “SHIFT” + ”USER” button.
AUT Automatisation; a module which provides functions like the control of the Automatic Target Recognition,
Change Face function or Positioning functions.
BAP Basic Applications; some functions, which can easily be used to get measuring data.
BMM Basic Man Machine; functions which controls some basic input/output functionality, e.g. set beep alarm, etc.
COMF Communication; a module, which handles the basic communication parameters. Most of these functions relate
to both client and server side.
COM Communication; functions to access some aspects of TPS1200 control, which are close to communication.
These functions relate either to the client side or to the server side.
CSV Central Services; this module provides functions to get or set central/basic information about the TPS1200
instrument.
CTL Control task; this module contains functions of the system control task.
EDM Electronic Distance Meter; the module, which measures distances.
FTR File Transfer, functions to list, download image files from instrument
IMG Image Processing; configure and capture Telescopic Camera Images
MOT Motorization; the part, which can be used to control the movement and the speed of movements of the
instrument.
SUP Supervisor; functions to control some of the general values of the TPS1200 instrument.
TMC Theodolite Measurement and Calculation; the core module for getting measurement data.

GeoCOM Reference Manual GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 6
Picture 1-1: Overview Client/Server Application
1.3 PRINCIPLES OF GEOCOM OPERATION
Communication takes place between two participants - a client and a server. The medium of communication is a serial
communication line. Refer to Appendix B for further information about settings and needed hardware.
The idea of GeoCOM is based on SUN Microsystems’ Remote Procedure Call (RPC) protocol.
On the low level of implementation, each procedure, which is executable on the remote instrument, is assigned a remote
procedure call identification number. This number is used internally to associate a specific request, including the
implicit parameters, to a procedure on the remote device. On this level, GeoCOM provides an ASCII interface, which
can be used to implement applications on platforms, which do not support MS-Windows.
On the high level, GeoCOM provides normal function call interfaces for C/C++ and MS-VBA to these remote
functions. These interfaces enable a programmer to implement an application as if it would be executed directly on the
TPS1200 instrument.
Note: Further on we will refer to a remotely executable system function as a RPC.
The TPS1200 instrument system software uses a multitasking operating system. Nevertheless, only one request can be
executed at once. This means in respect of calling RPC’s GeoCOM works synchronously only.
On the low level interface the server buffers subsequent requests if current request(s) has not been finished so far. If the
queue is full then subsequent requests will be lost.
Instead on the high level interface a function call will not return until it has been completely finished.
system software
SUPBMM
MOT TMC
CSV
AUT
BAP
EDM
PC application
GeoCOM
server
inclination
sensor angle sensor distance sensor
motorization basic
in/out
COM
GeoCOM
client
COMF
Serial Line
TPS
PC
CTL

GeoCOM Reference Manual General Concepts of Using GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 7
2GENERAL CONCEPTS OF USING GEOCOM
2.1 INTRODUCTION
Here we will describe several aspects of using GeoCOM. One of them is how to execute a function at a TPS1200
instrument.
The current implementation of GeoCOM supports two (three) kinds of usage. We can distinguish between a rather
rudimentary ASCII protocol and a high-level function call interface.
The former - ASCII protocol - is made up of requests and replies. Using GeoCOM in this way means that an application
assembles a request, sends it over the serial line to the listening TPS1200 instrument, wait for the answer and decode
the received reply.
The latter uses normal function calls either in C/C++ or in VBA. For explanation purposes we will split it into two
categories because the two supported programming environments differ in relation to their type systems. Using
GeoCOM in this way means calling a function. GeoCOM will handle any necessary communication implicitly.
2.2 GENERAL CONCEPT OF OPERATION
Fundamentally, GeoCOM is implemented as a point-to-point communication system. The two communication
participants are known as the client (external device) and the server (TPS1200 instrument). One communication unit
consists of a request and a corresponding reply. Hence, one communication takes place when the client sends a request
to the server and the server sends a reply back to the client.
Picture 2-1: Basic communication
GeoCOM is implemented as synchronous communication. A request/reply pair cannot be interrupted by another
request/reply. Instead, a communication unit must be completed successfully before a new communication unit may be
initiated. An indicator for completion is the receiving of the return code.
Although the ASCII protocol allows sending the next request before the corresponding reply has been received, it is not
recommended to do that. Of course, subsequent request will be buffered when the previous request has not been
finished so far. But if the buffer content reaches its limit in size then data may be lost.
2.3 ASCII PROTOCOL
In sequence we will define the syntax first and then give some information about how to use the ASCII protocol to call
a function on the TPS1200 instrument.
The ASCII protocol is a line protocol; hence it uses a line terminator to distinguish between different requests (replies).
One request must be terminated by one terminator.
2.3.1ASCII Protocol Syntax
Syntax of an ASCII request:
[<LF>]%R1Q,<RPC>[,<TrId>]:[<P0>][,<P1>,...]<Term>
Optional items are in brackets []. The angled-brackets <> surround names or descriptions. These names have variable
values depending on their types and meanings. The angled-brackets themselves are not part of the transferred text.
Characters not surrounded by brackets are literal text and are part of the GeoCOM protocol.
<LF> An initial line feed clears the receiver buffer.
%R1Q GeoCOM request type 1.
<RPC> Remote Procedure Call identification number in between 0 to 65535.
<TrId> Optional transaction ID: normally incremented from 1 to 7. Same value in
reply.
: Separator between protocol header and following parameters.
<P0>,<P1>,... Parameter 0, Parameter 1, ...
<Term> Terminator string (default CR/LF, use COM_SetTerminator to change the
request
Client Server
reply

GeoCOM Reference Manual General Concepts of Using GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 8
terminator). As a common shortcut ‘^m’ will be used in examples.
Example:
The following example uses the RPC CSV GetDateTime to query the current date and time of the instrument:
%R1R,5008:1^m (1^m denotes the terminator)
Note: Additional characters at the beginning of a request, between parameters or at the end are not allowed. They
might lead to errors during interpretation.
Syntax of an ASCII reply:
%R1P,<RC_COM>[,<TrId>]:<RC>[,<P0>,<P1>, ...]<Term>
Optional items are in brackets []. The angled-brackets <> surround names or descriptions. These names have variable
values as described in the types they have. The angled-brackets themselves are not a part of the communication text.
Characters not surrounded by angled-brackets are literal text and are part of the GeoCOM protocol.
%R1P GeoCOM reply type 1.
<RC_COM> GeoCOM return code. This value denotes the success of the communication.
GRC_OK = 0 means the communication was successful.
Refer to ‘3.7 Common Communication Errors’ for further information.
<TrId> Transaction ID - identical to that of the request. If the request had no
Transaction ID then it will be 0.
: Separator between protocol header and following parameters.
<RC> Return code from the called RPC and denotes the successful completion if it is
set to 0 (see table ‘RPC return codes’ in the appendix for further information).
<P0>,<P1>,... Parameter 0, Parameter 1, … These parameters will be valid only if <GRC> is
equal to 0 (GRC_OK).
<Term> Terminator string (default CR/LF, use COM_SetTerminator to change the
terminator).
Example:
The following example shows the reply to the RPC 5008 - CSV_GetDateTime.
%R1P,0,0:0,1996,'07','19','10','13','2f'^m
¦ ¦ ¦ ----------------------------
¦ ¦ ¦ ¦ The values for month, day, hour,
¦ ¦ ¦ +--- minute and second are replied in the byte-
¦ ¦ ¦ format (see table communication parameter
¦ ¦ ¦ for further information)
¦ ¦ +------ Return code from the RPC: 0 means no error
¦ ¦ (see RPC return codes for further information)
¦ +----- The Transaction ID of the request. If there was no ID
¦ the value returned is 0.
+---- Return code from GeoCOM: 0 means no error (see
GeoCOM return codes for further information)
2.4 FUNCTION CALL PROTOCOL - C/C++
The implementation of GeoCOM for C/C++ conforms to normal function calls. GeoCOM itself handles all necessary
communication. No intervention of the programmer in respect to the communication is necessary with one exception. If
the GeoCOM reports a communication error the programmer has to make sure that either the problem will be solved -
by calling GeoCOM support functions - or no further RPC’s will be called - by terminating the running task.
Nevertheless, the programmer has to initialise GeoCOM and set up the port’s settings to make sure that communication
can take place. Moreover the user has to make sure that the TPS1200 instrument is well connected.
Example:
An example code fragment for using TMC_GetSimpleMea could be the following. We do not take care of the necessary
initialisation and set up of GeoCOM here. Please refer to chapter 3.2.3 Basic GeoCOM Application Frame for C/C++
for this information.

GeoCOM Reference Manual General Concepts of Using GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 9
GRC_TYPE RetCode;
TMC_HZ_V_ANG Angles;
double dSlopeDist;
RetCode = TMC_GetSimpleMea( 1000, Angles,
dSlopeDist,
TMC_AUTO_INC );
if (RetCode == GRC_OK)
{
// do something - use values
}
else
{
// handle error
}
2.5 FUNCTION CALL PROTOCOL - VBA
Here almost all is valid for VBA as for C/C++. Please refer to Chapter 2.4. The only difference between VBA and
C/C++ is that VBA has a different type system. Hence, the defined data types differ slightly in their definition.
Furthermore, because of implementation reasons the RPC names must have an additional prefix, which is “VB_” for the
current implementation of GeoCOM.
Example:
We take the same example as in Chapter 2.4.
Dim RetCode As Integer
Dim Angles As TMC_HZ_V_ANG
Dim dSlopeDist As Double
RetCode = VB_TMC_GetSimpleMea( 1000, Angles,
dSlopeDist,
TMC_AUTO_INC )
If RetCode = GRC_OK Then
' do something - use values
Else
' handle error
End If

GeoCOM Reference Manual Fundamentals of Programming GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 10
3FUNDAMENTALS OF PROGRAMMING GEOCOM
3.1 INTRODUCTION
We will describe how programs can be written using the different protocols. Certainly, the type system, where the main
differences lie between the protocols, will be described in more detail.
3.2 ASCII PROTOCOL PROGRAMMING
Implementing an application, which uses the ASCII protocol, is based on simple data transfers using a serial line. The
programmer is responsible to set up the serial line parameters of the client such that they correspond to the settings of
the TPS1200 instrument. Then Remote calls are done by just sending the valid encoded requests and receiving and
decoding the replies of them.
For debugging purposes, it might be helpful to use a so-called Y-cable, which enables you to observe the
communication on the serial line using either a terminal or a terminal emulator. For further details see
Appendix B-2 Debugging Utility.
Note: If the settings of the active COM port will be set by any software part and if the server is online, then it is
strongly recommended to use a leading <LF> to clear the receiver buffer at the server side. This will reduce
unnecessary error messages of the next RPC.
3.2.1Data Types in ASCII Protocol
Each parameter of a RPC has its own associated data type with it. There are varieties of different data types, which have
been defined for the set of published functions. The ASCII protocol supports simple data types only. All data types,
which are different from the base, types in name and aggregated data types are converted and reduced to their base
types. Conversion means to serialise the aggregated data into a comma-separated list of its elements. Therefore, the
programmer has the responsibility to interpret the values depending on the associated data type.
The supported base types and their value range are defined below:
Format Type Valid range Len Valid input
representations Typical output representations
boolean 0 = false
1 = true 1 0,1 0,1
byte 0...255 2 (4) ‘00’,’FF’,’ff’,’7a’,
’A7’ ‘00’,’FF’,’ff’, ’7a’,’A7’
string - <512 ”abc\x0d\x0a” ”abc\x0d\x0a”
double ±2.225E-308...
±1.797E+308 17+3 1, 1.0, 1.0e4, -0.1e-07, -2 -0.1234567+e67
long (-231)...(231-1) 11 0x7FFFFFFF,
-54321 15, -154836, 900000
short -32768...32767 6 0, -1, -32700, 45,
56, 0x45e,
0X3AA
0, -1, -32700, 45,
56
unsigned long 0...(232-1) 10 0xFFFFFFFF 0, 1, 3400065,
95735
unsigned short 0...65535 5 0, 1, 34000, 65,
65535, 0x3a,
0x00, 0xFFFF
0, 1, 34000, 65,
65535
Table 3-1: Communication Parameter Types

GeoCOM Reference Manual Fundamentals of Programming GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 11
Note: Bytes are always represented in two-character hexadecimal notation. Hexadecimal notation can use upper- or
lower-case representation: 0.9 + [a .. f | A .. F].
Characters sent within a string which do not fall within the ASCII character range 0x20 to 0x7E (32 to 126
decimal) are sent using an adapted byte notation - e.g. ”\x9A”, where \x (or \X) introduces a byte value in
hexadecimal notation. To include the back slash, double quote, per cent or tilde character (\ “ % ~) as part of the
string, it must be preceded by a backslash character, e.g. “This is a \”quote\””.
Types of integer (short, unsigned short, long, unsigned long) can also be represented in hexadecimal notation,
introduced by 0x or 0X.
The following rules are for generating/interpreting values with a type different from the base types and aggregated data
types:
Numerical and string data type
The numerical data types correspond to the C-parameters in value, range and precision as close as possible. If no
identical data type is available then the next best one will be taken. Character and string will be replaced by the
string data type.
Enumerations
If the corresponding C-parameter is an enumeration data type, then the enumeration value of the ASCII
parameter is equal to the implicit value of the declaration of the C-data type. For clarification, we will give
always the name and the associated value in the description of an enumeration data type.
Structures
Structure data types will be converted into a comma-separated list of elements. One element’s representation
conforms to the data type representation of its base type. If an element itself is a structure then depth first
conversion will take place. If this rule does not apply then the types and their ASCII parameters are described
explicitly.
Arrays
An array will be converted into a comma-separated list of elements. One element’s representation conforms to
the data type representation of its base type.
Example for Enumeration Data Types and Structures
The following example gives a typical data type declaration and the corresponding procedure declaration used in
this manual for TMC_GetSimpleMea from the subsystem Theodolite Measurement and Calculation:
Constants and Types
typedef long SYSTIME;
struct TMC_HZ_V_ANG
{
double dHz;
double dV;
}
enum TMC_INCLINE_PRG
{
TMC_MEA_INC, // encoded as 0
TMC_AUTO_INC, // 1
TMC_PLANE_INC // 2
}
C-Declaration
TMC_GetSimpleMea(SYSTIME WaitTime,
TMC_HZ_V_ANG &OnlyAngle,
double &dSlopeDistance,
TMC_INCLINE_PRG Mode)
ASCII-Request
%R1Q,2108:WaitTime[long],Mode[long]
ASCII-Response
%R1P,0,0:RC,Hz[double],V[double],dSlopeDistance[double]
Please, notice that the RPC has two input and two output parameters. Anytime a request must encode and send
input and in/out parameters only and a reply must encode and send in/out and output parameters only!

GeoCOM Reference Manual Fundamentals of Programming GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 12
Note: Unnecessary parameters must not be sent.
Although the enclosed header file com_pub.hpp denotes default values for certain function parameters
they will not be supported. Hence, they have to be sent.
The ASCII Request to call this RPC with the value for WaitTime = 1000 and the inclination measure mode
TMC_AUTO_INC has the following form (note that the value 1 is used for the Mode parameter because the
counting of enumeration data types start at 0):
%R1Q,2108:1000,1^m
A possible reply can be as follows:
%R1P,0,0:0,0.9973260431694,1.613443448007,1.3581^m
Where the second and third value after the colon corresponds to the dHz and dV parts of the structure
TMC_HZ_V_ANG and the fourth value corresponds to the variable dSlopeDistance. (Note that the first value
after the ‘:’ is not a parameter but the return code value of the RPC).
3.2.2ASCII Protocol Program Example
For getting a feeling of how requests and replies are build up and work see also the provided geocom.trm file in the
samples directory. Please refer to Appendix C-1 Settings for Terminal Emulator for further information.
3.2.3Modes of Operation Concerning Communication
Section 3.6 - TPS1200 Instrument Modes of Operation - explains the different modes of operation of GeoCOM
concerning communication. Similar to that the following is valid for the ASCII protocol.
Since the client has to remind which mode is active, no support can be given from the TPS1200 instrument. The only
way to distinguish between modes is to remind the actions an application has initiated and their resulting replies. So far
no other possibility exists to determine the current mode.
To switch on the instrument a single character is sufficient. It is recommended to ignore the subsequent reply (one or
two lines).
3.3 C/C++ - PROGRAMMING
Programming in C/C++ is based on the well-known DLL concept, defined by Microsoft Corp. To compile a project
successfully first you have to include the file com_pub.hpp, which defines all necessary constants, data types and
function prototypes. Second geocoms2k.lib has to be included in the project, which enables the linker to resolve the
DLL exported functions. To operate successfully the geocoms2k.dll file must be accessible for the operating system,
hence it must be located in a directory, which the operating system looks up for the requested DLL file.
Project Options GEOCOMS2K.lib
Structure byte-alignment 4 bytes
Memory model N/A
Special #defines (if not using MFC) STRICT
3.3.1Data Types in C/C++
Since the main programming language of implementation of TPS1200 instruments Firmware is C/C++ all data types are
initially defined in C/C++. Therefore, no conversion of values or data types is necessary.
3.3.2Basic GeoCOM Application Frame for C/C++
A C/C++ GeoCOM application consists at least of the following parts:
- Initialise GeoCOM
- Open a connection to the server
- One or more GeoCOM RPC’s
- Close the active connection to the server
- Finalise GeoCOM
A sample implementation of above points could be:
// include standard system headers
#include "com_pub.hpp"
// include application headers

GeoCOM Reference Manual Fundamentals of Programming GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 13
#define NUM_OF_RETRIES 1
GRC_TYPE RetCode;
BOOLE bOpenAndRunning = FALSE;
// initialize GeoCOM
RetCode = COM_Init();
if (RetCode == GRC_OK)
{
// open a connection to the TPS1200 instrument
RetCode = COM_OpenConnection (COM_1, COM_BAUD_19200,
NUM_OF_RETRIES);
if (RetCode == GRC_OK)
{
bOpenAndRunning = TRUE;
}
}
// optionally set up other comm. parameters here
if (RetCode == GRC_OK)
{
// -- functionality of the application --
// here we just test if communication is up
RetCode = COM_NullProc();
if (RetCode != GRC_OK)
{
// handle error
}
}
// close channel
if (bOpenAndRunning)
{
RetCode = COM_CloseConnection ();
if (RetCode != GRC_OK)
{
// handle error
}
}
// anytime finalize and reset GeoCOM
RetCode = COM_End();
if (RetCode != GRC_OK)
{
// handle error
}
3.3.3C/C++ Development System Support
GeoCOM system files have been developed using Microsoft Visual C/C++ 6.0. Although this development
environment were the basis for the current GeoCOM implementation, it has been emphasised that it is independent of it,
hence other development environments can be used too. But please notice that it has not been tested thoroughly so far.
3.3.4Programming Hints
Order of Include Statements
Since GeoCOM redefines TRUE, FALSE and NULL we recommend the following include order:
1. Include system headers like stdio.h or stdafx.hpp
2. Include com_pub.hpp
3. Include the current project headers
BOOLE Definition
GeoCOM defines its own Boolean type as an enumeration type of FALSE and TRUE. It is called BOOLE. With one
exception, this does not produce any problems. Only if a BOOL type value will be assigned to a BOOLE type variable or
parameter the compiler (MS-VisualC/C++) generates an error. To solve this problem the expression, which will be
assigned to, has to be converted by a CAST statement to BOOLE.

GeoCOM Reference Manual Fundamentals of Programming GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 14
3.4 VBA - PROGRAMMING
Similar to C/C++ programming the programming of VBA is based on the DLL concept. To enable access to GeoCOM
the special module COM_StubsPub.bas has to be included in the project. COM_StubsPub.bas includes all constants,
data types and function prototypes, which are available in GeoCOM.
3.4.1Data Types in VBA - General rules for derivation
This subsection gives a summary of general derivation rules VBA-parameters from C-data types. Basically the C/C++ -
data types are given in a C/C++ notation before they are used in a RPC-description.
If the appearance of a VBA data type does not follow the general rules then they are described explicitly.
In general, the following rules can be applied:
Numerical data type
The numerical data types correspond to the C/C++-parameters in value and range as close as possible. If it
cannot be replaced directly then the best possible replacement will be taken.
String data type
Character and string types are replaced by string data types. Since string data types of C/C++ and VBA are not
directly interchangeable, the programmer has to take certain care of the necessary pre- and post-processing of
variables of this data type. Please refer to the example below.
Enumeration data type
Conceptually VBA does not have enumeration data types. Therefore, Long data types will be used instead. The
enumeration values will be defined by constants. Using the numerical value is also valid. Notice that some of the
enumeration values are reserved words in VBA. That is why we had to define different identifiers. Enumerated
return values are numerical values and correspond to the position of the enumeration value in the C/C++-
definition. For clarification, also the numerical values are given in the description of an enumeration data type.
Structures and Arrays
They are defined as in C/C++.
Example for Enumeration Data Types and Structures
The following example gives the data type declaration and the procedure declaration usually used in this manual
for an example procedure (TMC_GetSimpleMea from the subsystem Theodolite Measurement and Calculation):
VBA-Declaration
VB_TMC_GetSimpleMea(
WaitTime As Long,
OnlyAngle As TMC_HZ_V_ANG,
SlopeDistance As Double,
Mode As Long)
In the file COM_StubsPub.bas the corresponding items are defined:
Global Const TMC_MEA_INC = 0
Global Const TMC_AUTO_INC = 1
Global Const TMC_PLANE_INC = 2
Global Const TMC_APRIORI_INC = 3
Global Const TMC_ADJ_INC = 4
Global Const TMC_REQUIRE_INC = 5
Type TMC_HZ_V_ANG
dHz As Double
dV As Double
End Type
Obviously all enumeration values are encoded as global constants. The VBA structure definition equals to the C
structure definition. A valid procedure call would be:
Dim WaitTime As Long
Dim OnlyAngle As TMC_HZ_V_ANG
Dim SlopeDistance As Double
WaitTime = 1000
VB_TMC_GetSimpleMea( WaitTime,

GeoCOM Reference Manual Fundamentals of Programming GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 15
OnlyAngle,
SlopeDistance,
TMC_AUTO_INC)
3.4.2Basic GeoCOM Application Frame for VBA
Like in section 3.3.2 - Basic GeoCOM Application Frame for C/C++ - a VBA GeoCOM application consists at least of
the following parts:
- Initialise GeoCOM
- Open a connection to the server
- One or more GeoCOM RPC’s
- Close the active connection to the server
- Finalise GeoCOM
A sample implementation of above points could be:
CONST NUM_OF_RETRIES = 1
DIM RetCode As Integer
DIM bOpenAndRunning as Integer
DIM bAvailable as BOOLE
' initialize GeoCOM
bOpenAndRunning = False
RetCode = VB_COM_Init()
If (RetCode = GRC_OK) Then
' open a connection to the TPS1200 instrument
RetCode = VB_COM_OpenConnection(COM_1, COM_BAUD_19200,
NUM_OF_RETRIES)
If (RetCode = GRC_OK) Then
bOpenAndRunning = True
End If
End If
' optionally set up other comm. parameters here
If (RetCode = GRC_OK) Then
' functionality of the application
' we just test if communication is up
RetCode = VB_COM_NullProc()
If (RetCode <> GRC_OK) Then
' handle error
End If
End If
If (bOpenAndRunning) Then
' close channel
RetCode = VB_COM_CloseConnection ()
If (RetCode <> GRC_OK) Then
' handle error
End If
End If
' finalize and reset GeoCOM
RetCode = VB_COM_End()
If (RetCode <> GRC_OK) Then
' handle error
End If
3.4.3VBA Development System Support
This interface has been written for Microsoft Visual Basic for Applications 5.0 and higher only. Hence, no other
development environment will be supported.
3.4.4Programming Hints
Output Parameters of String Data Type
The internal representation of strings is not directly compatible between C/C++ and VBA. Therefore the one has to pre-
and post-process such an output parameter. In the following example, we know that the output parameter will be less
than 255 characters in length from the description of the RPC.

GeoCOM Reference Manual Fundamentals of Programming GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 16
Dim s As String
' initialise string
s = Space(255)
Call VB_COM_GetErrorText(GRC_IVPARAM, s)
' trim string, justify string length
s = Trim$(s)
Note: Incorrectly handled string output parameters may lead to severe runtime problems.
3.5 UNITS OF VALUES
All parameters are based on the SI unit definition, if not explicitly indicated differently. The SI units, and their
derivatives, used are:
Abbreviation Unit Description
M ( Meters ) for lengths, co-ordinates, ...
Rad ( Radians ) for angles
Sec ( Seconds ) for time
Hpa ( Hekto Pascal ) for pressure
C (Celsius ) for temperature
Table 3-2: SI Units
3.6 TPS1200 INSTRUMENT MODES OF OPERATION
In respect to communication, the TPS1200 instrument knows several states in which it reacts differently. The main state
for GeoCOM is online state or mode. There it is possible to use all RPC’s, which are described in this manual.
Especially we will describe the possibilities of changing the state by the built-in RPC’s. For the ASCII protocol refer to
section 3.2.3 - Modes of Operation Concerning Communication.
The possible states can be described as follows:
Off The instrument is switched off and can be switched on using COM_OpenConnection. To switch on the
instrument a single character is sufficient.
GeoCOM The instrument accepts RPC’s. To switch into GeoCOM mode start the “Configuration” menu on the
instrument, open the submenu “Interfaces” and enable interface “GeoCOM Mode”.
RCS The instrument accepts Remote Control sequences.
3.7 COMMON COMMUNICATION ERRORS
GeoCOM is based on calling functions remotely. Because of the additional communication layer the set of return codes
increases with return codes based on communication errors. Since all of these codes may be returned by any RPC we
will explain them here and omit them in the descriptions of the RPC’s.
Return-Code Value Description
GRC_OK 0 Successful termination, implies also no communication error.
GRC_COM_CANT_ENCODE 3073 Can't encode arguments in client. Returned by the client to the
calling application directly, i.e. without anything being sent to
the transport layer and beyond.
GRC_COM_CANT_DECODE 3074 Can't decode results in client. Once an RPC has been sent to
the server and a reply has been sent back, this return code
states that the encoded reply could not be decoded in the
client. This is usually the result of using different versions of
GeoCOM on client and server.
GRC_COM_CANT_SEND 3075 Failure in sending calls. If the resources at the transmitting
port have been allocated previously, i.e. GeoCOM does not
have exclusive rights to the port, or if the exception or similar
routine has experienced a failure, this error code is returned.

GeoCOM Reference Manual Fundamentals of Programming GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 17
Return-Code Value Description
GRC_COM_CANT_RECV 3076 Failure in receiving result. A failure has occurred during
reception of a packet at the data link layer. This could be due
to incorrect parameter settings or noise on the line, etc..
GRC_COM_TIMEDOUT 3077 Call timed out. The client has sent an RPC to the server but it
has not replied within the current time-out period as set for the
current transaction. This could be because: the server has not
received the request; the server has taken too long to execute
the request; the client has not received the reply; the
communication line (physical layer is no longer there; or, the
time-out is too short (especially true when communicating
over noisy or radio links at low baud rates).
GRC_COM_WRONG_FORMAT 3078 The request and receive formats are different. Something got
mixed up along the way or the application tried to send using a
format, which has not been implemented on both client and
server.
GRC_COM_VER_MISMATCH 3079 RPC protocol mismatch error. An RPC protocol has been
requested which does not exist. This error will indicate
incompatible client and server protocols.
GRC_COM_CANT_DECODE_REQ 3080 Can't decode request in server. If the client sends the server an
RPC but one, which cannot be decoded in the server, the
server replies with this error. It could be that the GeoCOM
versions running on the client and server are different or the
packet was not correctly sent over a noisy or unreliable line.
GRC_COM_PROC_UNAVAIL 3081 The requested procedure is unavailable in the server. An
attempt has been made to call an RPC, which does not exist.
This is usually caused when calling RPC’s, which have been
inserted, appended, deleted, or altered between the differing
versions of GeoCOM on client and server. To be on the safe
side, always use the same GeoCOM version whenever
possible on both sides.
GRC_COM_CANT_ENCODE_REP 3082 Can't encode reply in server. The server has attempted to
encode the reply but has failed. This can be caused by the
calling procedure trying to pass too much data back to the
client and in so doing has exceeded the maximum packet
length.
GRC_COM_SYSTEM_ERR 3083 Communication hardware error
GRC_COM_FAILED 3085 Mess into communication itself. Should be OK once the node
has been recycled, i.e. powered-down and -up again.
GRC_COM_NO_BINARY 3086 Unknown protocol. An unknown (or not yet supported)
Transport or Network protocol has been used. Could appear
when using differing GeoCOM versions on client and server.
GRC_COM_INTR 3087 Call interrupted. Something has happened outside of the scope
of GeoCOM, which has forced the current RPC to abort itself.
GRC_COM_REQUIRES_8DBITS 3090 This error indicates desired protocol requires 8 data bits
GRC_COM_TR_ID_MISMATCH 3093 Request and reply transaction ids do not match. Somewhere
along the line a packet (usually a reply) has been lost or
delayed. GeoCOM tries to bring everything back to order but
if this error continues during the session it may be wise to
inspect the line and, at least, to restart the session. The
immediately following RPC may be lost.
GRC_COM_NOT_GEOCOM 3094 Parse failed; data package not recognised as GeoCOM
communication package
GRC_COM_UNKNOWN_PORT 3095 Tried to access an unknown hardware port. The application
has not taken the physical resources of the machine on which
it is running into account.

GeoCOM Reference Manual Fundamentals of Programming GeoCOM
Leica TPS1200 / TS30 / TM30 – Version 1.50 18
Return-Code Value Description
GRC_COM_OVERRUN 3100 Overruns during receive. A packet has been received which
has exceeded the maximum packet length. It will be discarded!
This can be caused by a noisy line during GeoCOM Binary
format transmissions.
GRC_COM_SRVR_RX_CHECKSUM_ERROR 3101 Checksum received at server is wrong. The checksum
belonging to the current packet is wrong - no attempt is made
at decoding the packet.
GRC_COM_CLNT_RX_CHECKSUM_ERROR 3102 Checksum received at client is wrong. The checksum
belonging to the current packet is wrong - no attempt is made
at decoding the packet.
GRC_COM_PORT_NOT_AVAILABLE 3103 COM port not available. This can be caused by attempting to
open a port for unique use by GeoCOM, which has already
been allocated to another application.
GRC_COM_PORT_NOT_OPEN 3104 COM port not opened / initialised. The application has
attempted to use a COM port to which it has no unique rights.
GRC_COM_NO_PARTNER 3105 No communications partner on other end. The connection to
the partner could not be made or has been lost. Check that the
line is there and try again.
GRC_COM_ERO_NOT_STARTED 3106 The client, after calling an ERO has decided not to confirm the
start of the ERO and has instead called another RPC.
GRC_COM_CONS_REQ 3107 Attention to send consecutive requests. The application has
attempted to send another request before it has received a
reply to its original request. Although GeoCOM does not
return control to the app until a reply is received, this error is
still possible with event-driven applications, i.e., the user
pushing a button yields control back to the application code,
which can then call GeoCOM again.
GRC_COM_SRVR_IS_SLEEPING 3108 TPS has gone to sleep. Wait and try again.
GRC_COM_SRVR_IS_OFF 3109 TPS has shut down. Wait and try again

GeoCOM Reference Manual Remarks on the Description
Leica TPS1200 / TS30 / TM30 – Version 1.50 19
4REMARKS ON THE DESCRIPTION
This chapter contains some remarks on the description of RPC’s and on the structure of the descriptions.
4.1 STRUCTURE OF DESCRIPTIONS
The whole reference part is subdivided into sections. Each section contains descriptions of a set of functions, which
build up a subsystem. A subsystem gathers all functions, which are related to a specific functionality of a TPS1200
instrument, e.g. MOT describes all functions, which relate to motorization. Each subsystem is subdivided into the
descriptions of RPC’s.
4.1.1Structure of a Subsystem
A subsystem consists of the following parts:
1. Usage
This part gives some hints about the usage of the subsystem and general information of its functionality.
2. Constants and Types
All subsystem specific constants and data types are listed here. Also their meanings are described if they are not
obvious.
3. Functions
All RPC’s of these subsystems are listed here and described in detail.
Note: To reduce redundancy the VB declarations of data types and constants have been omitted. Please refer to chapter
3.3 to get more information about this subject.
4.1.2Structure of a RPC Description
One RPC description contains the following parts:
Title Contains the name of the RPC and a short description of the function.
C-Declaration
Contains the C declaration of the function (excluding the return type).
VB-Declaration
Declares the function in VB (excluding the return type).
ASCII-Request
Describes the request including the input parameters and their data types listed in [ ].
ASCII-Reply
Describes the reply including the output parameters and their data types listed in [ ].
Remarks
Gives additional information on the usage and possible side effects of the function.
Parameters In/Out
Explains the parameters, their data types and their meaning. Parameters and their ASCII equivalent are explained
at the beginning of each chapter.
Return-Codes
Lists the most common RC to this request, in RC name and RC value.
See Also
Cross-references shows other RPC’s which relate to this one.
Example
Gives an example of how this RPC could be used.

GeoCOM Reference Manual Remarks on the Description
Leica TPS1200 / TS30 / TM30 – Version 1.50 20
Note: To reduce redundancy the return type has been omitted from the C- and VB-declarations of the RPC’s.
ASCII-Request and Reply do not explain the whole data structures. Instead the corresponding base types will be
given. Please refer to chapter 2.2 to get more information on this topic.
Also because of redundancy the necessary CR/LF at the end has been omitted from ASCII-Request and Reply.
4.1.3Sample of a RPC Description
1.1.1CSV_GetDateTime- Get date and time.
C-Declaration
CSV_GetDateTime(DATIME &DateAndTime)
VB-Declaration
VB_CSV_GetDateTime (DateAndTime As DATIME)
ASCII-Request
%R1Q,5008:
ASCII-Response
%R1P,0,0:RC,Year[short],Month,Day,Hour,Minute,Second[all byte]
Remarks
The ASCII response a
type DATIME. A possible response can look like this:
%R1P,0,0:0,1996,'07', '19','10','13','2f' (see
chapter ASCII data type declaration for further information)
is formated corresponding to the dat
Parameters
DateAndTime out
Encoded date and time.
Return-Codes
GRC_OK Execution successful.
GRC_UNDEFINED Time and/or date is not set (yet).
See Also
CSV_SetDateTime
Example
GRC_TYPE rc;
DATIME DateAndT
rc = CSV_GetDateTime(DateAndTime);
if (rc == GRC_OK)
ime;
{
// use Date and time
}
else
{
// handle error
Title and description
Declarations for different
protocols
Remarks to this function and its usa
g
e
Detailed description of parameters
Meaning of return codes
Cross reference to related functions
A typical
usage of this
function