Communication Program

OPTIMUS-iC MGxxx

TangoDrv

Version 2.0 For DOS

Manual for programmer

Tabele of contents:

INTRODUCTION 

General Informations 

Features of programs 

Structure of program. 

CONTROL OF PROGRAM

Parameter list. 

Transmission parameters 

Data file names and location 

Input and output data file formats: 

The input file starting line 

The separator character 

Parentheses for data package field values

New Line mark

Call parameter syntax 

Data file contents

Data for programming 

Receiving data from the TANGO 

INFORMATION ON TRANSMISSION ERRORS 

The results of executing the TangoDrv.Exe program

The error file contents 

NOTES TO THE 1.0 BETA VERSION

INTRODUCTION

General Informations

Communication program for ECR OPTIMUS-IC TANGO TangoDrv.exe is designed for programming and receiving data from TANGO. This program works in DOS environment also it is possible to use it in Windows 3.11/95/98. Controlling of the program is done through calling parameters (command line). Data sent to ECR are in *.txt files.

Program makes possibility to use all function of Tango-PC protocol. Program makes programmer free from Tango-PC protocol allowing only to looking to sending data. This program allows fast Tango support in new or existing programs.

Features of programs

These are following features of communication program TangoDrv.exe:

Working in DOS and Windows 3.11/95/98 environment,

Control through call parameters,

Call parameters can be given in free sequence,

Not all call parameters must be given default values will be used

Make possible transmission through serial ports COM1 and COM2 with all used by Tango speeds of transmission 24000, 4800, 9600, 19200 bps

Use all Tango-PC protocol functions

Data are sending in *.txt files

Elastic data format in text files separated, fixed position

Format of input and output files are independent,

Position data in text file is same as in data packet sent to Tango.

All physical aspect of transmission with Tango are realised internally,

Structure of program.

Program consists of executable file TangoDrv.exe, input data file (default data_in.txt), output data file (default data_out.txt), errors file (default Error.txt). Name and location of data file can be modified.

CONTROL OF PROGRAM

Parameter list

For Program controlling the suitable call parameters must be used. Each parameter has form

IP=W,

IP it is two letters identification of parameters, W character or string of characters with value of parameter. This format and fact that every parameter has default value allows to elastic giving only needed parameters in any position.

This is list of all parameters including their identifications, full name, description, permitted and default values:

Transmission parameters

To control transmission, CP, CS and RT parameters are used. Transmission may be provided through serial ports 1 or 2. Port 1 is the default setting. if the cash register is connected to the COM2 port, the CP=2 sequence has to be given in the parameter list.

The TANGO cash register works with the following transmission rates: 2,400; 4,800; 9,600; 19,200 bauds. The 9,600 setting is the default one. If the cash register is set for e.g. 19,200, the CS=19200 sequence has to be given in the parameter list.

Transmission with the TANGO cash register may be broken due to certain reasons at various situations. The computer may, for example, stop receiving signals sent by the cash register . Such missing signals may interrupt with the following transmission. To avoid it, executing transmission reset procedure is recommended. The transmission reset procedure is by default executed in the beginning, before delivering data from the input file. The transmission reset procedure, however, lasts for 2.5 sec., which is due to the TANGO cash register time-out. If the most recent transmission was executed properly, this procedure may be skipped by giving RT=0 entry in the parameter list.

Here are sample program calls for setting transmission parameters in COM2, at 19,200, without resetting:

Tangodrv.exe CP=2 CS=19200 RT=0

As it has been mentioned, the sequence of parameters and letter style (caps) are of no significance.

Data file names and location

Data sent and received are included in text files. By default, input data are taken from the data_in.txt file, output data (sent back by TANGO) are saved in the data_out.txt file, and information on errors in the error.txt file. The files are loaded from the default folder: the program does not change the current folder. Every data file name may be freely changed with parameters IF, OF, EF for the input, output and error files, respectively. The new file name may include an access path, e.g. the input file may be set as C:TANGODATA_PLU.txt, podając w parameter list IF=C:TANGODATA_PLU.TXT. The DP parameter is an additional parameter affecting definition of data files by the program. It determines the access path, which is common for all the data files. By default, this is an empty string of characters, which does not affect the name (location) of data files. However, if this parameter is attributed a specific value, it shall be glued to the data file names. The path is given without the character. For example, if all the files have a standard name, yet are located in the C:TANGODATA folder (different from the current one), the program should be called as follows:

Tangodrv.exe DP=C:TANGODATA

Input and output data file formats:

Parameters defining the format of data in the file are additional parameters for data files. Generally speaking, each data sequence (the so-called package: see the TANGO-PC transmission protocol manual) engages one line. There are data fields in every package, for example, in the cashier data package there are the following fields: the cashier identifier package, the cashier code, name and password. There are other fields, as well, but these are not data fields: the STX code, the D data package symbol and the ETX code and the checksum in the end: the TangoDrv.exe program user does not have to deal with these. The data fields referred to above shall be placed in one input file line, which may be done in two ways: In one, every field has an arbitrary length dependent on its value and the separator character is inserted in the end of the field. The cashier package thus is as follows:

D;0;Cashier No 0;0000;

If such a package is sent to TANGO, the cashier with the code 0 would be programmed, with the name Cashier No 0, with the 0000 password. This data format is referred to as separated text format and is set forth by the IF=T calling parameter (for the input file) or by AF=T (for the output file). The T format is the default format for the input data file.

Another file data format is referred to as the binary-position one. Package data are here entered in the same way in every package in one line. Unlike in the previous package, data fields are not separated, with the requirement set forth instead for them to have size accurately defined. Size for particular fields is defined in the TANGO-PC transmission protocol instruction. This data format is defined by the IF=B (the input file) or AF=B (the output file) parameter. The B format is the default format for the input data file. The previous programming package would be as follows in this format:

D0Cashier.No 0.0000

(NOTE! Dots stand for spaces for recognition purposes. In reality, spaces are inserted.)

The input file starting line

The TangoDrv.exe program user may define, which line in the input file is to be transmitted as the first one. The lines preceding the starting line shall be skipped. The option for defining the starting line may be useful with continuation the transmission which was dropped. If, for example, the input file has many packages and after transmitting some of them an error, the transmission will be broken. if making the error good does not require interfering with the input file, the control program may call TangoDrv.exe with the SL=x parameter, where x stands for the starting line, which may be read from the error.txt file, including the number of the line, in which an error occurred. Thus, transmission may be continued without changing the input file. This way comes in handy with errors in physical transmission breaking (e.g. switching off the Tango device), errors in setting the Tango key lock (turn the key), errors forcing executing some kind of a report, etc. The input file first line has the number of 0.

The separator character

If the separated text format is the data file format, a separator character is inserted after each package data field. By default, the ; is the separator mark. The user may change the separator mark, e.g. to set as the separator mark, the following command shall be executed:

TangoDrv.exe SC

The separator mark must be carefully selected. It shall be a character, which is used as rarely as possible, or, even better, is not used altogether in parameter values. Setting e.g. a as a separator is a total misunderstanding, as it is used commonly in names. The following characters are best suited for this purpose: ; | ^ ~ or graphic characters with high ASCII codes. However, if the field value includes a separator mark, it shall be included in parentheses, which is referred to below.

Parentheses for data package field values

If data package field value includes a separator mark (in the separated text format for the data files), it shall be placed in parentheses, otherwise part of this field will be interpreted as belonging to the next field. E.g. if the PLU name is Klocki 1;2 if it were inserted in the text field without parentheses and ; were a separator, 2 of the name would be treated as the next field, denoting the price in this case. To provide the possibility of introducing such values and avoiding the mistakes as above, TangoDrv.exe has the parentheses mechanism enabled. A sample name value should be inserted in the file as while marks are standard parentheses. The program may change these characters with BO and BC parameters. E.g. to set [ and ] parentheses, the following program should be called:

TangoDrv.exe BO=[ BC=]

Enclosing values in the input file in parentheses is done with the control program. If the program does not do it, input data may be misinterpreted. The control program may discontinue placing parentheses if it is certain that the separator will not occur in field values (e.g. an unused separator character has been selected, e.g. not allowed in names). Parentheses may be identical. If the parentheses mark is to be used in the value, it must be placed twice sequentially. If, for example, the PLU name is Auto the input file should be {Auto {}}.

Enclosing values in the output file in parentheses remains with the TangoDrv.exe program. The program automatically encloses values in parentheses, which include a separator mark, and the output file format is set as separated text. The program for interpreting output file data must remember this and appropriately interpret parentheses characters. The control program shall not insert parentheses, yet it may select one of the two inserting modes. In the S (smart) mode, TangoDrv.exe encloses in parentheses only these values, which include a separator mark. In the A (all) mode, all the field values are enclosed in parentheses. By default, the S mode is applied. The BM (Bracket mode) parameter is used for setting the parentheses inserting mode. To use the A mode, the program shall be executed as follows:

TangoDrv.exe BM=A

Note! Enclosing in parentheses is an emergency procedure, aimed at maintenance of data integrity. By appropriate selection of the separator mar, the mechanism will remain unused and it may be left unattended. The best thing is when the control program uses a character, which is not allowed in names, for a separator mark. For standard separator marks, the characters have been selected, which are not easy to enter from the keyboard. If the TangoDrv.exe program is executed by another control program, an ASCII character forbidden editable names in this control program, e.g. 255, may be used as a separator mark.

Using parentheses and the separator mark problem do not apply if the binary position format is used for the data file. The binary format is a standard format for the output file.

New Line mark

As we know, successive data packages in the TANGO cash register are entered in the successive lines of data files. The new line mark is then used as a limiter for successive packages. There are case, however, where the new line mark may occur within the value of a given field. Generally, the TANGO cash register has two such fields: the header text and the advertising footer. In order to make it possible to insert a new line mark in the contents of these fields, the TangoDrv.exe program allows for defining a certain character to be used (when transmitted) and converted for the actual new line mark. By default, the character is interpreted as a new line mark. The NL (new line) parameter is used for defining the new line mark. The new line mark must be selected very carefully, being the mark used as rarely as possible, or, preferably, not used at all in parameter values. E.g., to define the | character as a new line mark, execute the program as follows:

TangoDrv.exe NL=|

Note! The new line mark is interpreted in the fields, in which it may be actually used. This applies to fields of the header contents and the advertising footer. If the character defined as a new line mark is inserted in a different field, e.g. in the PLU code, it shall not be converted into the actual new line mark.

Call parameter syntax

Call parameters are given one after another with spaces in between. The parameter order and letter size are irrelevant. If setting any parameter appears twice, the second (last) setting is accepted. All the parameters have default values set. If the given parameter value is equal to the default value, it need not be given.

Below, there is a sample call of the program with the following settings: COM2 serial port, 19,200 transmission rate, GetPLU.txt input data file, PLUData.txt output data file, | separator mark and text format for the output file:

TangoDrv.exe cp=2 cs=19200 if=GetPLU.txt of=PLUData.txt sc=| af=T

Data file contents

Note! To understand properly this chapter, The OPTIMUS-iC TANGO cash register to PC communication protocol manual is needed. The TangoDrv.exe program user should get acquainted with the chapters on data package formats (chapter 3).

Data for programming

In order for the transmission to run properly, the input file data must be formally correct, both in format and in contents. Every communication with the TANGO cash register consists in sending appropriate data packages to TANGO. These packages should be entered in successive input file lines. Each package has its own one-letter identification code and data fields. For example, in order to program an input file (separated text) for three cashiers, the following shall be included:

S;D;1;0;0;

D;1;Cashier No 0;0000;

D;2;Cashier No 1;1111;

D;3;Cashier No 2;2222;

Each cashier is allocated a number, a name and a password. The cashier data package has a D identifier.

The S identifier is a starting package to initiate the transmission. The second field in the S package determines, what kind of data shall be transmitted in the following packages: D stands for cashiers data. The next S package field determines transmission mode: 1 data sent from PC to TANGO. The next two fields define a range, which is irrelevant with the transmission from PC to TANGO. After the starting package, the cashiers data packages follow. Each of them includes an identifier package (D), the cashiers number, his/her name and a password. Each package occupies a separate line. Every field is limited with a separator (;).

Precise information on package identifiers and their contents are to be found in chapter 3 of The OPTIMUS-iC TANGO cash register to PC communication protocol manual available on the Web (www.optimus-ic.com.pl Informacja dla dealerow Programy Protokoly transmisji Tango) or in consultation posts. In this manual, each package is presented along with a precise description of its fields and allowed values. The manual presents the physical appearance of packages to be transmitted to the TANGO cash register. As it was mentioned, the TangoDrv.exe program user does not need to deal with physical aspects of transmission. Therefore, some package fields do not have to appear in data files (formally, they cannot appear). These are: the STX mark field, the ETX mark field and the checksum field. Generally speaking, the data files use fields, which appear between the STX and ETX marks (without these marks). The STX mark, the ETX mark and the checksum are generated at the time when the transmission is initiated by the TangoDrv.exe program. Additionally, this program is able to automatically generate the starting package for the PC to TANGO transmission. The above example may appear as follows:

D;1;Cashier no 0;0000;

D;2;Cashier no 1;1111;

D;3;Cashier no 2;2222;

However, if we use the binary positioning format, we must preserve field size for the required fields. In the description of each field in The OPTIMUS-iC TANGO cash register to PC communication protocol manual, there is a Length column in the field table, where the field size is defined in characters. The above example in the binary format would look like as follows:

D1Cashier.no.0.0000

D2Cashier.no.1.1111

D3Cashier.no.2.2222

(NOTE! Dots stand for spaces for orientation purposes. Physically, spaces are inserted.)

The input file may include any number of packages of various types. However, it is recommended that various types of packages are not mixed up, as interpretation of the retransmitted packages or reaction to existing errors may be difficult.

Receiving data from the TANGO

In order to receive data from the TANGO cash register, the input file should include data of an appropriate starting package, after receiving which the TANGO cash register will re-send the required data. For example, in order to collect data from all the cashiers, the input file should include:

S;D;0;0;7;

where S stands for the starting package, D means that the cashiers package will be used, 0 means that data shall be transmitted from TANGO to PC; 0 and 7 define the cashiers number limit. After running and terminating the TangoDrv.exe program, the output file shall include, for example:

D;1;Cashier no 0;0000;

D;2;Cashier no 1;1111;

D;3;Cashier no 2;2222;

The above packages would become the following in the binary format:

SD0..0..7

and

D1Cashier.no.0.0000

D2Cashier.no.1.1111

D3Cashier.no.2.2222

(NOTE! Dots stand for spaces for orientation purposes. Physically, spaces are inserted.)

Packets are described in The OPTIMUS-iC TANGO cash register to PC communication protocol manual. If we want to receive report data with simultaneous resetting of these data, the third field in the starting package should be set to 2 (see the starting package description in The OPTIMUS-iC TANGO cash register to PC communication protocol manual, chapter 3.1).

The input file may include any number of packages of various types. However, it is recommended that various types of packages are not mixed up, as interpretation of the retransmitted packages or reaction to existing errors may be difficult.

INFORMATION ON TRANSMISSION ERRORS

The results of executing the TangoDrv.Exe program

The TangoDrv.exe program, after execution, returns the following values to the system:

0 program executed without any errors, the error file is empty, the data output file has correct information;

1 errors in initialisation or transmission, the error file includes information on errors, the data output file includes information received correctly and/or an error package (see The OPTIMUS-iC TANGO cash register to PC communication protocol manual, chapter 3.4);

2 internal program errors; the program was immediately terminated, and the contents of the error and output files is unspecified;

3 internal program errors; the program was immediately terminated, and the contents of the error and output files is unspecified.

The result 1 may occur if the program initialisation is not successful (e.g. low memory, wrong file names, etc.) or the transmission is not correct due to improper conditions or data.

The results 2 and 3 occur if the program cannot continue its operations due to, for example, low memory. It has to be terminated or stopped immediately and cannot write error information in the error file.

The error file contents

If the program returned the result 1, the control program should interpret the error file contents. Each existing error occupies one line in this file. The line has the following format:

Error code; Input file line; Text information (in English);

The error code may have the following values:

1 Initialisation error

2 Low memory error

3 Wrong input data

100 Transmission error

101 Time-out exceeded

102 Checksum error

103 The package rejected by the cash register

When the Error 103 is reported, the output file shall include the error package (see The OPTIMUS-iC TANGO cash register to PC communication protocol manual chapter 3.4).

The Input file line field designates the line number at the interpretation, in which the error occurred. The first line is 0.

NOTE! The TangoDrv.exe program terminates its operation if any error occurs.

NOTES TO THE 1.0 BETA VERSION

The 1.0 beta version is the first version of the TangoDrv.exe program released for distribution. The following bugs have been found out in this version:

Parameter correctness control lacking. Wrong parameters may result in erroneous program operation. Wrong parameters may result in various error information. The control program must verify the parameter correctness.

Scarce error information (though all the necessary information is provided). Complex package error detection in the output file (with its own identifier for the wrong package, i.e. a different one, which is sent back from TANGO).

Imperfect parentheses mechanisms for values in the input file. If the parenthesis character is present in the value, it will not be repeated: complex detection of such values. Avoid parentheses mechanism or cleverly define parentheses marks.

Despite these shortcomings, the program is fully functional and does not include bugs, which would make its operation and use impossible.