Version 5.

Compiling and Running a System

Citect Pty Ltd

3 Fitzsimmons Lane
Gordon NSW 2072
Australia
www.citect.com
DISCLAIMER

Citect Pty. Limited makes no representations or warranties with respect to this manual and, to the
maximum extent permitted by law, expressly limits its liability for breach of any warranty that may be
implied to the replacement of this manual with another. Further, Citect Pty. Limited reserves the
right to revise this publication at any time without incurring an obligation to notify any person of the
revision.

COPYRIGHT

© Copyright 2003 Citect Pty Limited. All rights reserved.

TRADEMARKS

Citect Pty Limited has made every effort to supply trademark information about company names,
products and services mentioned in this manual. Trademarks shown below were derived from
various sources.

CitectSCADA, CitectHMI/SCADA, CitectFacilities and CitectSCADA Batch are regisitered

trademarks of Citect Pty. Limited.

IBM, IBM PC and IBM PC AT are registered trademerks of Internatrional Business Machine
Corporation.

MS-DOS, Windows, Windows 98, Windows 2000, Windows XP and Excel are trademarks of
Microsoft Corporation.

dBase is a trademark of Borland Inc.

General Notice:

Some product names used in this manual are used for identification purposes only and may be
trademarks of their respective companies.

October 2003 Edition for CitectSCADA Version 5.5

Manual Revision 1.0

Compiling and Running a System 2

Compiling the Project

The CitectHMI/SCADA compiler compiles (or builds) the elements of your project into a runtime
system.

Configuration
Cicode Databases Graphics

Compiler

Runtime

The compilation process checks the project for errors and optimises your system for fast and
efficient operation. The time required to compile a project depends on its size and on the speed of
your computer. Typically, compiling only takes several minutes.

NOTE: When the CitectHMI/SCADA compiler runs, it normally opens all files in exclusive
mode. In this mode only CitectHMI/SCADA has access to the files (while the compiler
is running). This improves the performance of the compiler, but can cause a problem if
two people try to compile different projects at the same time, as both compilations must
open the Include project.
The [General] ShareFiles Parameter tells the compiler to open all files in shared mode.
This option allows shared network users to run the compiler at the same time, but it can
increase the time required for the compilation.

To compile a project:
1. Select the Project Editor.

2. Click on the Compile button.

- or -
2. From the File menu select Compile

NOTE: If there are any compile errors, you must first fix the errors, and then re-compile.
CitectHMI/SCADA will automatically compile the project (if it is uncompiled) when you
try to run it.

Incremental Compilation

You can compile the project incrementally. With incremental compilation, CitectHMI/SCADA only
compiles the database records that were added (or changed) since the last compilation. The
remainder of the project is not re-compiled.

Compiling and Running a System 3

 NOTES: 1) Some database records are dependent on other database records. If you change a
dependent record, CitectHMI/SCADA compiles the entire database.
2) Before you run a system on a live plant, you should perform a complete compilation
(switch off Incremental Compile). When you restore a project from floppy disk, you
must perform a complete compilation the first time (switch off Incremental Compile).

To switch to Incremental Compile:

1. Select the Project Editor.

2. From the Tools menu, select Options

3. Check the Incremental Compile box
4. Click on the OK button to save the option, or Cancel.

Debugging the Compilation

If the compiler detects any errors during compilation, the errors are written to an error file. The
compiler will notify you of any errors as it compiles, and you can opt to cancel the compilation at any
stage. If there are multiple or severe errors, the compiler may automatically cancel. Once the
compiler is finished, you can locate each compile error and display information on it.

The compiler does not verify the operation of your project. Just because your project compiles does
not mean it will work correctly at runtime. For example, the compiler checks that the tags you use
are defined correctly, and that your Cicode has acceptable syntax. But, it does not check your tags
for incorrect scaling, or that your Cicode has no potential divide by zero errors.

NOTE: You should not attempt to run your system until you have resolved all (if any) of the
compile errors.

To view compilation errors:

1. Select the Project Editor.

2. Click on the Goto Next Compile

Error button.
- or -
2. From the File menu select Compile Errors.

To get further information on an error:

1. Click on the Help button (at the bottom of the Compile Errors form).
2. Read through the help topic associated with the error.

To locate the error (in the project):

1. Click on the Go To button (at the bottom of the Compile Errors form).

Compiling and Running a System 4

Running the System

After you have completed and compiled your project you can start your runtime system. However,
make sure you run the Computer Setup Wizard before attempting to run your system.

NOTE: Remember, the CitectHMI/SCADA software is protected against piracy. If you try to
run your CitectHMI/SCADA without a protection key, CitectHMI/SCADA will display an
error message, and you will have to run in Demo Mode.

Startup and Runtime Configuration

You can specify a Cicode function to execute automatically when CitectHMI/SCADA starts up. This
Cicode gets executed as soon as the Cicode system comes online. You should use the Computer
Setup Wizard to specify the name of the startup function.

You can also run a report on startup. CitectHMI/SCADA searches for a default report called
"Startup" when it starts up. If you have configured a report called "Startup", it is run automatically.
You can change the name of the startup report (or disable it altogether) by using the Computer
Setup Wizard.

You can customise many elements of CitectHMI/SCADA's runtime and startup behaviour. The
Computer Setup Wizard is usually all that is required, but you can also use Parameters for more
control.

To start your runtime system:

1. Click on the Run button.

- or -
1. From the File menu select Run

NOTE: CitectHMI/SCADA will automatically compile the project (if it is uncompiled) when you
try to run it.

To compile and run CitectHMI/SCADA online:

1. Click on the Run button.

- or -
1. From the File menu select Run

NOTE: CitectHMI/SCADA will automatically compile the project (if it is uncompiled) when you
try to run it.

Compiling and Running a System 5

Running Your System Over the Internet
The CitectHMI/SCADA Internet Display Client
If you have a computer with Internet access, you can use it to run your project over the Internet from
a remote location. Your computer would then be called an Internet Display Client. This is basically
a runtime-only version of CitectHMI/SCADA; you can run your project from that computer, just as
you would from any normal Display Client. However, an Internet Display Client cannot be a server,
and it cannot be used to make configuration changes - you can only run your project.

A computer can have a normal CitectHMI/SCADA installation as well as the Internet Display Client.
Before you can run a project over the Internet, you must switch the [Internet]Client parameter on.

It is also possible to run multiple instances of the Internet Display Client at the same time. This
allows you to work with more than one project, in runtime-only mode, on the remote computer.

NOTE: If you are using a firewall, you must ensure that ports 2073 to 2079 are unblocked so
that the Internet Display Client and the Internet Server can communicate.

The CitectHMI/SCADA Internet Server

Any I/O Server can be a CitectHMI/SCADA Internet Server - you just need to use the Computer
Setup Wizard. (A special protection key is required for the Internet Server. Please contact Citect
Support for protection key details.)
NOTE: If you are using a firewall, you must ensure that ports 2073 to 2079 are unblocked so
that the Internet Display Client and the Internet Server can communicate.

Startup and Runtime Configuration

You can customise many elements of CitectHMI/SCADA's runtime and startup behaviour via the
Computer Setup Wizard.

You can also configure an IDC installation to automatically connect to a CitectHMI/SCADA Internet
Server at startup. To do this, you need to adjust the parameters [Internet]IPAddress,
[Internet]Password and [Internet]ShowSetupDlg within the Citect.INI file of the IDC computer.

NOTE: The Citect.INI file is stored in BIN directory of the Internet Display Client installation.

Server - Client File Updates

When you logon to the CitectHMI/SCADA Internet Server, all the files needed to run the project are
downloaded to your computer. Because it is necessary to keep these files up to date,
CitectHMI/SCADA periodically compares the files on the Internet Server with the downloaded files
on the Internet Display Client. (This period is defined using the [Internet]UpdateTime parameter.) If
a file has been changed since the last update, it will be copied to the Internet Display Client.

To set up your CitectHMI/SCADA Internet Server:

1. Run the Computer Setup Wizard and select Custom Setup
2. Select Server and Display Client from Network Computer Section
3. Once you reach the Internet Server screen, select Internet Server.

Compiling and Running a System 6

4. Enter the TCP/IP address of your Internet Server computer (e.g. 10.5.6.7 or
plant.yourdomain.com). This information is downloaded and stored in the Internet Display
Client's citect.ini file when a connection is made.
To determine the TCP/IP address of the Internet Server computer:
For Windows NT4 or 2000, go to the Command Prompt, type IPCONFIG, and press the
[Enter] key.
For Windows 95 or 98, select Start | Run, type WINIPCFG, and press the [Enter] key.
5. Once you have completed the Computer Setup Wizard, define the passwords required by users
of your Internet Display Clients using the [Internet]Manager and/or [Internet]Display parameters.
6. If the Runtime project on the Internet Server has links to any included projects, the Internet
Display Client can only access the included project files if they are stored on the same directory
level as the Runtime project. For example, if the current project is located at:
C:\Citect\User\<current project>
then any Included projects must be located on the same level:
C:\Citect\User\<included project>
7. Any files you would like to make accessible to an anonymous FTP user should be placed in the
Internet Server's \Internet directory, located at C:\Citect\User\Internet by default. This is where
CitectHMI/SCADA stores the IDC.EXE file to allow remote installation of the Internet Display
Client.

NOTE: The Internet directory on the Internet Server will only be accessible to anonymous FTP
users if it shares the same directory level as the current Runtime project. For example,
if you use CitectHMI/SCADA's default settings, the current project folder will be located
at:
C:\Citect\User\<current project>
and the Internet directory will be located on the same level at:
C:\Citect\User\Internet
If the Runtime project on the Internet Server is stored elsewhere, an appropriately
located Internet directory will have to be created.

To install the Internet Display Client:

1. On the remote computer, run up your Internet browser.
2. Type in the FTP address of your CitectHMI/SCADA Internet Server (for example,
ftp://sanctus.citect.com.au/idc.exe).
3. Save the file (IDC.exe) to a temporary folder.
4. Go to this temporary folder and double click on IDC.exe.
5. Follow the prompts to complete the installation.

To run your project over the Internet:

1. Ensure you have installed the Internet Display Client and set up your Internet Server.
2. At the Internet Display Client,
double click on the Citect Runtime
icon in the CitectHMI/SCADA IDC
program group.
3. In the Citect Internet Client Setup dialog, type the TCP/IP address of your CitectHMI/SCADA
Internet Server (e.g. 10.5.6.7 or plant.yourdomain.com), then type your password.
4. Press OK. All the relevant data will be downloaded to your computer and your project will run (if
the Citect Internet Server is running).

Compiling and Running a System 7

 To connect to a different CitectHMI/SCADA Internet Server once your project is running on the
Internet Display Client:
1. Select Client Setup from the runtime Control menu.
2. In the Citect Internet Client Setup dialog, type the TCP/IP address of your CitectHMI/SCADA
Internet Server (e.g. 10.5.6.7 or plant.yourdomain.com), then type your password.
3. Press OK. All the relevant data will be downloaded to your computer and your project will run.

Citect Internet Client Setup Properties

You must complete the following properties in order to set up your Internet Display Client:

Address
Enter the TCP/IP address of the CitectHMI/SCADA Internet Server (e.g. 10.5.6.7 or
plant.yourdomain.com). The address of the last Internet Server used will be automatically
entered here. The addresses of all Internet Servers previously used are retained in the drop
down box (with the most recently used at the top).

Password
Enter the password supplied to you by the CitectHMI/SCADA Internet Server administrator.
Your password will be encrypted before it is sent across the Internet.
If you enter an incorrect password, the connection attempt will fail.

Compiling and Running a System 8

Providing Runtime Security

The CitectHMI/SCADA runtime system is a Windows-based application that runs in the standard
Windows 95 or NT environment. The Windows environment allows you to run several applications
at the same time. There are a number of different ways in which anyone accessing the PC can be
prevented from accessing software other than CitectHMI/SCADA.

Running CitectHMI/SCADA as a Service Under NT

To prevent anyone from accessing CitectHMI/SCADA or the operating system while

CitectHMI/SCADA is running, it can be run as a service. Once it is configured this way,
CitectHMI/SCADA will start when NT starts and it is not necessary for any users to log on. This is
appropriate for situations where CitectHMI/SCADA is acting as server and does not require the
display of screens or any input from the operator. You should consult the Citect Knowledge Base
for the latest information on running CitectHMI/SCADA as a service.

Running CitectHMI/SCADA as the Shell Under NT

To prevent users from switching from CitectHMI/SCADA back to the Program Manager or Explorer
in Windows NT you can run CitectHMI/SCADA as the Shell. Normally Windows NT runs either the
Program Manager or Explorer as the Shell (depending on your version of NT). You can change this
so that another program is run as the Shell when NT starts. To do this you must use the
Regedt32.exe to edit the registry. You should consult the Citect Knowledge Base for the latest
information on running CitectHMI/SCADA as a shell.

Disabling Windows Keyboard Commands

The Windows 95 and NT environment provides commands to switch between applications running
on the computer at the same time. When using CitectHMI/SCADA, these commands might not be
desirable - they allow an operator access to other Windows facilities without your direct control.
You may be able to disable some of these commands with the Computer Setup Wizard. You should
consult the Citect Knowledge Base for the latest information on disabling Windows keyboard
commands.

Disabling Control Menu Commands

The Control Menu (in the top left corner of an application window) provides commands to position
and size the application window, and in some applications to control the application. The runtime
system’s Control Menu can be tailored to give access to several commands specific to
CitectHMI/SCADA, such as Shutdown (to shut down the runtime system), or Kernel (to display the
Kernel).

You can enable and disable these commands with the Computer Setup Wizard.

Removing the Cancel button from the Startup Message Box

When the CitectHMI/SCADA runtime system starts, a message box displays the status of the
system startup. This message box normally contains a Cancel button that allows you to cancel the
startup. This button is most useful when you are debugging or testing the system. When you have
completed testing, you can remove the Cancel button from the message box with the Computer
Setup Wizard, to prevent an accidental cancellation of system startup.

Compiling and Running a System 9

Using an Alternative INI file

When CitectHMI/SCADA starts up, it reads default values from the Citect.ini. (By default,
CitectHMI/SCADA looks for the ini file in the Citect\Bin directory. If it can't find it there, it will search
the WINDOWS directory.) If you are running multiple projects, you can specify an alternative INI file
for each project. The new INI file name must be passed to the CitectHMI/SCADA system
applications, i.e. to CtExlplor.exe and Citect32.exe, as a command line argument.

To specify an alternative INI file for CitectHMI/SCADA :

1. Click on the Icon that you use to start the Citect Explorer or Runtime.
2. Right click to bring up the shortcut menu, and select Properties.
3. Click on the Shortcut tab.
4. Add the name of the INI file to the command line property of the appropriate icon using the /i
option. For example, to start CitectHMI/SCADA using the initialisation file MY.INI, enter the
following line:
c:\citect\bin\citect.exe /ic:\citect\user\myproj\MY.INI

NOTES: 1) The Computer Setup Wizard will use the same INI as specified for the Citect
Explorer.
2) You can specify different INIs for both the Runtime and Explorer programs.
However, if you initiate Runtime from the Explorer, it will use the INI specified for the
Explorer.

Compiling and Running a System 10

Debugging the Runtime System

To err is human, and it is very likely that any large project will have 'bugs' in the runtime system.
However, most problems have simple solutions and require only perseverance to solve them.
Hardware Alarms

When a system error occurs - that is a malfunction in Citect operation - Citect generates a hardware
alarm. Hardware alarms are usually displayed on a dedicated Hardware Alarm page, which is
available as a standard template.

The hardware alarm page is your primary indicator of what is happening in your CitectHMI/SCADA
system. If a communication fault occurs, if Cicode can't execute, if a graphics page is not updating
correctly, or if a server fails, this page will alert you to it. Hardware alarms consist of a unique
description and error code.

The hardware alarms do not have detailed information, but serve to point you in the right direction.
For example, if you have a Conflicting Animation alarm, CitectHMI/SCADA will not tell you the
cause. You must observe which page causes the hardware alarm, and locate the animations
yourself.

NOTE: Your system should have no recurring hardware alarms.

There are two hardware alarm fields that are not always shown on the hardware alarms pages.
ERRPAGE will display the name of the page that was displayed when the error occurred. This is
very useful for finding animation faults. ERRDESC provides extra information, which is specific to
the type of the alarm. For example, if the alarm is an I/O Device error, ERRDESC will display the
name of the device.

The SysLog.DAT File

The SysLog.DAT is a file maintained by CitectHMI/SCADA, that contains a useful log of

CitectHMI/SCADA System information. The variety of information that can be logged to the
SysLog.DAT is extensive; from low level driver traffic and Kernel messages, to user defined
messages.

The Log Read and Log Write fields in the I/O Devices Properties control whether logs are made for
each I/O Device.

NOTE: CitectHMI/SCADA locks the SysLog while running. However, you can still view it by
using the SysLog command in the Kernel.

This file is restricted in size (to 300k by default). When it reaches the size limit, CitectHMI/SCADA
renames it SysLog.BAK, and starts a new SysLog.DAT. You can make this restriction larger or
smaller by using the [Debug]SysLogSize parameter. For example, the following lines in the
Citect.INI will set the SysLog.DAT size to 1000k:

[DEBUG]
SysLogSize=1000

Compiling and Running a System 11

Debugging I/O Devices and Protocols

Before commissioning any system, you must test all communications between CitectHMI/SCADA
and the I/O Devices. Many people leave this to the last possible moment, only to find that there is
some problem with communications which they are unable to solve themselves.

The following information is intended to encourage you to test your communications thoroughly
before it becomes a time critical element in the job. It will also help you to debug communications
and protocol problems yourself.
Creating a Communications Test Project

The first step in any testing of Communications is to make sure that CitectHMI/SCADA can bring
your I/O Devices online. To do this create a test project. The Test Project needs to be as simple as
possible.

For example, if your system will eventually be communicating through a COM port, a KTX card, an
SA85 card, and via TCP/IP do not try and make all this work on your first try. Make the Test Project
with 1 element at a time. First add and test the COM port. When that works, make a new test
project for the KTX card, then make a new test project for the SA85 card, and finally one for the
TCP/IP. Once you are sure that each individual element works properly, start to add them together.

When creating a test project:

1. Use the Communications Express Wizard to setup your communications.
2. In the Project Editor go through the forms under the Communications menu.
3. Check that you have one I/O Server defined.
4. Check that you have one Board defined. Verify that the information for the Board is correct.
5. Check that you have one Port defined. Verify that the information for the Port is correct.
6. Check that you have one I/O Device defined.

NOTE: Do not add any variable tags. Do not make any graphics pages. Do not add anything
else.

While checking that you have only the absolute minimum information in the project to enable
communications, make sure that there are no duplicated records. The most reliable way to do this
is to open a form and then check the Record Number shown on the bottom left of the form. Make
sure it is on Record 1, and then click on the button in the scroll bar on the right hand side of the form
and drag it down. When you get to the bottom of the scroll bar, let the button go. If it pops back up
to the top of the form and the record numbers stays at 1 then you have only 1 record.

It is necessary to drag the scroll bar as all the forms are indexed on the I/O Server name. Quite
often there will be 'orphaned' records from a previous I/O Server name still in the database files. If
you find any extra records, delete them and then pack the project. The majority of all
communications problems come from having duplicated or orphaned records in the communications
database.

Once you have your communications setup as you think they should be, you are ready for a
communications test.

Before Running Your Test Project

There are a couple of things to make sure you do.

1. You need to have the Kernel enabled on CitectHMI/SCADA startup so that you can see what is
happening with your communications. To do this, edit your Citect.INI file so that it has the
following information.

Compiling and Running a System 12

 [DEBUG]
Kernel=1
This will show the CitectHMI/SCADA Kernel on startup of CitectHMI/SCADA. This enables you
to see, step by step, the startup procedures that CitectHMI/SCADA goes through.
2. Run the Computer Setup Wizard and make sure the computer is defined as a stand-alone
CitectHMI/SCADA system, configured to run your test project.

Running Your Test Project

Start the project running and as soon as you see the Kernel appear, double click on the title bar in
the Main window, then double click on the title bar of the Kernel. Doing this in order is important, as
it will maximise the Main window then Maximise the whole Kernel. If you don't do this then you will
not see what is happening as the information in the Kernel cannot be scrolled, and once it is off the
screen it is gone. This may require a bit of practice as the startup procedure may only take 1-2
seconds or less on a fast machine.

Once you have the project running (and assuming that everything worked) the last line in the Main
window in the Kernel should tell you that your I/O Devices are online. Do not confuse this with the
message telling you that your Port channels are online. CitectHMI/SCADA should first report that it
can communicate through the port you have setup, then report that it can communicate with the I/O
Device.

When Your Test Project Does Not Communicate

Check everything and run it again. Depending on the type of board driver you are using there are
different methods for debugging them. However, all of them are basically the same. Add one item
at a time and test.

Debugging a COMx Driver

A COMx driver is the board driver used for most serial communications. Version 2.01 of the COMx
driver provides a method to dump debug information. Three files are produced for each com port: a
write file, a read file and status file. The debug files are configured by settings in the citect.ini and
are written to the default OS path. The following citect.ini entries are used:

[COMx]
WritePortName=X1,X2...
WriteDebugLevel=Y
WriteFileSize=Z
ReadPortName=X1,X2...
ReadDebugLevel=Y
ReadFileSize=Z
StatusPortName=X1,X2...
StatusDebugLevel=Y
StatusFileSize=Z

Where:
Xn = a port name as it appears in the
Citect|Communications|Ports form. For
example, PORT_1
Y= 1 to enable debugging, 0 to disable debugging
Z= the file size in Kb. (The default is 1000 Kb)

Compiling and Running a System 13

Example

[comx]
WritePortName=PORT_1,PORT_2
WriteDebugLevel=1
WriteFileSize=2000
ReadPortName=PORT_1
ReadDebugLevel=1
ReadFileSize=1000
StatusPortName=PORT_2
StatusDebugLevel=1
StatusFileSize=10

The above example would:

Log to "write" files up to 2000Kb of the data sent by the CitectHMI/SCADA driver to both
PORT_1 and PORT_2;
Log to a "read" file 1000Kb of the data received by the CitectHMI/SCADA driver from
PORT_1; and
Log up to 10Kb of status data from PORT_2 to a "status" file.

This would also result in the following text files being created in the OS Path (generally WINDOWS
or WINNT):

WPORT_1.dat
WPORT_2.dat
RPORT_1.dat
SPORT_2.dat

In general, the format for the file names is "R", "W" or "S" followed by the Port name requested,
followed by ".dat". The file names represent the corresponding "Read", "Write" and "Status" files.

File Formats

The Write file will adopt the following format:

LINE 1 WRITE Debug file Started PORTNAME Debug Level 1

DOW MONTH DOM HH:MM:SS.msec
LINE 2 HH:MM:SS:.msec
LINE 3 Out W In X nBytes Y Status Z
LINES 4... AA BB CC ..

Where:
W&X= values of buffer pointers
Y= the number of bytes written
Z= the return status of the WriteFile
AA BB CC = the values in hex of each byte written

Example:

WRITE Debug file Started PORT1_BOARD1 Mon Dec 15 16:07:07.998

16:07:09.810
Out 0 In 8 nBytes 8 iStatus 997
0e 02 00 00 00 10 00 00
16:07:10.802
Out 8 In 16 nBytes 8 iStatus 997
0e 02 00 00 00 10 00 00
.

Compiling and Running a System 14

 .

The Read file will adopt the following format:

LINE 1 READ Debug file Started PORTNAME Debug Level 1

DOW MONTH DOM HH:MM:SS.msec
LINE 2 HH:MM:SS:.msec
LINE 3 Out W InRx X nBytes Y Status Z
LINES 4... AA BB CC ..

Where:
W&X= the values of buffer pointers
Y= the number of bytes read
Z= the number of characters remaining
in the buffer
AA BB CC = the values in hex of each byte written

Example:

READ Debug file Started PORT1_BOARD1 Mon Dec 15 16:07:07.998

16:07:09.830
Out 0 In 0 nBytes 8 iStatus 0
0e 02 00 00 00 10 00 00
16:07:10.822
Out 0 In 8 nBytes 8 iStatus 0
0e 02 00 00 00 10 00 00
.
.

The Status file will adopt the following format:

LINE 1 STATUS Debug file Started PORTNAME Debug Level 1

DOW MONTH DOM HH:MM:SS.msec
LINE 2 HH:MM:SS:.msec
LINE 3 modemStatus X

Example:

STATUS Debug file Started PORT_1 Debug Level 1 Wed Nov 05 15:28:55.310
15:29:55.950
modemStatus 34
.
.

NOTE: There may be more parameters added in the future, so you should always check the
COMx information in the Online Help and the Citect Knowledge Base.

Debugging a TCP/IP driver

A TCP/IP driver is the low level driver that is used for any TCP/IP communications. It may be over
Ethernet, Token Ring or Arcnet. This driver communicates between CitectHMI/SCADA and
Winsock, so it really utilises all the normal networking functionality of Windows. Parameters for

Compiling and Running a System 15

TCPIP:

[TCPIP]
Log=1 Dumps all traffic between the CitectHMI/SCADA TCPIP.DLL and Winsock to a text
file called TCPIP.DAT in your Windows directory. Note that this file does not have
a size limit and could potentially use all available disk space.
Debug=1 Opens a window at runtime and shows communication between
CitectHMI/SCADA and Winsock. It displays exactly the same data that is sent to
the log file, but allows you to see it as it is happening. The number of line
displayed is limited, though.

Debugging steps
1. Check to see if you can PING your target I/O Device. If you can't PING it then
CitectHMI/SCADA cannot talk to it. To do this open up a Command Window and type PING
aaa.bbb.ccc.ddd where a.b.c.d is the IP address of the I/O Device you are trying to connect to. If
PING does not work then you need to go back to your Windows Networking and fix that.
2. Keep using your Simple As Possible Project (SAPP).
3. Delete any old TCPIP.DAT files.
4. Set the Debug=1 and Log=1 parameters in your Citect.INI file.
5. Start the project. From the information in the maximised Main window of the Kernel and the
TCPIP Debug window, you should be able to see if CitectHMI/SCADA is sending requests to
your I/O Device - to initialise communications with it.

If there are no requests being sent, then there is a configuration problem with your software, and
you should check that there were no errors on startup of CitectHMI/SCADA. If there were errors on
startup look them up in the Online Help. Also check that your computer is an I/O Server (and that it
matches the one in your project). To do this run the Computer Setup Wizard, and configure the
computer for a stand-alone configuration.

If there are requests, you will be able to see all communications between CitectHMI/SCADA and
Winsock in a separate window. Here you will see the requests made by CitectHMI/SCADA to
connect to the I/O Device, and the corresponding response from the I/O Device. If you see any
errors, they will have a Winsock Error code that you can look up in the Microsoft Knowledge Base.
Most of these errors are fairly obvious and involve having the wrong IP address or Port number. If
you see a Connection OK message then CitectHMI/SCADA should be able to come online.

Debugging a Protocol Driver using Serial Communications

1. Keep using your Simple As Possible Project (SAPP).
2. Set the DebugStr=* all for your protocol.
3. Backup and delete SYSLOG.DAT and SYSLOG.BAK. This ensures you start with a fresh log
file.
4. Start the project. From the information you can see in the maximised Main window of the kernel
you should be able to see if CitectHMI/SCADA is sending requests to your I/O Device to initialise
communications with it.

If there are no requests being sent then there is a configuration problem with your software, and you
should check that there were no errors on Startup of CitectHMI/SCADA. If there were errors on
startup look them up in the Online Help. Also check that your computer is an I/O Server (and that it
matches the one in your project). To do this run the Computer Setup Wizard, and configure the
computer for a stand-alone configuration.

If there are requests being sent but no reply, then CitectHMI/SCADA is trying to communicate.

Compiling and Running a System 16

When CitectHMI/SCADA is sending requests but getting no reply, these are the most common
causes:
The request CitectHMI/SCADA is sending is not getting to the I/O Device.
Check the Address field in the I/O Devices form, and make sure it is correct. If the I/O Device is
one that needs a unique identifier (such as a node address), or you need some type of routing
path, then make sure it is correct.
Check that you have the same parameters in the Ports form that the I/O Device is using. If you
have 8 data bits and the I/O Device uses 7 data bits, you will never get communications
working.
Check that your cable is OK. The easiest way to do this is to create a new project and use the
Loopback protocol. You can use this to verify the Tx and Rx lines' integrity by placing a jumper
on these lines. Initially test this with a jumper between pins 2 and 3 on your PC. Then plug in
your cable and test again with the jumper between the Tx and Rx lines. Keep moving the
jumper until it is at the end of your communications bus. You can find more information on
using the Loopback protocol in the Citect Knowledge Base.
Even if the Loopback protocol shows no errors, your cable may still be faulty.
CitectHMI/SCADA usually places a far higher constant load on serial communications than
programming software does, this usually means that CitectHMI/SCADA will require much more
stringent handshaking than the programming software. So it is possible that the cable you use
to program your I/O Device works fine for programming, but not for CitectHMI/SCADA. Check
the Wiring Diagram for your Protocol in the help.
Another major cause of cabling problems is 9 pin to 25 pin converters. Many of these
converters are made specifically for serial mice. These typically only use the Tx, Rx and
Ground signals. If you use one of these converters they do not support any handshaking at all
and will most likely not work for your Protocol.
If all of the above checks OK, use the parameters for COMx (as mentioned above) to create
log files. Examine these log files and make sure that what CitectHMI/SCADA thinks it is
sending is actually what it is sending. The log files produced by using these parameters get
their information from a lower level than CitectHMI/SCADA and show you exactly what is going
through the COMx driver.
The Response from the I/O Device is not getting to CitectHMI/SCADA.
This is very unlikely and is usually caused by a cabling problem. Check your cabling as above.
Also, check that you are specifying everything you need within CitectHMI/SCADA. Many
protocols require CitectHMI/SCADA to send a unique identifier in its request packet. If this
identifier is incorrect then the response can never get back to CitectHMI/SCADA.
The I/O Device does not understand the Request.
All CitectHMI/SCADA protocols have a method of checking to see if an I/O Device is running.
Typically the protocol will attempt to read something from the I/O Device - usually a status
register or other register that should always be there. However, there are many pseudo
standard protocols, such as Modbus, that do not conform to the exact specification for that
protocol. Many of the protocols supplied with CitectHMI/SCADA will have some extra
parameters that will allow you to choose the specific initialisation request from
CitectHMI/SCADA. These can be found in either the Online Help or the CitectHMI/SCADA
Knowledge Base. Check with the manufacturer of your I/O Device to make sure it will respond
to the request that CitectHMI/SCADA is sending. If you are unsure of the request that
CitectHMI/SCADA is sending for its initialisation, you can use the DebugStr=* to get the actual
variable address that CitectHMI/SCADA is asking for in its initialisation.
Check the protocol you are using. CitectHMI/SCADA may have many different protocols for
communicating to an I/O Device. PLCs such as the AB PLC5 can use different serial
protocols, depending on the method you are trying to use. Make sure you are using the correct
one. If you are unsure, try the other possible protocols.
The I/O Device is not functioning properly.
To check this, there is usually some sort of software from the I/O Device manufacturer that can
be used to diagnose any problems with the I/O Device.

Debugging Proprietary Board Drivers

Compiling and Running a System 17

These are drivers such as the Allen Bradley KTX card, Modicon SA85 card, Siemens TIWAY card
etc, which have their own low level driver. Each of these drivers will have some debugging
parameters that will make it easier for you to debug problems. Check the Citect Knowledge Base
and the Online Help for any possible parameters. The CitectHMI/SCADA Knowledge Base will
likely have articles describing the methods for debugging each of these Board drivers.

Essentially the debugging process is exactly the same as with Serial:

1. Keep using your Simple As Possible Project (SAPP).
2. Set any debugging parameters for the protocol and Board drivers.
3. Start CitectHMI/SCADA with clean log files.
4. Find any errors and then look then up in the manufacturers documentation.

Contacting Citect Support

If you are unable to debug the problems on your own then please contact your local Citect support
centre. Make sure you have the following Information:
Blank Citect Solution Request (CSR), which you can obtain through Citect Support.
SysLog.DAT, SysLog.BAK, TCPIP.DAT, or COMx log files.
A copy of the SAPP, and the Citect.INI file.

Compiling and Running a System 18

Restarting the System Online

With the online restart facility, you can change the configuration of the project and examine the
results in the CitectHMI/SCADA runtime system - with a single button, and without having to
shutdown CitectHMI/SCADA. You can update your system while CitectHMI/SCADA is already
running.

NOTE: The time taken for the system changeover depends on the size of the project and the
extent of the changes to the project:
If you only change graphics pages, CitectHMI/SCADA does a partial restart
(changing only the pages in the runtime system). The changeover is instantaneous.
If you change any of the databases (e.g. you add a new Alarm Tag, Trend Tag, or
Cicode function), CitectHMI/SCADA does a full restart to run the updated project.
WARNING: Do not use this feature if you are making major changes to the project.

Restarting a Networked System Online

If you are using CitectHMI/SCADA on a network, you can use a structured restart procedure that
ensures control of the plant is maintained and no data is lost during changeover. You can use any
CitectHMI/SCADA computer on the network to initiate the online restart.

CitectHMI/SCADA automatically manages the online restart in the following sequence:

1. The originator
Originator issues the
Shutdown("Everybody")
command

6. The first Alarms Server restarts 2. The Alarms Server

its first phase clients and shuts that the originator is
down and restarts its second connected to shuts down
phase clients its first phase clients
First Phase
Second Phase
Clients
Clients

3. The Alarms Server

Alarms that the originator is
Server connected to advises the
other Alarms Server then
5. When the first Alarms Server shuts itself down
is back on line, the second
Alarms Server shuts down its
second phase clients and then
shuts itself down
First Phase
Second Phase Clients
Clients

Redundant
Alarms
4. The second Alarms Server
Server shuts down its first phase
clients and waits for the
other Alarms Server to restart
(running the new project)

Using Multiple Projects

Compiling and Running a System 19

The most effective method of using the online restart facility is to use two projects. The first project
becomes the current runtime system while the second project is in the development stage. You can
manage both projects as follows:

ProjectA ProjectB

1. Project A is currently the

runtime system while Project B
is under development

ProjectA ProjectB

2. When Project B is complete,

you can use the online restart
facility to change the runtime system
to Project B.

ProjectA ProjectB

3. You can then copy Project B to

Project A for further development

Initiating the Online Restart

To initiate the online restart, the originator (any CitectHMI/SCADA computer on the network) issues
a shutdown command with the Shutdown function, for example:

Shutdown("Everybody", "MyProject", 2);

Where possible, balance all Display Clients across both phases of the shutdown. The
[Shutdown]Phase parameter defines the phase to which each CitectHMI/SCADA computer
responds.

You can exclude selected computers (e.g. I/O Servers) from the online restart procedure with the
[Shutdown]NetworkIgnore parameter.

For security, you can prevent selected computers from initiating the online restart procedure with
the [Shutdown]NetworkStart parameter.

Using a Callback Function

You can use a callback function (with the OnEvent function) to perform any housekeeping tasks
before the system shuts down. You would normally call OnEvent() in the main startup function
(defined with the [Code]Startup parameter). Each time a Shutdown() call is made, the callback
function is run.

/* A user shutdown procedure. */

INT
FUNCTION
MyStartupFunction()
...
...

Compiling and Running a System 20

 OnEvent(25, MyShutdown);

...
...
END

INT
FUNCTION
MyShutdown()
STRING sPath;

// Perform housekeeping tasks

...
...
...

sPath = ProjectCurrentGet();
If sPath = "ProjectA" Then
ProjectSet("ProjectB");
Else
ProjectSet("ProjectA");
END

Shutdown("Everybody", sPath, 2);

END

Compiling and Running a System 21

Citect Software Protection

CitectHMI/SCADA uses a Hardware Key to safeguard against licence infringement. The Hardware
Key is a physical key that plugs into the parallel port of your computer. The Hardware Key contains
details of your user licence, such as type and I/O point limit.

Updating your Hardware Key

When you upgrade to a new version of CitectHMI/SCADA, you may need to update your Hardware
Key to enable the system to run. See the CitectHMI/SCADA Readme file to confirm whether you
need to perform an update.

The Hardware Key plugs into a parallel printer port on your computer and contains information
about your user licence including the point limit.

Updating the Hardware Key involves running the CitectHMI/SCADA Key Update, which is found in
the Help menu of Citect Explorer.

NOTE: If you have Citect v5.21 or 5.20, you will need to run CiUSAFE.exe from the Citect BIN
directory. You can also download the latest version of the upgrade program from the
Key Upgrade section of the Citect website.

Each time you launch the CitectHMI/SCADA Key Update, the program displays a Key ID. The serial
number of the Hardware Key will also be displayed if it has been written to the key. If not, read the
number from the printed label on the Hardware Key. To perform the update, visit the Citect web site
and enter the serial number. Provided that your Customer Service agreement and licence details
are valid, an Authorisation Code will display, which you enter in the CiUSAFE dialog.

To update the Hardware Key:

1. In Citect Explorer select Citect Key Update from the Help Menu. If you have CitectHMI/SCADA
5.21 or 5.20, run CiUSAFE.exe from the Citect BIN directory.
2. A Key ID will display. The Hardware Key's serial number may also display. If it does not, read
the serial number from the label on the key.
3. Visit http://www.citect.com/ and enter the serial number as prompted. You may also be
requested to provide the Key ID and your web login name and password.
4. An Authorisation Code will display. Type the code (or copy and paste it from the web site) into
the AUTHORISATION CODE field in CiUSAFE. Do not use any spaces when entering the
characters.
5. Click on the Update button.
6. The Return Code field will indicate whether the Hardware Key was updated successfully.

NOTE: Each time you run the CitectHMI/SCADA Key Update, a different Key ID will appear.
However, if you obtain an Authorisation Code, but do not immediately update the
Hardware Key, you can enter the same Authorisation Code the next time you run the
update.

CiUSAFE Dialog Properties

The CiUSAFE dialog has the following properties which allow you to update your Hardware Key:

Compiling and Running a System 22

Serial Number
The serial number of the computer's Hardware Key. It will only appear if the key was delivered
after September 11 2000, or has been updated since this time. If this is not the case, you can
read the number from the label on the Hardware Key. You will need to enter the serial number
at the Citect web site to perform the key update.

KeyID
Each time you launch CiUSAFE, a Key ID will display in the KEYID field. You may need to
provide the Key ID in addition to the serial number when updating the Hardware Key. This
depends on the status of the key in the Citect licence database, and you will be prompted if the
Key ID is required. Click Save KeyID to save the Key ID and serial number to a text file, which
you can refer to when visiting the Citect web site.

Authorisation Code
In order to update the Hardware Key you need to enter the 106-character Authorisation Code
into this field. You will be prompted with this code once you have entered the Key ID and serial
number, and your licence and Customer Service agreement have been verified. Clicking on
Update then updates your hardware key.

Return Code
The Return Code indicates the result of the key update:

0 The key was updated successfully.

1,3 Either the KeyID or the Authorisation code you entered is invalid.

2 Either the KeyID or the Authorisation code you entered has been corrupted.

4,16 Either the KeyID or the Authorisation code you entered is invalid.

9 No hardware key could be found.

When you wish to close the program, click Exit.

Citect Licence Point Count

The point limit is the maximum number of I/O Device addresses that can be read, and is specified
by your CitectHMI/SCADA licence. CitectHMI/SCADA counts static and dynamic points.

Static points are points that are known when the project is configured. This includes all tags used
by alarms, trends, reports, events, and pages.

Dynamic points are points that are used dynamically at runtime. Although they exist in the
Variables database, dynamic points are not used when the project is configured. They are used
when you call a Super Genie, use the TagRead() and TagWrite() Cicode functions, or read or write
them using DDE, ODBC, or the CTAPI.

NOTES: 1) Dynamic and Static points are counted only once, regardless of how many times
they are used.
2) At runtime, the static and dynamic point counts are available through the Kernel and
the CitectInfo() Cicode function.
3) It is very important to plan your system and keep aware of your point count so that
you do not exceed your point limit. This is particularly important at runtime when you
can unexpectedly add to your point count by using tags that have not yet been included
in the tally.

When you run CitectHMI/SCADA, the static point count is checked against your Hardware Key. If

Compiling and Running a System 23

the point count is too large, CitectHMI/SCADA will not start up. At runtime, the dynamic point count
is added to the static point count. CitectHMI/SCADA will not allow you to use a new dynamic point if
(at runtime) it pushes the total point count above the point limit - any new references to tags through
Super Genies, DDE, ODBC, or the CTAPI will fail.

Demo Mode

CitectHMI/SCADA can be run without the hardware key - in demonstration (or Demo) mode.
Demonstration mode allows you to use all the features of CitectHMI/SCADA normally, but with
restricted run-time and I/O. The following demonstration modes are available:
15 minutes with a maximum of 50,000 real I/O.
10 hours with no static points and a maximum of 1 dynamic real I/O. This is useful for
demonstrations using Memory and Disk I/O. CitectHMI/SCADA will start in this mode if no
static points are configured.
If you want to demonstrate DDE, CTAPI, or ODBC writes to CitectHMI/SCADA in this mode,
you will only be able to write 1 point. If you want to write to more than 1 point, you must force
CitectHMI/SCADA to start in 15 minute-50,000 I/O demo mode - by creating at least one static
I/O point.
NOTE: For this to work, you must configure a real variable tag, with an accompanying PLC or
I/O Device. The tag must be used by a page or in Cicode. If you do not have a real I/O
Device connected, CitectHMI/SCADA will give a hardware error, which you can disable
using the IODeviceControl function.
8 hours with a maximum of 42,000 real I/O. This is only available through special
CitectHMI/SCADA Integration Partners (CIP) keys.

Compiling and Running a System 24

Using the CitectHMI/SCADA Kernel

The CitectHMI/SCADA Kernel provides a window into the core of CitectHMI/SCADA. By using the
Kernel, you can perform low-level diagnostic and debugging operations, for runtime analysis of your
CitectHMI/SCADA system. You can use it to display all the low level data structures, run time
databases, statistics, debug traces, network traffic, I/O Device traffic and other useful information.
You can also call any in-built Cicode function or user-written Cicode function from the Kernel.

WARNINGS: 1. You should be experienced with CitectHMI/SCADA and Cicode before

attempting to use the Kernel as these facilities are very powerful, and if used
incorrectly, can corrupt your system.
2. You should only use the Kernel for diagnostics and debugging purposes, and not
for normal CitectHMI/SCADA operation.
3. It is important to restrict access to the Kernel, because once you are in the
Kernel, you can execute any Cicode function with no privilege restrictions. You (or
anyone using the Kernel) have total control of CitectHMI/SCADA (and subsequently
your plant and equipment).

Displaying the Kernel Window

You can display the Kernel window in several ways. CitectHMI/SCADA can open the window
automatically at startup, provide a command option on the Control menu, or you can define a
runtime command to display the Kernel window when required.

Displaying the Kernel from the Control Menu

To add a Kernel option to the Control menu of the runtime system, use the Computer Setup Wizard.
Run the wizard, select Custom mode, and tick the Kernel on menu option on the Security Setup -
Control Menu page.

You can then display the Kernel window by selecting the Kernel option from the Control Menu (top
left corner) at Runtime. If you do not have a Title Bar displayed you can access the Control Menu
by pressing ALT-SPACE (make sure the Alt-Space enabled option is ticked on the Security Setup -
Keyboard page).

NOTE: You should un-tick these options (the default) after commissioning, to prevent accidental
or unauthorised use of the Kernel.

Displaying the Kernel at Startup

To display the Kernel window automatically when CitectHMI/SCADA starts up, set the
[Debug]Kernel parameter to 1. The Kernel window is opened at startup and closed at shutdown.
The display is off (0) by default.

NOTE: You should reset this parameter after commissioning, to prevent accidental or
unauthorised use of the Kernel.

Defining a Runtime Command

To display the Kernel window, define a runtime command that calls the DspKernel() function,
passing 1 in the iMode argument:

Command DspKernel(1);
Comment Displays (opens) the Kernel window

Compiling and Running a System 25

To close the Kernel window, call the DspKernel() function again, passing 0 in the iMode argument:

Command DspKernel(0);
Comment Closes the Kernel window

NOTE: You should put the highest privilege level on the DspKernel command to prevent your
operators from opening the Kernel window.

Closing the Kernel Window

You can close the Kernel window at any time by selecting the Close option from the Control menu of
the main Kernel window.

Inside The Kernel

When displayed, the CitectHMI/SCADA Kernel consists of an application window and one or more
child windows. The first time the Kernel is invoked, one child window (called Main) is opened. The
Main window contains a command line interface (similar to the Command prompt) where you can
type in Kernel commands that perform a Kernel operation or display other child windows.

The Main window displays a line by line description of what CitectHMI/SCADA did when it started
up. However, CitectHMI/SCADA continues to report messages to the Main Kernel window while it
is running, providing a useful history of important events. A typical startup screen will look like this:

Compiling and Running a System 26

TIP: It can be difficult to see all of the startup information, since the Kernel window is not
maximised at startup. When CitectHMI/SCADA starts up double-click on the Main Kernel
window title bar, then double-click on the Kernel title bar.

Initializing Sub Systems - The primary parts of CitectHMI/SCADA are getting started.

Initializing Font System - Creating all fonts that have been defined within CitectHMI/SCADA. These
are fonts used for displaying items such as alarms, and pre-V5.0 dynamic text.

Initializing Client System.

Adding NetBIOS name

Adding NetBIOS name - You will only see these on a networked system. This indicates that
CitectHMI/SCADA has registered NetBIOS names on a protocol stack. This should appear twice,
as CitectHMI/SCADA has two NetBIOS capable protocol stacks.

Starting IO Server - You will only see these messages if the CitectHMI/SCADA computer is an I/O
Server. If the computer is an I/O Server, and this message does not display, most likely the
computer is improperly set up. You should run The Computer Setup Wizard to check your
configuration. IO Server Started - The server has started and is functioning correctly. It is very
unlikely that this will ever fail.

Compiling and Running a System 27

Initializing I/O Server - Starting to check what is needed to make the I/O Server work, and initializing
any cards that are required.
On a Client, these messages will be replaced with Calling '<I/O Server>' Connected.

Initializing Cicode System - All of the Cicode has been loaded into memory, and is prepared to run.

Initializing com System - Making sure that all ports and hardware is responding and functioning
correctly.

Initializing Request System - The system that handles requests from the Client part of
CitectHMI/SCADA to the Server parts of CitectHMI/SCADA.

Initializing Trend Client System - The Trend Client is slightly different than the normal client, so it
needs separate initialization.

Starting Trend Server - You will only see these messages if the CitectHMI/SCADA computer is a
Trends Server. If the computer is a Trends Server, and these messages do not display, most likely
the computer is improperly set up. You should run The Computer Setup Wizard to check your
configuration. Trend Startup - CitectHMI/SCADA is checking for all the trend files, and making new
ones if they can't be found.
Initializing Trend Acq System - Every trend you define has its own sample rate. Here
CitectHMI/SCADA is setting up the system so it can poll the data at the correct rate for each trend
pen.
On a Client, these messages will be replaced with Calling '<Trend Server>' Connected.

Initializing Alarm System.

Loading Alarm Databases - You will only see these messages if the CitectHMI/SCADA computer is
an Alarms Server. This is loading all alarm data into memory. If the computer is an Alarms Server,
and these messages do not display, most likely the computer is improperly set up. You should run
The Computer Setup Wizard to check your configuration.
Open Alarm Save File
Loading Alarm Save File
Alarm Save File Loaded - CitectHMI/SCADA gets the alarm save file (that was created in the
specified directory), and examines it in order to see the status of existing alarms. If you have a
redundant Alarms Server, then this Alarms Server will interrogate the other instead of using the
alarm save file - since the information on the other server will be newer than any file.
Starting Alarm Processing - This means that the server is now processing (and serving) alarm data.
On a Client, these messages will be replaced with Calling '<Alarm Server>' Connected.

Initializing Report System.

Starting Report Server - You will only see this message if the CitectHMI/SCADA computer is a
Reports Server. If the computer is a Reports Server, and this message does not display, most likely
the computer is improperly set up. You should run The Computer Setup Wizard to check your
configuration.
On a Client, this message will be replaced with Calling '<Report Server>' Connected.

Initializing Page System - CitectHMI/SCADA will now display the Startup Page. At this time
CitectHMI/SCADA will cover up the Kernel if it is displayed.

Initializing Functions - Executing any Cicode functions that have been defined as running at start up.

The next line of information is the start up time, and CitectHMI/SCADA version number.

Channel PORT# is Online

Channel PORT# is Online
Channel PORT# is Online - You will only see these messages if the CitectHMI/SCADA computer is
an I/O Server. These are messages telling you that any ports you have defined in the I/O Server
have come online. If you get a messages saying that the port is not online, or could not be opened,

Compiling and Running a System 28

check the configuration of your project. PORT# is the Port Name specified in the Ports form.

Unit 'UNIT#' Port PORT# is Online

Unit 'UNIT#' Port PORT# is Online
Unit 'UNIT#' Port PORT# is Online - You will only see these messages if the CitectHMI/SCADA
computer is an I/O Server. This indicates that the I/O Device with the Unit Number of UNIT# (as
defined in the I/O Devices form), is connected to port PORT# .

Communication System Online - CitectHMI/SCADA has completed start up operations, and is now
fully operational (running).

What to Look For

All systems in CitectHMI/SCADA should start smoothly - with no problems. When commissioning a
system, you should have a look in the Kernel to check that everything is OK. If any element
repeatedly fails at startup, your CitectHMI/SCADA system is not working correctly and you will need
to investigate the problem.

Common problems that may cause startup errors are:

1) Incorrect computer setup - usually solved by The Computer Setup Wizard.
2) Networking faults or bad hardware.
3) Communication faults - this is usually just a configuration issue.

The Main window is particularly useful to check that all of your I/O Devices come online correctly
when starting. First the ports must be initialized OK, then the I/O Device itself will come online. If
there is a problem, CitectHMI/SCADA will display a message; "PLC not responding", "I/O Device
Offline" or similar.

Some I/O Devices may take two attempts to come online. If this is the case, CitectHMI/SCADA will
wait (usually 30 seconds) and try again. If your I/O Device does not come online after the second
attempt, you should check your configuration (at both ends) and cabling.

NOTE: The Kernel continues to report changes in the status of the I/O Devices to the Main
window. This information may also be reported as alarms to the Hardware Alarms page.

Compiling and Running a System 29

Using Kernel Commands

Commands are issued at a command line interface (similar to the DOS prompt), usually from the
Main Kernel window. Some commands display their results in the Main Kernel window, while others
open a child window for information display (or for further commands). A maximum of five (5)
windows can be open at once.

You can use several keyboard keys to scan and reuse commands from the command history, to
speed up the issuing of Kernel commands. (The command history is a list of commands that you
have previously issued). These keyboard keys are listed below:

Key Description
Up arrow Scans back through the
command history. (Commands
are displayed in the command
line.)
Down arrow Scans forward through the
command history. (Commands
are displayed in the command
line.)
F3 Puts the last command you
issued in the command line.
Left arrow Moves the cursor back one
character at a time (in the
command line).
Right arrow Moves the cursor forward one
character at a time (in the
command line).
Delete Deletes the character to the
right of the cursor (in the
command line).
Backspace Deletes the character to the left
of the cursor (in the command
line).
Insert Switches from over-strike mode
to insert character mode (in the
command line).

NOTE: When typing a command in the Main window, occasionally a message may appear in the
middle of your command. Although this looks ruined on screen, you can still execute the
command normally. You can use the Shell command to open a new command window.

Kernel Commands

Cache Changes the cache timeout for each I/O Device.

Cicode Opens a child window that you can use to call Cicode functions.
Cls Clears all text from the Main or Cicode windows.
Debug Enables the debugging of raw data transferred between
CitectHMI/SCADA and a driver.
Exit Closes a Cicode or Shell window.
Help Displays a list of some of the commands available in the Kernel.
INI Displays the local Citect.INI file.
Log Enables or disables the logging of I/O Device reads and writes.
NetBIOS NetBIOS logging.

Compiling and Running a System 30

Page General Displays general statistics information.
Page Driver Displays information about each driver in the CitectHMI/SCADA
system.
Page Memory Displays the memory debug heap.
Page Netstat Displays NetBIOS specific statistics and information.
Page Table Displays information about CitectHMI/SCADA's internal data
structures.
Page RDB Displays information about CitectHMI/SCADA's Runtime
Databases.
Page Unit Displays information about each I/O Device in the
CitectHMI/SCADA system.
Pause Pause debug output.
Probe Displays read and write requests (and responses)
Shell Opens a new command (shell) window.
Stats Resets all system statistics.
SysLog Displays the SysLog.DAT file.

Compiling and Running a System 31

Gathering Runtime Information

The CitectHMI/SCADA Kernel can display a large amount of information about your
CitectHMI/SCADA runtime system. At first it can be confusing to know where you should look. The
following areas are very useful places to gather information:
1) General - Statistics and information on the overall performance of CitectHMI/SCADA. For
example, this page shows memory usage, summaries of protocol and I/O Device statistics, as
well as CPU usage. Access this by using the Page General command.
2) Table - Contains information about CitectHMI/SCADA's runtime data structures. This area is
very extensive and is initially a bit difficult to navigate. However, Page Table Stats is very
insightful. Access this by using the Page Table command.
3) Driver - Specific statistics and information about the individual protocols running on the I/O
Server. Each individual port has its own page of information. Access this by using the Page
Driver command.
4) Unit - Similar to the Driver information, this shows specific statistics and information about
each I/O Device. Access this by using the Page Unit command.

System Tuning

CitectHMI/SCADA is designed for optimal performance, so it not necessary for most users to tune
their system. However, special circumstances may require that you adjust your system to gain
optimal performance. The Kernel allows you to locate areas that need tuning, and the tuning itself is
usually done through parameters. For example, you can improve performance of the Display Client
by using the [Page]ScanTime and [Alarm]ScanTime parameters.

Cache Tuning

The cache should be tuned large enough so that unnecessary reads are not generated, and small
enough that old data is not returned while keeping the communication channel busy. If the cache is
too large, the communication channel may become idle for short periods of time and so waste its
bandwidth. Also if the cache is too large, a CitectHMI/SCADA client may start to short cycle on
reads request, which will generate unnecessary network or internal traffic load.

Read short cycling occurs when a client requests data from the I/O Server, and the data is returned
from the cache, so it is returned very quickly. The client will process the data, eg display it on the
screen (also very quickly), then ask for the same data again. If the I/O Server again returns the
same data from the cache, the client will process the same data again which is redundant and a
waste of CPU and the network (to transmit the request and response). When short cycling starts to
occur, the CPU and network loading will rise while the PLC communication traffic will start to fall.

To tune the cache you must balance the cache time between unnecessary reads and short cycling.
Use The following method:

NOTE: This information assumes to you know how to use the CitectHMI/SCADA debugging
Kernel.
1. Turn off all unit caching, use the CACHE command in the Kernel so you don't have to re-compile
your project.
2. Run one CitectHMI/SCADA client only on the network, use the Client in the I/O Server for the
test.
3. Display a typical page to generate normal PLC loading for your system.
4. In the Kernel use the STATS command to reset all the CitectHMI/SCADA statistics.
5. In the Kernel display the page 'PAGE TABLE STATS'. This page shows the cycle and execution
time of various CitectHMI/SCADA tasks, some of which consume PLC data. The tasks called

Compiling and Running a System 32

 'Citect n' where n is a number are the tasks which get data from the PLC and display on the
screen. Look at the Avg Cycle time, this is the third column from the left. Assume that the Avg
cycle time is 1200 ms. T his will mean that the current page is gathering all PLC data and
displaying its data on the screen in 1200ms. See the [Page]ScanTime parameter.
6. The cache time should always be below this average cycle time to prevent short cycling. On
average it should be less than half this time, ie 600 ms.
7. Set the cache time to half the cycle time (600ms). You may not see any improvement in
performance with a single client, as caching will only improve performance with multi clients.
You may see improvements if you are also running trends, alarms or reports which are
requesting the same data.
8. You should then add another CitectHMI/SCADA client which is displaying the same data. Reset
the STATS and check the Average cycle time. Each new client should not increase the cycle
time, it should drop slightly. Also look at PAGE GENERAL, to see that each new client should
service its reads from the cache, ie the % cache reads increases.
9. If the average cycle time drops to less than half the original time then short cycling is occurring
and you should decrease the cache time until this stops.
Tuning the cache is a trial and error process - as you change it, the read cycle time will also
change. The cache time will also depend on what the current PLC traffic is. The current traffic is
dynamic as CitectHMI/SCADA will only read what is required depending on the current page,
trend, alarm and reports running. You should always be on the safe side and set the cache a bit
lower to stop short cycling under lower loading conditions.

Compiling and Running a System 33