WinCC Stuff

09.99 WinCC C-Course

WinCC Configuration Manual 4-1C79000-G8276-C157-01

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 C-Course 09.99

4-2 WinCC Configuration Manual

C79000-G8276-C157-01

Sample 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.1 Development Environment 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.1.1 Action Editor of the 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.



Structure of a C-Action

In general, a C-Action corresponds to a function in C. There are two different types of C-

Actions: 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 (long in the sample code), the function header is identical for all properties. Three

parameters are transferred to the C-Action. These are the Picture Name

(lpszPictureName), the Object Name (lpszObjectName) and the Property Name

(lpszPropertyName).

• 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 long type.

• 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

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 lpszPictureName (Picture Name),

lpszObjectName (Object Name) and lpszPropertyName (Property Name) are transferred

to the C-Action. The lpszPropertyName 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 long type.

• 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 void type, i.e. no return value is expected.



Creation of a C-Action

The following table describes the individual steps required to create a C-Action.

Step Procedure: Creation of a C-Action

1 Open the Graphics Designer editor.

Open the desired WinCC picture.

Open the Object Properties dialog box of the desired object.

2The Edit Action editor is opened by R on the desired property or event and

then selecting C-Action from the pop-up menu.

3 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 apdefap.h is integrated. Through

this file, all project functions, standard functions as well as internal functions 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 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 C-

Action. 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.

5 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 Tag dialog, 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.

6 Another aid is the function selection in the left window of the action editor.

Using the function selection, all available project functions, standard functionsand internal functions 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

Assigning Parameters 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.




7 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 C-

Actions 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

window. Via a D on an error message in the output window, you can jump

directly to the corresponding code line.

8 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.

9 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

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.1.2 The Global Script 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 C-

Actions:

• 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 function 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 C-Action at the object, the picture volume is reduced. This results in faster picture opening

times and a higher performance in runtime.

• Password Protection: Project functions 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 standard functions are available. Contrary to the project functions, the

standard functions are available to all WinCC projects. Existing standard functions can be

changed. New standard functions 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.

Internal Functions

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

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 Global Script Runtime is checked in the startup list of the computer, all global actions

and all local actions belonging to the computer will activated upon project start.

Creation of a 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 of a Project Function

1 Open the Global Script editor.

2Via a R on the Project Functions entry and then selecting New Function

from the pop-up menu, the basic framework of a new project function will be

created.



Step Procedure: Creation of a Project Function

3 The project function 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 functions or standard functions are to be used in the present

function, the apdefap.h file must be integrated. This is done via the preprocessor

command #include "apdefap.h", which must be inserted before the function

header.

4 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.

5 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 D on

an error message in the output window, you can jump directly to the

corresponding code line.

6 Via the toolbar button displayed below, a description can be added to the project

function. Together with the description, a password can be defined to protect the

project function from unauthorized access.

7 The completed project function must be saved using an appropriate name.



C79000-G8276-C157-01

Creation of a Global Action

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 of a Global Action

1 Open the Global Script editor.

2Via a R on the Global Actions entry and then selecting New Actionfrom the pop-up menu, the basic framework of a new action will be created.

3 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.



Step Procedure: Creation of a Global Action

4 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.

5 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 function 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.

6 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

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 %d used in the sample above signals

the output of a decimal number. Additional possible combinations and their descriptions

can be found in the following table:

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



Global Script 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 Diagnostics W indow

1 Open the Graphics Designer editor.

Open the desired WinCC picture.

2 Configure a Smart Object Application Window.

After placing the application window in the picture, the Window Contents dialog

will be opened. From the list-box, select the Global Script entry. Exit the dialog

by clicking on OK.

The Template dialog will be opened. From the list-box, select the GSCDiagnostics entry. Exit the dialog by clicking on OK as well.

3 In order to work comfortably with the Global Script Diagnostics Window, it is

recommended to set all properties in the Object Properties dialog under the

Miscellaneous entry to Yes.



C79000-G8276-C157-01

Step Procedure: Global Script Diagnostics W indow

4 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.



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

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 4 Bytes.

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 4 Bytes, whereas a variable of the double data type has a

memory requirement of 8 Bytes.

Value Ranges of Data 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 Value Range

int -2 147 483 648 to 2 147 483 647

unsigned int 0 to 4 294 967 295

short -32 768 to 32 767

unsigned short 0 to 65 535

long -2 147 483 648 to 2 147 483 647

unsigned long 0 to 4 294 967 295

char -128 to 127 (all ASCII characters)

unsigned char 0 to 255 (all ASCII characters)

float -10 3̂8 to 0 3̂8

double -10 3̂08 to 0 3̂08



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, long, shortand 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

Output in the Diagnostics Window

The sample described in this section generates the following output in the diagnostics

window:



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 Button2 object 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 INT defined data type and their unsigned counterparts BYTE, WORD,

DWORD and UINT are defined. In addition, a variable of the BOOL data type is

defined. Variables of the BOOL data 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 thesample 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



window:

Type Definition

Data types used in this section have been assigned using the typedef command. The

following program code illustrates how the BYTE data type has been defined. BYTE is

simply the alias name for the default data type unsigned char 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:

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



4.2.3 Sam ple 3 - WinCC Tags (Integers)

In most cases, to solve tasks for making objects dynamic and similar things through a C-

Action 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 Button3 object 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 SetTag and 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 GetTag functions for reading

WinCC tags.



C79000-G8276-C157-01

• If a variable of the of the BOOL data type (alias name for int) is transferred to theSetTagBit() function, the compiler will issue a warning. This is done, because the

SetTagBit() function expects SHORT as the data type of the transferred variable.

Therefore, the content of the bNumber variable is converted to SHORT in 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 float

data type can be converted to the int data type.

Data Types of WinCC 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 GetTag functions.

Data Type of the W inCC Tag Data Type of the 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

Unsigned 16-Bit Value WORD

Unsigned 32-Bit Value DWORD



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 Button4 object displayed below at Event

Mouse Mouse Action.

C-Action at Button4

• In the first section, the variables are defined. One variable each of the float and doubledata 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 float type goes approximately to the seventh decimal

place. A variable of the double type can display numbers twice as accurate. This can be

seen in the output of the number values - using the printf() function - in the diagnosticswindow. 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.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 SetTag and 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 Button5 object displayed below at Event Mouse Mouse Action.

C-Action at Button5

• In the first section, the variables are defined. One variable each of the float and doubledata 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 SetTag functions used here for writing to WinCC tags,

GetTag functions for reading WinCC tags are also available.



4.2.6 Sam ple 6 - Static and External Variables

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.

External Variables

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 CreateExternalTags() 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

• Miscellaneous

• 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

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. Thiswill 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.3 Operators and Mathematical Functions 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, bit-

by-bit operators and assignment operators.

Mathem atical Operators

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

Bit-by-Bit Operators

These operators make it possible to set, query or reset individual bits in variables.


& 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

Logical Operators

All logical operators follow the same rule: 0 is FALSE, all other numbers are TRUE. These

operators either generate a 0 (FALSE) or a 1 (TRUE).


> 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



4.3.1 Sam ple 1 - Basic Mathematical Operations

In this sample, the basic mathematical operators are used. The sample has been configured


C-Action at Button1

• In the first section, two variables of the float data type are defined and initialized. The

mathematical operators are applied to these two variables.

• In the next section, four additional variables of the float 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.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


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.





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.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 Button3 object 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

(unsigned 16-Bit values). 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 Button6object. 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

(unsigned 8-Bit value).



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 dwValue1 and

dwValue2 variables. 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 dwValue1 and dwValue2 variables are connected bit-by-bit

depending on the content of the byOperation variable. The connection result is stored in

the dwResult variable. The connection operation to be performed is selected by a switch-

case construction. This construction is described in greater detail in the Loops chapter.

• In the next section, the connection result contained in the dwResult variable is written to

the corresponding WinCC tag.



C79000-G8276-C157-01

4.3.4 Sample 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 (unsigned 16-Bit value) byte-by-byte. This means the exchange of the high byte

and low byte. The sample has been configured at the Button4 object 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 dwValue variable.

• In the next section, the individual bits of the dwValue variable are moved to the left by

eight positions (one byte) and stored in the dwtempValue1 variable. Afterwards, the

individual bits of the dwValue variable are moved to the right by eight positions and

stored in the dwtempValue2 variable. Both values determined in this section are

connected bit-by-bit (OR) and the result stored in the dwValue variable.

• In the next section, the rotated variable value contained in the dwValue variable is

written to the corresponding WinCC tag.



4.3.5 Sam ple 5 - Mathem atical Functions

In this sample, various mathematical functions are used which are available in C by default.

The sample has been configured at the Button5 object displayed below at Event

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 thissample, the return value of the function corresponds to the third power of the dValue

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



window:

Additional Mathematical Functions

In the function selection, the mathematical functions can be found at Internal Functions

c_bib math. The following illustration depicts all available mathematical

functions (shaded gray).



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 5 variables of the int data type is defined.



C79000-G8276-C157-01

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 t r i n g 1 \0

S t r i n g 2 \0 ? ?



4.4.1 Sam ple 1- Pointers

In this sample, the basic pointer operations are performed. The sample has been configured


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 iValue1 variable is assigned to the pointer. Its address and

content is again output via the printf() function.

• Next, the address of the iValue2 variable 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.4.2 Sam ple 2 - Vectors

In this sample, the basic vector operations are performed. The sample has been configured


C-Action at Button2

• In the first section, a vector consisting of 5 variables 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 for 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.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 Button3 object displayed below at Event Mouse Mouse

Action.

C-Action at Button3

• In the first section, a vector consisting of 5 variables of the int data type is defined. Thevector 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 for loop by advancing the pointer to the individual elements

and the content operator *.



C79000-G8276-C157-01

• Next, the individual elements of the vector are accessed again. This time, however, thename of the vector itself is used as the pointer. The output of the program is displayed

in the next section.



window:



4.4.4 Sam ple 4 - Strings

In this sample, working with string variables is explained. The sample has been configured


C-Action at Button4

• In the first section, a character string (vector consisting of 13 characters) 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 for 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.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. Thefunction 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 strlen() 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.5 Loops and Conditional Statements

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-while 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

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.

Conditional Statem 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.5.1 Sam ple 1 - while Loop

In this sample, the application of the while loop is explained. The sample has been


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.5.2 Sam ple 2 - do-while Loop

In this sample, the application of the do-while loop is explained. The sample has been


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.5.3 Sam ple 3 - for Loop

In this sample, the application of the for loop is explained. The sample has been configured


C-Action at Button3


initialized.

• Next, a for 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.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 break statement. The sample has been

configured at the Button4 object displayed below at Event Mouse MouseAction.

C-Action at Button4

• In the first section, the symbolic constant MAX_COUNT is 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.



• In the loop, the iCount counter variable is checked. If this variable exceeds the value of

MAX_COUNT, the loop is exited via the break statement.

• The iCount counter variable will be incremented.

• The progress display shows the loops already performed in percent. For every newpercent 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 Global

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.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


Action.

C-Action at Button5

• In the first section, a byValue 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 byValue variable using

the GetTagByte() function.

• Next, a if-else statement is programmed. This statement makes - depending on the

content of the byValue variable - an output via the printf() function.



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


Action.

C-Action at Button6

• In the first section, a byValue 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 byValue variable using

the GetTagByte() function.

• Next, a switch-case statement is programmed. This statement makes - depending on thecontent of the byValue 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.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 Parameters

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.6.1 Sam ple 1 - Transfer of Value Parameters

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 MeanValue(). Three

variables of the double data type are transferred to the function. A variable also of the

double data type will be returned.

• Next, a variable of the double 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

C-Action at Button1

• In the first section, three variables of the double data type are defined and initialized.The mean value of these three tags is to be calculated. An additional variable of the

double data type is defined which will store the result of the calculation.

• Using the previously created function MeanValue(), the mean value of the variables

transferred is calculated.

• The result of the calculation is output via the printf() function. This output is displayed



The sample described in this section generates the following output in the diagnosticswindow:



4.6.2 Sam ple 2 - Transfer of Address 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 MeanValueVector(). Apointer pointing to a variable of the double 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 double data type will be returned.

• Next, a variable of the double 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

for 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

C-Action at Button2

• In the first section, a vector consisting of three variables of the double data type isdefined and initialized. The mean value of these three tags is to be calculated. An

additional variable of the double data type is defined which will store the result of the

calculation.

• Using the previously created function MeanValueVector(), 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.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 BOOL type. The sample has been configured at the Button3 object 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 for loop, the elements of the vector transferred are filled by the rand() function

with random numbers.



C79000-G8276-C157-01

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 if statement.

• The individual elements of the iVector vector are output via the printf() function. This

output is displayed in the next section.



window:



4.6.4 Return of the 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


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

• 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 internalfunction SysMalloc(). 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 SysMalloc() function will be checked. If not enough

memory space was available, the function is terminated and NULL returned.

• Using a for 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 randomnumbers 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.





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.7 Structures

In the WinCC project Project_C_Course, samples pertaining to the topic structures can be



Definition of a 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 of a 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.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_POINT structure 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 C-

Action 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 SetLeft() and SetTop() functions.



C79000-G8276-C157-01

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 Button2 object

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 structuretype 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_RECT can be used.



C-Action at Button2

• In the first section, a rect variable of the CC_RECT data 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_RECT data 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.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_RECT data type defined in the previous sample. The

sample has been configured at the Button3 object displayed below at Event Mouse

Mouse Action.

WinCC Structure Type Creation

Step Procedure: W inCC Structure Type Creation

1A new WinCC structure type is defined in the WinCC Explorer. 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.

2 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.

3 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 Left and is of the LONG data type. For the element, the

radio-button Internal Tag is 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.



Step Procedure: W inCC Structure Type Creation

4 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_RECT data type is defined. The CC_RECTdata 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.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 Button4 object displayed below at Event

Mouse Mouse Action.

Project Function GetTagRect()

• In the first section, the apdefap.h file is integrated, which contains the definition of the

tagCC_RECT structure 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_RECT data type.



• 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_RECTdata type. This is ensured by the internal function SysMalloc(). 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 SysMalloc() 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_RECT data

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_RECT data 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

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 Miscellaneous

Open Picture of the cc_9_example_04.PDL picture to initialize the WinCC structure tag.



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

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 CS functions 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 CS functions (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 CS functions, since from, the basic principle of

its application can be deduced for your own projects.

Sample 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.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


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 4 Bytes).



C79000-G8276-C157-01

• For the Position X and Position Y properties 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 Y properties 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 Left 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 if statement 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.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

Button2 object displayed below at Event Mouse Mouse Action.

C-Action at Button2

• In the first section, the trigger.h file 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 link variable of the LINKINO data type is defined.

• Next, a variable of the CMN_ERROR data type is defined.

• The structure elements of the link variable are filled with the information of the desired

tag connection. The LinkType element is assigned the BUBRT_LT_VARIABLE_DIRECTsymbolic 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

• Via the PDLRTSetLink() API function, a Tag Connection at the specified object iscreated. 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 link variable 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_example_10x.PDL picture. 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 CS functions 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.8.3 Sam ple 3 - Creating a New Object via a CS Function

In this sample, the application of the CS function of the Graphics Designer API for creating

a new object is shown. A new I/O Field will be created. The sample has been configured at

the Button3 object displayed below at Event Mouse Mouse Action.

C-Action at Button3



C79000-G8276-C157-01

• In the first section, the DLL of the Graphics Designer API is loaded. In addition, thepdl_guid.h file 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

PDLCSGetOleAppPtr() 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() APIfunction. As the next to last parameter, the dwFlags 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/OField2 will 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 thepicture 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 function

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

PDLCSDelOleAppPtr() 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 C-Action 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.8.4 Sam ple 4 - Changing Properties via a CS Function

In this sample, the application of the CS 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 Button4 object


C-Action at Button4



C79000-G8276-C157-01

• 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 PDLCSGetOleAppPtr() API function.

• The picture to be edited is opened via the PDLCSOpenEx() API function.

• Within a for 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 function ActualizeObjects().

• The picture is closed again via the PDLCSClose() API function.

• The connection to the Graphics Designer API is terminated again via the

PDLCSDelOleAppPtr() API function.



4.8.5 Sam ple 5 - Creating a Tag Connection via a CS Function

In this sample, the application of the CS 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 Button5 object


C-Action at Button5



C79000-G8276-C157-01


• In the second section, the required variables are defined.




• In the next section, the structure elements of the link variable 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 function ActualizeObjects().






4.8.6 Sam ple 6 - Listing Objects via a CS Function

In this sample, the application of the CS function 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


Project Function ObjectCallback()

• In the first section, the pdlcsapi.h file is integrated, which contains the definition of the

OBJECT_INFO_STRUCT structure 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_STRUCT data 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

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.








window:



C79000-G8276-C157-01

4.9 Project Environment

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.

General Inform 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.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 BOOL data type is defined.

• Next, a szProjectFile 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.9.2 Sam ple 2 - Determining 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 Button2 object displayed below at Event

Mouse Mouse Action.

C-Action at Button2

• In the first section, a bRet variable of the BOOL data type is defined and initialized.

• Next, a szProjectFile 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 0 is

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.





window:



C79000-G8276-C157-01

4.9.3 Sam ple 3 - Determining 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 function. The sample has been configured at the Button3 object


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.



C-Action at Button3

• In the first section, a bRet variable of the BOOL data type is defined and initialized.

• Next, a szProjectPath string 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 function is checked.

• Next, the determined project path is output.



C79000-G8276-C157-01

4.9.4 Sam ple 4 - Determining 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 szProjectFile 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 szGlobalLibDir structure element. The Global

Library folder is a subfolder of the WinCC installation folder.



• With the first strrchr() function, the last \ character is searched for in the determinedpath and replaced by a 0. With the second strrchr() function, the last \ character in the

remaining path is searched for. One position after, a 0 is inserted.

• Next, the determined installation folder is output. This output is displayed in the next

section.



window:



C79000-G8276-C157-01

4.9.5 Sam ple 5 - Determ ining the Com puter Name

In this sample, the procedure for determining the local computer name is outlined. The


Mouse Action.

C-Action at Button5

• In the first section, the Windows DLL Kernel32 is integrated. Since only one functionof 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 BOOL data type is defined and initialized.

• Next, a szComputerName string variable for accepting the computer name is defined. Inaddition, 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.9.6 Sam ple 6 - Determining 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 Button6 object displayed below at Event

Mouse Mouse Action.

C-Action at Button6

• In the first section, the Windows DLL advapi32 integrated. Since only one function ofthe 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 BOOL data 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.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.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 Miscellaneous Open Picture of the cc_0_startpicture_00.PDL start

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 1024 by 768.

• The remaining statements of the above program code perform initializations that are not

relevant for this sample.



C79000-G8276-C157-01

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 Time

• 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 GetLocalTime() 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

via the sprintf() function. At Property Miscellaneous Tooltip Text, another

C-Action following the steps described is created. This C-Action delivers the current

date.

• The function is executed in 1s cycles.



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 and Windows

API and vice versa. The sample is configured in the cc_2_keyboard_01.PDL picture at the

Button1 object.

Project Function CC_PlaySound()

• In the first section, the apdefap.h file 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

• The project function assumes that a sound subfolder exists in the project folder. In thisfolder, 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 szSoundPath variable.

• The sound is played via the PlaySound() Windows function. If the sound file cannot be

played, a brief beep sound is generated instead by the MessageBeep() Windows

function.



4.10.4 Sam ple 4 - Starting a Program

This sample shows the procedure for starting a program. For this purpose, an already

existing standard function is utilized, which uses the Windows API. The sample is

configured at the cc_0_startpicture_00.PDL picture.

Standard Function Program Execute()

• The standard function 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 standard function ProgramExecute(), the program calc.exe is started. This is theWindows 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.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



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.11.1 Sam ple 1 - Language Switch

This sample shows, how the WinCC standard dialog for the language switch can be used.


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 DMShowLanguageDialog() API function, the standard dialog for the languageswitch 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 dwGetLocaleID variable transferred.



C79000-G8276-C157-01

• The return value of the DMShowLanguageDialog() API function is checked. Amongothers, 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 CS language. In order to switch the RT

language, the internal function 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.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


Action.

C-Action at Button2

• In the first section, the trigger.h file 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 link variable

for accepting information about the tag connection are defined.



determined using its window title.



C79000-G8276-C157-01

• 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.11.3 Sam ple 3 - Error Box

This sample shows, how a Windows error box can be displayed. The sample has been

configured at the Button3object displayed below at Event Mouse Mouse

Action.

C-Action at Button3

• In the first section, a hWnd variable 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.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


Action.

C-Action at Button4

• In the first section, a hWnd variable 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.



Question Box

If the C-Action detailed above is executed, the following question box will be displayed:



C79000-G8276-C157-01

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 Action.

C-Action at Button5

• In the first section, the Windows DLL comdlg32 is integrated.

• In the next section, the variables required are defined. Among others, a ofn variable of

the OPENFILENAME structure type is defined.

• In the next section, the ofn variable is filled with information.

• The ofn variable is transferred to the GetOpenFileName() Windows function. This

function opens the file selection dialog. The name of the file selected by the user is

stored in the ofn variable. The name of the file selected is output.



Open Standard Dialog


Additional Samples

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 function GetFileName() 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.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.

M ode Description

r Opens a file for reading. The return value is NULL if the file does not exist or

there is no read authorization.

w Opens a file for writing. The return value is NULL if the file does not exist or

there is no write authorization.

a Opens a file for being attached to the end. If the file does not exist, it is created.

The return value is NULL if 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 NULL if

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 NULL if no read and write rights for the file are

available.



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.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 function 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 fopen() 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 fprintf() function, the data is written to the file. Afterwards, the file is closed

again.



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 Button2 object displayed below at Event

Mouse Mouse Action.

C-Action at Button2




• Next, the path to the file to be opened is compiled by the strcat() function. This path is

transferred to the fopen() function. With this function, the desired file to be read is

opened.

• Via the fscanf() 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.12.3 Sam ple 3 - Reporting

This sample shows, how a report file can be created. A project function is created to which

a report text is transferred. This text will then be written into the report file. The sample has


Action.

Project Function LogText()

• A string variable is assigned to the function, which will be attached to the end of the

report file.




• Next, the path to the file to be opened is compiled by the strcat() function. This path is

transferred to the fopen() function. With this function, the desired file to be attached is

opened.

• Via the fprintf() function, the report text transferred is entered into the file. Before each

report entry, the current system time is entered via the standard function

GetLocalTimeString(). Afterwards, the file is closed again.



C-Action at Button3

• In the C-Action, the content of a WinCC text tag is read and transferred to the

previously created project function LogText(). Consequently, the content of the WinCC

text tag is entered into the report file.



C79000-G8276-C157-01

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



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 used-

defined functions.

Working with the Dynamic 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 D

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.13.1 Creation of Dynam ic Wizard Functions

For the creation of user-defined Dynamic Wizard functions, a separate editor is available.

This editor is located in the \bin folder: is the dynwizedit.exe program.

Each Dynamic Wizard function 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 InstallationFolder\Wscripts\Wscripts.deuWinCC InstallationFolder\Wscripts\Wscripts.enu

WinCC InstallationFolder\Wscripts\Wscripts.fra

After starting the Dynamic Wizard Editor, select the desired language for which the new

Dynamic Wizard function is created from the toolbar.

A Dynamic Wizard function must follow a prescribed structure. In the scope of this manual,

two samples for the creation of Dynamic Wizard functions are provided. The script files, in

which these samples are located, are stored in the DynWiz subfolder - 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 Wizard Editor.

Dem o Wizard

In the Demo.wnf script file, a Dynamic Wizard named Demo Wizard has been created. This

Wizard displays basic functions which enable the user to enter data comfortably. However,

this Dynamic Wizard does not perform any actions.

Making a Motor Dynamic Wizard

In the Motor.wnf script file, a Dynamic Wizard named Making a Motor Dynamic has been

created. This Wizard has been especially created to add dynamics to a customized object

named Motor and cannot be used for any other object type. This customized object is stored

in the project library of the WinCC project Project_C_Course and can be inserted from

there into a picture. The customized object Motor is connected to a WinCC structure tag of

the Motor structure type via the Dynamic Wizard Making a Motor 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_selected exists. With the help of this tag,

the currently selected motor object can be marked.

Com piling Script Files

A completely created Dynamic Wizard function must be compiled via the Dynamic Wizard

Compile 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 Reading Wizard Script. The

script file to be read must be selected from the dialog displayed.



C79000-G8276-C157-01

4.13.2 Structure of a Dynam ic Wizard Function

The following explains the various sections that make up a Dynamic Wizard function.

Integration of Header Files and DLLs

The first part of a Dynamic Wizard function is the integration of the required header files.

The most important file to be integrated is the dynamic.h file, 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 Wizard function 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 Wizard function 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 Wizard function can be used for this object. This

option has been applied to the Dynamic Wizard Making a Motor Dynamic to only make this

Wizard functional for customized objects of the Motor type. This object type only has the

properties Manual and 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.



Processing Function

The processing function is the function which performs the actual work of the Dynamic

Wizard function after the Finish button is pressed. The name of this function must be

specified in the system interface. An extensive processing function is presented in the

Dynamic Wizard Making a Motor 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 Wizard function. The name of this function must be

specified in the system interface.

System Interface

Via the system interface, various properties of the new Dynamic Wizard function are

specified. The meaning of the individual parameters are explained following the code

sample.

• The first parameter specifies in which tab the Dynamic Wizard function is displayed.

• The second parameter specifies under which name the Dynamic Wizard function 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

• As the sixth parameter, a list containing the names of the individual option pages of thefunction created is specified. This list must conclude with a NULL entry. 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 Finish button 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.

Global Variables

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.

Documents

WinCC Stuff