KKS2Tag

Version 0.9

User’s Manual
Rev. 3, 9/28/05

Dipl.-Ing. H. Rothmaier
Bauerstr. 28
D-80796 München
www.kks2tag.de
KKS2Tag User's Manual

Content
1.Purpose of KKS2Tag ............................................................................................... 2
2.Using KKS2Tag ....................................................................................................... 3
2.1. The Main Window......................................................................................................3
2.2. Project.......................................................................................................................3
2.2.1. Select a Project...................................................................................................3
2.2.2. New Project ........................................................................................................4
2.2.3. Delete a Project ..................................................................................................4
2.3. Source File ................................................................................................................4
2.4. Template File ............................................................................................................4
2.5. Globals-File (optional) ...............................................................................................4
2.6. Output File.................................................................................................................5
2.7. Start Button ...............................................................................................................5
2.8. Exit Button.................................................................................................................5
3.Menü ........................................................................................................................ 6
3.1. File ............................................................................................................................6
3.2. Options......................................................................................................................6
3.2.1. mode = ...............................................................................................................6
3.2.2. Placeholder Markers... ........................................................................................6
3.2.3. List Separator ... .................................................................................................7
3.2.4. Close on finish ....................................................................................................7
3.2.5. Launch DBLoad.exe ...........................................................................................7
3.2.6. Enable Warnings ................................................................................................7
4.Composition of The Tables ...................................................................................... 8
4.1. Source-Table.............................................................................................................8
4.2. Template Table .........................................................................................................8
4.3. Globals Table ............................................................................................................9
4.3.1. Example 1: Debugging by Alarm Logger Messages............................................9
4.3.2. Example 2: Changing the I/O Server.................................................................10
4.4. Offset-Type Placeholder..........................................................................................11
4.5. Output CSV File ......................................................................................................11
4.6. DBLoad ...................................................................................................................11
5.Installation of KKS2Tag.......................................................................................... 13
5.1. OS Requirements....................................................................................................13
5.2. Settings ...................................................................................................................13
5.3. Installation ...............................................................................................................13
5.4. Removal and Update...............................................................................................13
6.Legal Issues........................................................................................................... 14
6.1. Disclaimer ...............................................................................................................14
6.2. License Agreement .................................................................................................14
6.3. Copyrights ...............................................................................................................14

User’s Manual Page 1

KKS2Tag User's Manual

1. Purpose of KKS2Tag
KKS2Tag is intended to support object-oriented development of the tagname
database of InTouch applications by means of Excel tables.
Usually, the objects of an application, i. e. motors, sensors, are represented by a set
of tagname variables, like status, alarms, commands, or numerical values. These
tagname variables have to be generated repeatedly for each instance of an object.
Between objects, they typically differ only in parts of their names. The name of the
status variable for motor M101 could be M101Status and for motor M102 could be
M102Status.
The concept of KKS2Tag is to generate this set of tagname variables from templates
and to import them into the tagname dictionary by DBLoad.exe. A list of objects
(source table) lists all objects, their particular properties and values like identifier, I/O
address etc. When the CSV file for DBLoad.exe is created, placeholders in the
template tables are expanded by the particular values in the object list to generate
unique variables with proper (initial) values for each object.
This approach makes managing thousands of objects with tens of thousands
tagname variables an easy thing and very straightforward at any development phase
of an application. Even major changes can easily be implemented to always achieve
the best design and to meet the requirements of challenging markets.

User’s Manual Page 2

KKS2Tag User's Manual

2. Using KKS2Tag
2.1. The Main Window
When starting, KKS2Tag shows this main window:

The items on this window are explained below.

2.2. Project
In KKS2Tag, all settings are associated with a particular project. They are saved
automatically when a different project is selected or when KKS2Tag terminates.

2.2.1. Select a Project

Click the Project combobox to get a list of existing projects. Select the desired
project to recall all settings as they were saved when the project was last used.

User’s Manual Page 3

KKS2Tag User's Manual

2.2.2. New Project

Click the New button to evoke the Add New Project dialog.

Enter a unique name for the new project and apply OK. Click Cancel or press ESC to
abort the dialog without creating a new project.

2.2.3. Delete a Project

Click Delete to remove the current project from the list. On the message box

confirm deletion of the current project by clicking OK. Click Cancel (locale-specific)
or press ESC to abort the dialog without deleting the project.

2.3. Source File

Enter the path of the Excel file, that holds the Source Table containing the list of
objects for which the tagname variables are to be generated. Next to Table select the
Source Table.
Chapter “Composition of the Source Table” below describes how to setup a Source
table.

2.4. Template File

Enter the path of the Excel file, that contains the template tables of the objects
referred to in the Source table. Chapter “Composition of the Template Table” below
describes how to setup a Template table.
For the Template file, no table can be selected, since KKS2Tag selects the required
Template table according to the identifier found in column A of the source table for
each object at run-time.
Template tables may reside in the same Excel file as the Source Table. In this case,
enter the same path as in Source File.

2.5. Globals-File (optional)

Enter the path of the Excel file, that lists global placeholders and replacement strings,
that are used in the templates, but not provided by the Objects list. Select the desired
table.
Chapter “Composition of the Globals Table” below describes how to setup a Globals
table.

User’s Manual Page 4

KKS2Tag User's Manual

Globals tables may reside in the same Excel file as the Source table and/or the
Template tables. In this case, enter the same path as in Source File or Template file,
respectively.
Using a Globals Table is optional. Leave the field blank if no Globals Table is used.

2.6. Output File

Enter the path of the CSV file that KKS2Tag should create. This CSV file will be
loaded into the InTouch tagname dictionary by DBLoad.exe, subsequently.

2.7. Start Button

Same as Start in the File menu.
The Start button initiates the KKS2Tag process. While creation of the CSV Output
file is in progress, the Start button turns into a Cancel button that allows for
aborting the process at any time.

2.8. Exit Button

Same as Exit in the File menu or <ALT><F4>.
The Exit button terminates KKS2Tag.

User’s Manual Page 5

KKS2Tag User's Manual

3. Menü
3.1. File
Start: See chapter „Start Button“, above.
Exit: See chapter “Exit Button“, above.

3.2. Options

3.2.1. mode = ...

This option evokes the Mode Options dialog.

The :mode= line will be inserted at the beginning of the resulting CSV file according
to the selected option. It defaults to :mode=replace. For more information about
the :mode= line, refer to the InTouch User’s Guide.
Hint: Select test to check that DBLoad processes your templates correctly. Once,
DBLoad runs successfully, select replace.
Select Don’t generate :mode= line, if no :mode= line should be inserted at
the beginning of the CSV file. This might be useful when KKS2Tag is used for other
targets than InTouch.

3.2.2. Placeholder Markers...

This option evokes the dialog to specify the prefix and suffix strings for placeholders.
Change only in cases where conflicts with the default values !@ for the prefix and !
for the suffix cannot be handled by other means.

User’s Manual Page 6

KKS2Tag User's Manual

Prefix and suffix must differ. Make it as short as possible. Test your changes
thoroughly.
Click OK to accept the entries. Click Cancel or press ESC to abort the dialog without
change.

3.2.3. List Separator ...

Available since version 0.9.4
This option is useful to freely define the list separator character.

If the Output file is supposed to be processed by DBLoad, the character entered in

List separator string must match the list separator character defined in the
computer that runs DBLoad. See Control Panel/Regional Settings/Tab Numbers/List
separator to view the setting.
If the Output file is supposed to be processed by DBLoad, any character string up to
4 characters may be defined in List separator string.
Click OK to accept the entries. Click Cancel or press ESC to abort the dialog without
change.

3.2.4. Close on finish

Set this option to close KKS2Tag automatically after successfully creating the CSV
file.

3.2.5. Launch DBLoad.exe

If this option is set, KKS2Tag automatically starts the DBLoad utility upon closing or,
with the Close on finish option set, after successfully creating the CSV file.

3.2.6. Enable Warnings

Available since version 0.9.3
If this option is set, the Output file is examined to ensure the syntactical correctness
for further processing by DBLoad. Several warnings inform about possible problems.

User’s Manual Page 7

KKS2Tag User's Manual

4. Composition of The Tables

4.1. Source-Table
The Source Table lists all objects, for which tagname variables are to be generated.

Lines preceded with the # character (lines 3 and 7, above) are comments and are
ignored. Comment lines as well as empty lines may appear at any place in any table.
The first non-comment line is the header line. It must contain the column header
TEMPLATE in the leftmost cell in column 1. The rest of the line declares the identifiers
of the placeholders (NAME, DB, COMMENT, LOG) that can be used by the template
tables.
The non-comment lines following the header line are called object lines. Each object
line declares one object. The first cell in column 1 of the object line defines the
template name for the object (Motor, Sensor). The cells to the right (M101, 100,
Mischer Tank 1 in line 4, above) specify the values that should be used by
KKS2Tag to replace the placeholders (NAME, DB, COMMENT and LOG) in the template
table. If a cell in the line is not used by the template, its content is ignored, as in cell
E4 and E5, above.
Each line defines exactly one object (Motor M101, Sensor LAH210, and so forth),
therefore, the terms "lines" and "objects" are synonyms. All object lines form the
object list.
The example above also demonstrates, that the cells may be formatted by fonts and
colors to improve readability. Formatting doesn’t affect KKS2Tag operation. Even
complex formulas are permitted, only the resulting expression of a cell is used.

4.2. Template Table

For each object used in the Source Table, the content of the entire template table
except comment lines is transferred to the Output file.
Template tables essentially consist of two kind of information: (1) Static text, that is
forwarded unchanged to the Output file and (2) placeholders, that are textually
replaced by the expression defined in the appropriate cell in the object line of the
source table. Placeholders may represent parts of a cell to be arbitrarily combined
with static text or form the whole cell.
Even more than one placeholder may be found in one cell. Placeholders are
identified by the prefix !@ and the suffix !, by default.

User’s Manual Page 8

KKS2Tag User's Manual

The Motor template table could look like this:

Each tagname variable to be generated is composed in one line (line 3 to 6 and line
8, above). Each variable type must be preceded by a type definition line starting with
a colon (:) (line 2 and 7, above). The items in the line must appear in the same order
and the same decoration as output by the DBDump utility. Textual items should be
surrounded by double quotation marks (") in order for DBLoad to work correctly.
The Sensor template table could look like this:

When designing a template table, it is recommended to import a tagname variable

including its type definition line (:IOReal ..., :MemoryInt ... etc.) from a CSV file
created using the DBDump utility rather than starting from scratch. You then modify
the variable to meet your needs.
Again, the cells may be formatted freely to improve readability.

4.3. Globals Table

The Globals table is optional and can be used to provide common replacement
values for those placeholders, that are not limited to a specific template.
Besides lines starting with #, a Globals table is composed of two lines: The first
active line defines the identifiers of the placeholders, comparable to the header line in
the Source Table (see chapter 4.1). The second line supplies the replacement
values. Comment lines and blank lines may be inserted as desired.
The following two examples show the benefits of Globals tables.

4.3.1. Example 1: Debugging by Alarm Logger Messages

If, for testing and debugging, certain events should be logged in the Alarm Logger,
enter, lets say, !@DEBUG! into the EventLogged cell in the template table of the
tagname variable in question.

User’s Manual Page 9

KKS2Tag User's Manual

Globals for testing Globals for final release

Logging then can be turned on and off by selecting the respective table and running
KKS2Tag without using the WindowMaker and modifying individual tags. This
method may be arbitrarily refined to selectively generate Logger Messages by adding
placeholders for different objects, i.e. !@DEBUGMotor! and !@DEBUGSensor!.

4.3.2. Example 2: Changing the I/O Server

Scenario: Your customer is running a hard PLC and S7.exe as I/O server. However,
your company cannot afford buying new hardware and a new I/O server license for
every new customer. Therefore, you are obliged to develop applications using a soft
PLC and OPCLink.exe, the standard I/O server of your company. Unfortunately,
these I/O servers use a different syntax for addressing items.
This situation is easily mastered by using different Globals tables, for instance S7
and OPCLink.

Observe, that the Accesnames (column N) can easily be adapted by

ACCESSNAMEAPPL as well.

User’s Manual Page 10

KKS2Tag User's Manual

The following table outlines, how the ItemName entries in a Template table should be
formed and how they are expanded by KKS2Tag, if the replacement text (in the
object list) provides 100 for the DB placeholder:
Data type ItemName in Template Table Itemname generated by KKS2Tag
S7 OPCLink
IODisc „!@XDB!!@DB!!@XDAT!6.0“ DB100,X100.6 DDB100.DBX100.6
IOInt „!@WDB!!@DB!!@WDAT!6“ DB100,W6 IDB100.DBW6
IOReal „!@RDB!!@DB!!@RDAT!10!@RSUFF!“ DB100,REAL10 RDB100.DBD10:REAL

4.4. Offset-Type Placeholder

Chapter “Composition of Template Table” states, that KKS2Tag substitutes
placeholders by the replacement value through a simple text copying process. There
is one exception to this rule, the offset-type placeholders. The syntax for offset-type
placeholders is !@PLACEHOLDER+n!, where PLACEHOLDER must expand to and n
must be an integer value. The resulting replacement value is the sum of both.

4.5. Output CSV File

Using the object, motor, and sensor tables presented in the chapters above,
KKS2Tag generates the following CSV-formatted Output file, ready for loading into
the InTouch tagname dictionary by DBLoad.exe:

All placeholders are substituted: !@NAME!Betrieb is expanded to M101Betrieb,

!@COMMENT! Betriebssignal to Mischer Tank 1 Betriebssignal,
DB!@DB!,X6.0 to DB100,X6.0, and so forth. All static text components of the
templates are forwarded to the Output file as found in the template file.
4.6. DBLoad
Some hints about the DBLoad utility:
• DBLoad uses the List Separator Character configured in the Numbers tab of the
Regional Settings on the Control Panel in Windows.

User’s Manual Page 11

KKS2Tag User's Manual

• DBLoad will not work, if a field, for instance the Comment field, contains the list
separator character (usually ; or ,) as defined in the Regional Settings of
the operating system. This would cause all subsequent entries in the .CSV file to
be shifted one position to the right.
• By default, DBLoad will use the CSV file who’s name is found in Win.ini, section
[Database Load], key CsvFile.

User’s Manual Page 12

KKS2Tag User's Manual

5. Installation of KKS2Tag
5.1. OS Requirements
KKS2Tag runs under Windows 95, Windows 98, Windows NT4.0 SP 6a, Windows
2000 SP 2 or above, or Windows XP. Windows ME is supposed to work, but not
tested.
5.2. Settings
All settings are memorized in a text file named KKS2Tag.ini, residing in the same
folder as the program file KKS2Tag.exe. KKS2Tag.ini may be copied to other
computers in order to clone the settings. However, all folder names found in
KKS2Tag.ini must match the folder structure of the target machine. If needed,
KKS2Tag.ini can be adapted using the Windows Notepad, for instance, as editor.
KKS2Tag leaves InTouch settings, InTouch files, or application files untouched. The
program makes no attempt to access the Windows registry.
Note: Observe license regulations when running a copy of KKS2Tag on a second
computer.

5.3. Installation
To install KKS2Tag, unpack the distribution archive into any temporary folder, i.e.
\Temp. To start the installation process, run Setup.exe. You will be guided through
the short installation process. Upon successful installation, the files in the temporary
folder are no longer required and may be deleted.

5.4. Removal and Update

KKS2Tag may be uninstalled by the normal uninstall routine of the operating system
(Control Panel/Add/Remove). The program folder and the file KKS2Tag.ini will
not be deleted by the uninstall process.
To install a later version of KKS2Tag, first uninstall the program. Then, install the new
program into the same folder.

User’s Manual Page 13

KKS2Tag User's Manual

6. Legal Issues
6.1. Disclaimer
KKS2Tag ("the software") is supplied “as is” without warranty of any kind. In no event
shall the author or its suppliers be liable for any special, incidental, indirect, or
consequential damages whatsoever. The user is solely responsible for adequate
protection and backup of the data and equipment used in connection with the
software, and the author will not be liable for any damages that the user may suffer in
connection with using the software.
The author does not warrant that the software will meet user's requirements, that the
software will operate in combinations other than as specified in the documentation,
that the operation of the software will be uninterrupted or error-free or that software
errors will be corrected.
The author reserves the right to make changes to the software at any time without
notice.
Suggestions and bug reports are welcome and should be sent to info@kks2tag.de.

6.2. License Agreement

By purchasing a license of the software, the author grants the user the right to use
one copy of the software solely for user's business operations on a single terminal
connected to a single computer. The software is licensed to user, not sold. The user
may not network the software or otherwise use it on more than one computer or
computer terminal at a time. The user must treat the software like any other
copyrighted material (e.g., a book) except that the user may make a copy of the
software solely for the user's own backup or archival purposes. Any reproduction or
redistribution of the software is expressly prohibited by law and may result in severe
civil and criminal penalties. Violators will be prosecuted to the maximum extent
possible. The user may transfer his or her rights under this License Agreement on a
permanent basis.

6.3. Copyrights
The names of products, brands or companies mentioned in the software or in this
document may be trademarks of their respective owners, even if not indicated as
such. All trademarks and copyrights are recognized.

User’s Manual Page 14