GeoCOM Reference manual 1. GeoCOM 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 TPS1100 nstrument Note: Further on we will refer to a remotely executable system function as saRPY The TPS1100 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 nstead on the high level interface a function call will not return until it has been completely finished TPS1100-Version 1.01
GeoCOM Reference Manual 1 . GeoCOM TPS1100-Version 1.01 1-4 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 TPS1100 instrument. Note: Further on we will refer to a remotely executable system function as a RPC. The TPS1100 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
GeoCOM Reference Manual 2. General Concepts of Using GeoCOM 2 GENERAL CONCEPTS OF USING GEOCOMI Here we will describe several aspects of using GeoCOM. One of them is how to execute a function at a tps 1 100 instrument The current implementation of GeoCOM supports two(three) kinds of usage. We an distinguish between a rather rudimentary ASCll 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 ne to the listening tps1100 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. Any necessary communication will be handled by GeoCOM implicitly 2.1 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(TPS1100 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 crier Client Server Picture 2-1: Basic communication bocOM is implemented as synchronou may no be interrupted by another request/reply. Instead, a communication unit must be completed successfully before a new communication unit may be initiated TPS1100-Version l01
GeoCOM Reference Manual 2 . General Concepts of Using GeoCOM TPS1100-Version 1.01 2-1 2 GENERAL CONCEPTS OF USING GEOCOM Here we will describe several aspects of using GeoCOM. One of them is how to execute a function at a TPS1100 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 TPS1100 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. Any necessary communication will be handled by GeoCOM implicitly. 2.1 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 (TPS1100 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 may no be interrupted by another request/reply. Instead, a communication unit must be completed successfully before a new communication unit may be initiated. Client Server request reply
GeoCOM Reference manual 2. General Concepts of Using GeoCOM 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 Note: In the current implementation, only one communication channel per session will be supported. Hence, only one instrument can be connected at a time Nevertheless, the nature of the ASCii protocol makes it possible to connect and communicate to more than one instrument at a time 2.2 ASCII PROTOCOI 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 TPS1100 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.2.1 ASCII Protocol Syntax Syntax of an AsCII request <LF>]器R1Q,<RPC>[,<TxId>]:[<P0>][,<P1>,,.]<Term> Optional items are in brackets [. The angled-brackets o 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 <F> An initial line feed clears the receiver buffer BRIQ GeoCOM request type l <RPC Remote Procedure Call identification number in between 0 to 65535 TPS1100-Version l01
GeoCOM Reference Manual 2 . General Concepts of Using GeoCOM TPS1100-Version 1.01 2-2 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. Note: In the current implementation, only one communication channel per session will be supported. Hence, only one instrument can be connected at a time. Nevertheless, the nature of the ASCII protocol makes it possible to connect and communicate to more than one instrument at a time. 2.2 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 TPS1100 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.2.1 ASCII 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
GeoCOM Reference Manual 2. General Concepts of Using GeoCOM TrId> Optional transaction ID: normally incremented from I to 7. Same value in re Separator between protocol header and following P0>,<P1> Parameter 0. Parameter I <Term> Terminator string(default CR/LF,use COM SetTerminator to change the terminator ).As a common shortcut"m will be used in examples Example The following example uses the RPC TMC SetPrismCorr to set the prism constant on 34 4mm("m denotes the terminator) 8R1Q,2024:34.4^m 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: BRlP, <GRC>[,<TrId>]: <RC>[, <P0>,<PI>,..]<Term> Optional items are in brackets [ The angled-brackets o 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 leoCOM protocol BLp GeoCOM reply type I GeoCOM return code. This value denotes the success of the communication. 0=RC OK means the communication was successful (see table ' GeoCOM return codes' in the appendix 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 TPS1100-Version l01
GeoCOM Reference Manual 2 . General Concepts of Using GeoCOM TPS1100-Version 1.01 2-3 <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 terminator). As a common shortcut ‘^m’ will be used in examples. Example: The following example uses the RPC TMC_SetPrismCorr to set the prism constant on 34.4mm (‘^m’ denotes the terminator): %R1Q,2024:34.4^m 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,<GRC>[,<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. <GRC> GeoCOM return code. This value denotes the success of the communication. 0 = RC_OK means the communication was successful (see table ‘GeoCOM return codes’ in the appendix 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
GeoCOM Reference Manual 2. General Concepts of Using GeoCOM <RC> Return code from the called rPc and denotes the successful completion if it is set to O(see table'RPC return codes' in the appendix for further <P0>,<P1> Parameter 0, Parameter 1,.. These parameters will be valid only if <GRC> is equal to O(RC 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 esv GetDaterime 8R1P,0,0:0,1996,"07!,19,110,113,"2f1^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: o 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 o +----Return code from GeoCOM: 0 means no error(see GeoCOM return codes for further information) 2.3 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 ports settings to make sure that communication can take place. Moreover the user has to make sure that the tps 1 100 instrument is well connected Example: An example code fragment for using TMC GetsimpleMea could be the followin We do not take care of the necessary initialisation and set up of GeoCOM here TPS1100-Version l01
GeoCOM Reference Manual 2 . General Concepts of Using GeoCOM TPS1100-Version 1.01 2-4 <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 (RC_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.3 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 TPS1100 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