《GeoCOM Reference Manual（Ver. 1.01）》Gc1100

GeoCOM Reference manual 2. General Concepts of Using GeoCOM Please refer to chapter 3.2.3 Basic GeoCOM Application Frame for C/C++ for this information RC TYPE Recode TMC HZ V ANG Angle double dslopeDist Retcode TMC GetsimpleMea( 1000, Angles dslopeDist, if (RecOde = RC OK) // do something - use values else / handle error 2.4 FUNCTION CALL PROTOCOL- VBA Here almost all is valid for VBA as for C/C++. Please refer to Chapter 2.3. 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.3 Dim Recode As Integer Dim Angles AS TMC HZ V ANG Dim dslopeDist As Double Retcode VB TMC GetsimpleMea( 1000, Angles dslopeDist TMC AUTO INC If Recode rc ok Then mething -u Else handle error TPS1100-Version l01

GeoCOM Reference Manual 2 . General Concepts of Using GeoCOM TPS1100-Version 1.01 2-5 Please refer to chapter 3.2.3 Basic GeoCOM Application Frame for C/C++ for this information. RC_TYPE RetCode; TMC_HZ_V_ANG Angles; double dSlopeDist; RetCode = TMC_GetSimpleMea( 1000, Angles, dSlopeDist, TMC_AUTO_INC ); if (RetCode == RC_OK) { // do something – use values } else { // handle error } 2.4 FUNCTION CALL PROTOCOL – VBA Here almost all is valid for VBA as for C/C++. Please refer to Chapter 2.3. 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.3. 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 = RC_OK Then ' do something – use values Else ' handle error End If

GeoCOM Reference Manual 3. Fundamentals of Programming geoCOM 3 FUNDAMENTALS OF PROGRAMMING GEOCOM 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.1 ASCII PROTOCOL PROGRAMMING Implementing an application, which uses the ASCll protocol, is based on simple data transfers using a serial line. The programmer is responsible to set up the serial ine parameters of the client such that they correspond to the settings of the TPS1100 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 ote: 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 rpo 3.1.1 Data Types in ASCll 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 ASCll protocol supports simple data types only. All data type which are different from the base, types in name and aggregated data types are 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 inpl Typical output representationsrepresentations TPS1100-Version l01

GeoCOM Reference Manual 3 . Fundamentals of Programming GeoCOM TPS1100-Version 1.01 3-1 3 FUNDAMENTALS OF PROGRAMMING GEOCOM 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.1 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 TPS1100 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.1.1 Data 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 there 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

GeoCOM Reference Manual 3. Fundamentals of Programming geoCOM Format Type Valid range Len Valid input Typical output representations representations boolean 0=false 0,1 0.1 true 0.255 2(4)00,FF;m;7a, 7a.A7 string <512 abclxOdlxOa” double ±225E-308.17+31,1.0,10e4, -0.1234567+e67 ±1.797E+308 -0.le-07.-2 long II OX7FFFFFFF 15,-154836, 54321 short 327683276760,-1,-32700,45,56,0,-1,-32700, 0x45e. 0X3AA uns9ned|0.(232-1) 10 OXFFFFFFFF 0.1.3400065 long 95735 unsigned.65535 510,1,3400065,0,1,3400065 short 655350x3a,0x00,65535 OXFFFF Table 3-1: Communication Parameter Types Note: Bytes are always represented in two-character hexadecimal notation Hexadecimal notation can use upper-or lower-case representation: 0.9+ [a Characters sent within a string which do not fall within the ascii character notation-e.g"9A",where x(or X) introduces a byte value in yte range Ox20 to Ox7E (32 to 126 decimal) are sent using an adapted byte hexadecimal notation Types of integer(short, unsigned short, long, unsigned long) can also be represented in hexadecimal notation, introduced by Ox or OX The following rules are for generating/interpreting values with a type different from the base types and aggregated data types umerical 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 ther the next best one will be taken. Character and string will be replaced by the string data TPS1100-Version l01

GeoCOM Reference Manual 3 . Fundamentals of Programming GeoCOM TPS1100-Version 1.01 3-2 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 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. 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

GeoCOM Reference Manual 3. Fundamentals of Programming GeoCOM 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 tl 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 typ 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 ASCll parameters are described explicitly 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 Example for Enumeration Data Types and structures corresponding procedure declaration used in this manual for d the The following example gives a typical data type declaration MC GetsimpleMea from the subsystem Theodolite Measurement and Calculation Constants and t typedef long SYSTIME; struct TMC HZ V dHz: enum TMC INCLINE PRG TMC MEA INC, / encoded as o TMC AUTO INC TMC PLANE IN TPS1100-Version l01

GeoCOM Reference Manual 3 . Fundamentals of Programming GeoCOM TPS1100-Version 1.01 3-3 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 }

GeoCOM Reference Manual 3. Fundamentals of Programming GeoCOM C-Declaration TMC GetSimpleMea(SYSTIME waitTime, TMC HZ V ANG &OnlyAngle double &dslopeDistance TMC INCLINE PRG Mode) ASCIl-Request BR1Q, 2108: AirtIme/long/, Mode/long ASCII-Response BR1P,0,0: RC, H=/double]. /double. aSlope Distance/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 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 ASCll 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 I is used for the Mode parameter because the counting of enumeration data types start at O 号R1Q,2108:1000,1^m a possible reply can be as follows Where the second and third value after the colon corresponds to the dHz and pal of the structure TMC HZ V2 ANG and the fourth value to the variable dslopeDistance ( Note that the first value after the is not a parameter but the return code value of the RPC) 3.1.2 ASCII 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 TPS1100-Version l01

GeoCOM Reference Manual 3 . Fundamentals of Programming GeoCOM TPS1100-Version 1.01 3-4 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! 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.1.2 ASCII 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