WinCC C-Course PDF

09.
99
WinCC C-Course
4 WinCC C-Course
To make objects dynamic, various options are available in WinCC. Among others, these are
tag connections, dynamic dialogs and direct connections. With these aids, the
implementation of complex dynamics is possible. Nevertheless, they reach their limits with
growing demands. A much broader range of possibilities is available to users through the
configuration of C-Actions, project functions or actions. They are created in the WinCC
script language C. For many applications it is not necessary to have a very comprehensive
knowledge of C. It is sufficient to supply existing functions with parameters. However, to
use all capabilities of C as the WinCC script language, a basic knowledge of this
programming language is needed. This course can provide you with this knowledge.
Target Group
This course is intended to provide basic knowledge about the general application of the
programming language C to everybody who is not familiar with it. Experienced C
programmers can learn the special features of C when applied to WinCC.
The sample project for this course can be copied directly from the online document to your
hard drive. By default, it will be stored to the C:\Configuration_Manual folder.
Project_C_Course
WinCC Configuration Manual

C79000-G8276-C157-01
4-1
WinCC C-Course
09.99
Sam ple Project
The interface of the sample project is divided into several sections. They are listed below:
Navigation Bar (1): The navigation bar allows the selection of the pictures pertaining to
the various chapters.
Chapter Window (2): The chapter window displays the pictures assigned to the
individual chapters. These pictures contain all samples described in the particular
chapter. Most of these samples are created at buttons.
Script Window (3): The script window displays the code of the sample currently
selected in the chapter window. The currently selected sample is marked red in the
chapter window.
Diagnostics Window (4): The diagnostics window displays all outputs of the various
samples initiated by the printf()function.
4-2

C79000-G8276-C157-01
09.99
WinCC C-Course
4.1 Developm ent Environm ent for C-Scripts

For the creation of C-Scripts, WinCC provides two different editors. On is the action editor
in the Graphics Designer for the creation of C-Actions at objects, the other is the Global
Script editor for the creation of project functions and global actions. The syntax of the
script language corresponds to Standard C following ANSI.
Another area of application for the programming language C in WinCC pertains to the
creation of Dynamic Wizards. For this, a separate editor is available. The usage of this
editor is explained in the sample pertaining to the Dynamic Wizard and will not be treated
in the general overview.

C79000-G8276-C157-01
4-3
WinCC C-Course
09.99
4.1.1 Action Editor ofthe Graphics Designer

In the Graphics Designer, object properties can be made dynamic via C-Actions. In the
same way, C-Actions can be used to react to object events.
Action Editor
For the configuration of a C-Action, the action editor is available. This editor is opened
from the Object Properties dialog box via a
R on the desired property or event and then selecting C-Action from the displayed pop-up
menu. Already existing C-Actions are marked by a green arrow at the property or event.
In the action editor, the C-Action can be programmed. For C-Actions at properties, a trigger
must be defined. For C-Actions at events, this is not necessary since the event itself is the
trigger. The completed C-Action must be compiled. If no errors are detected by the
compiler, the action editor can be exited by clicking on OK.
4-4

C79000-G8276-C157-01
09.99
WinCC C-Course
Structure ofa C-Action

In general, a C-Action corresponds to a function in C. There are two different types of CActions: Actions that are created at Properties and actions that are created at Events.
Generally, a C-Action at a property is used to control the value of this property with respect
to different environmental conditions (e.g. the value of a tag). For this type of C-Action, a
trigger must be defined which controls its execution. A C-Action at an event is used to react
to this event.
C-Action at a Property
The sample code above represents a typical C-Action at a property. The meaning of the
individual sections is described below.
Header (gray): The first three lines shaded gray form the header of the C-Action. This
header is generated automatically and cannot be changed. Except for the return value
type (l
ongin the sample code), the function header is identical for all properties. Three
parameters are transferred to the C-Action. These are the Picture Name
(l
pszPictureName), the Object Name (lpszObjectName)and the Property Name
(l
pszPropertyName).
Variable Declaration (1): In this first code section that can be edited, the variables
used are declared. In the sample code this is one variable of the l
ongtype.
Value Computation (2): In this section, the computation of the property value is
performed. In the sample code, only the value of one WinCC tag is read in.
Value Return (3): The computed property value is assigned to the property. This is
done via the return command.

C79000-G8276-C157-01
4-5
WinCC C-Course
09.99
C-Action at an Event
The sample code above represents a typical C-Action at an event. The meaning of the
individual sections is described below.
Header (gray): The first three lines shaded gray form the header of the C-Action. This
header is generated automatically and cannot be changed. The function header differs
for the various types of events. The parameters l
pszPictureName (Picture Name),
l
pszObjectName (Object Name)and l
pszPropertyName (Property Name)are transferred
to the C-Action. The l
pszPropertyName parameter only contains relevant information
for events that react to the change of a property. Additional event-specific parameters
can be transferred.
Variable Declaration (1): In this first code section that can be edited, the variables
used are declared. In the sample code this is one variable of the l
ongtype.
Event Processing (2): In this section, the actions reacting to the corresponding event
are performed. In the sample code, the value of one WinCC tag is read in. This value is
assigned as position X to the own object. The return value of a C-Action at an event is
of the voidtype, i.e. no return value is expected.
4-6

C79000-G8276-C157-01
09.99
WinCC C-Course
Creation ofa C-Action

The following table describes the individual steps required to create a C-Action.
Step
Procedure:Creation ofa C-Action
Open the Graphics Designer editor.

Open the desired WinCC picture.
Open the Object Properties dialog box of the desired object.
The Edit Action editor is opened by

R on the desired property or event and
then selecting C-Action from the pop-up menu.
The Edit Action editor will be displayed.

In it, the basic framework of a function will be displayed.
Among other things, the header of the C-Action has been automatically
generated. This header cannot be changed.
In the first line of the C-Action
s header, the file apdef
ap.
his integrated. Through
this file, all project f
unctions, standardf
unctions as well as internalf
unctions are
announced to the C-Action.
The second part of the C-Action
s header is the function header. The function
header provides information about the return value of the C-Action and
transferred parameters which can be used within the C-Action.
The third part of the C-Action
s header is the open bracket. This bracket cannot
be deleted. Between this open bracket and the closing bracket, the actual code of
the C-Action is programmed.

C79000-G8276-C157-01
4-7
WinCC C-Course
09.99
Step
Another automatically generated code section consists of two comment blocks.

These blocks are necessary to give the CrossReference editor access to the
internal information of a C-Action. They are also needed to enable the rewiring
within a C-Action. If both of these options are not going to be utilized, these
comments can also be deleted. The first comment block is used for the definition
of the WinCC tags used in the C-Action. In the program code, the defined name
of the variables instead of the real variable names must be used. The second
comment block is used for the definition of the WinCC pictures used in the CAction. Here as well the defined name of the picture must be used in the program
code instead of the real picture name. A sample code pertaining to this topic can
be found following this table. It includes the definitions of a WinCC tag and a
WinCC picture as well as the subsequent application of these definitions.
Programming the function body, which executes the desired calculations, actions
and so forth. Several programming aids are available. One of these aids is the tag
selection dialog. This dialog is opened via the toolbar button displayed below. In
the displayed Select Tagdialog, a WinCC tag is selected and then confirmed by
clicking on OK. The name of the selected WinCC tag will then be inserted at the
current cursor position in the C-Action.
Another aid is the function selection in the left window of the action editor.
Using the function selection, all available project f
unctions, standardf
unctions
and internalf
unctions can be inserted automatically at the current cursor position
in the C-Action.
For this, the desired function is selected via a

D. This will display the
AssigningParameters dialog, which contains a list of all parameters that must be
fed and their data types. The function can be parameterized in the Value column.
In addition to the plain text input, the options Select Tag, Graphic Objects and
Pictures are available. To insert the function at the current cursor position in the
C-Action, confirm the dialog by clicking on OK.
4-8

C79000-G8276-C157-01
09.99
WinCC C-Course
Step
The completed function must now be compiled. This is done via the toolbar
button displayed below.
The result of the compiling process is displayed in the lower left corner of the
action editor. This includes the number of errors found and the number of
warnings. Errors always cause a C-Action to be not executable. Warnings on the
other hand are notes pointing out possible errors that can occur during the
execution of the C-Action. Good programming style precludes the creation of CActions with the output result other than 0 Error(s),0 Warning(s).
If errors occur during the compiling process, they will be displayed in the output
D on an error message in the output window, you can jump
window. Via a
directly to the corresponding code line.
For C-Actions that have been created at an object property, a trigger must be
defined. For C-Actions at events, this is not necessary since the event itself form
the trigger.
The definition of the trigger is carried out via the toolbar button displayed below.
You have the option to use time or tag triggers.
By clicking on the OK button of the action editor, the programmed C-Action will
be placed at the desired property or event. A property or event made dynamic
through a C-Action will be marked by a green arrow.

C79000-G8276-C157-01
4-9
WinCC C-Course
09.99
Defining WinCC Tags and WinCC Pictures
If a new C-Action is created, the automatically generated code will include two comment
blocks. These comment blocks are necessary to give the CrossReference editor access to
the internal information of a C-Action. They are also needed to enable the rewiring within a
C-Action.
Variable Definition: The first comment block is used for the definition of the WinCC
tags used in the C-Action. This comment block begins with the line /
/WINCC:
TAGNAME_SECTION_START and ends with the line /
/WINCC:
TAGNAME_SECTION_END. In between these two lines, the names of all WinCC tags
used in the C-Action are defined. A definition takes place through the preprocessor
command #define followed by the defined name (in the sample code this is
S32I_COURSE_TEST_1)followed by the name of the WinCC tag (in the sample code
this is S32i_course_test_1).
Picture Definition: The second comment block is used for the definition of the WinCC
pictures used in the C-Action. This comment block begins with the line /
/WINCC:
PICNAME_SECTION_START and ends with the line /
/WINCC:
PICNAME_SECTION_END. In between these two lines, the names of all WinCC
pictures used in the C-Action are defined. This follows the same convention as
described above for the definition of tag names.
Application: In the actual program code, the defined values must be used instead of the
real tag and picture names. Before compiling the C-Action, the preprocessor will replace
all defined names with the real names.
4-10

C79000-G8276-C157-01
09.99
WinCC C-Course
4.1.2 The GlobalScript Editor

The Global Script editor is used for the creation of project functions, standard functions and
actions.
Project Functions
If the same functionality is frequently required in C-Actions, this functionality can be
formulated in a project function. Project functions can be called in all C-Actions of a
WinCC project, in the same manner as all other functions. The following lists the
advantages of using project functions as opposed to creating the entire program code in CActions:
Central place for editing: A change of a project function affects all C-Actions in which
this function is being used. If no project functions are used, all concerned C-Actions
must be changed manually. This not only simplifies the configuration, but also
maintenance and troubleshooting.
Reusability: Once a project f
unction has been programmed and extensively tested, it
can be used again at any time without requiring additional configurations or new tests.
Reduced Picture Volume: If not the entire program code is placed directly in the CAction at the object, the picture volume is reduced. This results in faster picture opening
times and a higher performance in runtime.
Password Protection: Project f
unctions can be protected against changes by assigning
a password. This protects the configuration data as well as your know-how.
Project functions are only available project-internal. They are stored in the
WinCCProjectFolder\LIBRARY folder and defined in the ap_pbib.h file located in the
same folder.
A number of standardf
unctions are available. Contrary to the project f
unctions, the
standard functions are available to all WinCC projects. Existing standardf
unctions can be
changed. New standardf
unctions can also be created.
Standard functions only differ from project functions with regard to their availability:
standard functions are available across projects, whereas project functions are only
available project-internal. Standard functions are stored in the
WinCCInstallationFolder\APLIB folder and defined in the ap_glob.h file located in the
same folder.
InternalFunctions
In addition to the project functions and the standard functions, there are also internal
functions. Among others, these are standard C functions. They cannot be changed by the
user and new internal functions can also not be created.

C79000-G8276-C157-01
4-11
WinCC C-Course
09.99
Actions
Actions are - contrary to the previously described functions - not called from a C-Action or
other function. A trigger must be assigned to the action controlling its execution. It is
executed independently of the currently selected picture in runtime.
Actions can be configured globally, i.e. across projects. In this case, they are stored in the
WinCCProjectFolder\PAS folder. You can also configure local actions (computer-specific
actions), which will be stored in the WinCCProjectFolder\ComputerName\PAS folder.
If Gl
obalScript Runtime is checked in the startup list of the computer, all gl
obalactions
and all l
ocalactions belonging to the computer will activated upon project start.
Creation ofa Project Function

The steps required to create a project function are identical to the steps required to create a
standard function. The following description therefore also applies to the creation of a
standard function.
Step
Procedure:Creation ofa Project Function
Open the Gl
obalScript editor.
4-12
Via a
R on the Project Functions entry and then selecting New
Function
from the pop-up menu, the basic framework of a new project f
unction will be
created.

C79000-G8276-C157-01
09.99
WinCC C-Course
Step
Procedure:Creation ofa Project Function
The project f
unction can be completely formulated by the user. There are no code
sections that cannot be edited.
Programming the function header. The function must be given a name, which is
used in C-Actions or other functions to call it. Additionally, the return value and
required transfer parameters of the function must be specified.
If other project f
unctions or standardf
unctions are to be used in the present
function, the apdef
ap.
hfile must be integrated. This is done via the preprocessor
command #incl
ude "apdef
ap.
h", which must be inserted before the function
header.
Programming the function body.

For this, the same aids as for programming C-Actions are available. Specifically,
these are the tag selection and function selection.
The completed function must now be compiled. This is done via the toolbar
button displayed below.
The result of the compiling process is displayed in the output window. Errors
occurred and warnings will be listed and their quantity displayed. Via a
an error message in the output window, you can jump directly to the
corresponding code line.
D on
Via the toolbar button displayed below, a description can be added to the project
f
unction. Together with the description, a password can be defined to protect the
project f
unction from unauthorized access.
The completed project f

unction must be saved using an appropriate name.

C79000-G8276-C157-01
4-13
WinCC C-Course
09.99
Creation ofa GlobalAction

The steps required to create a global action are identical to the steps required to create a
local action. The following description therefore also applies to the creation of a local
action.
Step
Procedure:Creation ofa Global Action
Open the Gl
obalScript editor.
4-14
Via a
R on the Gl
obalActions entry and then selecting New
Action
from the pop-up menu, the basic framework of a new action will be created.
The header of the action will be generated automatically and cannot be changed.
In addition, two comment blocks for the definition of the WinCC tags and
WinCC pictures are inserted.
The meaning of these two comment blocks has already been described in the
previous C-Actions section.

C79000-G8276-C157-01
09.99
WinCC C-Course
Step
Procedure:Creation ofa Global Action
Programming the action body.

For this, the same aids as for programming C-Actions are available. Specifically,
these are the tag selection and function selection.
The action has a return value of the type int. This return value, however, cannot
be evaluated by the user. By default, the value 0 is returned.
Via the toolbar button displayed below, a description can be added to the action,
similar to the function description. A password can also be defined to protect the
project f
unction from unauthorized access.
Contrary to functions, it is also necessary to set a trigger, which controls the
execution of the action. For the selection of a trigger for an action, the user has a
greater range of options than for the selection of a trigger for a C-Action at an
object. Among other things, a one-time execution can be programmed.
The completed action must be saved.
Test Output
The execution of a program can be followed through test outputs. This facilitates
troubleshooting and error diagnostics during development. Test outputs can be initiated via
the printf()functions. Through this function, simple texts, but also current tag values, can
be output. To make the output texts visible, a Global Script Diagnostics Window must be
configured.

C79000-G8276-C157-01
4-15
WinCC C-Course
09.99
The printf()Function
The printf()function allows test outputs to be made. A sample application of this function
is displayed below:
The printf()function requires at least one parameter. This parameter is a character string.
The type and quantity of additional parameters to be transferred depends on this character
string.
The % character is used by the printf()function as an identifier that the value of a variable
is to be inserted at this position. The character following the % character determines the
data type of this variable. The character combination %dused in the sample above signals
the output of a decimal number. Additional possible combinations and their descriptions
can be found in the following table:
4-16
Parameter
Description
%d
Output of a decimal number (int or char)
%ld
Output of a variable of the type long as a decimal number
%c
Output of a character (char)
%x
Output of a number in hexadecimal format (with lower case a...f)
%X
Output of a number in hexadecimal format (with upper case A...F)
%o
Output of a number in octal format
%u
Output of a decimal number (only for unsigned types)
%f
Output of a float value in floating point notation, e.g. 3.43234
%e
Output of a float value in exponential notation, e.g. 23e+432
%E
Like %e, but with upper case E, e.g. 23E+432
%s
Output of a character string (char*)
%le
Output of a double value
%%
Output of a % character
\n
Output of a line change (carriage return)
\r
Output of a line feed
\t
Output of a tab
\\
Output of a \ character

C79000-G8276-C157-01
09.99
WinCC C-Course
GlobalScript Diagnostics Window

The text outputs specified by the printf()function are displayed in the Global Script
Diagnostics Window. The steps for the configuration of such a Diagnostics Window are
described in the following table:
Step
Procedure:Global Script DiagnosticsW indow
Open the Graphics Designer editor.

Open the desired WinCC picture.
Configure a Smart Object

Appl
ication Window.
After placing the application window in the picture, the Window Contents dialog
will be opened. From the list-box, select the Gl
obalScript entry. Exit the dialog
by clicking on OK.
The Templ
ate dialog will be opened. From the list-box, select the GSC
Diagnostics entry. Exit the dialog by clicking on OK as well.
In order to work comfortably with the Gl

obalScript Diagnostics Window, it is
recommended to set all properties in the Object Properties dialog under the
Miscel
l
aneous entry to Yes.

C79000-G8276-C157-01
4-17
WinCC C-Course
4-18
09.99
Step
Procedure:Global Script DiagnosticsW indow
If the project is in runtime, the text outputs specified by the printf()function will
be displayed in the diagnostics window. If the update is stopped using the
appropriate button on the toolbar, the window content can be saved or printed
out.

C79000-G8276-C157-01
09.99
WinCC C-Course
4.2 Variables
In the WinCC project Project_C_Course, samples pertaining to the topic variables can be
accessed by clicking on the navigation bar icon displayed below. The samples are
configured in the cc_9_example_00.PDL picture.
Variables
Variables are data objects manipulated by a program. A variable can only be used after it
has been defined. All variables used in a program must be defined before the first
instruction can be carried out.
Variables can be compared to a container. Through a variable name, we give the container a
unique name. The type of the content of the container is specified by its data type. The start
content of the container is specified by its initialization value. In most cases, this content
will be manipulated during program execution.
The variables described here should not be mistaken for WinCC tags. They are only
available within the program code.
A sample for the definition of a variable is illustrated by the following program code. In
this case, a variable of the int data type is defined with the name iNumber. The code line is
concluded with a semicolon. In front of the variable name is a prefix describing the data
type. This is not mandatory, but it makes the data type of the variable immediately
recognizable during program creation.
It is also possible to initialize a variable while it is being defined.
Constants
In addition to variables, a program also works with constants. This is simply the direct
application of a number value. To clarify the meaning of such a number value, a symbolic
constant can be defined for it using the #define command.
A sample for the definition of a symbolic constant is shown by the program code below. In
this case, the symbolic constant MAX_INT_VALUE is defined with the number value
2147483647. Note that the code line must not be concluded by a semicolon. It is a common
programming guideline that symbolic constants are written in upper case letters to easier
differentiate them from variables.

C79000-G8276-C157-01
4-19
WinCC C-Course
09.99
Data Types
C recognizes the basic data types listed in the table below.
Data Type
Description
char
One Byte, can accept one character
int
Integer value
float
Floating-point number single accuracy
double
Floating-point number with double accuracy
A variable of the char data type has a memory requirement of one Byte. Its content can be
interpreted as a character or as a number.
The int data type can be preceded by the signed or unsigned keyword. The keyword signed
stands for a signed value, the keyword unsigned for an unsigned value.
The int data type can also be preceded by the long or short keywords. These keywords can
also be used without int - and still have the same meaning. A variable of the short (or short
int)data type has a memory requirement of 2 Bytes, a variable of the long (or long int)data
type has - just as the variable of the int data type - a memory requirement of 4Bytes.
The double data type only differs from the float data type by its value range. Numbers can
be represented with greater accuracy by the double data type. A variable of the float data
type has a memory requirement of 4Bytes, whereas a variable of the double data type has a
memory requirement of 8Bytes.
Value Ranges ofData Types

Each data type is capable of displaying number values in a certain value range. Differences
arise from the different memory requirements of the different data types and the difference
between signed and unsigned data types.
Data Type
4-20
Value Range
int
-2 147483648to 2 147483647
unsigned int
0to 4294967295
short
-32 768to 32 767
unsigned short
0to 65535
long
-2 147483648to 2 147483647
unsigned long
0to 4294967295
char
-128to 127(all ASCII characters)
unsigned char
0to 255(all ASCII characters)
float
-10^38to 0^38
double
-10^308to 0^308

C79000-G8276-C157-01
09.99
WinCC C-Course
4.2.1 Sam ple 1 - C Data Types (Integers)

In this sample, the available default data types of C are used to display integers. The sample
has been configured at the Button1 object displayed below at Event
Mouse
Mouse Action.
C-Action at Button1
The first three lines are the header of the C-Action. This header cannot be changed.
In the next section, the variables are defined. One variable each of the char, l
ong, short
and int data type and their unsigned counterparts are defined. The names of the
variables are preceded by a prefix describing the data type. This is not mandatory, but it
makes the data type of a variable immediately recognizable during program creation. As
the comment, each line includes the memory space required by the variable (comments
begin with the character string //are marked in green).
In the next section, values are assigned to the variables. This is done using the
assignment operator =. The number values used in the sample exactly hit the limits of
the value ranges that can be displayed for the various data types.
The number values are output in the diagnostics window through the function printf().
This output is displayed in the next section.

C79000-G8276-C157-01
4-21
WinCC C-Course
09.99
Output in the Diagnostics Window

The sample described in this section generates the following output in the diagnostics
window:
4-22

C79000-G8276-C157-01
09.99
WinCC C-Course
4.2.2 Sam ple 2 - Defined Data Types (Integers)

Instead of the default data types available in C, specifically defined data types can also be
used. These specifically defined data types are however only alias names of the real data
types. In this sample, various defined data types are used to display integers. The sample
has been configured at the Button2object displayed below at Event
Mouse
Mouse Action.
C-Action at Button2
In the first section, the variables are defined. One variable each of the CHAR, SHORT,
LONG and INTdefined data type and their unsigned counterparts BYTE, WORD,
DWORD and UINTare defined. In addition, a variable of the BOOLdata type is
defined. Variables of the BOOLdata type can be assigned the defined values TRUE or
FALSE. The names of the variables are preceded by a prefix describing the data type as
in the previous example.
In the next section, values are assigned to the variables. The number values used in the
sample again exactly hit the limits of the value ranges that can be displayed for the
various data types.
The number values are output in the diagnostics window through the function printf().
This output is displayed in the next section.

C79000-G8276-C157-01
4-23
WinCC C-Course
09.99

window:
Type Definition
Data types used in this section have been assigned using the typedefcommand. The
following program code illustrates how the BYTE data type has been defined. BYTE is
simply the alias name for the default data type unsignedchar available in C. You can also
define your own alias names.
The following table contains the defined data types pertaining to the default data types
available in C:
4-24
Defined Data Type
C Data Type
BOOL
int
CHAR
char
SHORT
short
LONG
long
INT
int
BYTE
unsigned char
WORD
unsigned short
DWORD
unsigned long
UINT
unsigned int

C79000-G8276-C157-01
09.99
WinCC C-Course
4.2.3 Sam ple 3 - WinCC Tags (Integers)

In most cases, to solve tasks for making objects dynamic and similar things through a CAction or another function, WinCC tags must be used. For this purpose, various functions
for reading and writing the value of a WinCC tag are available. These functions can be used
with each WinCC default tag type. In this sample, values are written to various WinCC
tags. The contents of the WinCC tags are displayed in output fields. The sample has been
configured at the Button3object displayed below at Event
Mouse
Mouse
Action.
C-Action at Button3
In the first section, the variables are defined. The data types of the variables were
selected according to the data types available for WinCC tags.
In the next section, values are assigned to the variables. The number values used in the
sample again exactly hit the limits of the value ranges that can be displayed for the
various data types.
The variable values are assigned to the various WinCC tags using the corresponding
functions. The function names consist of the text SetTagand the data type designation
of the WinCC tag to which the function is applied. Corresponding to the SetTag
functions for writing to WinCC tags, there are also GetTagfunctions for reading
WinCC tags.

C79000-G8276-C157-01
4-25
WinCC C-Course
09.99
If a variable of the of the BOOLdata type (alias name for int)is transferred to the
SetTagBit()function, the compiler will issue a warning. This is done, because the
SetTagBit()function expects SHORTas the data type of the transferred variable.
Therefore, the content of the bNumber variable is converted to SHORTin this sample
code before it is transferred to the SetTagBit()function. This process is also called
Typecast (type conversion).
Type Conversion
The content of a variable can be converted to a different data type before it is transferred to
a function or assigned to another variable. The data type of the variable itself remains
unchanged, however. The following program code illustrates how a variable of the f
l
oat
data type can be converted to the int data type.
Data Types ofWinCC Tags

The following table contains the various data types of WinCC tags corresponding to the
data types available in C. These are the data types which are transferred to the SetTag
functions and returned by the GetTagfunctions.
4-26
Data Type ofthe W inCC Tag
Data Type ofthe C Variable
Signed 8-Bit Value
char
Signed 16-Bit Value
short int
Signed 32-Bit Value
long int
Binary Tag
short int
Unsigned 8-Bit Value
BYTE
WORD
DWORD

C79000-G8276-C157-01
09.99
WinCC C-Course
4.2.4 Sam ple 4 - C Data Types (Floating-Point Num bers)

In this sample, the available default data types of C are used to display floating-point
numbers. The sample has been configured at the Button4object displayed below at Event
Mouse
Mouse Action.
C-Action at Button4
In the first section, the variables are defined. One variable each of the f
l
oat and doubl
e
data type is defined.
In the next section, values are assigned to the variables. In this sample, the same number
value is assigned to both variables.
The accuracy of a variable of the f
l
oat type goes approximately to the seventh decimal
place. A variable of the doubl
e type can display numbers twice as accurate. This can be
seen in the output of the number values - using the printf()function - in the diagnostics
window. In addition to the value of the variable, its memory requirement is also output.
The memory requirement of a variable is determined via the sizeof()command. The
memory requirement is indicated in Bytes.

window:

C79000-G8276-C157-01
4-27
WinCC C-Course
09.99
4.2.5 Sam ple 5 - WinCC Tags (Floating-Point Num bers)

In addition to integers, WinCC tags can also contain floating-point numbers. For this, two
data types for WinCC tags corresponding to the C data types float and double are available.
To access these WinCC tags in read or write mode, corresponding SetTagand GetTag
functions are provided. In this sample, values are written to various WinCC tags. The
contents of the WinCC tags are displayed in output fields. The sample has been configured
at the Button5object displayed below at Event
Mouse
Mouse Action.
C-Action at Button5
In the first section, the variables are defined. One variable each of the f
l
oat and doubl
e
data type is defined.
In the next section, values are assigned to the variables. In this sample, the same number
value is again assigned to both variables.
The variable values are assigned to the various WinCC tags using the corresponding
functions. Corresponding to the SetTagfunctions used here for writing to WinCC tags,
GetTagfunctions for reading WinCC tags are also available.
4-28

C79000-G8276-C157-01
09.99
WinCC C-Course
4.2.6 Sam ple 6 - Static and ExternalVariables

The sample has been configured at the Button6object displayed below at Event
Mouse
Mouse Action.
Static Variables
A C variable is valid in a function after its definition. It becomes invalid again after the
function terminates. If the function is called again, the C variable will be generated again.
However, if the keyword static precedes the variable, the variable will be maintained in
between two function calls. It will therefore keep its value. For C-Actions however, this is
only valid as long as the WinCC picture is selected. The static variables become invalid if
the picture is deselected. The static variable will be generated again after the picture is
opened again during the initial execution of the C-Action.
ExternalVariables
A C variable can only be accessed within the function in which it has been defined.
However, if the variable is defined outside of any function, it becomes a global (external)
variable. This variable can then be declared in any function using the keyword extern and
be accessed.
Project Function CreateExternalTags()
The CreateExternal
Tags()function only serves the purpose of defining and initializing
an external variable of the int type. At the start of the project, the function is called once
(at Events
Miscel
l
aneous
Open Picture of the start picture cc_0_startpicture_00.

PDL). From this time on, the
ext_iNumber variable is defined and can be used in any C-Action and any other
function.

C79000-G8276-C157-01
4-29
WinCC C-Course
09.99
C-Action at Button6
In the first section, the external variable ext_iNumber is declared in order to be able to
use the variable in the C-Action.
In the second section, the static variable stat_iNumber is defined and initialized. This
will be performed at the first execution of the C-Action after the WinCC picture has
been selected. For further executions of the C-Action, the value of the variable will be
maintained. If the picture is deselected and then selected again, the variable will be
generated again.
The number values of the variables are incremented by one through the increment
operator ++ and output in the diagnostics window via the printf()function. The variable
ext_iNumber will therefore indicate the number of clicks on the button since the project
start and the variable stat_iNumber the number of clicks since the opening of the
picture. This output is displayed in the next section.

window:
4-30

C79000-G8276-C157-01
09.99
WinCC C-Course
4.3 Operators and Mathem aticalFunctions in C

In the WinCC project Project_C_Course, samples pertaining to the topic operators can be
Operators
In a program, operators control what happens to variables and constants. Variables and
constants are connected to operators - this results in new variable values.
Operators can be divided into various categories. This includes mathematical operators, bitby-bit operators and assignment operators.
Mathem aticalOperators
Operator
Description
+ (unary)
Positive sign (actually has no effect)
- (unary)
Negative sign
+ (binary)
Addition
- (binary)
Subtraction
Multiplication
Division
Modulo (returns the remainder of a division)
++
Increment
--
Decrement

C79000-G8276-C157-01
4-31
WinCC C-Course
09.99
Bit-by-Bit Operators
These operators make it possible to set, query or reset individual bits in variables.
Operator
Description
&
Bit-by-Bit AND
Bit-by-Bit OR
Bit-by-Bit exclusive OR
Bit-by-Bit inversion
<<
Move bits to the left
>>
Move bits to the right
LogicalOperators
All logical operators follow the same rule: 0is FALSE, all other numbers are TRUE. These
operators either generate a 0(FALSE)or a 1 (TRUE).
4-32
Operator
Description
>
Greater than
>=
Greater than or equal to
==
Equal to
!=
Not equal to
<=
Less than or equal to
<
Less than
&&
Logical AND
|
|
Logical OR
Logical inversion

C79000-G8276-C157-01
09.99
WinCC C-Course
4.3.1 Sam ple 1 - Basic Mathem aticalOperations

In this sample, the basic mathematical operators are used. The sample has been configured
at the Button1 object displayed below at Event
Mouse
Mouse Action.
C-Action at Button1
In the first section, two variables of the f

l
oat data type are defined and initialized. The
mathematical operators are applied to these two variables.
In the next section, four additional variables of the fl
oat data type are defined. These
variables store the results of the mathematical operations to be performed.
In the next section, the mathematical operators are used to add, subtract, multiply and
divide.
The results of these calculations are output through the printf()function in the
diagnostics window. This output is displayed in the next section.

window:

C79000-G8276-C157-01
4-33
WinCC C-Course
09.99
4.3.2 Sam ple 2 - Increm ent and Decrem ent Operator

In this sample, the increment and decrement operators are used. The sample has been
Mouse
Mouse
Action.
Prefix and Postfix

The increment and decrement operators are available in a prefix and postfix version. Both
versions perform the same action - they increase or decrease the value of the variable to
which they are applied to by one. The difference lies in the return value. The prefix version
increments or decrements the value of the variable and returns this new value. The postfix
version returns the original value of the variable and only then increments or decrements
the variable.
C-Action at Button2
In the first section, two variables of the int data type are defined and initialized.
The increment operator in the prefix or postfix version are applied to these two
variables. The return values of these operators are output through the printf()function in
the diagnostics window. Afterwards, the variable contents are also output by the printf()
function in the diagnostics window. This output is displayed in the next section.
4-34

C79000-G8276-C157-01
09.99
WinCC C-Course

window: It can be seen that the prefix version of the increment operator returns the
incremented variable value, whereas the postfix version returns the original variable value.
However, in both cases the variable will be incremented.

C79000-G8276-C157-01
4-35
WinCC C-Course
09.99
4.3.3 Sam ple 3 - Bit Operations

In this sample, the basic bit-by-bit operators are used. The sample has been configured at
the Button3object displayed below at Event
Mouse
Mouse Action.
Description
In this sample, the bit-by-bit operators are applied to the content of two WinCC tags
(unsigned16-Bit val
ues). The result of the operation is stored in another WinCC tag of the
same type. The operator applied is controlled and simultaneously displayed by the Button6
object. The bit-by-bit connections AND, OR, NAND, NOR and EXOR are available. A
number value is assigned to each selection option, which is stored in another WinCC tag
(unsigned8-Bit val
ue).
4-36

C79000-G8276-C157-01
09.99
WinCC C-Course
C-Action at Button3
In the first section, one variable of the BYTE data type and three variables of the
DWORD data type are defined. These variables are used to temporarily store the WinCC
tags.
In the next section, the two WinCC tags to be connected are read into the dwVal
ue1 and
dwVal
ue2variables. Additionally, the WinCC tag determining the type of the bit-by-bit
connection operator will be read into the byOperation variable.
In the next section, the dwVal
ue1 and dwVal
ue2variables are connected bit-by-bit
depending on the content of the byOperation variable. The connection result is stored in
the dwResul
t variable. The connection operation to be performed is selected by a switchcase construction. This construction is described in greater detail in the Loops chapter.
In the next section, the connection result contained in the dwResul
t variable is written to
the corresponding WinCC tag.

C79000-G8276-C157-01
4-37
WinCC C-Course
09.99
4.3.4 Sam ple 4 - Rotating Byte-by-Byte

In this sample, the bit-by-bit move operators are used to rotate the value contained in a
WinCC tag (unsigned16-Bit val
ue)byte-by-byte. This means the exchange of the high byte
and low byte. The sample has been configured at the Button4object displayed below at
Event
Mouse
Mouse Action.
C-Action at Button4
In the first section, a variable of the DWORD data type is defined. This variable is used
to temporarily store the WinCC tag. In addition, two help variables of the DWORD type
are defined.
In the next section, the WinCC tag to be processed is written to the dwVal
ue variable.
In the next section, the individual bits of the dwVal
ue variable are moved to the left by
eight positions (one byte)and stored in the dwtempValue1 variable. Afterwards, the
individual bits of the dwVal
ue variable are moved to the right by eight positions and
stored in the dwtempValue2variable. Both values determined in this section are
connected bit-by-bit (OR)and the result stored in the dwVal
ue variable.
In the next section, the rotated variable value contained in the dwVal
ue variable is
written to the corresponding WinCC tag.
4-38

C79000-G8276-C157-01
09.99
WinCC C-Course
4.3.5 Sam ple 5 - Mathem aticalFunctions

In this sample, various mathematical functions are used which are available in C by default.
Mouse
Mouse Action.
C-Action at Button5
In the first section, the variables are defined.

First, the pow()function is called. Two parameters are assigned to this function. In this
sample, the return value of the function corresponds to the third power of the dVal
ue
variable content.
Next, the sqrt()function is called. The return value of this function is the square root of
the value transferred.
Next, the abs()function is called. The return value of this function is the absolute value
of the value transferred.
Next, the rand()function is called. No parameters are assigned to this function. The
function will return a random value as the return value.
The results of these calculations are output through the printf()function in the
diagnostics window. This output is displayed in the next section.

C79000-G8276-C157-01
4-39
WinCC C-Course
09.99

window:
AdditionalMathem aticalFunctions
In the function selection, the mathematical functions can be found at InternalFunctions
c_bib
math. The following illustration depicts all available mathematical
functions (shaded gray).
4-40

C79000-G8276-C157-01
09.99
WinCC C-Course
4.4 Pointers
In the WinCC project Project_C_Course, samples pertaining to the topic pointers can be
Working with Pointers

Pointers are an essential component of the C language. A pointer is variable containing an
address - usually the address of another variable.
Pointers are defined just like regular variables. However, the unary character *is added to
the name of the data type to which the pointer is pointing. This character must not be
mistaken for the binary operator *for the multiplication. In the following program code, a
pointer is defined at a variable of the int data type.
The content of the pointer is not defined. It is still pointing to an invalid variable of the int
data type. To clarify this, a pointer should be initialized with the value NULL while it is
being defined. Before its application, the pointer can then be checked for validity.
To have the pointer point to a variable of the int data type, it must be assigned the address
of the variable. This is done via the unary operator , the so-called address operator. This
operator returns the address of the variable instead of its value. In the following program
code, the address of a variable with the int data type is assigned to the pointer.
The access to the value of the variable to which the pointer is pointing is realized via the
unary operator *, which is also called the content operator. In the following program code,
the value of the variable to which the pointer is pointing is assigned to a variable of the int
data type.
Working with Vectors

Pointers and vectors are closely related. In the following program code, a vector consisting
of 5variables of the int data type is defined.

C79000-G8276-C157-01
4-41
WinCC C-Course
09.99
The individual elements of the vectors can be accessed via its index. In the following
program code, the content of the last vector element is accessed. This is done via the index
operator [].
The vector name can also be used as a pointer pointing to the first vector element. A certain
vector element can also be accessed by moving this pointer by a certain number of
elements. This is done as illustrated in the program code below by adding a int value to the
pointer. The content of the resulting pointer is accessed via the content operator *. As
shown previously, the last value of the vector is accessed.
Character Strings
In C, a character string can be defined as a vector consisting of characters or as a pointer
pointing to a character. In addition to the coded character, C adds a null character to the end
of the character string. It serves as the end character of the character string. In the program
code displayed below, the definition of string variables is shown using both types.
Below, the internal display of both string variables is shown. In the first case, exactly as
much memory space has been reserved for the string variable as is needed for accepting the
string indicated for the initialization. In the second case, as much memory space has been
reserved as was specified during the definition of the vector.
S
S
4-42
t
t
r
r
i
i
n
n
g
2
1
\0
\0
?

C79000-G8276-C157-01
09.99
WinCC C-Course
4.4.1 Sam ple 1- Pointers

In this sample, the basic pointer operations are performed. The sample has been configured
Mouse
Mouse Action.
C-Action at Button1
In the first section, two variables of the int data type are defined and initialized.
Next, a pointer pointing to a variable of the int data type is defined and initialized with
NULL.
Next, the address contained in the pointer is output via the printf()function. The
content, to which the pointer is currently pointing, is not defined. Accessing the content
of the pointer via the content operator *would cause a general access violation at this
time.
Next, the address of the iVal
ue1 variable is assigned to the pointer. Its address and
content is again output via the printf()function.
Next, the address of the iVal
ue2variable is assigned to the pointer and the result output
again. The output of this program is displayed in the next section.

window:

C79000-G8276-C157-01
4-43
WinCC C-Course
09.99
4.4.2 Sam ple 2 - Vectors

In this sample, the basic vector operations are performed. The sample has been configured
Mouse
Mouse Action.
C-Action at Button2
In the first section, a vector consisting of 5variables of the int data type is defined. The
vector is already initialized with number values while it is being defined.
Next, the iIndex counter variable of the int data type is defined.
The individual elements of the vector are output via the printf()function. The access to
the individual elements is achieved in a f
or loop via the index operator []. Dealing with
loops is described in the next chapter Loops. This output is displayed in the next section.

window:
4-44

C79000-G8276-C157-01
09.99
WinCC C-Course
4.4.3 Sam ple 3 - Pointers and Vectors

In this sample, the relationship between pointers and vectors is explained. The sample has
been configured at the Button3object displayed below at Event
Mouse
Mouse
Action.
C-Action at Button3
In the first section, a vector consisting of 5variables of the int data type is defined. The
vector is already initialized with number values while it is being defined. In this case,
the size specification can also be omitted during while defining the vector.
Next, the iIndex counter variable of the int data type is defined.
Next, a piElement pointer is defined for a variable of the int data type and initialized
with NULL.
Next, the address of the first vector element is assigned to the piElement pointer. This
address is output via the printf()function.
Next, the individual elements of the vector are accessed by the piElement pointer. The
access is carried out in a f
or loop by advancing the pointer to the individual elements
and the content operator *.

C79000-G8276-C157-01
4-45
WinCC C-Course
09.99
Next, the individual elements of the vector are accessed again. This time, however, the
name of the vector itself is used as the pointer. The output of the program is displayed
in the next section.

window:
4-46

C79000-G8276-C157-01
09.99
WinCC C-Course
4.4.4 Sam ple 4 - Strings

In this sample, working with string variables is explained. The sample has been configured
Mouse
Mouse Action.
C-Action at Button4
In the first section, a character string (vector consisting of 13characters)is defined. This
length of the character string is one character more than the length of the assigned
initialization string to make room for the closing null character.
Next, the i counter variable of the int data type is defined.
Next, the individual characters of the character string are output via the printf()
function. The access to these characters is carried out in a f
or loop via the index
operator [].
Next, the entire character string is output via the printf()function. The output of the
program is displayed in the next section.

window:

C79000-G8276-C157-01
4-47
WinCC C-Course
09.99
4.4.5 Sam ple 5 - WinCC Text Tags

In this sample, the relation between string variables in C and WinCC text tags is explained.
Mouse
Mouse Action.
C-Action at Button5
In the first section, a character string (pointer pointing to the first character)is defined.
This string is initialized with NULL.
Next, the content of a WinCC text tag is read in via the GetTagChar()function. The
function reserves the memory space required for the character string as returns its
starting address.
Next, the entire character string is output via the printf()function. In addition, the length
of the character string is determined by the strl
en()function and output together with the
starting address of the character string. The output of the program is displayed in the
next section.

window:
4-48

C79000-G8276-C157-01
09.99
WinCC C-Course
4.5 Loops and ConditionalStatem ents

In the WinCC project Project_C_Course, samples pertaining to the topic loops can be
Loops
Loops can be used to repeatedly perform a code section as long as a condition is satisfied.
In general, there are two types of loops: pre-check and post-check loops. The pre-check
loops check before the loop body, if this loop is to be performed. The post-check loops
check after the loop body, if this loop is to be performed. Therefore, post-check loops are
performed at least once.
The following types of loops can be differentiated.
while
A sample of a while loop is displayed below. The loop is repeated as long as the condition
is satisfied. In this sample, the loop is performed as long as the value of the i variable is less
than 5.
do - while
A sample of a do-whil
e loop is displayed below. The loop is performed at least once and
then repeated as long as the condition is satisfied. In this sample, the loop is performed as
long as the value of the i variable is less than 5.

C79000-G8276-C157-01
4-49
WinCC C-Course
09.99
for
A sample of a for loop is displayed below. The loop is repeated as long as the condition is
satisfied. The initialization of the loop counter as well as the processing of the loop counter
can be formulated within the loop.
ConditionalStatem ents
In loops, the body of the loop is processed for as long as a condition is true. In conditional
statements, a statement is processed exactly once if a condition is true.
The following types of conditional statements can be differentiated.
if-else
If the condition is true, the statement in the if branch is processed. If the condition does not
apply, the alternative statement in the else branch will be processed. The else branch can
also be omitted, if no alternative statement is to be performed.
switch-case
In this case, a variable is checked for a match. Switch specifies the variable to be checked.
It is checked, which of the case branches agrees with the value of the variable. This case
branch is then performed. Any number of case branches can be defined. Each case branch
must end with a break. Optionally, a default branch can be inserted. This branch will be
performed, if the value of the variable to be checked agrees with none of the case branches.
4-50

C79000-G8276-C157-01
09.99
WinCC C-Course
4.5.1 Sam ple 1 - while Loop

In this sample, the application of the whil
e loop is explained. The sample has been
configured at the Button1 object displayed below at Event
Mouse
Mouse
Action.
C-Action at Button1
In the first section, a iCount counter variable of the int data type is defined and
initialized.
Next, the while loop is programmed. This loop will be executed as long as the content
of the iCount counter variable is less than 5. Each time the loop is performed, an output
is made by the printf()function. At the end of the loop, the iCount counter variable is
increased by one. The output of the program is displayed in the next section.

window:

C79000-G8276-C157-01
4-51
WinCC C-Course
09.99
4.5.2 Sam ple 2 - do-while Loop

In this sample, the application of the do-whil
e loop is explained. The sample has been
Mouse
Mouse
Action.
C-Action at Button2
initialized.
Next, the do-while loop is programmed. This loop will be executed as long as the
content of the iCount counter variable is less than 5. However, the loop is performed at
least once, since this condition is only checked for after the loop has been performed.
Each time the loop is performed, an output is made by the printf()function. At the end
of the loop, the iCount counter variable is increased by one. The output of the program
is displayed in the next section.

window:
4-52

C79000-G8276-C157-01
09.99
WinCC C-Course
4.5.3 Sam ple 3 - for Loop

In this sample, the application of the f
or loop is explained. The sample has been configured
Mouse
Mouse Action.
C-Action at Button3
initialized.
Next, a f
or loop is programmed. This loop will be executed as long as the content of the
iCount counter variable is less than 5. The initialization of the counter variable is
programmed directly in the call of the loop just as the action for incrementing the
counter variable. Each time the loop is performed, an output is made by the printf()
function. The output of the program is displayed in the next section.

window:

C79000-G8276-C157-01
4-53
WinCC C-Course
09.99
4.5.4 Sam ple 4 - Endless Loops

In this sample, endless loops are explained. In most cases, these loops are created
unintentionally by programming errors, when a loop condition always holds true. However,
they can also be applied intentionally. In this case, the termination of the loop must be
realized using another method, namely through the breakstatement. The sample has been
Mouse
Mouse
Action.
C-Action at Button4
In the first section, the symbolic constant MAX_COUNTis defined. This constant
represents the maximum number of executions for the following endless loop.
In the next section, a iCount counter variable of the int data type is defined and
initialized.
The current number of loop executions is to be displayed by a progress display. The
display consists of a bar, whose length contains the iProgressBar variable and a static
text, whose content contains the szProgressText string variable.
Next, the endless loop is programmed. This loop could also be formulated using the
while (TRUE)statement.
4-54

C79000-G8276-C157-01
09.99
WinCC C-Course
In the loop, the iCount counter variable is checked. If this variable exceeds the value of
MAX_COUNT, the loop is exited via the breakstatement.
The iCount counter variable will be incremented.
The progress display shows the loops already performed in percent. For every new
percent reached, the value of the progress display is set again. If no new percent has
been reached, the loop is immediately performed again via the continue statement and
the remaining lines skipped.
The values of the progress display are set by setting the width of the ProgressBar bar
with the SetWidth()function and by setting the text of the ProgressText static text with
the SetText()function. The text used is configured with the sprintf()function. This
function follows the principle of printf
(). The text, however, is not output by the Gl
obal
Script Diagnostics Window, but written to a string variable. This string variable must be
defined as the first parameter of the function.

C79000-G8276-C157-01
4-55
WinCC C-Course
09.99
4.5.5 Sam ple 5 - if-else Statem ent

In this sample, the application of the if
-else statement is explained. The sample has been
Mouse
Mouse
Action.
C-Action at Button5
In the first section, a byVal

ue variable of the BYTE data type is defined. In this variable,
the content of a WinCC tag is stored.
In the next section, the content of a WinCC tag is read into the byVal
ue variable using
the GetTagByte()function.
Next, a if
-else statement is programmed. This statement makes - depending on the
content of the byVal
ue variable - an output via the printf
()function.
4-56

C79000-G8276-C157-01
09.99
WinCC C-Course
4.5.6 Sam ple 6 - switch-case Statem ent

In this sample, the application of the switch-case statement is explained. The sample has
Mouse
Mouse
Action.
C-Action at Button6
In the first section, a byVal

ue variable of the BYTE data type is defined. In this variable,
the content of a WinCC tag is stored.
In the next section, the content of a WinCC tag is read into the byVal
ue variable using
the GetTagByte()function.
Next, a switch-case statement is programmed. This statement makes - depending on the
content of the byVal
ue variable - an output via the printf()function. To perform the
same statements for several different number values of the variable to be checked, the
corresponding case branches must be arranged among one another. The statements to be
performed are programmed in the last case branch.

C79000-G8276-C157-01
4-57
WinCC C-Course
09.99
4.6 Functions
In the WinCC project Project_C_Course, samples pertaining to the topic functions can be
Functions
Functions make it possible to better structure a program code. Instead of programming
often repeated statements over and over again, they can be shifted into a function. This also
results in a central location for editing the program code and easier maintenance.
In WinCC, functions can be created as project functions or standard functions.
Transfer Param eters

Values can be transferred to functions, depending on which the function executes
statements. These values can be transferred in various ways.
A constant value can be transferred.
A variable can be transferred. Only the value of the variable is transferred to the
function. The functions has no access to the variable itself.
A pointer can be transferred. This gives the function access to the variable to which the
pointer is pointing. Vectors and structures can only be assigned to a function via
pointers.
Return Value
A function can simply execute statements without returning a value. In this case, the return
value is of the void data type. If, however, for example a calculation is performed, the value
determined can be returned to the caller of the function via the return value. In this case,
values or other addresses can be returned.
Another option to return values to the caller is to write to a transferred address area. Vectors
or structures can only be returned in this manner.
4-58

C79000-G8276-C157-01
09.99
WinCC C-Course
4.6.1 Sam ple 1 - Transfer ofValue Param eters

In this sample, a simple function for calculating the mean value of three numbers is created.
The parameters are transferred to the function as values, the result will also be returned as a
value. The sample has been configured at the Button1 object displayed below at Event
Mouse
Mouse Action.
Project Function MeanValue()
In the function header, the name of the function is specified as MeanVal

ue(). Three
variables of the doubl
e data type are transferred to the function. A variable also of the
doubl
e data type will be returned.
Next, a variable of the doubl
e data type, in which the return value will be stored, is
defined. This return value is calculated by adding the three transferred values and
dividing the resulting sum by three.
Via the return statement, the result is returned to the caller of the function.

C79000-G8276-C157-01
4-59
WinCC C-Course
09.99
C-Action at Button1
In the first section, three variables of the doubl

e data type are defined and initialized.
The mean value of these three tags is to be calculated. An additional variable of the
doubl
e data type is defined which will store the result of the calculation.
Using the previously created function MeanVal
ue(), the mean value of the variables
transferred is calculated.
The result of the calculation is output via the printf()function. This output is displayed

window:
4-60

C79000-G8276-C157-01
09.99
WinCC C-Course
4.6.2 Sam ple 2 - Transfer ofAddress Param eters

In this sample, a simple function for calculating the mean value of the elements of a vector
of any length is created. The address of the vector and its length are transferred to the
function. The result is returned as a value. The sample has been configured at the Button2
object displayed below at Event
Mouse
Mouse Action.
Project Function MeanValueVector()
In the function header, the name of the function is specified as MeanVal

ueVector(). A
pointer pointing to a variable of the doubl
e data type is transferred to the function. This
pointer points to the first element of the vector expected. Additionally, the length of the
vector is transferred to the function. A variable of the doubl
e data type will be returned.
Next, a variable of the doubl
e data type is defined and initialized. In this variable, the
sum of the elements of the transferred vector are stored. This sum is calculated using a
f
or loop.
Via the return statement, the result is returned to the caller of the function. The result
corresponds to the sum of the vector elements divided by the number of vector
elements.

C79000-G8276-C157-01
4-61
WinCC C-Course
09.99
C-Action at Button2
In the first section, a vector consisting of three variables of the doubl

e data type is
defined and initialized. The mean value of these three tags is to be calculated. An
additional variable of the doubl
e data type is defined which will store the result of the
calculation.
Using the previously created function MeanVal
ueVector(), the mean value of the
transferred vector elements is calculated.
The result of the calculation is output via the printf()function. This output is displayed

window:
4-62

C79000-G8276-C157-01
09.99
WinCC C-Course
4.6.3 Writing to the transferred Address Range

In this sample, a simple function for filling a vector of any length with random numbers is
created. The address of a vector and its length are transferred to the function. As the return
value, the function will display if the action could be performed successfully via a variable
of the BOOLtype. The sample has been configured at the Button3object displayed below
at Event
Mouse
Mouse Action.
Project Function FillVector()
In the function header, the name of the function is specified as FillVector(). A pointer
pointing to a variable of the int data type is transferred to the function. This pointer
points to the first element of the vector expected. Additionally, the length of the vector
is transferred to the function. A variable of the BOOL data type is returned indicating
whether the function has been performed successfully or not.
Next, a counter variable of the int data type is defined.
Next, the transferred pointer is checked. The caller is responsible for the transfer of the
correct vector length. If an incorrect value is transferred, this might lead to a general
access violation.
Using a f
or loop, the elements of the vector transferred are filled by the rand()function
with random numbers.

C79000-G8276-C157-01
4-63
WinCC C-Course
09.99
C-Action at Button3
In the first section, a symbolic constant VECTOR_SIZE for the number of vector
elements is defined.
Next, a vector iVector consisting of VECTOR_SIZE variables of the int data type is
defined.
Next, a i counter variable of the int data type is defined.
Using the previously created FillVector()function, the elements of the iVector vector
transferred are filled with random numbers. The return value of the FillVector()
function is checked while it is being called with the help of an ifstatement.
The individual elements of the iVector vector are output via the printf()function. This
output is displayed in the next section.

window:
4-64

C79000-G8276-C157-01
09.99
WinCC C-Course
4.6.4 Return ofthe Result Address

In this sample, a simple function is created which fills a vector random numbers. The length
of the desired vector is transferred as a parameter to the function. As the return value, the
function will supply the address of the first element of the vector created. The sample has
Mouse
Mouse
Action.
Project Function GetFilledVector()
In the function header, the name of the function is specified as GetFilledVector(). The
number of elements of the vector created is transferred to the function. The pointer
pointing to the first vector element of the int*data type is returned.

C79000-G8276-C157-01
4-65
WinCC C-Course
09.99
Next, a piVector pointer is defined for a variable of the int data type and initialized with
NULL.
Sufficient memory space must be reserved for the vector. This is ensured by the internal
function SysMal
l
oc(). To this function, the size of the desired memory block is
transferred which is calculated by multiplying the memory requirement of a variable of
the int data type by the desired number of vector elements. The function will return the
address of the reserved memory block or NULL, if the memory space available is
insufficient.
Next, the address received from the SysMal
l
oc()function will be checked. If not enough
memory space was available, the function is terminated and NULL returned.
Using a f
or loop, the elements of the vector are filled by the rand()function with
random numbers.
The address of the vector created is returned to the caller via the return statement.
C-Action at Button4
In the first section, a symbolic constant VECTOR_SIZE for the number of vector
elements is defined.
Next, a piVector pointer is defined for a variable of the int data type and initialized with
NULL.
Using the previously created function GetFilledVector(), a vector filled with random
numbers is created, whose address is then stored in the piVector pointer. The return
value of the GetFilledVector()function is then checked for validity.
The individual elements of the vector created are output via the printf()function. This
output is displayed in the next section.
4-66

C79000-G8276-C157-01
09.99
WinCC C-Course

window:
Note:
The procedure for transferring structures to functions and the procedure for the return of
structures are described in the next chapter.

C79000-G8276-C157-01
4-67
WinCC C-Course
09.99
4.7 Structures
In the WinCC project Project_C_Course, samples pertaining to the topic structures can be
Definition ofa Structure Type

In addition to the default data types, user-defined types can also be defined with the help of
structures. In the following program code, a principal structure type definition is displayed.
The defined structure type consists of an int and a float structure element. A name must be
assigned to each structure element.
Application ofa Structure Variable

After defining the new structure type, variables of the struct ExampleStruct data type can be
defined. This is shown in the following program code. It is also shown how the elements of
the structure variable are accessed.
If instead of a structure variable only a pointer pointing to a structure variable is available,

its individual elements can be accessed as illustrated by the following program code.
Ensure that the pointer is pointing to a valid structure variable or that at least memory space
has been reserved for it.
4-68

C79000-G8276-C157-01
09.99
WinCC C-Course
4.7.1 Sam ple 1 - Structure Variable

In this sample, the definition and application of a simple structure type is explained. The
sample has been configured at the StaticText1 object displayed below at Event
Mouse
Mouse Press Left.
C-Action at Static Text1
In the first section, a CC_POINTstructure type consisting of two int elements is

defined. The structure type will accept the coordinates of a mouse click.
Next, a posObject structure variable of the struct CC_POINT data type is defined.
Next, values are assigned to the elements of the posObject structure variable. The values
assigned are the coordinates of the mouse click. These coordinates are supplied by a CAction at Event
Mouse
Mouse Press Left as the x and y transfer parameters.
Next, the coordinates of an object are set with the values contained in the structure
variable via the SetLef
t()and SetTop()functions.

C79000-G8276-C157-01
4-69
WinCC C-Course
09.99
4.7.2 Sam ple 2 - Type Definition

In this sample, the definition and application of a simple structure type is explained. As
opposed to the previous sample, this structure type will be available in the entire project
and not only for one C-Action. The sample has been configured at the Button2object
displayed below at Event
Mouse
Mouse Action.
Structure Definition in apdefap.h
A tagCC_RECT structure type consisting of four int elements is defined. The structure
type will accept the position and dimensions of a rectangular area. A variable of this
structure type must be defined as a variable of the struct tagCC_RECT data type. To
avoid this sometimes tedious notation, an alias name is defined using the typedef
statement. If you now want to define a variable of this data type, it is sufficient to use
the CC_RECT notation to specify the data type. If a pointer should point to a variable of
this data type, the notation PCC_RECTcan be used.
4-70

C79000-G8276-C157-01
09.99
WinCC C-Course
C-Action at Button2
In the first section, a rect variable of the CC_RECTdata type is defined and initialized.
Next, a prect variable of the PCC_RECT data type is defined and initialized with NULL.
This data type is a pointer pointing to a variable of the CC_RECTdata type.
Next, via the operator . , the elements of the rect structure variable are accessed. Its
content is output via the printf()function.
Next, the address of the rect variable is assigned to the prect pointer. Next, via the
operator ->, the elements of the structure variable - to which the prect pointer is
pointing - are accesed. The content of the structure variable is again output via the
printf()function. The output of the program is displayed in the next section.

window:

C79000-G8276-C157-01
4-71
WinCC C-Course
09.99
4.7.3 Sam ple 3 - WinCC Structure Type

In this sample, the definition and application of a WinCC structure type is explained. Its
structure will be identical to the CC_RECTdata type defined in the previous sample. The
sample has been configured at the Button3object displayed below at Event
Mouse
Mouse Action.
WinCC Structure Type Creation

Step
1
Procedure:W inCC Structure Type Creation

A new WinCC structure type is defined in the WinCC Expl
orer. Via a
R on
the Structure Types entry and then selecting New Structure Type from the pop-up
menu, the dialog for the definition of the properties of a new WinCC structure
will be opened.
The dialog Structure Properties will be opened.

The name of the new structure type must be specified. This is done via a
R on
the default name NewStructure and then selecting Rename from the pop-up
menu. This sample uses the name Rect.
Definition of the elements of the new structure type.

A new element can be added via the button New Element. The name and the data
type of the new element are specified via a
R on the element. In the sample,
the element is named Lef
t and is of the LONG data type. For the element, the
radio-button InternalTagis selected. The names and data types of the remaining
elements can be seen in the following illustration.
The Structure Properties dialog can be closed by clicking on OK.
4-72

C79000-G8276-C157-01
09.99
WinCC C-Course
Step
Procedure:W inCC Structure Type Creation
Now WinCC tags of the Rect data type can be created. In this sample this means
that a total of four tags corresponding to the four structure elements must be
created.
C-Action at Button3
In the first section, a rect variable of the CC_RECTdata type is defined. The CC_RECT
data type has been defined in the previous sample.
Next, the values contained in a WinCC structure tag are written to the elements of the
rect variable. In this sample, the values contained in the WinCC structure tag are
displayed via four I/O Fields and can also be edited in them.
Next, the elements of the rect structure variable are output via the printf()function. The
output of the program is displayed in the next section.

window:

C79000-G8276-C157-01
4-73
WinCC C-Course
09.99
4.7.4 Sam ple 4 - Function for Reading a WinCC Structure Type

In this sample, a function for reading the WinCC structure type defined in the previous
sample is created. This function can then be used similarly like the internal GetTag
functions. The sample has been configured at the Button4object displayed below at Event
Mouse
Mouse Action.
Project Function GetTagRect()
In the first section, the apdef

ap.
hfile is integrated, which contains the definition of the
tagCC_RECTstructure type.
In the function header, the name of the function is specified as GetTagRect. A string
variable is transferred to the function containing the name of the WinCC structure tag to
be read. A pointer pointing to a memory block of an undefined data type (void*)is
returned.
In the next section, a prect variable of the PCC_RECT data type is defined and
initialized with NULL. This data type is a pointer pointing to a variable of the
CC_RECTdata type.
4-74

C79000-G8276-C157-01
09.99
WinCC C-Course
Next, a string variable for accepting the element names of the WinCC structure tag is
created.
Next, enough memory space must be reserved to accept a variable of the CC_RECT
data type. This is ensured by the internal function SysMal
l
oc(). The size of the desired
memory block, which can be determined via the sizeof
()statement, is transferred to this
function. The function will return the address of the reserved memory block or NULL, if
the memory space available is insufficient.
Next, the address received from the SysMal
l
oc()function will be checked. If not enough
memory space was available, the function is terminated and NULL returned.
Next, the names of each element of the WinCC structure tag are composed and the
content of the corresponding element read into the reserved memory area.
The address of the reserved memory block, in which the content of the WinCC structure
tag has been stored, is returned. This memory block will remain reserved and keep its
data even after the function has bee exited.
Note:
If, instead of the procedure presented here, simply a local variable of the CC_RECTdata
type had been created - whose elements contain the content of the WinCC structure tag and
returns its address - the caller of the function would receive an invalid pointer. This can be
explained by the fact that the variable of the CC_RECTdata type would become invalid at
the end of the function and consequently an address of an invalid object would be returned.

C79000-G8276-C157-01
4-75
WinCC C-Course
09.99
C-Action at Button4
In the first section, a prect variable of the PCC_RECT data type is defined and
initialized with NULL.
Next, a WinCC structure tag is read via the previously created GetTagRect()function.
The GetTagRect()function returns a pointer pointing to the memory block containing
the desired data. This pointer is converted to a pointer of the PCC_RECT type.
Next, the pointer received from the GetTagRect()function is checked. If not enough
memory space is available, the function will return the value NULL.
Next, the names of each element of the WinCC structure tag are composed and the
content of the corresponding element read into the reserved memory area.
The address of the reserved memory block, in which the content of the WinCC structure
tag has been stored, is returned. This memory block will remain reserved and keep its
data even after the function has bee exited.
Next, the elements of the structure tag, to which prect is pointing, are output via the
printf()function. The output of the program is displayed in the next section.

window:
Project Function SetTagRect()

In addition to the GetTagRect()function, a corresponding SetTagRect()function has been
created as well. In the sample, this function is used at Event
Miscel
l
aneous
Open Picture of the cc_9_example_04.
PDL picture to initialize the WinCC structure tag.
4-76

C79000-G8276-C157-01
09.99
WinCC C-Course
4.8 WinCC API

In the WinCC project Project_C_Course, samples pertaining to the topic WinCC API can
be accessed by clicking on the navigation bar icon displayed below. The samples are
WinCC Application Program Interface

As a completely open and expandable system, WinCC provides an extensive API
(Application Program Interface). This is an interface, which is used by applications to
access WinCC. The functions of the WinCC API can also be used in the WinCC project
itself.
The WinCC ODK (Open Developers Kit)provides an extensive description of the WinCC
API. In it, the WinCC API is explained thoroughly by means of function descriptions and
samples. It also includes all header files and required function declarations. However, the
WinCC ODK is not part of the WinCC base package and must be purchased separately.

C79000-G8276-C157-01
4-77
WinCC C-Course
09.99
Function Libraries
Each (major)application of WinCC (Graphics Designer, Tag Logging, Alarm Logging,
etc.)provides its own API, which is located in one or multiple DLLs. A DLL (Dynamic
Load Library)is a dynamically loaded function library. The declarations of the functions
contained in a DLL are provided in an associated header file.
The integration of a DLL into a C-Action or other function is shown in the following
program code sample. In the first line, the name of the DLL to be loaded is specified. In the
sample, this is the DLL which contains the CSfunctions of the Graphics Designers. In the
second line, the header file with the function declarations is integrated. If only one or two
functions are required, the declaration of the function can also be made directly at this
point. The closing line is formed by #pragma code(). In the above sample, the names of the
DLL and header files agree, which appears to make sense. This, however, is not always the
case.
RT Functions and CS Functions

The API functions of every application can roughly be separated into two different types.
These are the so-called CSfunctions (Configuration System)and RT function (Runtime).
In most cases, RT functions can be called without the loading of a particular DLL in a
WinCC project. RT functions only affect runtime. After the restart of a project or in most
cases even after a picture change, modifications made using RT functions will be lost.
Before the application of a CS function in a WinCC project, the corresponding DLL - in
which the function has been programmed - must be loaded. The application of CS functions
in the WinCC project itself, however, only makes sense in rare cases. The present sample
nevertheless will illustrate the application of CSfunctions, since from, the basic principle of
its application can be deduced for your own projects.
Sam ple Project

In the sample project, no detailed description of every WinCC application API is provided.
However, the general principles of working with the WinCC API are explained, using the
Graphics Designers API as an example. The samples work with objects in the
cc_9_example_10x.PDL picture, especially configured for this purpose. It is displayed via a
Picture Window in the picture assigned to this chapter.
4-78

C79000-G8276-C157-01
09.99
WinCC C-Course
4.8.1 Sam ple 1 - Changing Properties via an RT Function

In this sample, the application of the RT function of the Graphics Designer API for setting
the properties of objects is shown. The position of an object is changed by setting the
properties Position X and Position Y. The sample has been configured at the Button1 object
Mouse
Mouse Action.
C-Action at Button1
In the first section, a bRet variable of the BOOL data type is defined and initialized. This
variable will accept the return value of the API functions called.
Next, two string variables are defined. Their content - the picture name and object name
- specifies the object to be edited. Make sure that the picture name does not include the
file extension PDL.
To define the type of the properties to be set, a variable is created. For this, a separate
data type is available. This is the VARTYPE data type. For each existing property type, a
symbolic constant is defined. The properties to be set for this sample are of the VT_I4
data type (int with a length of 4Bytes).

C79000-G8276-C157-01
4-79
WinCC C-Course
09.99
For the Position X and Position Yproperties to be set, a variable each of the int type is
defined, which includes the new value of the property.
Next, a variable of the CMN_ERROR data type is defined. If a function call fails, this
structure will contain information about the error occurred.
Via the PDLRTSetPropEx()API function, the Position X and Position Yproperties of
the specified object are set. The first parameter of the API function denotes the
addressing mode of the object. The next three parameters denote the desired picture
name, object name and property name. To specify the desired property, the English
name, not the German one, must be used. For the previous example, these are Lef
t and
Top. The next parameter denotes the property type. In the following parameter, the
address of the variable is specified, which contains the new value of the property. The
next four parameters are not relevant for the desired functionality. In the last parameter,
the address of the error structure is specified.
The return value of every API function is checked in an ifstatement after it has been
called. If the call fails, this is indicated by an output. Part of this output includes the
information contained in the szErrorText structure element of the error structure.
Note:
In this sample, the return value of the API function is assigned to a variable of the BOOL
data type. This variable is then checked. The call of the API function and the check of the
return value can also be combined into one line. This procedure will be used in the
subsequent samples of this chapter.
4-80

C79000-G8276-C157-01
09.99
WinCC C-Course
4.8.2 Sam ple 2 - Creating a Tag Connection via an RT Function

In this sample, the application of the RT function of the Graphics Designer API for
creating a tag connection is shown. A tag connection is created at Property
Output/
Input
Output Value of an I/O Field. The sample has been configured at the
Button2object displayed below at Event
Mouse
Mouse Action.
C-Action at Button2
In the first section, the trigger.

hfile is integrated. This file contains the definition of a
symbolic constant used in this sample.
Next, two string variables are defined. Their content - the picture name and object name
- specifies the object to be edited.
To specify the properties of a tag connection, a separate data type is available. This is
the LINKINFO structure type. A linkvariable of the LINKINO data type is defined.
Next, a variable of the CMN_ERROR data type is defined.
The structure elements of the l
inkvariable are filled with the information of the desired
tag connection. The LinkType element is assigned the BUBRT_LT_VARIABLE_DIRECT
symbolic constant. This constant stands for a direct tag connection. The dwCycle
element is assigned the value 0, which corresponds to the Upon Change trigger. The
szLinkName element specifies the variable to be used.

C79000-G8276-C157-01
4-81
WinCC C-Course
09.99
Via the PDLRTSetLink()API function, a TagConnection at the specified object is

created. The first parameter of the API function denotes the addressing mode of the
object. The next three parameters denote the desired picture name, object name and
property name. In the following parameter, the address of the l
inkvariable is specified,
which determines the tag connection to be created. The next two parameters are not
relevant for the desired functionality. In the last parameter, the address of the error
structure is specified. If the call of the API function fails, this is indicated by an output.
Note:
The first two samples of this chapter refer to the I/OField1 object of the
cc_9_exampl
e_10x.
PDLpicture. The first sample changes the position of the object in the
picture, the second creates a tag connection at it. After a picture change, the modifications
made are lost. Ensure that after the execution of the CSfunctions described in the
subsequent samples, a picture change must always be performed. This means that changes
in the picture achieved by using on of the first two button will be lost after clicking on one
of the other buttons.
4-82

C79000-G8276-C157-01
09.99
WinCC C-Course
4.8.3 Sam ple 3 - Creating a New Object via a CS Function

In this sample, the application of the CSfunction of the Graphics Designer API for creating
a new object is shown. A new I/O Fiel
dwill be created. The sample has been configured at
the Button3object displayed below at Event
Mouse
Mouse Action.
C-Action at Button3

C79000-G8276-C157-01
4-83
WinCC C-Course
09.99
In the first section, the DLL of the Graphics Designer API is loaded. In addition, the
pdl
_guid.
hfile is integrated, which contains the definition of a symbolic constant used
in this sample.
Next, a szProjectName string variable for accepting the project name is defined.
Next, a string variable for accepting the picture name is defined. Note that the picture
name must include the file extension PDL(which differs from the RT functions).
Next, the additional variables required are defined. This includes a variable of the GUID
data type, which determines the object type to be created.
In the next section, the project name is determined via the DMGetRuntimeProject()API
function. The project name will be stored in the szProjectName variable. If the
determination of the project name fails, this will will be indicated by an output. In this
case, the C-Action is exited via the return statement.
In the next section, the Graphics Designer API is initialized by the
PDLCSGetOl
eAppPtr()API function. If the initialization of the Graphics Designer API
fails, this will be indicated by an output. In this case, the C-Action is exited via the
return statement as well.
In the next section, the picture to be edited is opened via the PDLCSOpenEx()API
function. As the next to last parameter, the dwFl
ags variable set to the value 1 is
transferred to the API function. This causes the picture not to be displayed on the
screen. If the opening of the picture fails, this will will be indicated by an output. Via
the goto statement, a jump is made to the code position where the connection to the
Graphics Designer API is terminated.
In the next section, a new object named I/OField2will be created via the
PDLCSNewObjectEx()API function. If the creation of the new object fails, this will
will be indicated by an output. Via the goto statement, a jump is made to the code
position where the previously opened picture is closed.
In the next section, the picture is saved via the PDLCSSave()API function. If saving the
picture fails, this will will be indicated by an output. Via the goto statement, a jump is
made to the code position - just as in the section above - where the previously opened
picture is closed.
Next, the picture to be edited is selected again via the project f
unction
ActualizeObjects().
Next, the previously opened picture is closed again via the PDLCSClose()API function.
Before this statement, a mark is inserted, which is the jump target for previous goto
statements.
Next, the connection to the Graphics Designer API is terminated again via the
PDLCSDel
Ol
eAppPtr()API function. Before this statement, a mark is inserted as well,
which is the jump target for a previous goto statement.
Note:
The C-Actions, which will be created in the subsequent samples are very similar to the CAction created in the present sample. We will therefore omit detailed explanations, which
have been provided in the present sample. The code descriptions will be limited to an
overview of the program
s execution.
4-84

C79000-G8276-C157-01
09.99
WinCC C-Course
4.8.4 Sam ple 4 - Changing Properties via a CS Function

In this sample, the application of the CSfunction of the Graphics Designer API for setting
the properties of objects is shown. The position of an object is changed by setting the
properties Position X and Position Y. The sample has been configured at the Button4object
Mouse
Mouse Action.
C-Action at Button4

C79000-G8276-C157-01
4-85
WinCC C-Course
09.99
In the first section, the DLL of the Graphics Designer API is loaded.
In the second section, the required variables are defined. The names of the properties
and the property values to be set are stored in vectors, as opposed to following the
procedure described in sample 1.
The project name is determined via the DMGetRuntimeProject()API function.
The Graphics Designer API is initialized by the PDLCSGetOl
eAppPtr()API function.
The picture to be edited is opened via the PDLCSOpenEx()API function.
Within a f
or loop, the properties of the object are set via the PDLCSSetPropertyEx()
API function. If properties of different types are to be set in this way, a vector must be
defined instead of the vt variable. This vector will determine the property type of each
property to be set.
The picture is saved via the PDLCSSave()API function.
The picture to be edited is selected again via the project f
unction Actual
izeObjects().
The picture is closed again via the PDLCSClose()API function.
The connection to the Graphics Designer API is terminated again via the
PDLCSDel
Ol
4-86

C79000-G8276-C157-01
09.99
WinCC C-Course
4.8.5 Sam ple 5 - Creating a Tag Connection via a CS Function

In this sample, the application of the CSfunction of the Graphics Designer API for creating
a tag connection is shown. A tag connection is created at Property
Output/
Input
Output Value of an I/O Field. The sample has been configured at the Button5object
Mouse
Mouse Action.
C-Action at Button5

C79000-G8276-C157-01
4-87
WinCC C-Course
09.99
In the second section, the required variables are defined.
In the next section, the structure elements of the l
inkvariable are filled with the
information of the desired tag connection.
The tag connection at the object is created via the PDLCSSetLink()function.
The picture is saved via the PDLCSSave()API function.
The picture to be edited is selected again via the project f
unction Actual
izeObjects().
PDLCSDel
Ol
4-88

C79000-G8276-C157-01
09.99
WinCC C-Course
4.8.6 Sam ple 6 - Listing Objects via a CS Function

In this sample, the application of the CSfunction of the Graphics Designer API for listing
objects contained in a picture is shown. For each available object, the API will call an
especially created function to which the information about the corresponding object is
transferred. Such a function is called a Callback function. The sample has been configured
Mouse
Mouse Action.
Project Function ObjectCallback()
In the first section, the pdl

csapi.
hfile is integrated, which contains the definition of the
OBJECT_INFO_STRUCTstructure type.
The data type of the return value as well as the data types and the quantity of transfer
parameters are specified for this function and can be obtained from the WinCC ODK.
Next, a pointer pointing to a variable of the OBJECT_INFO_STRUCTdata type is
defined. To this pointer, the address contained in the first transfer parameter is assigned.
The pointer is then checked for validity.
The name of the object, whose OBJECT_INFO_STRUCT was received, will be output.

C79000-G8276-C157-01
4-89
WinCC C-Course
09.99
C-Action at Button6
In the second section, the required variables are defined.
All objects contained in the picture will be listed by the PDLCSEnumObjList()API
function. For this purpose, the address of the previously created ObjectCallback()
project function is transferred to the API function. This type of function is also know as
a Callback function. It will be called once for every object contained in the picture, at
which point the data of one object will be transferred.
PDLCSDel
Ol
4-90

C79000-G8276-C157-01
09.99
WinCC C-Course

window:

C79000-G8276-C157-01
4-91
WinCC C-Course
09.99
4.9 Project Environm ent

In the WinCC project Project_C_Course, samples pertaining to the topic Project
Environment can be accessed by clicking on the navigation bar icon displayed below. The
samples are configured in the cc_9_example_11.PDL picture.
GeneralInform ation
Many times the programming of a C-Action or other function requires the specification of a
file path, the name of the local computer and such. These values can then be specified according to the current conditions - as absolute values. This can cause problems if a
project is transferred to another computer. The conditions encountered there are in all
likelihood different from those of the creation system. It is therefore recommended to
refrain from using absolute path specifications and such when creating a project. Instead
such information should be determined while in runtime. This chapter contains samples,
which illustrate how information about conditions on the local computer are accessed. For
this purpose, the WinCC API as well as the Windows API are used.
4-92

C79000-G8276-C157-01
09.99
WinCC C-Course
4.9.1 Sam ple 1- Determ ining the Project File

In this sample, the procedure for determining the project file of a WinCC project is
outlined. The sample has been configured at the Button1 object displayed below at Event
Mouse
Mouse Action.
C-Action at Button1
In the first section, a bRet variable of the BOOLdata type is defined.

Next, a szProjectFil
e string variable for accepting the project name is defined. The
length of this tag is set to accommodate (store)the longest possible path specification.
Next, the project name is determined via the DMGetRuntimeProject()API function. The
project name will be stored in the szProjectFile variable. As the second parameter, the
size of the memory space reserved for the project name is specified. As the third
parameter, the address of the error structure is specified. If no error information is
needed, NULL can be transferred.
Next, the return value of the DMGetRuntimeProject()API function is checked.
Next, the determined name of the project file is output. This output is displayed in the
next section.

window:

C79000-G8276-C157-01
4-93
WinCC C-Course
09.99
4.9.2 Sam ple 2 - Determ ining the Project Path

In this sample, the procedure for determining the project path of a WinCC project is
outlined. The sample has been configured at the Button2object displayed below at Event
Mouse
Mouse Action.
C-Action at Button2
In the first section, a bRet variable of the BOOLdata type is defined and initialized.
Next, a szProjectFil
e string variable for accepting the project name is defined. In
addition, a string variable is defined as char*and initialized with NULL.
Next, the return value of the DMGetRuntimeProject()API function is checked.
Next, the strrchr()function searches for the last position of the \ character in the
determined name of the project file. One position after the found character, a 0is
inserted. Only the path specification of the project file - without the name of the project
file itself - will remain.
Next, the determined project path is output. This output is displayed in the next section.
4-94

C79000-G8276-C157-01
09.99
WinCC C-Course

window:

C79000-G8276-C157-01
4-95
WinCC C-Course
09.99
4.9.3 Sam ple 3 - Determ ining the Project Path via a Project Function
In this sample, the determination of the project folder illustrated in the previous sample is
shifted to a project f
unction. The sample has been configured at the Button3object
Mouse
Mouse Action.
Project Function GetProjectPath()
A string variable is transferred to the project function, in which the determined project
path is written. The caller of the function must ensure that enough memory space has
been reserved for the string variable. If the function has been executed successfully can
be seen by its return value.
The procedure for determining the project path follows the same principle shown in the
previous sample.
The project path determined is copied to the transferred string variable via the strcpy()
function.
4-96

C79000-G8276-C157-01
09.99
WinCC C-Course
C-Action at Button3
In the first section, a bRet variable of the BOOLdata type is defined and initialized.
Next, a szProjectPathstring variable for accepting the project path is defined.
Using the previously created GetProjectPath()project function, the project path is
determined. Afterwards, the return value of the project f
unction is checked.
Next, the determined project path is output.

C79000-G8276-C157-01
4-97
WinCC C-Course
09.99
4.9.4 Sam ple 4 - Determ ining the Installation Folder

In this sample, the procedure for determining the installation folder of WinCC is outlined.
Mouse
Mouse Action.
C-Action at Button4
In the first section, a szProjectFil

e string variable for accepting the name of the project
file is defined.
Next, a dmDirInfo variable for accepting the path information is defined. This is a
variable of the DM_DIRECTORY_INFO structure type.
Next, a char*string variable is defined and initialized with NULL.
Via the DMGetProjectDirectory()API function, the dmDirInfo variable is filled with
the path information. One of the paths contained in the variable is the path to the Global
Library folder. This path is stored in the szGl
obal
LibDir structure element. The Global
Library folder is a subfolder of the WinCC installation folder.
4-98

C79000-G8276-C157-01
09.99
WinCC C-Course
With the first strrchr()function, the last \ character is searched for in the determined
path and replaced by a 0. With the second strrchr()function, the last \ character in the
remaining path is searched for. One position after, a 0is inserted.
Next, the determined installation folder is output. This output is displayed in the next
section.

window:

C79000-G8276-C157-01
4-99
WinCC C-Course
09.99
4.9.5 Sam ple 5 - Determ ining the Com puter Nam e

In this sample, the procedure for determining the local computer name is outlined. The
Mouse
Mouse Action.
C-Action at Button5
In the first section, the Windows DLL Kernel32 is integrated. Since only one function
of the DLL is required, this function is declared directly. In addition, a symbolic
constant for the maximum length of the computer name is defined.
Next, a bRet variable of the BOOLdata type is defined and initialized.
Next, a szComputerName string variable for accepting the computer name is defined. In
addition, a variable of the DWORD data type is defined, which is initialized with the
length of the previously defined string variable.
The name of the local computer is determined by the GetComputerNameA()Windows
function. This name is written to the szComputerName string variable transferred.
Next, the return value of the GetComputerNameA()Windows function is checked.
Next, the determined computer name is output.
4-100

C79000-G8276-C157-01
09.99
WinCC C-Course
4.9.6 Sam ple 6 - Determ ining the User Nam e

In this sample, the procedure for determining the user currently logged on to Windows NT
is outined. The sample has been configured at the Button6object displayed below at Event
Mouse
Mouse Action.
C-Action at Button6
In the first section, the Windows DLL advapi32 integrated. Since only one function of
the DLL is required, this function is declared directly. In addition, a symbolic constant
for the maximum length of the user name is defined.
Next, a bRet variable of the BOOLdata type is defined and initialized.
Next, a szUserName string variable for accepting the user name is defined. In addition,
a variable of the DWORD data type is defined, which is initialized with the length of the
previously defined string variable.
Via the GetUserNameA()Windows function, the name of the user currently logged on
to Windows NT is determined. This name is written to the szUserName string variable
transferred.
Next, the return value of the GetComputerNameA()Windows function is checked.
Next, the determined user name is output.

C79000-G8276-C157-01
4-101
WinCC C-Course
09.99
4.10 Windows API

The samples described in this chapter are configured in the cc_0_startpicture_00.PDL and
cc_2_keyboard_01.PDL pictures of the WinCC project Project_C_Course.
Windows Application Program Interface

In addition to the WinCC API, the entire Windows API can also be utilized in a WinCC
project. This provides almost unlimited access to the system.
The following samples provide you with an overview of this topic. With the help of these
samples, the general procedure for the application of the Windows API is shown. This is,
however, not an exhaustive treatment of the Windows API.
The functions of the Windows API are also located in various DLLs, just like the functions
of the WinCC API. The declarations of the functions are located in various header files.
The integration of the DLLs follows the same principle that has been used for the
integration of WinCC DLLs. The following sample program code illustrates the integration.
4-102

C79000-G8276-C157-01
09.99
WinCC C-Course
4.10.1 Sam ple 1 - Setting Windows Properties

This sample shows, how the properties of a Windows window can be changed. In this
sample, the title and geometry of the runtime window is changed. The sample is configured
at Event
Miscel
l
aneous
Open Picture of the cc_0_startpicture_00.
PDLstart
picture.
C-Action at the Start Picture
The Windows functions used in this sample are already known to the WinCC project.
Therefore no Windows DLL needs to be loaded.
In the first section, a variable of the HWND type is defined and initialized with NULL.
This variable is a so-called window handle - a pointer pointing to a Windows window.
Via the FindWindow()Windows function, the window handle of a Windows window
can be determined by specifying its window title. If the default title of the runtime
window is indicated, its window handle can be determined.
Via the SetWindowText()Windows function, the title of the runtime window can be
changed. In this sample, the title is changed to WinCC C-Course.
Via the SetWindowPos()Windows function, the position and dimensions of the runtime
window displayed on the screen can be specified. In this sample, the runtime window is
positioned at the top left corner (position 0/0)of the screen and is sized to 1024by 768.
The remaining statements of the above program code perform initializations that are not
relevant for this sample.

C79000-G8276-C157-01
4-103
WinCC C-Course
09.99
4.10.2 Sam ple 2 - Reading the System Tim e

This sample shows how the system time can be read and displayed. In this sample, the time
and date are displayed. The sample is configured at the cc_0_startpicture_00.
PDL picture.
C-Action at the Static Text Tim e
In the first section, the Windows DLL Kernel32 is integrated. Since only one function
of the DLL is required, this function is declared directly.
Next, the sysTime variable of the SYSTEMTIME data type is defined. This is a structure
type, which stores the system time.
Next, a szTime string variable for accepting the current time in the hh:mm format
defined.
Via the GetLocal
Time()Windows function, the current system time is written to the
sysTime variable.
Next, the current system time is set to the hh:mm format and returned as a return value
Miscel
l
aneous
Tooltip Text, another
via the sprintf()function. At Property
C-Action following the steps described is created. This C-Action delivers the current
date.
The function is executed in 1s cycles.
4-104

C79000-G8276-C157-01
09.99
WinCC C-Course
4.10.3 Sam ple 3 - Playing Sound Files

This sample shows how sound files can be played. In this sample, a sound file is played if
there is a switch from the navigation bar Basics to the navigation bar WinCC andWindows
APIand vice versa. The sample is configured in the cc_2_keyboard_01.
PDLpicture at the
Button1 object.
Project Function CC_PlaySound()
In the first section, the apdef

ap.
hfile is integrated. With this, other project functions can
also be called from the present project function.
The function header defines a string variable as the transfer parameter. With this
variable, the name of the sound file to be played is transferred.
In the next section, the Windows DLL winmm is integrated. Since only one function of
the DLL is required, this function is declared directly. In addition, two symbolic
constants are defined.

C79000-G8276-C157-01
4-105
WinCC C-Course
09.99
The project f
unction assumes that a sound subfolder exists in the project folder. In this
folder, the sound files used in the project are stored. The path to the desired sound file is
composed of the project path, the name of the sound folder and the transferred name of
the sound file. It will be stored in the szSoundPathvariable.
The sound is played via the Pl
aySound()Windows function. If the sound file cannot be
played, a brief beep sound is generated instead by the MessageBeep()Windows
function.
4-106

C79000-G8276-C157-01
09.99
WinCC C-Course
4.10.4 Sam ple 4 - Starting a Program

This sample shows the procedure for starting a program. For this purpose, an already
existing standardf
unction is utilized, which uses the Windows API. The sample is
configured at the cc_0_startpicture_00.
PDL picture.
Standard Function Program Execute()
The standardf
unction ProgramExecute()simply forwards the parameter transferred to
the WinExec()Windows function. The return value of the WinExec()function is
forwarded to the caller of the ProgramExecute()function. The start of a program was
successful, if the return value is greater than 31.
C-Action at Graphic Object Execute
Via the standardfunction ProgramExecute(), the program calc.

exe is started. This is the
Windows calculator program. No path needs to be specified, since this is not necessary
for programs located in the Windows folder.

C79000-G8276-C157-01
4-107
WinCC C-Course
09.99
4.11 Standard Dialogs

In the WinCC project Project_C_Course, samples pertaining to the topic Standard Dialogs
can be accessed by clicking on the navigation bar icon displayed below. The samples are
GeneralInform ation
The regular procedure for creating a dialog in WinCC consists of creating a WinCC picture
and then have this picture displayed using a Picture Window. There is also the possibility to
create standard dialogs in C-Actions or other functions. In this case, WinCC standard
dialogs as well as Windows dialogs can be used.
In this chapter, the application of some of the available standard dialogs is shown. There a
number of available standard dialogs that will not be mentioned here. Information about
these dialogs can be found in the WinCC ODK and the Windows API documentation.
4-108

C79000-G8276-C157-01
09.99
WinCC C-Course
4.11.1 Sam ple 1 - Language Switch

This sample shows, how the WinCC standard dialog for the language switch can be used.
The sample has been configured at the Button1 object displayed below at Event
Mouse
Mouse Action.
C-Action at Button1
In the first section, the variables used are defined. Among others, a vector consisting of
the IDs of the three desired languages is defined.
Via the FindWindow()Windows function, the window handle of the runtime window is
determined using its window title. Note that the window title specified in this code
sample is not the default title of the runtime window.
Via the DMShowLanguageDial
og()API function, the standard dialog for the language
switch is displayed. A vector with the IDs of the languages to be displayed in the dialog
is transferred to this function. The function writes the ID of the language selected by the
user to the dwGetLocal
eID variable transferred.

C79000-G8276-C157-01
4-109
WinCC C-Course
09.99
The return value of the DMShowLanguageDial

og()API function is checked. Among
others, this return value can have the value FALSE, if the user terminates the dialog by
clicking on Cancel
.
The dialog used here only switches the CSlanguage. In order to switch the RT
language, the internalf
unction SetLanguage()must be used. The ID of the language
selected in the dialog is transferred to this function.
Select Language Dialog

If the C-Action detailed above is executed, the following dialog will be displayed:
4-110

C79000-G8276-C157-01
09.99
WinCC C-Course
4.11.2 Sam ple 2 - Tag Selection

This sample shows, how the WinCC standard dialog for the tag selection can be used. The
content of the tag selected from the dialog is displayed in an I/O Field. The sample has
Mouse
Mouse
Action.
C-Action at Button2
In the first section, the trigger.

hfile is integrated. This file contains the definition of a
symbolic constant used in this sample.
In the next section, the variables used are defined. Among others, a dmVarKey variable
for accepting information about the WinCC tag selected in the dialog and a l
inkvariable
for accepting information about the tag connection are defined.
determined using its window title.

C79000-G8276-C157-01
4-111
WinCC C-Course
09.99
Via the DMShowVarDatabase()API function, the tag selection dialog is opened.

Information about the WinCC tag selected in the dialog is stored in the dmVarName
variable transferred.
If a tag has been selected, its name will be displayed in a Static Text field and its content
in an I/O Field.
Select Tag Dialog

4-112

C79000-G8276-C157-01
09.99
WinCC C-Course
4.11.3 Sam ple 3 - Error Box

This sample shows, how a Windows error box can be displayed. The sample has been
Mouse
Mouse
Action.
C-Action at Button3
In the first section, a hWndvariable of the HWND data type is defined. Via the
FindWindow()Windows function, the window handle of the runtime window is
assigned to this variable.
Via the MessageBox()Windows function, an error box is opened. As the second
parameter, the error text and as the third parameter, the title of the error box are
specified. The fourth parameter specifies the appearance and behavior of the error box.
The error box only contains an OK button (MB_OK), displays the error symbol
(MB_ICONSTOP)and is modal (MB_APPLMODAL). In this way, the user must
acknowledge the error box first, before he or she can proceed.
If a tag has been selected, its name will be displayed in a Static Text field and its content
in an I/O Field.
Error Box
If the C-Action detailed above is executed, the following error box will be displayed:

C79000-G8276-C157-01
4-113
WinCC C-Course
09.99
4.11.4 Sam ple 4 - Question Box

This sample shows, how a Windows question box can be displayed and how another action
can be performed depending on the button pressed by the user. The sample has been
Mouse
Mouse
Action.
C-Action at Button4
In the first section, a hWndvariable of the HWND data type is defined. In addition, a
iRet variable of the int type is defined.
determined using its window title.
Via the MessageBox()Windows function, a question box is opened. The fourth
parameter specifies the appearance and behavior of the question box. The question box
only contains a Yes and No button (MB_YESNO), displays a question mark
(MB_ICONQUESTION)and is modal (MB_APPLMODAL). The return value of the
function is stored in the iRet variable.
In the last section, the return value of the function is analyzed. If the dialog was ended
with Yes, the return value is IDYES, if the dialog was ended with No, the return value is
IDNO.
4-114

C79000-G8276-C157-01
09.99
WinCC C-Course
Question Box
If the C-Action detailed above is executed, the following question box will be displayed:

C79000-G8276-C157-01
4-115
WinCC C-Course
09.99
4.11.5 Sam ple 5 - Open Standard Dialog

This sample shows, how the standard dialog for opening a file can be displayed. The
Mouse
Mouse Action.
C-Action at Button5
In the first section, the Windows DLL comdl

g32is integrated.
In the next section, the variables required are defined. Among others, a of
n variable of
the OPENFILENAME structure type is defined.
In the next section, the of
n variable is filled with information.
The of
n variable is transferred to the GetOpenFil
eName()Windows function. This
function opens the file selection dialog. The name of the file selected by the user is
stored in the of
n variable. The name of the file selected is output.
4-116

C79000-G8276-C157-01
09.99
WinCC C-Course
Open Standard Dialog

AdditionalSam ples
The subsequent samples in this chapter deal - just like sample 5- with the standard file
dialogs.
In sample 6, the Save As dialog is used.
In sample 7, the project f
unction GetFil
eName()is created, which facilitates dealing with
the standard file dialogs. This function can, depending on the symbolic constant transferred,
display an Open or a Save As dialog. Symbolic constants available are GFN_OPEN and
GFN_SAVE.

C79000-G8276-C157-01
4-117
WinCC C-Course
09.99
4.12 Files
In the WinCC project Project_C_Course, samples pertaining to the topic Files can be
Open FiIe
In C, a file is viewed - independent of its content - as a collection of characters. Before a
file can be used in a C-Action or another function, it must be openend. If the work with a
file is complete, the file should be closed.
A file is opened using the fopen()function. In the program code displayed below, the
application of the fopen()function is shown.
In order to be able to work with the file, a pointer pointing to it must be defined. For this
purpose, the FILE*data type is available. The fopen()function returns a pointer pointing to
the opened file or NULL, if opening the file has failed. As the first parameter, the name of
the file to be opened with path specification must be transferred to the fopen()function. As
the second parameter, the mode with which the file is opened (e.g. for reading)is
transferred to the function. The values that can be specified for the mode are listed in the
table below.
4-118
M ode
Description
Opens a file for reading. The return value is NULLif the file does not exist or
there is no read authorization.
Opens a file for writing. The return value is NULLif the file does not exist or
there is no write authorization.
Opens a file for being attached to the end. If the file does not exist, it is created.
The return value is NULLif no file can be created or the file cannot be written to.
r+
Opens a file for being read and written to alternately. The return value is NULLif
the file does not exist or there are no read and write authorizations for the file.
w+
Creates a file for being read and written to alternately. If the file already exists, it
will be deleted. The return value is NULL if no rights for these actions are
available.
a+
Opens a file for being read or attached to the end. The file is created if it does not
exist. The return value is NULLif no read and write rights for the file are
available.

C79000-G8276-C157-01
09.99
WinCC C-Course
Close File
After completing the work with the file, the file should be closed. A file is closed using the
fclose()function. In the program code displayed below, the application of the fclose()
function is shown. The pointer pointing to the file to be closed is transferred to the function.
Writing To and Reading a File

For writing to a file, a function similar to the printf()function is available. This is the
fprintf()function. The application of the fprintf()function follows the same principle as the
application of the printf()function. The output, however, is not made to a Global Script
Diagnostics Window, but to a file. As the first parameter, the function expects a pointer
pointing to this file. In the program code displayed below, the application of the fprintf()
function is shown.
For reading a file, the fscanf()function is available. The fscanf()function is structured

identically to the fprintf()function. However, instead of specifying the variables whose
values are written to the file, the addresses of the variables are specified to which the
contents of the file are written to.

C79000-G8276-C157-01
4-119
WinCC C-Course
09.99
4.12.1 Sam ple 1 - Securing Data

This sample shows, how data can be written to a file. The data to be written is first read
from WinCC tags. The sample has been configured at the Button1 object displayed below at
Event
Mouse
Mouse Action.
C-Action at Button1
In the first section, the variables required are defined. Among others, a variable of the
FILE*type is defined and initialized.
Via the project f
unction GetProjectPath(), the project path is determined.
Next, the path to the file to be created is compiled by the strcat()function. This path is
transferred to the f
open()function. With this function, the desired file is opened or
created.
In the next section, the data to be written is read from the WinCC tags.
Via the f
printf()function, the data is written to the file. Afterwards, the file is closed
again.
4-120

C79000-G8276-C157-01
09.99
WinCC C-Course
4.12.2 Sam ple 2 - Reading Data

This sample shows, how data can be read from a file. The data read is written to WinCC
tags. The sample has been configured at the Button2object displayed below at Event
Mouse
Mouse Action.
C-Action at Button2
Via the project f
Next, the path to the file to be opened is compiled by the strcat()function. This path is
open()function. With this function, the desired file to be read is
opened.
Via the f
scanf()function, the data is read from the file. Afterwards, the file is closed
again.
In the next section, the data read is written to the WinCC tags.

C79000-G8276-C157-01
4-121
WinCC C-Course
09.99
4.12.3 Sam ple 3 - Reporting

This sample shows, how a report file can be created. A project f
unction is created to which
a report text is transferred. This text will then be written into the report file. The sample has
Mouse
Mouse
Action.
Project Function LogText()
A string variable is assigned to the function, which will be attached to the end of the
report file.
Via the project f
Next, the path to the file to be opened is compiled by the strcat()function. This path is
open()function. With this function, the desired file to be attached is
opened.
Via the f
printf()function, the report text transferred is entered into the file. Before each
report entry, the current system time is entered via the standardf
unction
GetLocal
TimeString(). Afterwards, the file is closed again.
4-122

C79000-G8276-C157-01
09.99
WinCC C-Course
C-Action at Button3
In the C-Action, the content of a WinCC text tag is read and transferred to the
previously created project f
unction LogText(). Consequently, the content of the WinCC
text tag is entered into the report file.

C79000-G8276-C157-01
4-123
WinCC C-Course
09.99
4.13 Dynam ic Wizard

In the WinCC project Project_C_Course, samples pertaining to the topic Dynamic Wizard
can be accessed by clicking on the navigation bar icon displayed below. The samples are
GeneralInform ation
The Dynamic Wizard is available in the Graphics Designer as an additional function. It can
support the user with often repeated configuration processes. This reduces the configuration
efforts and decreases possible configuration errors.
The Dynamic Wizard is made up of various Dynamic Wizard functions. A large number of
Dynamic Wizard functions are already available. They can be complemented by useddefined functions.
Working with the Dynam ic Wizard

The Dynamic Wizard is displayed in the Graphics Designer via the View
Toolbars
Dynamic Wizard menus. The following shows the structure of the Dynamic Wizard.
In the various tabs, Dynamic Wizard functions already available are displayed. Via a
on the desired Dynamic Wizard function, the function is started.
A Dynamic Wizard function consists of multiple pages that must be filled out by the user.
These pages include a start page, a trigger page, various option pages and a final page,
which summarizes the settings made in the previous pages.
4-124

C79000-G8276-C157-01
09.99
WinCC C-Course
4.13.1 Creation ofDynam ic Wizard Functions

For the creation of user-defined Dynamic Wizardfunctions, a separate editor is available.
This editor is located in the \
bin folder: is the dynwizedit.
exe program.
Each Dynamic Wizardfunction is stored in a separate script file. For each of the languages
German, English and French, a separate script file exists. These script files - depending on
the language - are stored in the following folders:
WinCC Instal
l
ationFol
der\Wscripts\Wscripts.
deu
WinCC Instal
l
ationFol
enu
WinCC Instal
l
ationFol
f
ra
After starting the Dynamic WizardEditor, select the desired language for which the new
Dynamic Wizardfunction is created from the toolbar.
A Dynamic Wizardfunction must follow a prescribed structure. In the scope of this manual,
two samples for the creation of Dynamic Wizardfunctions are provided. The script files, in
which these samples are located, are stored in the DynWizsubfolder - especially created for
this purpose - of the WinCC project Project_C_Course. These script files must be copied to
the folders listed above, where the default script files are located. Afterwards, the samples
can be opened from the Dynamic WizardEditor.
Dem o Wizard
In the Demo.
wnfscript file, a Dynamic Wizardnamed Demo Wizardhas been created. This
Wizard displays basic functions which enable the user to enter data comfortably. However,
this Dynamic Wizarddoes not perform any actions.
Making a Motor Dynam ic Wizard

In the Motor.
wnfscript file, a Dynamic Wizardnamed MakingaMotor Dynamic has been
created. This Wizard has been especially created to add dynamics to a customizedobject
named Motor and cannot be used for any other object type. This customizedobject is stored
in the project library of the WinCC project Project_C_Course and can be inserted from
there into a picture. The customizedobject Motor is connected to a WinCC structure tag of
the Motor structure type via the Dynamic WizardMakingaMotor Dynamic. More
specifically, various C-Actions and tag connections are created at this object. It is assumed
that an internal WinCC text tag T08i_course_wiz_sel
ectedexists. With the help of this tag,
the currently selected motor object can be marked.
Com piling Script Files

A completely created Dynamic Wizardfunction must be compiled via the Dynamic Wizard
Compil
e Script menus and then be saved. In order to use the Dynamic Wizard
function in the Graphics Designer, it must be integrated into the database of the Dynamic
Wizard. This is done via the menus Dynamic Wizard
ReadingWizardScript.The
script file to be read must be selected from the dialog displayed.

C79000-G8276-C157-01
4-125
WinCC C-Course
09.99
4.13.2 Structure ofa Dynam ic Wizard Function

The following explains the various sections that make up a Dynamic Wizardfunction.
Integration ofHeader Files and DLLs

The first part of a Dynamic Wizardfunction is the integration of the required header files.
The most important file to be integrated is the dynamic.
hfile, in which the functions
pertaining to the appearance of the Dynamic Wizard
s user interface are declared. In
addition, all desired DLLs of the Windows or WinCC API can be integrated here.
Language-Dependent Definitions
If the Dynamic Wizardfunction is to be available in several languages, a separate script file
must be created for each language. Therefore, language-dependent texts should be defined
before the program code. Then, a script file created for a certain language can simply be
copied. Only the section with the language-dependent definitions must then be adapted.
Properties List
There is the option to specify, if a Dynamic Wizardfunction can only be used for certain
object types. This is done by specifying a list of object properties. If an object has one or
more of the properties listed, the Dynamic Wizardfunction can be used for this object. This
option has been applied to the Dynamic WizardMakingaMotor Dynamic to only make this
Wizard functional for customizedobjects of the Motor type. This object type only has the
properties Manualand Selection. If a blank properties list is used, a Dynamic Wizard
function can be applied to all object types. In any case, a properties list must exist, even if it
is blank.
4-126

C79000-G8276-C157-01
09.99
WinCC C-Course
Processing Function
The processing function is the function which performs the actual work of the Dynamic
Wizardfunction after the Finishbutton is pressed. The name of this function must be
specified in the system interface. An extensive processing function is presented in the
Dynamic WizardMakingaMotor Dynamic.
Info Function
The info function summarizes the settings made by the user and displays them in summary
form on the last page of the Dynamic Wizardfunction. The name of this function must be
specified in the system interface.
System Interface
Via the system interface, various properties of the new Dynamic Wizardfunction are
specified. The meaning of the individual parameters are explained following the code
sample.
The first parameter specifies in which tab the Dynamic Wizardfunction is displayed.
The second parameter specifies under which name the Dynamic Wizardfunction is
displayed.
As the third parameter, NULL is always transferred.
The fourth parameter contains the name of the icon used for the Dynamic Wizard
function.
As the fifth parameter, a help text describing the functionality of the Dynamic Wizard
function in more detail can be transferred.

C79000-G8276-C157-01
4-127
WinCC C-Course
09.99
As the sixth parameter, a list containing the names of the individual option pages of the
function created is specified. This list must conclude with a NULLentry. A maximum
of five option pages can be created.
As the seventh parameter, the name of the processing function is specified, which is
called after the Finishbutton is pressed.
As the eighth parameter, the name of the function is specified, which summarizes the
settings made in the option pages and displays them before the user presses the Finish
button.
As the ninth parameter, a list of triggers to be displayed on the trigger page is specified.
For the most frequently occurring application cases, macros are available which will fill
out this trigger list.
GlobalVariables
For each parameter to be set in the option pages, a global variable must be defined. This
ensures that the parameters set are known to all functions created and can be worked with.
Option Pages
For each option page required, a separate function must be created. The names of these
functions must be specified in the system interface.
4-128

C79000-G8276-C157-01

WinCC C-Course PDF

Uploaded by

Copyright:

Available Formats

WinCC C-Course PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

WinCC C-Course PDF

Uploaded by

Copyright:

Available Formats

What are the different sections of the sample project interface?

What are the different sections of the sample project interface?

What are the two editors provided by WinCC for creating C-Scripts?

What are the two editors provided by WinCC for creating C-Scripts?

09.

WinCC Configuration Manual

Sam ple Project

WinCC Configuration Manual

4.1 Developm ent Environm ent for C-Scripts

WinCC Configuration Manual

4.1.1 Action Editor ofthe Graphics Designer

WinCC Configuration Manual

Structure ofa C-Action

WinCC Configuration Manual

WinCC Configuration Manual

Creation ofa C-Action

Procedure:Creation ofa C-Action

Open the Graphics Designer editor.

The Edit Action editor is opened by

The Edit Action editor will be displayed.

WinCC Configuration Manual

Procedure:Creation ofa C-Action

Another automatically generated code section consists of two comment blocks.

For this, the desired function is selected via a

WinCC Configuration Manual

Procedure:Creation ofa C-Action

WinCC Configuration Manual

Defining WinCC Tags and WinCC Pictures

WinCC Configuration Manual

4.1.2 The GlobalScript Editor

WinCC Configuration Manual

Creation ofa Project Function

Procedure:Creation ofa Project Function

WinCC Configuration Manual

Procedure:Creation ofa Project Function

Programming the function body.

The completed project f

WinCC Configuration Manual

Creation ofa GlobalAction

Procedure:Creation ofa Global Action

WinCC Configuration Manual

Procedure:Creation ofa Global Action

Programming the action body.

The completed action must be saved.

WinCC Configuration Manual

Output of a decimal number (int or char)

Output of a variable of the type long as a decimal number

Output of a character (char)

Output of a number in hexadecimal format (with lower case a...f)

Output of a number in hexadecimal format (with upper case A...F)

Output of a number in octal format

Output of a decimal number (only for unsigned types)

Output of a float value in floating point notation, e.g. 3.43234

Output of a float value in exponential notation, e.g. 23e+432

Like %e, but with upper case E, e.g. 23E+432

Output of a character string (char*)

Output of a double value

Output of a line change (carriage return)

Output of a line feed