SINUMERIK 840D sl / 828D / One

Programming Manual 11/2019

SINUMERIK Integrate Create MyHMI /3GL

(CPP Api)

Manufacturer Documentation
 Introduction 1

Getting started 2

SINUMERIK 840D sl / 828D / One Communication with 3

the NC/PLC

SINUMERIK Integrate Create Program instance 4

MyHMI /3GL (CPP Api) services (PI services)

Access to alarms and 5

Programming Manual events

Directory and file 6

services

Infrastructure services 7

Valid for
Archive service 8
Software version 4.93
Drive machine data 9
service

TraceDataRecorder 10
service

ToolManagement 11
service

Action log service 12

Display Manager 13

11/2019 Index I
SINUMERIK® documentation

Edition history

Brief details of this edition and previous editions are listed below.

The status of each edition is shown by the code in the ”Remarks" columns.

Status code in the ”Remarks" column:

A .... New documentation.

B .... Unrevised reprint with new order number.
C .... Revised edition with new revision level.

Edition Order No. Remark

11/2019 ----- A

Trademarks

All names identified by the trademark symbol ® are registered trademarks of Siemens AG. Other product
names used in this documentation may be trademarks which, if used by third parties, could infringe the
rights of their owners.

Disclaimer of liability

We have checked that the contents of this document correspond to the hardware and software
described. Nonetheless, differences might exist and therefore we cannot guarantee that they are
completely identical. Nevertheless, the information contained in this document is reviewed regularly and
any necessary changes will be included in subsequent editions.

Copyright © Siemens AG 1995 - 2019.

Order No. -----

Siemens AG 2019.
Subject to change without prior notice
11/2019 Content

Content

1 Introduction ..................................................................................... 1-9

1.1 System and software architecture ................................................ 1-9

2 Getting started ................................................................................ 2-13

2.1 New project ................................................................................... 2-13

2.1.1 Creating a new project ............................................................... 2-13
2.1.2 Error evaluation.......................................................................... 2-17
2.1.3 Notes on adapting a Win32 project ........................................... 2-17

2.2 Integrating the application into SINUMERIK Operate................... 2-19

2.2.1 Integrating a CPP application into SINUMERIK Operate .......... 2-19
2.2.2 Parameterizing the OEMFrame application (oemframe.ini) ..... 2-26
2.2.3 OEM subdirectories and versioning ........................................... 2-34

2.3 Debugging a project ...................................................................... 2-38

2.3.1 Overview .................................................................................... 2-38
2.3.2 Starting Visual Studio ................................................................ 2-38
2.3.3 Debugging.................................................................................. 2-38

2.4 General classes ............................................................................ 2-39

2.4.1 Overview .................................................................................... 2-39
2.4.2 SlString class ............................................................................. 2-39
2.4.3 SlVector class ............................................................................ 2-41
2.4.4 SlValue class ............................................................................. 2-43

2.5 FAQs ............................................................................................. 2-47

2.5.1 FAQs on the topic of debugging ................................................ 2-47

3 Communication with the NC/PLC.................................................. 3-49

3.1 Introduction ................................................................................... 3-49

3.1.1 Class model ............................................................................... 3-49
3.1.2 Explanation of terms .................................................................. 3-50

3.2 Step-by-step examples ................................................................. 3-53

3.2.1 Preparation ................................................................................ 3-53
3.2.2 Reading/writing a variable ......................................................... 3-53
3.2.3 Hotlink to a variable ................................................................... 3-55
3.2.4 Reading/writing multiple variables – "array access" .................. 3-57
3.2.5 Reading/writing multiple variables – "multi-access" .................. 3-59

3.3 Reference SlDataSvc ................................................................... 3-61

3.3.1 Definitions .................................................................................. 3-61
3.3.2 Creating an SlDataSvc object .................................................... 3-61
3.3.3 Reading variables ...................................................................... 3-61
3.3.4 Write variables ........................................................................... 3-63

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 v
Content 11/2019

3.3.5 Notification regarding a variable change (hotlink) ..................... 3-64

3.3.6 Additional properties of Class SlDataSvc .................................. 3-65

3.4 SlDataSvcItem reference .............................................................. 3-70

3.4.1 Definitions .................................................................................. 3-70
3.4.2 Variable paths ............................................................................ 3-70
3.4.3 Creating an SlDataSvcItem object ............................................. 3-79
3.4.4 Properties and functions ............................................................ 3-79

3.5 SlDataSvcStatus reference ............................................................ 3-81

3.5.5 Definitions .................................................................................. 3-81
3.5.6 Properties ................................................................................... 3-81

3.6 FAQs ............................................................................................. 3-82

3.6.1 FAQs regarding hotlink ............................................................... 3-82
3.6.2 FAQs regarding machine data/GUDs ........................................ 3-82

4 Program instance services (PI services) ...................................... 4-83

4.1 Introduction ................................................................................... 4-83

4.1.1 Class model ............................................................................... 4-83

4.2 Step-by-step examples ................................................................. 4-84

4.2.1 Preparation ................................................................................ 4-84
4.2.2 Sending a general PI service ..................................................... 4-84

4.3 Reference SlPiSvc ........................................................................ 4-87

4.3.1 Definitions .................................................................................. 4-87
4.3.2 Creating an SlPiSvc object ........................................................ 4-87
4.3.3 Sending a PI service .................................................................. 4-87
4.3.4 Additional functions .................................................................... 4-88

5 Access to alarms and events ........................................................ 5-91

5.1 Overview ....................................................................................... 5-92

5.1.1 Introduction and explanation of terms ....................................... 5-92
5.1.2 Class model ............................................................................... 5-93

5.2 Step-by-step examples ................................................................. 5-95

5.2.1 Preparation ................................................................................ 5-95
5.2.2 Accessing the alarm list ............................................................. 5-95
5.2.3 Triggering / reset of alarms ........................................................ 5-97

5.3 SlAlarmSvc reference ................................................................... 5-99

5.3.1 Definitions .................................................................................. 5-99
5.3.2 Creating an SlAlarmSvc object .................................................. 5-99
5.3.3 Notification about a change in the current alarm list.................. 5-99
5.3.4 Notification about a change in the event list .............................. 5-100
5.3.5 Notification about a change in an individual event .................... 5-101
5.3.6 Additional functions .................................................................... 5-103

5.4 SlAlarm reference .......................................................................... 5-104

5.4.7 Definitions .................................................................................. 5-104
5.4.8 Functions ................................................................................... 5-104

Unrestricted © Siemens AG 2019 All Rights Reserved

vi SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 Content

5.5 SlAlarmSource reference .............................................................. 5-113

5.5.1 Definitions .................................................................................. 5-113
5.5.2 Functions ................................................................................... 5-113

6 Directory and file services ............................................................. 6-115

6.1 Introduction ................................................................................... 6-115

6.1.1 Class model ............................................................................... 6-115
6.1.2 Explanation of terms .................................................................. 6-116

6.2 Step-by-step examples ................................................................. 6-119

6.2.1 Preparation ................................................................................ 6-119
6.2.2 Listing the contents of a folder (synchronous) ........................... 6-119
6.2.3 Listing the contents of a folder (asynchronous) ......................... 6-121
6.2.4 Generating, copying and deleting a file (synchronous) ............. 6-123
6.2.5 Generating, copying and deleting a file (asynchronous) ........... 6-125
6.2.6 Determining file or folder attributes ............................................ 6-127
6.2.7 Block-by-block reading and writing of data ................................ 6-128

6.3 Reference SlNode......................................................................... 6-132

6.3.1 Definitions .................................................................................. 6-132
6.3.2 Creating an SlNode object ......................................................... 6-132
6.3.3 Functions ................................................................................... 6-133

6.4 SlFileSvc reference ........................................................................ 6-135

6.4.1 Definitions .................................................................................. 6-135
6.4.2 Creating an SlFileSvc object...................................................... 6-135
6.4.3 Administration functions ............................................................. 6-135
startBlockTransferReadAsync ............................................................. 6-141
unSubscribe ......................................................................................... 6-142
6.4.4 Callback methods ...................................................................... 6-143
6.4.5 FileSvc in 1:N constellations ...................................................... 6-145

6.5 SlAccessRights reference ............................................................. 6-147

6.5.1 Definitions .................................................................................. 6-147
6.5.2 Functions ................................................................................... 6-147

6.6 SlFileSvcStatus reference ............................................................ 6-149

6.6.1 Definitions .................................................................................. 6-149

7 Infrastructure services ................................................................... 7-151

7.1 Introduction ................................................................................... 7-152

7.1.1 Class model ............................................................................... 7-152
7.1.2 Explanation of terms .................................................................. 7-152

7.2 Step-by-step examples ................................................................. 7-154

7.2.1 Preparation ................................................................................ 7-154
7.2.2 Current language - read, switchover, notify for change .............. 7-154

7.3 SlInfraStructSvc reference ............................................................ 7-157

7.3.1 Definitions .................................................................................. 7-157
7.3.2 Creating a SlInfraStructSvc object ............................................. 7-157
7.3.3 Current resolution ...................................................................... 7-157
7.3.4 Current channel number ............................................................ 7-158

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 vii
Content 11/2019

7.3.5 Current language ....................................................................... 7-159

7.3.6 Current access level .................................................................. 7-160
7.3.7 Current NCU .............................................................................. 7-162
7.3.8 Current operating area and area switchover ............................. 7-162
7.3.9 Shutdown Operate ..................................................................... 7-163

8 Archive service ............................................................................... 8-165

8.1 Introduction ................................................................................... 8-166

8.1.1 Class model ............................................................................... 8-166

8.2 Step-by-step examples ................................................................. 8-168

8.2.1 Preparation ................................................................................ 8-168
8.2.2 Creating archives ....................................................................... 8-168
8.2.3 Reading-in archives and reading-out supplementary information8-170

8.3 SlArchivingSvc reference .............................................................. 8-172

8.3.1 Definition .................................................................................... 8-172
8.3.2 Creating an SlArchivingSvc object............................................. 8-172
8.3.3 Functions ................................................................................... 8-172

9 Drive machine data service ........................................................... 9-177

9.1 Introduction ................................................................................... 9-178

9.1.1 Class model ............................................................................... 9-178

9.2 Step-by-step examples ................................................................. 9-179

9.2.1 Preparation ................................................................................ 9-179
9.2.2 Listing the drive objects of a control .......................................... 9-179
9.2.3 Reading-out drive parameters ................................................... 9-180

9.3 Reference SlDrivesSvc ................................................................. 9-182

9.3.2 Creating an SlDrivesSvc object ................................................. 9-182
9.3.3 Functions ................................................................................... 9-182

9.4 Reference SlDrive ......................................................................... 9-183

9.4.2 Creating an SlDrive object ......................................................... 9-183
9.4.3 Functions ................................................................................... 9-183

10 TraceDataRecorder service ......................................................... 10-187

10.1 Introduction ................................................................................. 10-188

10.1.1 Class model ............................................................................. 10-188

10.2 Step-by-step examples ............................................................... 10-191

10.2.1 Preparation .............................................................................. 10-191
10.2.2 Example 1 ................................................................................ 10-194
10.2.3 Example 2 ................................................................................ 10-197

10.3 Reference SlTraceDataRecorder ............................................... 10-201

10.3.2 Creating an SlTraceDataRecorder object ................................ 10-201
10.3.3 Functions ................................................................................. 10-201

11 ToolManagement service ............................................................. 11-205

Unrestricted © Siemens AG 2019 All Rights Reserved

viii SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 Content

11.1 Introduction ................................................................................. 11-206

11.1.1 Class model ............................................................................. 11-206

11.2 Step-by-step examples ............................................................... 11-208

11.2.1 Preparation .............................................................................. 11-208
11.2.2 Tracking changes .................................................................... 11-208

11.3 Reference SlToolMngmntSvc ..................................................... 11-211

11.3.2 Creating an SlToolMngmntSvc object ..................................... 11-211
11.3.3 Functions ................................................................................. 11-211
11.3.4 Notification ............................................................................... 11-212

12 Action log service ......................................................................... 12-213

12.1 Introduction ................................................................................. 12-214

12.1.1 Class model ............................................................................. 12-214

12.2 Step-by-step examples ............................................................... 12-217

12.2.1 Preparation .............................................................................. 12-217
12.2.2 Synchronously reading out the action log ................................ 12-217
12.2.3 Asynchronously reading out the action log .............................. 12-220

12.3 Reference SlTripRecorder .......................................................... 12-223

12.3.1 Definition .................................................................................. 12-223
12.3.2 Creating an SlTripRecorder object .......................................... 12-223
12.3.3 Starting and stopping the recording ......................................... 12-223
12.3.7 Canceling a request that is being executed ............................. 12-226
12.3.8 Callback methods .................................................................... 12-226
12.3.9 Events ...................................................................................... 12-226

13 Display Manager ........................................................................... 13-229

13.1 Introduction ................................................................................. 13-230

13.1.1 Class model ............................................................................. 13-230

13.2 SlDisplayManager reference ...................................................... 13-231

13.2.1 Definitions ................................................................................ 13-231
13.2.2 Creating an SlDisplayManager object ..................................... 13-231
13.2.3 API functions ............................................................................. 13-231
13.2.4 Notifications .............................................................................. 13-234

I Index .................................................................................................. I-233

I.1 Keyword index ............................................................................... I-233

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 ix
Content 11/2019

Unrestricted © Siemens AG 2019 All Rights Reserved

x SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 1 Introduction
1.1 System and software architecture

1
1 Introduction

1.1 System and software architecture

Operate provides a pure C++ interface for communicating with the SINUMERIK
840D sl.

This interface is a pure communication interface. No GUI components are

provided.

! Important
Machine-critical OA functions must be secured using suitable
real-time applications. Under no circumstances should
machine-critical functions be implemented based on HMI
functions alone. In particular, the "hotlink mechanism" (notification on a value
change) cannot be used as the sole basis for implementing machine-critical
functions.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 1-11
1 Introduction 11/2019
1.1 System and software architecture

Unrestricted © Siemens AG 2019 All Rights Reserved

1-12 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.1 New project

2 Getting started
2
2.1 New project
2.1.1 Creating a new project

Overview
Use of the C++ interface (C++ API) is explained using basic Win32 application
examples. The intention is to focus on using the interface, not on Windows
programming. However, it will help if the user is familiar with the 32-bit Windows
API.

Supported programming languages

The C++ interface can be used in the following programming languages:
• Microsoft C++

The following steps must be performed before the interfaces of the C++ interface
can be used.

Open Visual Studio

Visual Studio must be started with an item in the start menu installed by Siemens.
Only if it is started in this way will the settings that are required to access the
interfaces be made to the environment:

Start  Programs  Siemens Automation  Sinumerik  SINUMERIK Integrate

Create MyHMI -3GL  Tools  Visual Studio 2017

Create a project
Operate must have a window to be able to link the application later. For this
reason, a "Win32 Project" is created, for example, under "C++ / Win32". If the
application requires multiple windows, it should be designed as an MDI application
(Multiple Document Interface application). You will find more detailed information
on MDI in the Microsoft documentation.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-13
2 Getting started 11/2019
2.1 New project

Fig. 2-1: Creating a new project (Win32 project)

Confirm with "OK".

Linking the C++ interface

To be able to use the C++ interface, you must now adapt the project settings:
1. "Project" menu
2. "Properties" menu item
3. Select "Configuration Properties"

Settings for Include paths:

1. Select All Configurations
2. Under "C/C++" – "General"
3. "Additional Include Directories"
4. Enter $(HMI_SL_PP_SUBST)include

Unrestricted © Siemens AG 2019 All Rights Reserved

2-14 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.1 New project

Fig. 2-2: Include path settings

Runtime library setting:

1. Select All Configurations
2. Under "C/C++" – "Code Generation"
3. "Runtime Library", select Multi-threaded DLL (/MD)

Fig. 2-3: Runtime library settings

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-15
2 Getting started 11/2019
2.1 New project

Settings for library paths:

1. Select All Configurations
2. Under "Linker" – "General"
3. "Additional Library Directories", enter $(HMI_SL_PP_SUBST)hmisl\lib

Fig. 2-4: Library path settings

Settings for the library to be used:

1. Select All Configurations
2. Under "Linker" – "Input"
3. "Additional Dependencies", enter sloperatecppapi.lib

Fig. 2-5: Library

Unrestricted © Siemens AG 2019 All Rights Reserved

2-16 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.1 New project

Include
All classes of the C++ interface are defined in the following header file:

sloperatecppapi.h

The following Include entry must be present to be able to use the functions:

#include "sloperatecppapi.h"

2.1.2 Error evaluation

Errors are not evaluated in some of the step-by-step examples. However, this must
remain the exception. All functions of the C++ interface provide error numbers in
the return value in case of error.

long error = function call(s);

if (error != 0)
{
// Error evaluation
}

The error evaluation is shown precisely in the source code of the individual
examples.
Information about error numbers
More detailed information about error numbers can be found using the
"errorLookup" application.

2.1.3 Notes on adapting a Win32 project

After the project had been generated using the Visual Studio wizard, the following
was changed or adapted in the generated CPP file in the examples:

• The UI (buttons, text fields, etc.) is created in the message WM_CREATE.

case WM_CREATE:
CreateWindow(L"static", L"Item:", WS_VISIBLE | WS_CHILD,
10, 20, 100, 20, hWnd, 0, GetModuleHandle(0), 0);
break;

• The window size is limited.

hWnd = CreateWindow(szWindowClass, szTitle, WS_OVERLAPPEDWINDOW,

0, 20, 640, 450, NULL, NULL, hInstance, NULL);

• The menu, which is present by default, is hidden.

wcex.lpszMenuName = NULL; //MAKEINTRESOURCE

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-17
2 Getting started 11/2019

• Feedback from buttons is evaluated in WM_COMMAND.

case WM_COMMAND:
wmId = LOWORD(wParam);
wmEvent = HIWORD(wParam);
// Parse the menu selections:
switch (wmId)
{
case 1: // read
ReadControlData();
break;
}

• Auxiliary functions are usually declared at the beginning of the file (with the
exception of asynchronous functionalities).

Unrestricted © Siemens AG 2019 All Rights Reserved

2-18 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.2 Integrating the application into SINUMERIK Operate

2.2 Integrating the application into SINUMERIK Operate

2.2.1 Integrating a CPP application into SINUMERIK Operate
Win32 applications must be integrated into SINUMERIK Operate using the
"OEMFrame". Generally, these applications are selected using a softkey on the
area switchover bar. The required settings are described in this chapter.

SINUMERIK Operate is started and controlled from an application called System

Manager. This System Manager also handles the control of the OEMFrame
applications.

The System Manager is configured using the systemconfiguration.ini file.

System configuration
The systemconfiguration.ini configuration file, is used to define from which
operating areas the HMI is configured.

To integrate an OEMFrame application into the system, create the

systemconfiguration.ini file in one of the following two directories:
• <Installation path>/user/sinumerik/hmi/cfg
• <Installation path>/oem/sinumerik/hmi/cfg

The sections of the systemconfiguration.ini file that are relevant for linking
OEMFrame applications are described below.

Section [processes]
This section specifies the processes to be managed by the System Manager. The
applications to be linked as OEMFrame applications must be specified here. The
following entries are relevant for OEMFrame applications:

Table 4-1: Entries in the [processes] section that are relevant for OEMFrame applications
Value Meaning
process Symbolic name of the OEMFrame application. This is required for the
operating area configuration.
cmdline Command line, passed to the oemframe.exe process on starting. "\\" must
be used as path separator.
(the path does not have to be specified if the OEMFrame application is in
the directory "\oem\sinumerik\hmi\appl")
oemframe Should always be set to "true" for OEMFrame applications.
windowname Window name of the OEMFrame application - determined using the
supplied Findwindow tool
(Start  Programs  Siemens Automation  Sinumerik  SINUMERIK
Integrate Create MyHMI -3GL  Tools  Find Window)

Maximum 255 characters

classname Class name of the OEMFrame application - determined using the
supplied Findwindow tool (start menu entry, see "windowname").

Maximum 127 characters

deferred true: OEMFrame application is not started when the HMI starts up, but the
first time it is selected.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-19
2 Getting started 11/2019
2.2 Integrating the application into SINUMERIK Operate

Value Meaning
startupTime The linked process starts as follows:
immediately  (default)
afterServices  After all services have started.
afterGuis  After all GUI components have started.

When shutting down SINUMERIK Operate, the order is inverted:

immediately  (default)
afterServices  After all services have shut down.
afterGuis  After all GUI components have shut down.
gimmekeys Release mask for keys of the system configuration that are to be
handled by the OEMFrame application. The parameterization is
performed in the form of a bit mask.
(See example 2)
disablekeys Parameterization for the behavior of the keyboard filter. The
parameterization is performed in the form of a bit mask.
(See example 2)
menuselectkey Changes the key that displays the operating area menu (default: F10).
The value is a logically ORed combination of the modifiers Key_Shift,
Key_Alt, Key_Ctrl, and the virtual key code, as defined by Microsoft.
(See example 3)
timeout Maximum duration for the search for the OEMFrame application in
milliseconds. If the OEMFrame application was not found within this
time, it can be managed by the System Manager.
(Default: systemconfiguration.ini / [miscellaneous] /
startTimeoutDefault)
shutdowntime Maximum duration for downloading the OEMFrame application in
milliseconds. If the OEMFrame application was not found within this
time, the process is canceled.
(Default: systemconfiguration.ini / [miscellaneous] /
shutdownTimeoutDefault)
processaffinitymask Bit mask which can be used to specify on how many processor cores
the OEMFrame application runs.
(Default: systemconfiguration.ini / [miscellaneous] /
ProcessAffinityMask)

The Gimmekeys bit mask can be parameterized as follows:

Table 4-2: Gimmekey bit mask

Bit Keys Meaning
0 F1 – F8 Horizontal softkeys (upper bar, HU)
1 Shift+F1 – Shift+F8 Vertical softkeys (right bar, VR)
2 Ctrl+F1 – Ctrl+F8 Horizontal softkeys (lower bar, HL)
3 Shift+Ctrl+F1 – Vertical softkeys (left bar, VL)
Shift+Ctrl+F8
4 F9 Recall
5 Shift+F9 ETC switchover
6 F10 Operating area menu
7 Shift+F10 M key
8 F11 Channel switchover key
9 Shift+F11 M key (hard key)
10 F12 Info/help
11 Shift+F12 Custom key (hard key)
12 ESC Alarm cancel
13 HOME Window switchover key
14 END PROGRAM (hard key)
15 PAGE UP ALARM (hard key)

Unrestricted © Siemens AG 2019 All Rights Reserved

2-20 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.2 Integrating the application into SINUMERIK Operate

Bit Keys Meaning

16 PAGE DOWN TOOL OFFSET (hard key)
17 HOME (NUMPAD) PROGRAM MANAGER (hard key)
18 F13 – F20 Extended horizontal softkeys (upper bar, HU)
19 Shift+F13 – Shift+F20 Extended, vertical softkeys (right bar, VR) and right
direct keys HT8
20 Ctrl+F13 – Ctrl+F20 Extended horizontal softkeys (lower bar, HL)
21 Shift+Ctrl+F13 – Extended, vertical softkeys (left bar, VL) and left
Shift+Ctrl+F20 direct keys HT8

The Gimmekey bit mask for an OEMFrame application is set to 0xF by default. This
means that all key combinations of F1 through F8 are available to the OEMFrame
application. The OEMFrame application itself can handle a specific key (or key
combination) by setting additional bits. Otherwise, the system configuration will
evaluate the key (or key combination) and it will not even reach the OEMFrame
application.

The Disablekeys bit mask can be parameterized as follows:

Table 4-3: Disablekeys bit mask

Bit Keys Meaning
0-7 Reserved
8 (Shift)+Ctrl+F1 Lower and left-hand softkey bar (HL, VL)
9 (Shift)+Ctrl+F2 Lower and left-hand softkey bar (HL, VL)
10 (Shift)+Ctrl+F3 Lower and left-hand softkey bar (HL, VL)
11 (Shift)+Ctrl+F4 Lower and left-hand softkey bar (HL, VL)
12 (Shift)+Ctrl+F5 Lower and left-hand softkey bar (HL, VL)
13 (Shift)+Ctrl+F6 Lower and left-hand softkey bar (HL, VL)
14 (Shift)+Ctrl+F7 Lower and left-hand softkey bar (HL, VL)
15 (Shift)+Ctrl+F8 Lower and left-hand softkey bar (HL, VL)
16 Reserved
17 Reserved

The Disablekeys bit mask for an OEMFrame application is set to 0x3FFFF by

default. This means that all keyboard sequences are filtered out and will not reach
the OEMFrame application. If a bit is set to 0, the keyboard filter for the
corresponding keyboard sequence will be deactivated and the OEMFrame
application will be unable to receive it. If you want an OEMFrame application to
receive all softkeys of the lower and left-hand softkey bar, for example, set the
Disablekeys bit mask to 0x300FF.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-21
2 Getting started 11/2019
2.2 Integrating the application into SINUMERIK Operate

The ProcessAffinityMask bit mask can be parameterized as follows:

Table 4-4: ProcessAffinityMask bit mask
Bit Core Meaning
0 Core0 OEMFrame application is running in the 1st
core
1 Core1 OEMFrame application is running in the 2nd
core
2 Core2 OEMFrame application is running in the 3rd
core
X CoreX etc.

Per default, the setting from the systemconfiguration.ini at [miscellaneous] /

ProcessAffinityMask applies. If the OEMFrame application is to run in several
processor cores, the appropriate bits are set. The entry 0xFFFFFFFF means that
the application is running simultaneously on all processor cores.

The Gimmekeys bit mask, the Disablekeys bit mask and the ProcessAffinityMask
bit mask can be specified with a decimal code (e.g. 31) or a hexadecimal code
(e.g. 0x1F).

Example 1:
[processes]
PROC500=process:=notepadOEM, cmdline:="C:\\WINDOWS\\system32\\notepad.exe",
oemframe:=true, deferred:=true, windowname:="Untitled - Notepad",
classname:="Notepad"

PROC501=process:=calcOEM, cmdline:="C:\\WINDOWS\\system32\\calc.exe",
oemframe:=true, deferred:=true, windowname:="Calculator",
classname:="SciCalc"

[areas]
AREA500=name:=AreaNote, process:=notepadOEM
AREA501=name:=AreaCalc, process:=calcOEM

In this example, the two Windows applications "notepad.exe" and "calc.exe" are
configured as OEMFrame applications.

Example 2:
[processes]
PROC600= process:=keycatcherOEM, cmdline:="keycatcher.exe", oemframe:=true,
deferred:=true, windowname:="keycatcher", classname:="QWidget",
gimmekeys:=0x1F, disablekeys:=0x300FF

[areas]
AREA500=name:=AreaKeyCatcher, process:= keycatcherOEM

The Windows "keycatcher.exe" application is linked in this example. This is located

in directory "\oem\sinumerik\hmi\appl"; this is the reason that the path does not
have to be specified. In this case, all 4 softkey bars and the Recall key are made
available to the Windows application. The keyboard filter for the lower and the left-
hand softkey bar is deactivated.

Example 3:
[processes]
PROC600= process:=keycatcherOEM, cmdline:="keycatcher.exe", oemframe:=true,
deferred:=true, windowname:="keycatcher", classname:="QWidget",
gimmekeys:=0x4F, disablekeys:=0x300FF, menuselectkey:=Key_Control|0x7B

[areas]
AREA500=name:=AreaKeyCatcher, process:= keycatcherOEM

Unrestricted © Siemens AG 2019 All Rights Reserved

2-22 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.2 Integrating the application into SINUMERIK Operate

The Windows "keycatcher.exe" application is linked in this example. In this case, all
four softkey bars and the F10 key will reach the Windows application. Press
Ctrl+F12 to show the operating area menu when a Windows application is
displaying (the system configuration no longer evaluates F10).

Example 4:
[processes]
PROC600= process:=keycatcherOEM, cmdline:="keycatcher.exe", oemframe:=true,
deferred:=true, windowname:="keycatcher", classname:="QWidget",
gimmekeys:=0xF, disablekeys:=0x300FF

[areas]
AREA500=name:=AreaKeyCatcher, process:= keycatcherOEM

The Windows "keycatcher.exe" application is linked in this example. In this case, all
four softkey bars are fed to the Windows application. Key sequences Ctrl-F1 to
Ctrl-F8 can be mapped onto key sequences Ctrl-F13 to Ctrl-F20.

Section [areas]
The HMI operating areas are configured in this section. The following entries are
relevant for OEMFrame applications:

Table 4-5: Entries of the [areas] section that are relevant for OEMFrame applications
Value Meaning
name Symbolic name for the operating area
process Name of the OEMFrame application as set in the [processes] section.
panel Name of the panel (header) to be used. Only "SlHdStdHeaderPanel" is
currently available for OEM applications.
plcid ID to identify the operating area using the Operate HMI monitor
(only values in the range of 150-199 are permitted)

Example:
[areas]
AREA600= name:=AreaOEM, process:=notepadOEM
AREA601= name:=AreaCalc, process:=calcOEM, panel:=SlHdStdHeaderPanel

! Important
In the "processes" and "areas" sections, the number range
500-999 is reserved for OEM customers. If numbers less than 500 are used,
basic Siemens components may be overwritten.

! Important
OEMFrame applications that use the programming interfaces of HMI Advanced
are not supported.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-23
2 Getting started 11/2019
2.2 Integrating the application into SINUMERIK Operate

! Important
In order to avoid write errors, the entries under "Section [processes]" and
"Section [areas]" should only be determined using the "Find Window" tool
provided (Start  Programs  Siemens Automation  Sinumerik 
SINUMERIK Integrate Create MyHMI -3GL  Tools  Find Window).

Additional information is provided in document "FindWindow.pdf" in the

SINUMERIK Integrate Create MyHMI /3GL documentation.

Section [miscellaneous]
Various settings can be made in this section. However, only the Start operating
area is usually changed here.

Table 4-6: Entries for the [miscellaneous] section

Key Value
startuparea Name of the start operating area.

Example:
[miscellaneous]
startuparea = AreaOEM

Operating area menu configuration

The operating area menu is used to switch between the operating areas configured
in "systemconfiguration.ini". A softkey for selecting the appropriate operating area
is provided on the horizontal softkey bar for each operating area that is configured.

The operating area displays the configured names of the operating areas from
"systemconfiguration.ini" as the text on the operating area softkeys. The menu
automatically searches for a free softkey on the horizontal softkey bar for each
operating area. If the operating area is to be assigned a certain softkey in the
operating area menu, or if a foreign language text or an icon for the operating area
should be displayed on the softkey, additional configuration is possible and is also
necessary.

This configuration is performed in the "slamconfig.ini" configuration file. This file is

stored in the same directory as the "systemconfiguration.ini" file.

A section can be created for each operating area that has been configured in
systemconfiguration.ini. The section must have the name configured for the
operating area in question, e.g. AreaOEM.

The following values can be set for an operating area:

Unrestricted © Siemens AG 2019 All Rights Reserved

2-24 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.2 Integrating the application into SINUMERIK Operate

Table 4-7: Values for configuring the operating area in slamconfig.ini

Value Meaning
TextId Text-ID for a foreign-language text that is to be displayed as the
softkey label.
TextContext Context of the foreign-language text.
TextFile Name of the text file which includes the context and the foreign-
language text.
Picture Name of an image file that is to be used as an icon for the softkey.
SoftkeyPosition Fixed softkey position of the area softkey. Positions 1 through 8 are
the first ETC level; 9 through 16, the second ETC level, and so on.
AccessLevel Access level as from which the softkey will appear. If this value is
not specified, the access level will be set to 7 = keyswitch position 0.

Example:
[AreaOEM]
; Text-ID of a language dependent text
TextId = MY_AREA
; File name of the text file which contains the Text-ID
TextFile = mytextfile
; Context in the text file to which the Text-ID is assigned to
TextContext = mycontext
; File name of an icon shown on the area softkey
Picture = mypicture.png
; Position of the area softkey on area menu,
; If no position is specified, an empty position is searched
SoftkeyPosition = 7
; Access level of the area softkey
AccessLevel = 5

The area softkey for the "AreaOEM" operating area is configured in this example.
The softkey is at position 7 in the operating area menu and is displayed with
access level "Keyswitch position 2" and higher. This softkey displays the text
stored in the mytextfile_xxx.ts text file in the context "mycontext" with the Text-ID
"MY_AREA". The mypicture.png icon is also displayed.

Example of a text file (mytextfile_deu.ts)

stored under "\oem\sinumerik\hmi\lng":
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE TS>
<TS>
<context>
<name>mycontext</name>
<message>
<source>MY_AREA</source>
<translation>AppName</translation>
</message>
</context>
</TS>

! Important
Operating area position 7 is reserved for OEM customers.

Note
If an OEMFrame application comprises several forms, then these should be
combined under one MDI frame. Only then can it be guaranteed that the System
Manager correctly executes the area switchover.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-25
2 Getting started 11/2019
2.2 Integrating the application into SINUMERIK Operate

2.2.2 Parameterizing the OEMFrame application (oemframe.ini)

Additional parameters can be assigned for OEMFrame applications using file
"oemframe.ini".

A dedicated section is created for each OEMFrame application for which

parameters are to be stored. This section has the same name as the
corresponding program file but without the file name extension.

The "oemframe.ini" is located in directory "..\compat\oem". If "oemframe.ini" does

not yet exist, it should be created at that location.

Parameter overview
Table 2-8: "oemframe.ini" parameters
Entry Meaning Default
WindowStyle_On Defines properties to be assigned to the 0
window.
WindowStyte_Off Defines properties that the window must not 0
have.
x Horizontal starting coordinate of the 0
OEMFrame application
(Unit: pixels)
y Vertical starting coordinate of the OEMFrame 0
application
(Unit: pixels)
Width Width of the Width of the desktop
OEMFrame application
(Unit: pixels)
Height Height of the Height of the desktop
OEMFrame application
(Unit: pixels)
nDelayInitComplete Delays feedback to the System Manager. 0
fSearchOnlyForTask- States whether the window specified in the 1
Window "systemconfiguration.ini" belongs to the task
also specified in that file.
fRestoreTaskWindow Defines the behavior when exiting an 0
application that was started from the
OEMFrame application.
fKeepPlacement Deactivates the size adaptation. 0
fForceTaskFocus Define which window of the OEMFrame 0
fSearchForPopUps application will be displayed when starting. 1
nInitShowMode State in which the window of the OEMFrame SW_SHOWMIN-
application is displayed when the application NOACTIVE
is started.
nShowMode State in which the window of the OEMFrame SW_SHOW-
application is displayed when it is shown. NORMAL
nUnShowMode State into which the window of the SW_SHOWMIN-
OEMFrame application is put when it is NOACTIVE
hidden.
fWinForms Must be set if the application is a "Windows 0
Forms Application".
nSwitchToTaskAfter- Controls the behavior when the OEMFrame -1
Termination application is exited.
fFindWindowWithWil Should be set when using "wildcards" (?,*) for 0
dcards the window name.
nPlacementMode Behavior when using with SideScreen or 0
DisplayManager

Unrestricted © Siemens AG 2019 All Rights Reserved

2-26 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.2 Integrating the application into SINUMERIK Operate

WindowStyle_On / WindowStyle_Off
The appearance of a Windows application is defined in part using the
SetWindowLong Windows API functions. When the SetWindowLong function is
called, the appearance of the application is controlled using an 8-byte word. Two
bytes of this word can be changed using the WindowStyle_On and
WindowStyle_Off attributes. These are explained in the following table:

Table 2-9: Control options using the WindowStyle attributes

0000 0000 xxxx xxxx 0000 0000 0000 0000
1010 Header
1000 Border
0100 Type of window frame on a dialog box
0010 Vertical scroll bar
0001 Horizontal scroll bar
1000 System menu
0100 Frame (Thickframe)
0010 Minimize box
0001 Maximize box

The values shown in binary notation here are assigned to the WindowStyle
attributes as a decimal number. You can use the pocket calculator of Windows to
convert from binary to decimal, and vice versa. The calculator is usually found in
the Accessories program group.

Example:
The properties of the system menu as well as the horizontal and vertical scroll bar
should be defined. According to the table, these are:

0000 0000 0011 1000 0000 0000 0000 0000 binary or 0038 0000 Hex.
Now, call the pocket calculator and
- Click the Hex button
- Enter the string of digits 380000 (leading zeros can be omitted)
- Click the Dec selection button
- Copy result 3670016, using the Edit menu
- Insert the result at Attribute

The "WindowStyle_On" parameter defines the properties that will be assigned to

the window, and the "WindowStyle_Off" parameter defines the properties that the
window will not have.

Example 1:
For the Notepad editor, the system menu as well as the horizontal and vertical
scroll bar should be activated:
[notepad]
WindowStyle_On = 3670016

Example 2:
No minimize box and no maximize box should be displayed for the Notepad editor:
[notepad]
WindowStyle_Off = 196608

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-27
2 Getting started 11/2019
2.2 Integrating the application into SINUMERIK Operate

X/Y
The X and Y attributes define the starting coordinates of the window of the
Windows application to be linked, measured from an origin in the upper left corner
of the screen.

X is the horizontal coordinate; Y is the vertical coordinate pointing downward. The

unit of measurement is pixels.
Width
This attributes defines the width of the window for the Windows application,
measured in pixels from the window origin according to attribute X.

Height
This attribute defines the height of the window for the Windows application,
measured in pixels from the window origin according to attribute Y.

nDelayInitComplete
As soon as the window of the Windows application has been found, a message
indicating this is sent to the System Manager. The Windows application can then
be selected using the System Manager. This message can be delayed using the
"nDelayInitComplete" parameter. This is necessary if the Windows application still
has to execute actions that will take a long time after its window has been created,
which could result in the window being incorrectly displayed if it were activated too
early by the System Manager.
.
(Unit: milliseconds, default value: 0)

Example:
After creating its window, a Windows application "app.exe" reads additional status
data from a database that is absolutely necessary for the Windows application to
run correctly. The window of the Windows application may only be displayed after
all status data has been read. On the average, this read operation should take
approx. 1 sec. The following parameter assignment is required:
[app]
;worst case
nDelayInitComplete = 2000

fSearchOnlyForTaskWindow
This parameter specifies whether or not the window specified in the file
"systemconfiguration.ini" using ClassName/WindowName belongs to the task that
is also specified there. If the window belongs to the specified task, the parameter
"fSearchOnlyForTaskWindow" is assigned the value 1. If the window does not
belong to the specified task, "fSearchOnlyForTaskWindow" should be set to 0. In
this case, not just the windows of the task configured in "systemconfiguration.ini"
are considered in the search for the specified window, but all of the windows that
exist in the system at the time of the search.
(Flag, default value: 1)

Unrestricted © Siemens AG 2019 All Rights Reserved

2-28 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.2 Integrating the application into SINUMERIK Operate

Example:
The Windows application comprises more than one process, e.g. a "startup.exe"
and a "user.exe". In the "systemconfiguration.ini" file (only) "startup.exe" is entered,
from which "user.exe" is then started. The application window belongs to
"user.exe" and is therefore not found when searching is restricted to the windows
of "startup.exe". The following parameter assignment is required:
[startup]
fSearchOnlyForTaskWindow = 0

fRestoreTaskWindow
This parameter defines the behavior when exiting a Windows application that was
started from the OEMFrame application (second task level).

Note
This situation cannot be completely controlled and should therefore be avoided if
at all possible!

When the OEMFrame application is selected, the last window that was active
(ForegroundWindow) is saved by default. This window is reactivated when the
OEMFrame application is reselected. If another application has been started from
the OEMFrame application, the active window will usually belong to this Windows
application.

OEMFRAME  OEM application  Application  ForegroundWindow

Basic window

The proxy application (OEMFRAME.EXE) cannot detect when the Windows

application ends. It is therefore unable to put the window of the OEMFrame
application into the foreground in this situation, which may result in incorrect
scenarios being displayed when the second task level is ended.

The "fRestoreTaskWindow" parameter provides a partial remedy. If the value 1 is

assigned to this parameter, two windows are always activated when the
OEMFrame application is selected or an application is started from the OEMFrame
application. The basic window of the OEMFrame application is placed in the
foreground first and then the "ForegroundWindow" is placed over this window. This
ensures that the basic window of the OEMFrame application will appear when the
second task level is ended.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-29
2 Getting started 11/2019
2.2 Integrating the application into SINUMERIK Operate

Restrictions:
If a modal window (dialog box) is active in the OEMFrame application when the
second application is started, this modal window will lose the input focus when the
second application is ended. In this case, the operator must explicitly set the focus
in the dialog box (e.g. using the mouse).

fForceTaskFocus / fSearchForPopUps
These two parameters define which window the OEMFrame application will
activate after it has been deselected and reselected again. On switching from one
operating area to another, the default setting is that the last active window of the
OEMFrame application is saved. When the application is selected again, this
window is activated again. In the Windows API, this window is called the
ForegroundWindow.

OEMFRAME  OEM application  ForegroundWindow

fForceTaskFocus=0
Basic window fSearchForPopUps: irrelevant

This (default) behavior makes sense for the majority of applications. However,
there are exceptions for which this behavior can be changed. If the two parameters
"fForceTaskFocus" and "fSearchForPopUps" are set to the value 1, when the
OEMFrame application is deselected, a search is not made for the
ForegroundWindow but rather for an active popup window that belongs to the basic
window of the application. If a popup window is found, it will be displayed when the
OEMFrame application is selected again. If there is no popup window, the basic
window of the application will be displayed when the application is reselected.

OEMFRAME  OEM application  PopUpWindow

fForceTaskFocus=1
Basic window fSearchForPopUps=1

A search for an active popup window is not made if parameter

"fSearchForPopUps" is set to the value 0. When an application is
deselected and then selected again, only the basic window of the OEMFrame
application is considered. The basic window is specified in
ClassName/WindowName in the "systemconfiguration.ini" file.

Unrestricted © Siemens AG 2019 All Rights Reserved

2-30 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.2 Integrating the application into SINUMERIK Operate

fKeepPlacement
This function deactivates the resizing (zooming) for the basic window of the OEM
application. The application is normally zoomed to the screen size before it is
displayed. In the case of applications that do not allow their windows to be
zoomed, the resizing can result in display problems. In such cases, the zoom
function must be deactivated.

Example:
An application "fixres.exe" should be displayed in its programmed window size.
size. The following parameter assignment is required:
[fixres]
fKeepPlacement = 1

nInitShowMode / nShowMode / nUnShowMode

The three parameters define how the application window will be displayed when
the application (nInitShowMode) is started, hidden, and shown. The "nShowMode"
parameter refers to showing (area is activated); the "nUnShowMode" parameter, to
hiding. The following value range applies to both parameters:

0: The application window is hidden (SW_HIDE).

1: The application window is displayed in its original form (position,

size) and has the input focus (SW_SHOWNORMAL,
SW_NORMAL).

2: The application is minimized and has the input focus

(SW_SHOWMINIMIZED).

3: The application window is maximized (SW_SHOWMAXIMIZED).

4: The application window is displayed without having the input focus

(SW_SHOWNOACTIVATE).

5: The application is displayed and has the input focus

(SW_SHOW).

6: The application window is minimized and loses the input focus

(SW_MINIMIZE).

7: The application window is minimized without having the input focus

(SW_SHOWMINNOACTIVE).

8: The application window is displayed without having the input focus

(SW_SHOWNA).

9: The application window is displayed in its original form (position,

size) (SW_RESTORE).

10: The application window is displayed in the same way as when the
application was started (SW_SHOWDEFAULT).

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-31
2 Getting started 11/2019
2.2 Integrating the application into SINUMERIK Operate

Note
The default settings are suitable for most applications. However, in some cases,
display problems can occur (window not maximized, etc.). This can be remedied
by setting parameter nShowMode=3.

fWinForms
If the OEMFRAME application is a "Windows Forms Application" with the name
"myApp.exe", then the following parameterization is required:
[myApp]
fWinForms = 1

Note
If the parameter is not set, the OEMFrame application will not be started as a
maximized window and any sizing (X, Y, Width, Height) will have no effect.

nSwitchToTaskAfterTermination
This parameter controls the behavior when the OEMFrame application is exited.
The System Manager normally displays the area switch menu in this situation and
the user must explicitly
switch to another area. This parameter can be used to initiate an automatic switch
to the previously active area.

Value range of the parameter:

–1 Area switch menu display
–2 Switch to the previously active area
(Default value: –1)

Example:
When the "closeapp.exe" Windows application is exited, a switch should be made
to the previous area. The following parameter assignment is required:
[closeapp]
nSwitchToTaskAfterTermination = -2

fFindWindowWithWildcards
This parameter activates the wildcard search for the window name. ? (an arbitrary
character) and * (arbitrary number of characters) can be used. In this way it is
possible to identify applications that do not have the same window name at every
start (e.g. access level, time in the window name, etc.).

Value range of the parameter:

0  Wildcard search is deactivated
1  Wildcard search is activated

Unrestricted © Siemens AG 2019 All Rights Reserved

2-32 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.2 Integrating the application into SINUMERIK Operate

Example:
An application is to be integrated that contains the start time in the
window name.

oemframe.ini:
[MyQtTest]
fFindWindowWithWildcards=1

systemconfiguration.ini:
[processes]
PROC500=process:=ProcessOEM, cmdline:="C:\\Program Files
(x86)\\Siemens\\MotionControl\\oem\\sinumerik\\hmi\\appl\\MyQtTest.exe",
oemframe:=true, windowname:="MyQtTest - ??:??:??", classname:="QWidget",
deferred:=true

[areas]
AREA500=name:=Test, process:=ProcessOEM

nPlacementMode
This parameter influences the behavior in conjunction with the Siemens Sidescreen
and the Display Manager

Value range of the parameter:

2  The OEMFRAME application no longer maximizes itself over the entire
available screen so that Siemens Sidescreen or DisplayManager will not be
superimposed.

3  Should be set for OEMFRAME applications, which should be displayed within

the DisplayManager.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-33
2 Getting started 11/2019
2.2 Integrating the application into SINUMERIK Operate

2.2.3 OEM subdirectories and versioning

OEM subdirectories
If multiple OEM applications (Operate dialog boxes or OEMFrame applications) are
to be linked, these can be distributed across the OEM's own subdirectories. The
advantage is the clear assignment of the files to a particular OEM application. This
is especially true for the "systemconfiguration.ini" as there is a risk of it being
accidentally overwritten when copying, which may hide other OEM applications.

OEM subdirectories can be created with any directory name under

"/oem/sinumerik/hmi". These subdirectories are communicated in the file
"systemconfiguration.ini" in the cfg directory ("/oem/sinumerik/hmi/cfg"). They are
created in section "oem_dirs" with the following syntax:

OEM_<Number>=<OEM subdirectory name>

Example:
[oem_dirs]
OEM_1=oem_example
OEM_2=oem_new

When required, the appl, cfg, lng, hlp, etc. directories can be created again below
these two OEM subdirectories ("/oem/sinumerik/hmi/oem_example" and
"/oem/sinumerik/hmi/oem_new").

Versioning of OEM applications

To provide OEM applications with their own versioning, which can then be viewed
in the "Diagnostics" area under the "Version" softkey, appropriate version files
should be generated (versions.xml). These must be provided by the OEM
application and saved in the OEM directory ("/oem/sinumerik/hmi") or in the
corresponding OEM subdirectory (e.g. "/oem/sinumerik/hmi/oem_new").

A version file must have the name "versions.xml" and is generated in a format
similar to XML. As a minimum, a name and a version are required:

Example (minimum):
<info>
<Name>OEM1</Name>
<Version>1.1</Version>
</info>

Unrestricted © Siemens AG 2019 All Rights Reserved

2-34 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.2 Integrating the application into SINUMERIK Operate

Beyond this, there can also be an internal version and subcomponents or

references to additional version files using the tag <Path>.

Example (subcomponents, internal version):

<info>
<Name>OEM1</Name>
<Version>1.1</Version>
<InternalVersion>999</InternalVersion>
<Component>
<Name>OEM1 componentX</Name>
<Version>6.1</Version>
</Component>
<Component>
<Name>OEM1 componentY</Name>
<Version>00.00</Version>
<InternalVersion>L00.00.06.00</InternalVersion>
</Component>
</info>

Example (path):
<info>
<Name>OEM1</Name>
<Version>1.1</Version>
<Component>
<Name>OEM1 componentX</Name>
<Version>6.1</Version>
<Path>appl</Path>
</Component>
</info>

During startup, the OEM directory as well as possibly existing OEM subdirectories
are scanned and a higher-level version file is created in the "/oem" directory.

Note
The higher-level version file is only created if such a version file does not exist
under "/oem". This means that it must be deleted when a new OEM application is
installed.

References to the OEM applications from the OEM directory or the OEM
subdirectories are entered into this higher-level version file. If OEM subdirectories
and the OEM directory are used simultaneously, it should be ensured that the
entries of the version files do not overwrite one another.

Note
The description of the versioning applies to the PCU50/IPC and LinuxEmbedded
target systems. The associated required infrastructure is missing on the
development PC.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-35
2 Getting started 11/2019
2.2 Integrating the application into SINUMERIK Operate

Version management of applications (only the PCU50/IPC target system)

The following configuration should be made if you wish to display the Windows
version of OEM applications.

<info defaultFileType="*.exe"
defaultFileVersion="01.01.00.00"
LinkName="appl">
<Name>OEM6 component</Name>
<Version>16.16</Version>

<!--- Version 1 -->

<File VersionInfoMode="UseWinVersion">
<Name>TestVersion.exe</Name>
<Version>16.17.18.19</Version>
</File>

<!--- Version 2 -->

<File VersionInfoMode="ShowVersionInfoOnly">
<Name>TestVersion.exe</Name>
</File>
</info>

In version 1, attribute "UseWinVersion" is set. Here, an attempt is made to

determine the Windows version of the "TestVersion.exe" application. An empty
string is assumed if this is not possible. A comparison is then made with the
specified version (reference-actual comparison)

In version 2, attribute "ShowVersionInfoOnly" is set. Here, an attempt is made to

determine the Windows version of the "TestVersion.exe" application. An empty
string is assumed if this is not possible. No reference-actual comparison is made
here. Only the determined Windows version is displayed.
Versioning of INI files
To be able to also display the versions of INI files, the following two lines are
required at the start of the INI file:

;VERSION: <Version> ;DATE: YYYY-MM-DD

;CHANGE: <Version> ;DATE: YYYY-MM-DD

Example :
;VERSION: 06.02.08 ;DATE: 2002-01-07
;CHANGE: 06.02.04 ;DATE: 2001-07-23

In addition, a "versions.xml" with the following contents should be saved in the cfg
directory of the corresponding INI file.

<info defaultFileType=" *.ini"

defaultFileVersion="06.02.08" LinkName="OEM">
<Name>ini files</Name>
</info>

By specifying the "defaultFileType", the version information is directly read out from
all INI files and displayed. The "defaultFileVersion" specifies the target version. If
the reference and actual version do not match, this is clearly indicated in the
version display by a red attention sign.

Unrestricted © Siemens AG 2019 All Rights Reserved

2-36 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.2 Integrating the application into SINUMERIK Operate

Note
The version file in the "cfg" directory is not automatically considered. Therefore, a
link to it must be created in the higher-level OEM directory (or OEM subdirectory)
by specifying "Path":

<Component>
<Name>OEM1 componentX</Name>
<Version>6.1</Version>
<Path>cfg</Path>
</Component>

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-37
2 Getting started 11/2019
2.3 Debugging a project

2.3 Debugging a project

2.3.1 Overview
If a project using the C++ interface is started under debugger control, the following
issues must be considered.

2.3.2 Starting Visual Studio

After installation, the start menu will contain the following menu item, which is then
used to start Visual Studio:

Start  Programs  Siemens Automation  Sinumerik  SINUMERIK Integrate

Create MyHMI -3GL  Tools  Visual Studio 2017

This link can also be copied to the desktop.

2.3.3 Debugging
Visual Studio must be started as described above. SINUMERIK Operate must then
be started. As soon as a connection has been made to the control, the application
can be started in Visual Studio under debugger control.

Unrestricted © Siemens AG 2019 All Rights Reserved

2-38 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.4 General classes

2.4 General classes

2.4.1 Overview
Various general classes have been provided for use by the C++ API. These are:

• SlString - String class

• SlVector - Vector template class
• SlValue - Values class ("Variant" implementation)

2.4.2 SlString class

The SlString class is an implementation for string operations.
SlString
Constructors of the SlString class.

Table 2-10:
SlString ()

Table 2-11:
SlString (const char*)
Parameter Meaning
const char* Pointer to a 0-terminated C string

Table 2-12:
SlString (SlString&)
Parameter Meaning
SlString& Reference to SlString object

~SlString
Destructor of the SlString class.

Table 2-13:
~SlString ()

clear
Deletes the string (length = 0).

Table 2-14:
void clear ()

length
Reads the length of the string.

Table 2-15:
long length ()
Parameter Meaning
Return Number of characters in the string

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-39
2 Getting started 11/2019
2.4 General classes

at
Returns a character from the string.

Table 2-16:
char at (long)
Parameter Meaning
long Index in the string
Return Characters in the string

append
Appends further characters to the string.

Table 2-17:
void append (const char*)
Parameter Meaning
const char* Character string to be appended

Table 2-18:
void append (const SlString&)
Parameter Meaning
const SlString Character string to be appended

c_str
Returns the string as a 0-terminated C string.

Table 2-19:
char* c_str ()
Parameter Meaning
Return 0-terminated C string

equals
String comparison operation.

Table 2-20:
bool equals (SlString&)
Parameter Meaning
SlString& String to be compared
Return true/false

==
String comparison operation.

Table 2-21:
bool operator== (SlString&)
Parameter Meaning
SlString& String to be compared
Return true/false

Unrestricted © Siemens AG 2019 All Rights Reserved

2-40 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.4 General classes

=
Assignment operator.
Table 2-22:
SlString& operator= (const char*)
Parameter Meaning
const char* 0-terminated C string to be assigned
Return Reference to SlString

Table 2-23:
SlString& operator= (SlString&)
Parameter Meaning
SlString& SlString to be assigned
Return Reference to SlString

2.4.3 SlVector class

The SIVector template class provides an implementation for array operations.
SlVector
Constructors of the SlVector class.

Table 2-24:
SlVector ()

Table 2-25:
SlVector (const SlVector&)
Parameter Meaning
SlVector& Reference to vector class

~SlVector
Destructor of the SlVector class.

Table 2-26:
~SlVector ()

clear
Deletes the vector (length = 0).

Table 2-27:
clear ()

size
Returns the length of the vector (number of elements in the vector).

Table 2-28:
size ()

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-41
2 Getting started 11/2019
2.4 General classes

at
Reads an element at position (index).

Table 2-29:
T& at (long)
Parameter Meaning
long Index of a vector element
Return Reference to vector element

remove
Deletes an element at position (index).

Table 2-30:
long remove (long)
Parameter Meaning
long Index of a vector element
Return New size of the vector

push_back
Includes an element at the end of the list (in the vector).

Table 2-31:
void push_back (T&)
Parameter Meaning
T& Reference to new element

pop_back
Removes an element from the end of the list (in the vector).

Table 2-32:
void pop_back ()

=
Assignment operator.

Table 2-33:
SlVector& = (SlVector&)

Unrestricted © Siemens AG 2019 All Rights Reserved

2-42 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.4 General classes

2.4.4 SlValue class

The SlValue class provides an implementation for data (a type of "Variant") in the
C++ Api context.
Value types are mapped via an enum and are:

enum type
{
Invalid,
Boolean,
Char,
UChar,
Int,
UInt,
Long,
ULong,
LongLong, // 64 bit
ULongLong, // 64 bit
Double,
String,
SlValueArray
};

SlValue
Default constructor.

Table 2-34:
SlValue ()

Constructors with value assignment

Table 2-35:
SlValue (const bool)
SlValue (const char)
SlValue (const unsigned char)
SlValue (const int)
SlValue (const unsigned int)
SlValue (const long)
SlValue (const unsigned long)
SlValue (const long long)
SlValue (const unsigned long long)
SlValue (const double)
SlValue (const SlString&)
SlValue (const SlValue&)
SlValue (const SlVector<SlValue>&)
Parameter Meaning
(…) Initialization parameters

~SlValue
Destructor.

Table 2-36:
~SlValue ()

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-43
2 Getting started 11/2019
2.4 General classes

=
Assignment operators.

Table 2-37:
SlValue& operator= (const bool)
SlValue& operator= (const char)
SlValue& operator= (const unsigned char)
SlValue& operator= (const int)
SlValue& operator= (const unsigned int)
SlValue& operator= (const long)
SlValue& operator= (const unsigned long)
SlValue& operator= (const long long)
SlValue& operator= (const unsigned long long)
SlValue& operator= (const double)
SlValue& operator= (const SlString&)
SlValue& operator= (const SlValue&)
SlValue& operator= (const SlVector<SlValue>&)
Parameter Meaning
(..) Value to be assigned
Return Reference to SlValue

GetType
Gets the type of a value.

Table 2-38:
type GetType ()
Parameter Meaning
Return enum type

toBool
Converts to Boolean.

Table 2-39:
bool toBool ()
Parameter Meaning
Return Boolean value

toChar
Converts to Character.

Table 2-40:
char toChar ()
Parameter Meaning
Return char value

Unrestricted © Siemens AG 2019 All Rights Reserved

2-44 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.4 General classes

toUChar
Converts to Character (byte) unsigned.

Table 2-41:
unsigned char toUChar ()
Parameter Meaning
Return char value unsigned

toInt
Converts to Integer.

Table 2-42:
int toInt ()
Parameter Meaning
Return Integer value

toUInt
Converts to Integer unsigned.

Table 2-43:
int toUInt ()
Parameter Meaning
Return Integer value unsigned

toLong
Converts to Long.

Table 2-44:
int toLong()
Parameter Meaning
Return Long value

toULong
Converts to Long unsigned.

Table 2-45:
int toULong()
Parameter Meaning
Return Long value unsigned

toLongLong
Converts to LongLong.

Table 2-46:
int toLongLong()
Parameter Meaning
Return LongLong value

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-45
2 Getting started 11/2019
2.4 General classes

toULongLong
Converts to LongLong unsigned.

Table 2-47:
int toULongLong()
Parameter Meaning
Return LongLong value unsigned

toDouble
Converts to Double.

Table 2-48:
double toDouble()
Parameter Meaning
Return Double value

toSlString
Converts to SlString.

Table 2-49:
SlString toString()
Parameter Meaning
Return SlString value

toSlValueArray
Converts to SlValue Vector.

Table 2-50:
SlVector<SlValue>& toSlValueArray()
Parameter Meaning
Return Vector of SlValue values

Unrestricted © Siemens AG 2019 All Rights Reserved

2-46 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 2 Getting started
2.5 FAQs

2.5 FAQs

2.5.1 FAQs on the topic of debugging

Why do I always get the error message "Unable To Locate Component" when I
start my application?

Fig. 2-6: Unable to locate component

Cause
Visual Studio was not started via the link provided.

Remedy
Start Visual Studio via the link provided (see Chapter 2.3).

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 2-47
2 Getting started 11/2019
2.5.1 FAQs on the topic of debugging

Unrestricted © Siemens AG 2019 All Rights Reserved

2-48 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.1 Introduction

3 Communication with the NC/PLC

3
Objective of the chapter
This chapter describes the DataService interface. This is used for
communication between applications and the NC/PLC.

Note
The communication time is not guaranteed. Real-time tasks therefore
cannot be performed with the C++ interface.

3.1 Introduction
3.1.1 Class model

Overview
The class model of the DataService essentially comprises the following classes:
• SlDataSvc
• SlDataSvcItem
• SlDataSvcStatus

All classes are defined in sloperatecppapi.h.

#include "sloperatecppapi.h"

Class SlDataSvc
Data accesses to the NC and PLC are implemented using SlDataSvc objects.
In particular, variables can be read and written, and you can
be notified if the value of a variable changes.
Class SlDataSvcItem
The SlDataSvcItem object is used for the individual calls of the SlDataSvcItem
object to identify variables. The value to be written or read is also included in this
object.
Class SlDataSvcStatus
Additional information on the SlDataSvc request currently being executed can be
queried using the SlDataSvcStatus object. These include, for example, the time
stamp or the status of the current hotlink connection.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-49
3 Communication with the NC/PLC 11/2019
3.1 Introduction

3.1.2 Explanation of terms

Synchronous calls
Synchronous calls only return after the request has been executed, i.e.
the calling thread is blocked during execution. This can interfere with
event processing. For example, operator inputs and displays may be
withheld during a synchronous call. This is the reason why calls that
could take a long time should be executed asynchronously.

Asynchronous calls
Asynchronous calls and hotlinks return as soon as the request has been sent
to the DataService. The returned error code cannot therefore indicate
whether the request has been completed successfully;
it can only indicate whether the request has been sent
successfully. For example, an error occurs if call parameters are not correctly
assigned. The actual request status is provided in the callbacks of the DataService.

Single call
Single calls access a variable with read or write access.
The following single calls are available:

Table 3-1: Single calls

SlDataSvc call Description
read Synchronous reading of a variable
write Synchronous writing to a variable
readAsync Asynchronous reading of a variable
writeAsync Asynchronous writing to a variable

Multi-variable call
In a multi-variable call, multiple variables are read or
written. In this case, the variables of a request can address completely different
data. The following multi-variable calls are available:

Table 3-2: Multi-variable calls

SlDataSvc call Description
read Synchronous reading of multiple variables
write Synchronous writing to multiple variables
readAsync Asynchronous reading of multiple variables
writeAsync Asynchronous writing to multiple variables

Note
The function names of the multi-variable calls do not differ from those of the
single calls. Only their call parameters are different.

Unrestricted © Siemens AG 2019 All Rights Reserved

3-50 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.1 Introduction

Hotlink
A hotlink is a notification that one or more variables have changed. After
notification, a callback function is invoked in the implementation of the interface
class ISlDataSvcCb (see sloperatecppapi.h):

virtual void SlDataSvcItemChanged(SlDataSvcItem& /*variable*/,

SlDataSvcStatus& /*status*/) = 0;

virtual void SlDataSvcItemsChanged(SlVector<SlDataSvcItem>& /*variables*/,

SlVector<SlDataSvcStatus>& /*status*/) = 0;

virtual void SlDataSvcAsyncReadResult(SlDataSvcItem& /*variable*/,

SlDataSvcStatus& /*status*/) = 0;

virtual void SlDataSvcAsyncReadResult(SlVector<SlDataSvcItem>& /*var…s*/,

SlVector<SlDataSvcStatus>& /* status */) = 0;

virtual void SlDataSvcAsyncWriteResult(SlDataSvcItem& /*variable*/,

SlDataSvcStatus& /*status*/) = 0;

virtual void SlDataSvcAsyncWriteResult(SlVector<SlDataSvcItem>& /*var…s*/,

SlVector<SlDataSvcStatus>& /* status */) = 0;

These callback functions must be implemented by the calling item.

The first notification provides the value at the time the hotlink was set up.

DataService sends notifications as soon as it has identified a value

change. In this case, intermediate values may be lost, but not the
final value.

With notifications, intermediate values are always lost if the client is unable to
process all value changes.

The following calls are available:

Table 3-3: Hotlink calls

SlDataSvc call Description
subscribe Set up a hotlink to one or more variables
unSubscribe End a hotlink to one or more variables

Array access
For some variables, multiple consecutive variables can be specified
in the variable name. This is known as an
array access.

Array accesses accelerate data access, therefore improving the

speed of the overall system, as the communication resources required are
significantly reduced.

For example, an array access to three consecutive R parameters (R7, R8, R9)
would be
"/channel/parameter/r[u1,7,#3]"

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-51
3 Communication with the NC/PLC 11/2019
3.1 Introduction

Connection monitoring
The following variables should be used to monitor the connection. The returned
value 30 indicates that a connection exists.

Table 3-4: Items for connection monitoring

Variable Description
/nc/connect_state Connection monitoring to the NC
/plc/connect_state Connection monitoring to the PLC

In addition, for the NCK, variable "nck/state/anpowerOnState" can be monitored.

The NCK is ready for communication as soon as 16777223 (decimal) is returned
here.

Note
Previously, the variable "/bag/state/opmode" or
"/Nck/Configuration/maxNumChannels" was used to monitor the connection to
the NCK and variable "ib0" to the PLC. However, this is no longer recommended
as under certain circumstances this procedure is no longer sufficient.

Unrestricted © Siemens AG 2019 All Rights Reserved

3-52 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.2 Step-by-step examples

3.2 Step-by-step examples

Overview
The following chapters show the various applications for the
DataService step-by-step. For every "step-by-step example," there is an
executable example in SINUMERIK Integrate Create MyHMI /3GL.

These and all other examples are shown in the following overview of examples.

Table 4-5: Overview of the examples

Application Example Chapter
Reading/writing a variable SlDataSvcReadWriteChange 3.2.2
Hotlink to a variable SlDataSvcReadWriteChange 3.2.3
Reading/writing multiple variables – SlDataSvcArrayReadWriteChange 3.2.4
"array access"
Reading/writing multiple variables – SlDataSvcMultiReadWriteChange 3.2.5
"multi-access"

Only the items relevant for the DataService are explained or described on each
example. The comments for the sources contain more detailed
information (e.g. screen layout, outputs, etc.).
3.2.1 Preparation

Overview
Preparatory measures are described in Chapter 2.1  "New Project". All of the
items described there must be executed first.
3.2.2 Reading/writing a variable

Overview
This example shows how data can be read from and written to a control using the
SlDataService interface.

In this example, you can enter an item and then read it using the "read data" button
or write it using the "write data" button. The status bar indicates whether the calls
have been successful.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-53
3 Communication with the NC/PLC 11/2019
3.2 Step-by-step examples

Fig. 3-1: Example of SlDataSvcReadWriteChange

Step 1
Create the member variable of type SlDataSvc:

// create a reader
SlDataSvc reader;

// create a writer
SlDataSvc writer;

To read and write, it is not absolutely necessary to create the SlDataSvc object as
a member variable. It can also be created locally in the specific function.
Step 2
Read the control value. A SlDataSvcItem-type object is first created. The
variable name to be read is passed during creation. (In the example, the content of
the text field is passed; here, the path is specified directly.)

The read() function of the SlDataSvc object is used to read the item. The value
read is located in the value property of the SlDataSvcItem object.

// create item object and initialize itempath

SlDataSvcItem item("/channel/parameter/r[u1,10]");

// read the value R10

SlDataSvcError err = reader.read(item);

Step 3
Write the control value. The value property of the SlDataSvcItem object is
assigned the value to be written. The value is written to the control using the
write() function of the SlDataSvc object.

Unrestricted © Siemens AG 2019 All Rights Reserved

3-54 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.2 Step-by-step examples

// value to write
item.Value = 1.2345;

// write the value to R10

SlDataSvcError err = writer.write(item);

3.2.3 Hotlink to a variable

Overview
The following step-by-step example shows how to set up a hotlink to a variable.

In the example, you can enter an item and then, using the "start refresh" button, set
up a hotlink that can then be ended again using "stop refresh". The status bar
indicates whether the calls have been successful.

Fig. 3-2: Example of SlDataSvcReadWriteChange

Step 1
Create the required member variables. For the hotlink, an ISlDataSvcCb is
required to identify the hotlink in addition to the SlDataSvc object:

SlDataSvc m_RefreshDataSvc;
ISlDataSvcCb* m_ pCb;

Step 2
Create the hotlink. A SlDataSvcItem-type object is first created. The variable
name to be read is passed during creation. (In the example, the content of the text
field is passed; here, the path is specified directly.)

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-55
3 Communication with the NC/PLC 11/2019
3.2 Step-by-step examples

The hotlink is set up using the subscribe() function of the SlDataSvc object.
Here, both the pointer to the callback function and the SlDataSvcItem object are
transferred.

// create item object and initialize itempath

SlDataSvcItem item("/channel/parameter/r[u1,10]");

// subscribe item, specify callback implementation

SlDataSvcError err = m_RefreshDataSvc.subscribe(item, m_pCb);

Step 3
Implement the callback function. The SlDataSvcItemChanged() function is
already defined as virtual void. The user must implement the desired function
to evaluate the value of value. The GetType() function determines whether the
access is a single value or multiple values (e.g. an array, i.e.
SlValue::SlValueArray).

// global variables
double dRefreshValue = 0.0;
// window to inform
HWND msgWindow;

class SlDataSvcCb : public ISlDataSvcCb

{
// Callback single item subscription
void SlDataSvcItemChanged(SlDataSvcItem& variable,
SlDataSvcStatus& status)
{
if (variable.value.GetType() == SlValue::SlValueArray)
{
// array of values reported, e.g. /channel/parameter/r[u1, 1, #5]
SlValue values = variable.value;
for (long i = 0; i < values.toSlValueArray().size(); i++)
{
}
}
else
{
// single value reported
// mutex access in case of concurrency
dRefreshValue = variable.value.toDouble();

// here you can call main window to show new value dRefreshValue
…

}
}

…
}

Step 4
Unsubscribe the running hotlink. This is done using the unSubscribe() function.

SlDataSvcError err = m_RefreshDataSvc.unSubscribe();

Unrestricted © Siemens AG 2019 All Rights Reserved

3-56 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.2 Step-by-step examples

3.2.4 Reading/writing multiple variables – "array access"

Overview
The following step-by-step example shows you how to read and write multiple data
items simultaneously. In this case, the data must be located contiguously in the
control, for example, a consecutive number of R parameters or PLC bytes.

In this example, you can enter an item and then read it using the "read data" button
or write it using the "write data" button. The status bar indicates whether the calls
have been successful.

Fig. 3-3: Example of SlDataSvcArrayReadWriteChange

Step 1
Create the member variable of type SlDataSvc:

// create a reader
SlDataSvc reader;

// create a writer
SlDataSvc writer;

To read and write, it is not absolutely necessary to create the SlDataSvc object as
a member variable. It can also be created locally in the specific function.
Step 2
Read the control values. An SlDataSvcItem-type object is first created. The
variable name to be read is passed during creation. (In the example, the content of
the text field is passed; here, the path is specified directly.)

The values are read using the read() function of the SlDataSvc object. The value
read is located in the value property of the SlDataSvcItem object.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-57
3 Communication with the NC/PLC 11/2019
3.2 Step-by-step examples

// create item object and initialize itempath

SlDataSvcItem item("/channel/parameter/r[u1,10,#4]");

// read the 4 values from R parameters: 10, 11, 12, 13

SlDataSvcError err = reader.read(item);

Step 3
Process the data that has been read. To start, a check is made to see whether the
value property of the SlDataSvcItem object contains an array. If it does, the
content of the property can be converted to an array. value1, value2,
value3, value4 are the returned values that the user can display.

if (item.value.GetType() == SlValue::SlValueArray)
{
SlValue values = item.value;
for (long i = 0; i < values.toSlValueArray().size(); i++)
{
if (i == 0) value1 = values.toSlValueArray().at(0).toDouble();
if (i == 1) value2 = values.toSlValueArray().at(1).toDouble();
if (i == 2) value3 = values.toSlValueArray().at(2).toDouble();
if (i == 3) value4 = values.toSlValueArray().at(3).toDouble();
}
}

Step 4
Write multiple control values. Assuming: value1, value2, value3, value4
are assigned new values and written back into the same SlDataSvcItem object
"/channel/parameter/r[u1,10,#4]".

// set new values to write

SlValue value1 = 1.11;
SlValue value2 = 2.22;
SlValue value3 = 3.33;
SlValue value4 = 4.44;

// array of values
SlVector<SlValue> values;
values.push_back(value1);
values.push_back(value2);
values.push_back(value3);
values.push_back(value4);

The value property is then assigned the prepared array.

// set item value

item.value = values;

The values are written to the control using the write() function of the SlDataSvc
object.

// write the item to the control

SlDataSvcError err = writer.write(item);

Unrestricted © Siemens AG 2019 All Rights Reserved

3-58 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.2 Step-by-step examples

3.2.5 Reading/writing multiple variables – "multi-access"

Overview
The following step-by-step example shows you how to read and write multiple data
items simultaneously. In this case, any data can be used, even mixed NC and PLC
data.

In this example, you can enter two different items and then read them using the
"read data" button or write them using the "write data" button. The status bar
indicates whether the calls have been successful.

Fig. 3-4: Example of SlDataSvcMultiReadWriteChange

Step 1
Create the member variable of type SlDataSvc:

// create a reader
SlDataSvc reader;

// create a writer
SlDataSvc writer;

To read and write, it is not absolutely necessary to create the SlDataSvc object as
a member variable. It can also be created locally in the specific function.
Step 2
Read the control values.

// create item object and initialize itempath

SlDataSvcItem item1("/channel/parameter/r[u1,10]");
SlDataSvcItem item2("/channel/parameter/r[u1,15]");

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-59
3 Communication with the NC/PLC 11/2019
3.2 Step-by-step examples

SlVector<SlDataSvcItem> items;
items.push_back(item1);
items.push_back(item2);

// read the value

SlDataSvcError err = reader.read(items);

The values read are in the value property of the SlDataSvcItem object as an array
of items.

items.at[0].value.ToDouble()
items.at[1].value.ToDouble()

Step 3
Write multiple control values. Assuming: The value property of the SlDataSvcItem
object is assigned a new value and written back to the same address (as during
reading) "/channel/parameter/r[u1,10,10]" and
"/channel/parameter/r[u1,10,15]".

// set values
item1.value = 1.234;
item2.value = 2.468;

SlVector<SlDataSvcItem> items;
items.push_back(item1);
items.push_back(item2);

The values are written into the control using the write() function of the
SlDataSvc object.

// write the item to the control

writer.write(items);

Unrestricted © Siemens AG 2019 All Rights Reserved

3-60 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.3 Reference SlDataSvc

3.3 Reference SlDataSvc

3.3.1 Definitions

Overview
Data accesses to the NC and PLC are implemented using SlDataSvc objects.
Variables can be read and written, or notification is possible when the value of a
variable changes.

Synchronous calls block the calling item until the request has been completed.
Notification of the change in value is performed using callback functions.

The class is defined in sloperatecppapi.h

Mapping of variables
Variables are mapped as SlDataSvcItem-type objects. This SlDataSvcItem
object includes both the variable name and the value.

Array access
If access to multiple consecutive variables is specified in the variable name (array
access), SlDataSvc will return an array in the SlDataSvcItem object.

An array type can be determined as follows:

if (item.value.GetType() == SlValue::SlValueArray)

3.3.2 Creating an SlDataSvc object

The SlDataSvc class only has one default constructor.

3.3.3 Reading variables

read
Synchronous reading of variables.

Table 3-6: read – reading variables

public SlDataSvcError read(SlDataSvcItem& item)
Parameter Meaning
item Specifies the variable to be read. The read
value is also in this parameter in the value
property.
Return SlDataSvcError: Error number

Example: See Chapter 3.2.2

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-61
3 Communication with the NC/PLC 11/2019
3.3 Reference SlDataSvc

Table 3-7: read – reading multiple variables

public SlDataSvcError read(SlVector<SlDataSvcItem>& items)
Parameter Meaning
items Array of SlDataSvcItem objects that specify
the variables to be read. The values that
are read are also located in these
parameters.
Return SlDataSvcError: Error number

Example: See Chapter 3.2.5

readAsync
Asynchronous reading of variables.

Table 3-8: readAsync – read from a variable

public SlDataSvcError readAsync(SlDataSvcItem& variable,
ISlDataSvcCb* pSlDataSvcAsyncReadResult);
Parameter Meaning
variable Specifies the variable to be read.
pSlDataSvcAsyncReadResult Pointer to callback class
Return SlDataSvcError: Error number

Table 3-9: readAsync – read several variables

public SlDataSvcError readAsync(SlVector<SlDataSvcItem>& variables,
ISlDataSvcCb* pSlDataSvcAsyncReadResult);
Parameter Meaning
variables Array of SlDataSvcItem objects that specify
the variables to be read.
pSlDataSvcAsyncReadResult Pointer to callback class
Return SlDataSvcError: Error number

Table 3-10: Callback–implementation for one variable

public void SlDataSvcAsyncReadResult( SlDataSvcItem& variable,
SlDataSvcStatus& status);
Parameter Meaning
variable Specifies the variable and its new value
(value property).
status Status of the active asynchronous read
access. See chapter 3.5 SlDataSvcStatus
reference

Table 3-11: Callback– implementation for several variables

public void SlDataSvcAsyncReadResult( SlVector<SlDataSvcItem>& variables,
SlVector<SlDataSvcStatus>& status);
Parameter Meaning
variables Specifies the variables and their new value
(property value).
status Status of the active asynchronous read
access. See chapter 3.5 SlDataSvcStatus
reference

Unrestricted © Siemens AG 2019 All Rights Reserved

3-62 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.3 Reference SlDataSvc

3.3.4 Write variables

write
Synchronous writing of variables.

Table 3-12: write – writing to a variable

public SlDataSvcError write(SlDataSvcItem& item)
Parameter Meaning
item Specifies the variable to be written. The
value is also in this parameter in the Value
property.
Return SlDataSvcError: Error number

Example: See Chapter 3.2.2

Table 3-13: write – writing to multiple variables

public SlDataSvcError write(SlVector<SlDataSvcItem>& items)
Parameter Meaning
items Array of SlDataSvcItem objects that specify
the variables to be written. The values are
also located in this parameter.
Return SlDataSvcError: Error number

Example: See Chapter 3.2.5

writeAsync
Asynchronous writing of variables.

Table 3-14: writeAsync – writing to a variable

public SlDataSvcError writeAsync(SlDataSvcItem& variable,
ISlDataSvcCb* pSlDataSvcAsyncReadResult);
Parameter Meaning
variable Specifies the variable to be written.
pSlDataSvcAsyncWriteResult Pointer to callback class
Return SlDataSvcError: Error number

Table 3-15: writeAsync – writing to several variables

public SlDataSvcError writeAsync(SlVector<SlDataSvcItem>& variables,
ISlDataSvcCb* pSlDataSvcAsyncReadResult);
Parameter Meaning
variables Array of SlDataSvcItem objects that specify
the variables to be written.
pSlDataSvcAsyncWriteResult Pointer to callback class
Return SlDataSvcError: Error number

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-63
3 Communication with the NC/PLC 11/2019
3.3 Reference SlDataSvc

Table 3-16: Callback–implementation for one variable

public void SlDataSvcAsyncWriteResult( SlDataSvcItem& variable,
SlDataSvcStatus& status);
Parameter Meaning
variable Specifies the variable
status Status of the active asynchronous read
access. See chapter 3.5 SlDataSvcStatus
reference

Table 3-17: Callback– implementation for several variables

public void SlDataSvcAsyncWriteResult( SlVector<SlDataSvcItem>& variables,
SlVector<SlDataSvcStatus>& status);
Parameter Meaning
variables Specifies the variables
status Status of the active asynchronous read
access. See chapter 3.5 SlDataSvcStatus
reference

3.3.5 Notification regarding a variable change (hotlink)

subscribe
Sets up a notification when one or more variable values change. The call returns
as soon as the setup request has been forwarded to the server. The notification is
performed by calling the implemented callback function. The first notification
returns the value at the time the hotlink was set up.

Intermediate values can be lost, but not the final value (see also
Chapter 3.1.2 "Definitions", completeness of signaled value changes).

Notifications can be canceled using an Unsubscribe call. The request is also

canceled as soon as deletion of the relevant SlDataSvc object has been detected.

Table 3-18: subscribe – hotlink to one variable

public SlDataSvcError subscribe(SlDataSvcItem& item, ISlDataSvcCb* cb)
Parameter Meaning
item Variable, for which a notification is to be set
up.
cb Pointer to callback class
Return SlDataSvcError: Error number

Table 3-19: SlDataSvcItemChanged – specification for the callback implementation of

one variable
public void SlDataSvcItemChanged(SlDataSvcItem& item, SlDataSvcStatus&
status)

Parameter Meaning
item Specifies the variable and its new value
(value property).
status Status of the running hotlink. See chapter
3.5 SlDataSvcStatus reference
Return -

Example: See Chapter 3.2.3.

Unrestricted © Siemens AG 2019 All Rights Reserved

3-64 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.3 Reference SlDataSvc

Table 3-20: subscribe – hotlink to multiple variables

public SlDataSvcError subscribe(SlVector<SlDataSvcItem>& items, ISlDataSvcCb*
cb)
Parameter Meaning
items Variables, for which notifications are to be
set up.
cb Pointer to callback class
Return SlDataSvcError: Error number

Table 3-21: SlDataSvcItemsChanged – specification for the callback implementation of

multiple variables
public void SlDataSvcItemsChanged(SlVector<SlDataSvcItem>& items,
SlDataSvcStatus& status)

Parameter Meaning
items Vector of variables and their new values
(value property).
status Status of the running hotlink. See chapter
3.5 SlDataSvcStatus reference
Return -

unSubscribe
Unsubscribes a hotlink

Table 3-22:unSubscribe – exiting a hotlink

public SlDataSvcError unSubscribe()
Parameter Meaning
Return SlDataSvcError: Error number

3.3.6 Additional properties of Class SlDataSvc

getDeadBand / setDeadBand
Gets or sets a range within which notifications are suppressed when a value does
not differ sufficiently from the preceding value. This is only active for numerical
values and hotlinks.

If the value is greater than 0, no changes will be forwarded if the value does not
differ from the preceding value by at least the magnitude of the dead band (i.e.
value ± dead band).

A value that is less than 0 produces a series of fixed steps. Values are forwarded
only if the new value is within a different step.

Table 3-23: getDeadBand / setDeadBand

public double geDeadBand ()
Parameter Meaning
Return Tolerance band

public void setDeadBand (double deadband)

Parameter Meaning
deadband Tolerance band
Return -

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-65
3 Communication with the NC/PLC 11/2019
3.3 Reference SlDataSvc

getPriorityFlags / setPriorityFlags
Gets or sets the processing priority of the DataService accesses.

Table 3-24: getPriorityFlags / setPriorityFlags

public SlPriorityFlags getPriorityFlags ()
Parameter Meaning
Return Processing priorities:
SlPriorityFlags.lowPriority
SlPriorityFlags.highPriority
SlPriorityFlags.defaultPriority

public void setPriorityFlags (SlPriorityFlags flag)

Parameter Meaning
Flag Processing priorities:
SlPriorityFlags.lowPriority
SlPriorityFlags.highPriority
SlPriorityFlags.defaultPriority
Return -

DataService uses three processing priorities:

SlPriorityFlags.lowPriority
Low processing priority. This value should be used for cyclic activities and activities
running in the background. By default, the DataService uses this priority for
Subscribe requests once the first value has arrived.

SlPriorityFlags.highPriority
High processing priority. This value is reserved for exclusive use by the machine
manufacturer to achieve productivity goals (e.g. tool change).

SlPriorityFlags.defaultPriority
Default processing priority. By default, DataService executes all read and write
requests in this priority. This priority is also used when accessing the first value for
subscribe requests.

Please note the following supplementary conditions:

1. As requests with high processing priority prevent requests with low

processing priority from being processed, only the priority lowPriority
may be used for cyclic requests (hotlinks).

2. The processing priorities are active only within the DataService. Low-
priority requests that have already started will no longer be overtaken by
higher-priority requests.

Note
The flag defaultPriority (value = 0) does not have to be explicitly set. This
value is automatically set after an SlDataSvc object has been created.

Unrestricted © Siemens AG 2019 All Rights Reserved

3-66 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.3 Reference SlDataSvc

getTimeOut / setTimeOut
Gets or sets the timeout for access control.

Table 3-25: getTimeOut / setTimeOut

public int getTimeOut ()
Parameter Meaning
Return Timeout in msec

public void setTimeOut (int timeout)

Parameter Meaning
timeout Time limit for the call duration, in
milliseconds. After this time has
expired, the call will return with an
error.
Return -

setSynchronizedMultivarAccess
Occasionally, multiple individual data refer to each other and have to be read or
written simultaneously. However, the DataService does not guarantee that the
variables of a multi-variable call will be sent in one request. In particular, if there is
a high communication load, it attempts to optimize the throughput instead.

This can be influenced using the setSynchronizedMultivarAccess function:

Table 3-26:setSynchronizedMultivarAccess
public void setSynchronizedMultivarAccess (bool flag)
Parameter Meaning
flag true/false
Return -

SynchronizedMultivarAccess = true;
For a multi-variable call, setting this flag in the SlDataSvc object will force the
variables to be sent in one request and also the result to be returned in one
request.

Note that there are a number of additional constraints to be complied when setting
this flag. Failure to do so will cause the entire request to be rejected. Possible
causes could be:

1. The variables must be located on the same unit (PLC, NC, or drive).

2. In the case of NCK variables, channel-specific data may only address one
channel and drive-specific data only one drive.

3. Request and result must not exceed the size of one PDU.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-67
3 Communication with the NC/PLC 11/2019
3.3 Reference SlDataSvc

Note
The space available in a PDU (protocol data unit) depends on several parameters
of the terminal device (NC, PLC, drive) and cannot be specified generally.

The following apply as guide values for the PLC:

Read requests: Space for at least 16 variables
Write requests: Space for at least 8 variables
Net data volume: Approx. 190 bytes

The following apply as guide values for the NC:

Read requests: Space for at least 100 variables
Write requests: Space for at least 50 variables
Net data volume: Approx. 800 bytes

getSynchronizedMultivarAccess
Gets the flag for "congruence access" for multivar access.

Table 3-27:getSynchronizedMultivarAccess
public bool getSynchronizedMultivarAccess (bool flag)
Parameter Meaning
Return true/false

getUpdaterate / setUpdaterate
Gets or sets the maximum notification rate for hotlinks (subscribe calls).

Table 3-28: getUpdaterate / setUpdaterate

public int getUpdaterate ()
Parameter Meaning
Return Value in msec

public void setUpdaterate (int rate)

Parameter Meaning
rate Value in msec
Return -

Possible predefined update values:

These values can be defined by functions standardUpdateRate(),

highUpdateRate(), lowUpdateRate(), veryLowUpdateRate() of class
SlDataSvc.

Unrestricted © Siemens AG 2019 All Rights Reserved

3-68 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.3 Reference SlDataSvc

Example:

SlDataSvc data;

data.standardUpdateRate()
Default value. This value is used for variables that change relatively infrequently,
but that affect the display when they do change. Examples include machine data,
operating modes, etc. (200 milliseconds).

data.highUpdateRate()
This value is used for variables whose change is tracked directly by the operator
and that change frequently. Examples include axis positions (50 milliseconds).

data.lowUpdateRate()
This value is used for variables whose acquisition is not time-critical (1000
milliseconds).

data.veryLowUpdateRate()
This value is used for variables whose acquisition is not time-critical (10000
milliseconds).

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-69
3 Communication with the NC/PLC 11/2019
3.4 SlDataSvcItem reference

3.4 SlDataSvcItem reference

3.4.1 Definitions

Overview
An instance of an SlDataSvcItem class represents a variable in the control (NC,
PLC, machine or drive data). This object includes both the variable name and the
value.

The class is defined in sloperatecppapi.h.

3.4.2 Variable paths

Variable names for NC data

You obtain the variable path for NC accesses from the OPI help. It is also included
in the documentation for SINUMERIK Integrate Create MyHMI /3GL.

Table 3-29: Examples of variable names (NC accesses)

Variable name Description
/channel/parameter/r[u1,10] R parameter 10 in channel 1.
/channel/parameter/r[u1,4,#5] R parameter array from R4 to R8 in
channel 1.
/channel/parameter/r[u2,40,42] R parameter array from R40 to R42 in
channel 2.
/channel/geometricAxis/name[u2,3] Name of the 3rd axis in channel 2.
/channel/geometricAxis/actToolBasePos[u1,3] Position of the 3rd axis in channel 1.

Variable names for GUDs and machine data

GUDs and machine data do not have to be explicitly declared. They are
automatically declared when the SlDataSvc object is instantiated for the first time.

Table 3-30: Examples of GUDs and machine data

Variable name Description
/NC/_N_CH_GD1_ACX/GUDNAME1[u1] Access to variable GUDNAME1 in channel
1 (u1) of the 1st GUD area (SGUD)
/NC/_N_NC_GD4_ACX/GUDNAME2 Access to the NC global variable
GUDNAME2 of the 4th GUD area
/NC/_N_NC_TEA_ACX/<NAME> Access to NC global machine data
/NC/_N_CH_TEA_ACX/<NAME> Access to channel-specific machine data
/NC/_N_AX_TEA_ACX/<NAME> Access to axis-specific machine data
/NC/_N_NC_SEA_ACX/<NAME> Access to NC global setting data
/NC/_N_CH_SEA_ACX/<NAME> Access to channel-specific setting data
/NC/_N_AX_SEA_ACX/<NAME> Access to axis-specific setting data

Notes regarding the table:

1. <NAME> must be replaced by the name of the relevant machine or setting
data.

GUD arrays are 1-indexed for access, and from the perspective of the SlDataSvc
are always one-dimensional. This means, the index must be calculated for multi-
dimensional arrays.

Unrestricted © Siemens AG 2019 All Rights Reserved

3-70 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.4 SlDataSvcItem reference

Example 1 – one-dimensional array:

UGUD.DEF file
DEF NCK INT ARRAY[2]
M17

Access is realized as follows:

ARRAY[0]  /NC/_N_NC_GD3_ACX/ARRAY[1]
ARRAY[1]  /NC/_N_NC_GD3_ACX/ARRAY[2]

Example 2 – two-dimensional array:

UGUD.DEF file
DEF CHAN INT ABC[3,3]
M17

Access is realized as follows:

ABC[0,0]  /NC/_N_CH_GD3_ACX/ABC[u1, 1]
ABC[0,1]  /NC/_N_CH_GD3_ACX/ABC[u1, 2]
ABC[0,2]  /NC/_N_CH_GD3_ACX/ABC[u1, 3]
ABC[1,0]  /NC/_N_CH_GD3_ACX/ABC[u1, 4]
ABC[1,1]  /NC/_N_CH_GD3_ACX/ABC[u1, 5]
ABC[1,2]  /NC/_N_CH_GD3_ACX/ABC[u1, 6]
ABC[2,0]  /NC/_N_CH_GD3_ACX/ABC[u1, 7]
ABC[2,1]  /NC/_N_CH_GD3_ACX/ABC[u1, 8]
ABC[2,2]  /NC/_N_CH_GD3_ACX/ABC[u1, 9]

Variable names for PLC accesses (840D sl

The variable names for PLC accesses conform to S7 syntax. Both SIMATIC and
IEC addressing can be used for this.

Table 3-31: PLC syntax

Area Address Address Permissible data types
(SIMATIC) (IEC)
Output image Ax.y Qx.y BOOL
Output image ABx QBx BYTE, CHAR, STRING, DT
Output image AWx QWx WORD, INT, DATE, S5TIME, CHAR
Output image ADx QDx DWORD, DINT, REAL, TIME, TOD
Data block DBz.DBXx.y DBz.DBXx.y BOOL
Data block DBz.DBBx DBz.DBBx BYTE, CHAR, STRING, DT
Data block DBz.DBWx DBz.DBWx WORD, INT, DATE, S5TIME, CHAR
Data block DBz.DBDx DBz.DBDx DWORD, DINT, REAL, TIME, TOD
Input image Ex.y Ix.y BOOL
Input image EBx IBx BYTE, CHAR, STRING, DT
Input image EWx IWx WORD, INT, DATE, S5TIME, CHAR
Input image EDx IDx DWORD, DINT, REAL, TIME, TOD
Bit memory Mx.y Mx.y BOOL
Bit memory MBx MBx BYTE, CHAR, STRING, DT
Bit memory MWx MWx WORD, INT, DATE, S5TIME, CHAR
Bit memory MDx MDx DWORD, DINT, REAL, TIME, TOD
Timer Tx Tx S5TIME
Counter Zx Cx WORD

Notes regarding the table:

1. In the table, "x" stands for the byte offset in the area; "y" for the bit number
in the byte; and "z" for the data block.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-71
3 Communication with the NC/PLC 11/2019
3.4 SlDataSvcItem reference

2. The underscored data type is the default data type in each case and does
not have to be specified when addressing. In addition, the specifications
DB2.DBB5:BYTE and DB2.DBB5 are equivalent, for example.
3. Square brackets are used to access arrays, e.g. DB5.DBW2:[10] (word
array of length 10).
Examples

Table 3-32: Examples of variable names (PLC accesses)

Variable name Description
M5.0 Memory bit 0 at byte offset 5.
DB5.DBW2 Word (16-bit) at byte offset 2 in data block 5.
DB5.DBW2:S5TIME Word (16-bit) at byte offset 2 in data block 5 as S5 time.
DB8.DBB2:STRING UTF8 string starting at byte offset 2 in data block 8.
DB8.DBW2:[10] Array of 10 words starting at byte offset 2 in data block 8.
DB100.DBB1 Byte at byte offset 1 in data block 100.
DB100.DBW7:[5] Array of 5 words starting at byte offset 7 in data block 100.
DB2.DBD0:REAL[10] Array of 10 double words (32-bit) at byte offset 0 in data block 2,
which should be formatted as a floating-point number.
Clock PLC time

The following points should be noted:

• Timers can only be read. A timer is active if it contains a value other than
0.
• If the data type CHAR or STRING is used in conjunction with a byte
access, UTF8 characters are read, but if either data type is used in
conjunction with a word access, UTF16 characters are read.
• Variables of type STRING contain the maximum length in the first
byte/word and the actual length in the second byte/word. When strings are
written, the maximum length does not change.
• For data type STRING in conjunction with a byte access (e.g.
DB99.DBB0:STRING) the maximum string length is 255 characters. As a
result of the UTF8 formatting, for several characters (e.g. for the "µ"), two
bytes are required, so that the maximum string length is correspondingly
reduced.
• Only one-dimensional arrays are supported. With STRING arrays, all
elements have the same maximum length.
• On array accesses with type CHAR, a string is returned instead of an
array. The first 0 character marks the end of the string.

Variable paths for PLC accesses (Sinumerik One)

The variable path for PLC axis operations to a Sinumerik One depends on attribute
"Optimized block access" in the TIA Portal. This data block can be activated or
deactivated using the properties dialog.

Unrestricted © Siemens AG 2019 All Rights Reserved

3-72 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.4 SlDataSvcItem reference

If this is deactivated, then the syntax behaves analogously to 840D sl:

Fig. 3-5: deactivated "Optimized block access"

If this is activated, then the corresponding symbolic addressing can be used in the
SlDataSvc:

Fig. 3-6: activated "Optimized block access"

This variable path then comprises:

<NameData block>.<VariableName>

Table 3-33: Examples of variable paths (PLC accesses, SINUMERIK One)

Variable path Description
MyPlcData.MyBool Variable "MyBool" in data block "MyPlcData"
MyPlcData.MyInt Variable "MyInt" in data block "MyPlcData"
MyPlcData.MyWordArray[4] 5th element of the array variable "MyWordArray" in data
block "MyPlcData"

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-73
3 Communication with the NC/PLC 11/2019
3.4 SlDataSvcItem reference

The following data types from the TIA Portal are supported:
• Bool • SInt
• Byte • USInt
• Char • Int
• WChar • UInt
• String • DInt
• WString • UDInt
• Time • LInt
• Time_Of_Day • ULInt
• LTime (read only) • Word
• LTime_Of_Day • DWord
• Date • LWord
• Date_And_Time • Real
• LReal

All data types, with the exception of "String" and "WString", can also be used as
array. For arrays, it is only possible to access an individual element.

Variable paths for 1:N constellations

By default, data is accessed on the NCU which is being viewed by Operate. In a
1:N constellation, data can be accessed on a specific NCU (an NCU other than the
one displayed in Operate) as follows:

1. Addition of NCU name and domain (NC/PLC) to the variable path.

Data can be accessed on a specific NCU by prefixing the actual variable
path with the name of the NCU and the domain.
Examples:
R 5, from NCU2 and channel 3 -
@NCU2/NC/Channel/Parameter/R[u3,5]
MB5 from NCU2 - @NCU2/PLC/MB[5]

Note
NCU names are listed in MMC.INI (see also Fig. 3.5).
Entry:
[GLOBAL]
NcddeMachineNames=NCU1,NCU2

Unrestricted © Siemens AG 2019 All Rights Reserved

3-74 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.4 SlDataSvcItem reference

Fig. 3-7: NCU names for 1 : N

Variable paths CTRL-Energy

The following variable paths are available for accesses to energy management
(CTRL-Energy):

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-75
3 Communication with the NC/PLC 11/2019
3.4 SlDataSvcItem reference

Table 3-34: Variable paths CTRL-Energy

Variable Description
/Hmi/CtrlEnergy/State Format: QVariant / UInt
Available: Always
Meaning: 1  Measurement active
0  Measurement inactive
/Hmi/CtrlEnergy/DeviceNames Format: QVariant / QVariantList<QString>
Available: Always
Meaning: Contains the names
(language-independent) of
the configured devices as
they are listed in the Ctrl-Energy table
(total drives, total
machine, manual, X1, Y1, …).
/Hmi/CtrlEnergy/Types Format: QVariant / QVariantList<Int>
Available: Always
Meaning: Contains, parallel to
/Hmi/CtrlEnergy/DeviceNames,
an identifier for the type of
each configured device:
0..31  Axis
1000  Manual
1100  Total drives
1200  SENTRON PAC or
total machine
1300  Total machine
/Hmi/CtrlEnergy/Power Format: QVariant / QVariantList<double>
Available: Always
Meaning: Parallel to
/Hmi/CtrlEnergy/DeviceNames,
contains the current power of each
configured device.
/Hmi/CtrlEnergy/ActiveEnergy Format: QVariant / QVariantList<double>
Available: For active measurement
Meaning: Parallel to
/Hmi/CtrlEnergy/DeviceNames,
contains the infeed energy of each
configured device.
/Hmi/CtrlEnergy/ReactiveEnergy Format: QVariant / QVariantList<double>
Available: For active measurement
Meaning: Parallel to
/Hmi/CtrlEnergy/DeviceNames,
contains the regenerative energy of each
configured device.

/Hmi/CtrlEnergy/TotalEnergy Format: QVariant / QVariantList<double>

Available: For active measurement
Meaning: Parallel to
/Hmi/CtrlEnergy/DeviceNames,
contains the total energy (infeed
+ regenerative energy) of each
configured device.

Unrestricted © Siemens AG 2019 All Rights Reserved

3-76 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.4 SlDataSvcItem reference

The available variable paths in the standard operating area Parameter:

Fig. 3-8: SINUMERIK CTRL-Energy variable paths

In order that the variable paths are active, the configuration file "slctrl_energy.ini"
should be created in the directory "<Installation path>/oem/sinumerik/hmi/cfg" with
the following content:

[Misc]
EnableOAInterface=true

Variable path for tool data depending on the cursor position

The data of the tool selected with the cursor in the standard tool management of
HMI Operate (orange bar) is available in the following variable:

/Hmi/TMHMICurData

In order that this variable path is active, the configuration file "sltmlistconfig.xml"
(milling machine) or "sltmturninglistconfig.xml" (turning machine) should be created
in the directory "<Installation path>/oem/sinumerik/hmi/cfg" with the following
content:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<CONFIGURATION>
<SETTINGS>
<CursorPositionInfoEnabled value="true" type="bool" />
</SETTINGS>
</CONFIGURATION>

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-77
3 Communication with the NC/PLC 11/2019
3.4 SlDataSvcItem reference

Fig. 3-9: Standard tool management of the "DRILL" tool selected with the cursor

In the variable, the data of the currently selected tool is listed as a string. Access to
the variable path can be as read access or as notification (hotlink).

The string has the following format (sample string for above figure):
-adaptNo 0 -containerNo 1 -datetime 2014-09-04T14:55:57 -dlNo 0 -edgeNo 1 -
magNo 1 -mtNo 0 -mtPlaceNo 0 -ncuName @ncu1.local -placeNo 2 -toaNo 1 -
toolDuplo 1 -toolIdent DRILL -toolNo 3 -toolType 200

Table 3-35: Available tool data from "/Hmi/TMHMICurData"

ID Description
General data
-datetime Time stamp
-ncuName Name of the current NCU
-toaNo Current TOA number
-containerNo Current container number

Data to identify a tool

-toolNo T no. ("0" if the cursor is at an empty location)
-toolIdent Tool identifier
(empty string if the cursor is at an empty location)
-toolDuplo Duplo no. of the tool
("0" if the cursor is at an empty location)
-edgeNo Tool cutting edge number
("0" if the cursor is at an empty location)
-toolType Tool type ("0" if the cursor is at an empty location)
-dlNo Tool cutting edge correction location number
("0" if the cursor is at an empty location or no DL corrections have been
set up)

Data to identify a location

Unrestricted © Siemens AG 2019 All Rights Reserved

3-78 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.4 SlDataSvcItem reference

ID Description
-magNo Magazine number
("0" if the current tool is not on a magazine location)
-placeNo Magazine location number
("0" if the current tool is not on a magazine location)
-mtNo Multitool number
("0" if the current tool is not on a multitool location)
-mtPlaceNo Multitool location number
("0" if the current tool is not on a multitool location)
-adaptNo Magazine location adapter number
("0" if the current tool is not on a location or an adapter number has not
been assigned to the location)

Note
The variable is always updated when one of the list screens of the standard tool
management of HMI Operate is exited. This means that the content of the
variable is empty after the startup of HMI Operate.

The order in which the tool data is stored in the variable is not specified.

3.4.3 Creating an SlDataSvcItem object

A number of constructors are available for creating an SlDataSvcItem object. If you
use the default constructor, the values can be set or overwritten later using the
properties.

Table 3-36:Constructors of the item class

public SlDataSvcItem. SlDataSvcItem ()
public SlDataSvcItem. SlDataSvcItem (SlString& name)
public SlDataSvcItem. SlDataSvcItem (char * name)

Parameter Meaning
name Variable name

Example: See Chapter 3.2.2

3.4.4 Properties and functions

name
Variable name of the required data item. The name is stored as a string. The
formatting can be seen in Chapter "Variable names".

Table 3-37: name

public SlString SlDataSvcItem.name;

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-79
3 Communication with the NC/PLC 11/2019
3.4 SlDataSvcItem reference

getName / setName
Gets and sets the variable names.

Table 3-38: getName / setName

public SlString getName();
Parameter Meaning
Return Variable name

public void setName(SlString& name);

Parameter Meaning
name Variable name
Return -

Note
You can also read out and manipulate the name property directly without using
setName() and getName(), for example:

SlDataSvcItem item;
item.name = “/channel/parameter/r[u1, 1]“;
SlString name = item.name;

value
Value of the variable. The type of these properties is SlValue::type, and can have
different contents depending on the specified variable (number, text). On an array
access, the value property contains an array of SlDataSvcItem objects.

Table 3-39:value
public SlValue SlDataSvcItem.value;

There are two further functions for setting/reading value: setValue() and
getValue().
getValue / setValue
Table 3-40: getValue / setValue
public SlValue getValue ();
Parameter Meaning
Return Value

public void setValue (SlValue& value);

Parameter Meaning
value Value
Return -

Note
You can also read out and manipulate the value property directly without using
setValue() and getValue(), for example:

SlDataSvcItem item;
item.value = 1.234;
double value = item.value;

Unrestricted © Siemens AG 2019 All Rights Reserved

3-80 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 3 Communication with the NC/PLC
3.5 SlDataSvcStatus reference

3.5 SlDataSvcStatus reference

3.5.5 Definitions

Overview
Information that is evaluated infrequently when reading, writing, or for notifications
is combined in the class described below.

The class is defined in sloperatecppapi.h.

3.5.6 Properties

error
Error number

Table 3-41:error
public SlDataSvcError error;

timestamp
Time at which the read data was last received in the DataService.

Table 3-42:timeStamp
public time_t timestamp;

readInfo
Information about servers and sequence numbers.

Table 3-43:readInfo
public SupplementReadInfo readInfo;

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 3-81
3 Communication with the NC/PLC 11/2019
3.6 FAQs

3.6 FAQs
3.6.1 FAQs regarding hotlink

Do I need an SlDataSvc object for each hotlink?

Yes. A separate SlDataSvc object is required for each hotlink because an
SlDataSvc object can only ever execute one request at a time.
When should I deactivate or cancel hotlinks?
Whenever a hotlink is not needed, it should be deactivated ("Unsubscribe"). A
hotlink on a form that is not visible is an unnecessary load on communication
resources.
Why does the creation of the first SlDataSvc object take longer?
When an SlDataSvc object is created for the first time, a check is made whether all
data is known (channel, axis and general machine data, all GUD areas, channel,
axis and general setting data). The so-called mapping of this data involves
processing performed only for the first creation.
With an update rate of 200 ms, why are value changes more frequently than
every 200 ms?
The update rate specifies a maximum time frame in which potential value changes
should be returned. If the value changes within the 200 ms, the client application is
informed of this value change more than once within 200 ms. An artificial brake is
not built in.
Values are then supplied less frequently (e.g. only every 200 ms) if the
communication load in the server component is increased by your own or a further
client application.
3.6.2 FAQs regarding machine data/GUDs

Do I have to communicate (map) GUDs and machine data?

No. Mapping is performed once automatically during startup of the application. In
this case, all data is mapped that can be accessed (channel, axis and general
machine data, all GUD areas, channel, axis and general setting data). The access
paths of these variables are described in the "Variable paths for GUDs and
machine data" chapter.
How do I access two-dimensional GUDs?
GUD variables, which are defined in two dimensions, must first be converted to a
one-dimensional array. This means calculating the index. To do this, the
dimensions of the array must be known.

Example:
Definition of GUD: DEF NCK REAL _MYVAR[99,11]
We intend to read variable _MYVAR[2,3].
The index of the access path is calculated as follows: 2*11 + 3 + 1 => 26
It is assumed that this variable is an SGUD, resulting in the following access path:
/NC/_N_CH_GD1_ACX/_MYVAR [26]

Unrestricted © Siemens AG 2019 All Rights Reserved

3-82 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 4 Program instance services (PI services)
4.1 Introduction

4 Program instance services (PI services)

4
Objective of the chapter
This chapter describes the interface of the PiService. This is used for
communication between applications and the NC/PLC, specifically to send program
instance services (PI services).

Note
A PI service call returns immediately. However, it is not guaranteed that the PI
service has been completely executed when it returns. Some PI services return
their status via OPI variables.

4.1 Introduction
4.1.1 Class model

Overview
The class model of the PiService consists primarily of the SlPiSvc class.

class SlPiSvc
This class is defined in "sloperatecppapi.h". It provides functions for
executing PI services.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 4-83
4 Program instance services (PI services) 11/2019
4.2 Step-by-step examples

4.2 Step-by-step examples

Overview
The following chapters show the various applications for the
PiService step-by-step. For every "step-by-step example," there is an
executable example in SINUMERIK Integrate Create MyHMI /3GL.

These and all other examples are shown in the following overview of examples.

Table 4-1: Overview of the examples

Application Example Chapter
Sending a general PI service SlPiSvcCmd 4.2.2

Only the items relevant for the PiService are explained or described in each
example. The comments for the sources contain more detailed
information (e.g. screen layout, outputs, etc.).

4.2.1 Preparation

Overview
Preparatory measures are described in Chapter 2.1  "New Project". All of the
items described there must be executed first.

4.2.2 Sending a general PI service

Overview
The following example shows how a general PI service is sent. The required
parameters can be entered on the user interface. The PI service is then sent using
the "execute" button. In this example, part program "MYMPF.MPF" in channel 1
(201) is selected for processing (_N_SELECT). To enable the example to be
executed, a part program with the name "MYMPF.MPF" must be created in the NC.

Unrestricted © Siemens AG 2019 All Rights Reserved

4-84 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 4 Program instance services (PI services)
4.2 Step-by-step examples

Fig. 4-1: Example of SlPiSvcCmd

Step 1
Prepare the arguments. First an array of four strings args is created to receive the
entry from the user interface. This array of arguments includes the parameter
assignment for the PI service.

#define MAX_LOADSTRING 100

char buffer[MAX_LOADSTRING];
TCHAR wBuffer[MAX_LOADSTRING] = {0};
LPWSTR uiArg = wBuffer;
LPCSTR sArg = buffer;

// read arguments
SlVector<SlString> args;

// Arg1
GetWindowText(hwndEditArg1, uiArg, MAX_LOADSTRING);
UnicodeToAnsi(uiArg, (LPSTR) sArg, MAX_LOADSTRING);
args.push_back(SlString(sArg));

// Arg2
GetWindowText(hwndEditArg2, uiArg, MAX_LOADSTRING);
UnicodeToAnsi(uiArg, (LPSTR) sArg, MAX_LOADSTRING);
args.push_back(SlString(sArg));

// Arg3
GetWindowText(hwndEditArg3, uiArg, MAX_LOADSTRING);
UnicodeToAnsi(uiArg, (LPSTR) sArg, MAX_LOADSTRING);
args.push_back(SlString(sArg));

// Arg4
GetWindowText(hwndEditArg4, uiArg, MAX_LOADSTRING);
UnicodeToAnsi(uiArg, (LPSTR) sArg, MAX_LOADSTRING);
args.push_back(SlString(sArg));

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 4-85
4 Program instance services (PI services) 11/2019
4.2 Step-by-step examples

Step 2
Create the SlPiSvc object. When you create the object, the array of the arguments
for the PI service is passed in the constructor.

// create an instance of the SlPiSvc

SlPiSvc piSvc840Dsl(args);

Step 3
Send the PI command. Execution of the PI service is initiated using the start()
function.

// execute PI Cmd
SlPiSvcError err = piSvc840Dsl.start(status);

Unrestricted © Siemens AG 2019 All Rights Reserved

4-86 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 4 Program instance services (PI services)
4.3 Reference SlPiSvc

4.3 Reference SlPiSvc

4.3.1 Definitions

Overview
The SlPiSvc object is used to send program instance services (PI services).

All calls are implemented as synchronous and asynchronous accesses.

Synchronous calls block the calling item until the request has been completed.

The SlPiSvc class is defined in "sloperatecppapi.h".

4.3.2 Creating an SlPiSvc object

Two constructors are available for creating an SIPiSvc object.

Table 4-2:Constructors of the SlPiSvc class

public SlPiSvc.SlPiSvc(void)

public SlPiSvc.SlPiSvc(SlVector<SlString>& args)

Parameter Meaning
args Array of parameters required to execute a
general PI service in the NCK.
Return -

Example: See Chapter 4.2.2

4.3.3 Sending a PI service

A PI service is sent using the functions: start(), startAsync(),
cancel(), stop().

start

Triggers a PI service.

Table 4-3: start

public SlPiSvcError start()
Parameter Meaning
Return SlPiSvcError

public SlPiSvcError start(SlPiSvcStatus& status)

Parameter Meaning
Status Status (error number and timestamp)
Return SlPiSvcError

Example: See Chapter 4.2.2

startAsync
Triggers a PI service asynchronously.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 4-87
4 Program instance services (PI services) 11/2019
4.3 Reference SlPiSvc

Table 4-4: startAsync

public SlPiSvcError startAsync(ISlPiSvcCb* cb)
Parameter Meaning
Cb Callback interface: Pointer to the
implementation of the class ISlPiSvcCb
Return SlPiSvcError

cancel
Cancels a PI service.

Table 4-5: cancel

public SlPiSvcError cancel()
Parameter Meaning
Return SlPiSvcError

stop
Triggers a PI STOP command.

Table 4-6: stop

public void stop()
Parameter Meaning
Return -

4.3.4 Additional functions

plcMemoryReset
Triggers a PLC memory reset.

Table 4-7: plcMemoryReset

public void plcMemoryReset ()
Parameter Meaning
Return -

getTimeout / setTimeout

Gets the timeout for access control.

Table 4-8: getTimeout / setTimeout

public long void getTimeout ()
Parameter Meaning
Return Time in msec

public void setTimeout (long t)

Parameter Meaning
T Time in msec.
Return -

getArgs / setArgs
Gets or sets PI service parameters (string array).

Unrestricted © Siemens AG 2019 All Rights Reserved

4-88 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 4 Program instance services (PI services)
4.3 Reference SlPiSvc

Table 4-9: getArgs / setArgs

public SlVector<SlString> getArgs ()
Parameter Meaning
Return PI service parameters (SlString array).

public void setArgs (SlVector<SlString>& args)

Parameter Meaning
args PI service parameters (SlString array).
Return -

getPriorityFlags / setPriorityFlags
Gets or sets flags for access control.

Table 4-10: getPriorityFlags / setPriorityFlags

public SlPriorityFlags getPriorityFlags ()
Parameter Meaning
Return SlPriorityFlags: Priority
SlPriorityFlags.lowPriority
SlPriorityFlags.highPriority
SlPriorityFlags.defaultPriority
(see setPriorityFlags)

public void setPriorityFlags (SlPriorityFlags prio)

Parameter Meaning
prio Priority
Return -

The Pi service uses three processing priorities:

SlPriorityFlags.lowPriority
Low processing priority. This value should be used for cyclic activities and activities
running in the background.

SlPriorityFlags.highPriority
High processing priority. This value is reserved for exclusive use by the machine
manufacturer to achieve productivity goals (e.g. tool change).

SlPriorityFlags.defaultPriority
Default processing priority.

Please note the following supplementary conditions:

The processing priorities are active only within the PiService. Low-priority
requests that have already started will no longer be overtaken by higher-priority
requests.

Note
The flag defaultPriority (value = 0) does not have to be explicitly set. This
value is automatically set after creating an SlPiSvc object.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 4-89
4 Program instance services (PI services) 11/2019
4.3 Reference SlPiSvc

Unrestricted © Siemens AG 2019 All Rights Reserved

4-90 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.1 Overview

5
5 Access to alarms and events

Objective of the chapter

This chapter describes the interface of the alarm service. It provides functions for
handling alarms and messages from the PLC, the NCK (including drive alarms),
and the HMI. It supplies all alarms and messages of the HMI as well as an NCU
connected to the HMI (NCK and PLC). Specific alarms and messages include:
• HMI alarms
• NCK alarms including drive alarms (provided they are forwarded from the
NCK)
• Part program messages from the NCK
• Diagnostic buffer alarms and PLC messages (FC10)
• Alarm_S(Q) alarms (SFC17/18, PDiag, HiGraph, S7-Graph) with results of
criteria analysis

All applications wishing to acquire alarms and events, for example, for display
purposes or for further processing and forwarding to MES, are referred to as clients
in the following.

Note
The communication time is not guaranteed. Real-time tasks therefore
cannot be performed with the C++ interface.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-91
5 Access to alarms and events 11/2019
5.1 Overview

5.1 Overview
5.1.1 Introduction and explanation of terms

Alarms and events

An alarm designates an interval during which an exceptional or critical state exists
in a process (NCK/PLC/HMI). In contrast, an event designates a certain point in
time at which an alarm occurs, disappears, or is acknowledged by the user
(coming, going or acknowledgment event). Therefore, an alarm can be in various
states depending on the events and an event is a transition from one state to
another. Fig. 5-1 below illustrates the relationship.

Fig. 5-1: Alarms and events

Client, service and source

The alarm service provides functions for implementing an alarm client.
An alarm client is generally an application that is used for monitoring alarms along
with their states, parameters, timestamps, etc. The alarm client always
communicates with the alarm service. The alarm service, in turn, communicates
with the various alarm sources (alarm sources) in the system, i.e. HMI, PLC, and
NCK alarms (including drive alarms).

The following subchapters describe the signal flow between client, service, and
source as a function of the various alarm types.

Alarm source
The alarm service supplies alarms from various alarm sources of an NC. The alarm
service makes a distinction between the following standard sources:

Table 5-1: Specified alarm source identifiers (source URL) of the alarm service
Source Source URL
HMI /HMI
NCK /NCK
NCK channels /NCK/Channel#<Channel No>/Partprogram
(only for part program messages
PLC diagnostic buffer /PLC/DiagBuffer
PLC PMC alarms /PLC/PMC
(Alarm_S(Q): PDiag, S7-Graph, and
HiGraph)

Unrestricted © Siemens AG 2019 All Rights Reserved

5-92 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.1 Overview

Alarm attributes
With every alarm, the client is provided not only with the alarm number identifying
the alarm but also with additional data such as the alarm state, a timestamp, or
associated process values. This data is referred to as attributes. There are
standard attributes and additional attributes. The standard attributes are identical
for all alarm categories (see alarm category), while the additional attributes can
vary from category to category.

In addition, the attributes differ according to their source: They can originate
directly from the alarm source (e.g. timestamp, associated process values) or,
alternately, they can come from a configuration (e.g. priority).

The alarm service provides a fixed number of attributes via the alarm object.

Alarm category
Not all alarms support the same set of attributes: For example, part program
messages have no associated process values. To be able to differentiate alarms
with regard to their attributes, they are assigned to different categories. All alarms
of one category support the same set of attributes.

HMI alarms
HMI alarms are alarms that originate in the HMI itself. In this case, the HMI
applications are the alarm source.

Synchronous calls
Synchronous calls return only after the request has been performed, i.e. the calling
thread is blocked. This can interfere with event processing since control inputs and
displays are withheld during a synchronous call. For this reason, calls that may
take a long time should be performed asynchronously.

5.1.2 Class model

Overview
The class model of the alarm service consists primarily of the following classes:
• SlAlarmSvc
• SlAlarm
• SlAlarmSource

All classes are defined in sloperatecppapi.h.

#include "sloperatecppapi.h"

Class SlAlarmSvc
The SlAlarmSvc class provides functions to monitor alarms. Further, via this class,
the existing alarm sources can be read out.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-93
5 Access to alarms and events 11/2019
5.1 Overview

Class SlAlarm
This class represents an individual alarm. The class contains only functions that
reflect the various attributes of an alarm.

Class SlAlarmSource
The SlAlarmSource class represents an alarm source. The class only comprises
functions that are required to define an alarm source.

Unrestricted © Siemens AG 2019 All Rights Reserved

5-94 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.2 Step-by-step examples

5.2 Step-by-step examples

Overview
The following chapters show the various applications of the alarm service step-by-
step. An executable example is included in the SINUMERIK Integrate Create
MyHMI /3GL for each "step-by-step example".

These and all other examples are shown in the following overview of examples.

Table 5-2: Overview of the examples

Application Example Chapter
Accessing the alarm list. Displaying the SlAlarmSvcAlarmList 5.2.2
currently pending alarms
Triggering/resetting alarms SlAlarmSvcSetResetAlarm 5.2.3

Only the items relevant for the AlarmService are explained or described in each
example. The comments for the sources contain more detailed information (e.g.
screen layout, outputs, etc.).

5.2.1 Preparation

Overview
Preparatory measures are described in Chapter 2.1  "New Project". All of the
items described there must be executed first.

5.2.2 Accessing the alarm list

Overview
In this example, a notification is activated about the change to the alarm list after
"Subscribe" is clicked. All currently pending alarms are displayed in the list box. If
the alarm list changes, then it is output again with current data.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-95
5 Access to alarms and events 11/2019
5.2 Step-by-step examples

Fig. 5-2: Accessing the alarm list

Step 1
Create the required member variables (an object of type SlAlarmSvc and a
variable of type IslAlarmSvcCb, that is, a pointer that points to the callback
method):

// Object alarm
SlAlarmSvc m_Alarm;

// Pointer to callback method

ISlAlarmSvcCb* m_pAlarmCb;
m_pAlarmCb = new AlarmCb();

Step 2
Create a subscription. Here, the pointer of the implemented callback method in
which the change to the alarm list is to be communicated is passed.

SlAlarmSvcError err = m_Alarm.subscribeAlarms(m_pAlarmCb);

Step 3
Implement the callback method. Here, the alarms that are currently pending are
now displayed.

Unrestricted © Siemens AG 2019 All Rights Reserved

5-96 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.2 Step-by-step examples

// list of alarms received

SlVector<SlAlarm> alarmList;

// window to inform
HWND msgWindow;

void SlAlarmlistChanged(SlVector<SlAlarm>& alarms)

{
alarmList.clear();
for(int i = 0; i < alarms.size(); i++)
{
alarmList.push_back(alarms.at(i));
}

// call main window to show result

PostMessage(msgWindow, WM_COMMAND, 10, 0);
}

Step 4
Unsubscribe the subscription.

SlAlarmSvcError err = m_Alarm.unSubscribeAlarms(m_pAlarmCb);

5.2.3 Triggering / reset of alarms

Overview
In this example, an alarm is triggered with "set alarm". The alarm is displayed in the
list box. It is reset with "reset alarm".

! Important
Configuration and language files (error message texts) must first be copied from
the example project to the OEM configuration (cfg) or language file directory (lng).

Copy the following files to "../oem/sinumerik/hmi/lng":

• slCppApiEventSource_alarmtext_deu.ts
• slCppApiEventSource_alarmtext_eng.ts

Copy the following files to "../oem/sinumerik/hmi/cfg":

• slaesvcadapconf.xml
• slaesvcconf.xml
• slCppApiEventSource_db.xml

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-97
5 Access to alarms and events 11/2019
5.2 Step-by-step examples

Fig. 5-3: Triggering/resetting alarms

Step 1
Create the necessary variables (an object of type SlAlarmSvc):

// Object alarm
SlAlarmSvc m_Alarm;

Step 2
Trigger (or reset) an alarm.

// Alarm number, e.g. 131000

int alarmNo = 131000;

// Set alarm
SlAlarmSvcError err = m_Alarm.SetAlarm (alarmNo);

...
// … or reset alarm
SlAlarmSvcError err = m_Alarm.ResetAlarm (alarmNo);

Unrestricted © Siemens AG 2019 All Rights Reserved

5-98 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.3 SlAlarmSvc reference

5.3 SlAlarmSvc reference

5.3.1 Definitions

Overview
The SlAlarmSvc object can be used to access alarms that are currently active. This
is achieved using a subscription. The notification that the current alarm list has
changed is effected by calling the implemented callback method.

Only the default constructor exists. SlAlarmSvc objects cannot be copied or

assigned.

The class is defined in sloperatecppapi.h.

Subscription
The client-side access to alarms (e.g. for an alarm display) is implemented using
subscriptions and the alarm service manages a dedicated subscription for each
client. If the state of an alarm changes, the client is notified via the subscription
assigned to it by calling the implemented callback method.

The following subscriptions are currently available:

• Subscription with alarm list
• Subscription with event list
• Subscription with individual events

Note
No provision is made for sharing of one subscription by multiple clients.

5.3.2 Creating an SlAlarmSvc object

The following constructors are available to create an SlAlarmSvc object:

Table 5-3: Creating an SlAlarmSvc object

public SlAlarmSvc(SlString language)
public SlAlarmSvc(SlString language, SlString ncu)
public SlAlarmSvc(SlString language, SlString ncu, int eventlistLength)
Parameter Meaning
language Language, in which the alarm texts are to be communicated.
("eng", "deu", etc.)
ncu Defines in 1:N constellations which
NC supplies data
eventlistLength Defines the size of the event list, default: 20

5.3.3 Notification about a change in the current alarm list

subscribeAlarms
Creates a notification about a change in the current alarm list. The call returns as
soon as the setup request has been forwarded to the server. Notification is

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-99
5 Access to alarms and events 11/2019
5.3 SlAlarmSvc reference

performed by implementing the callback method SlAlarmListChanged(). The

first notification returns the state at the time of the setup.

Notifications can be canceled using an unsubscribe() call. The request is also

canceled as soon as the deletion of the relevant SlAlarmSvc object is detected.

Table 5-4: subscribeAlarms – creating a subscription.

public SlAlarmSvcError subscribeAlarms (ISlAlarmSvcCb* cb)
Parameter Meaning
cb Pointer to the callback method
implementation for reporting the state
change. That is, this pointer points to the
IslAlarmSvcCb class where the callback
method SlAlarmlistChanged() to be
implemented is located.
Return SlAlarmSvcError

Table 5-5: SIAlarmListChanged – specification for the callback implementation

public void SlAlarmlistChanged(SlVector<SlAlarm>& alarms)
Parameter Meaning
alarms Array of alarm objects. This array reflects
alarms that are currently pending. See
Chapter: 5.4 SlAlarm reference

Return -

Example: See Chapter 5.2.2

unsubscribeAlarms
Unsubscribes a running subscription.

Table 5-6:unsubscribeAlarms – ending a subscription

public void UnSubscribe(AlarmListChanged cb)
Parameter Meaning
cb Pointer to the callback method
implementation for reporting the state
change. That is, this pointer points to the
IslAlarmSvcCb class where the callback
method SlAlarmlistChanged() to be
implemented is located.
Return SlAlarmSvcError

Example: See Chapter 5.2.2

5.3.4 Notification about a change in the event list

subscribeEventList
Creates a notification about a change to the content of the alarm-event ring buffer;
this notification contains the state changes (coming, going, acknowledgment) of the
alarms. The call returns as soon as the setup request has been forwarded to the
server. Notification is performed by implementing the callback method
SlAlarmEventlistChanged().The first notification returns the content of the
event ring buffer at the time of creation. Subsequently, the complete content of the

Unrestricted © Siemens AG 2019 All Rights Reserved

5-100 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.3 SlAlarmSvc reference

ring buffer is returned when new events occur. Because the size of the list cannot
be infinite, the oldest elements are deleted when new events are generated (FIFO
principle).

Table 5-7: subscribeEventList – creating a subscription.

public SlAlarmSvcError subscribeEventList(
ISlAlarmSvcEventsCb* SlAlarmEventlistChanged)
Parameter Meaning
SlAlarmEventlistChanged Pointer to the callback method
implementation for reporting the state
change. That is, this pointer points to the
ISlAlarmSvcEventsCb class where the
callback method
SlAlarmEventlistChanged() to be
implemented is located.
Return SlAlarmSvcError

Table 5-8: SlAlarmEventlistChanged – specification for the callback implementation

public void SlAlarmEventlistChanged(SlVector<SlAlarm>& alarms)
Parameter Meaning
alarms Array of alarm objects. It contains the
alarm events from the ring buffer.
Return -

unSubscribeEventList
Unsubscribes a running subscription.

Table 5-9: unsubscribeEventList

public SlAlarmSvcError unSubscribeEventList(
ISlAlarmSvcEventsCb* SlAlarmEventlistChanged)
Parameter Meaning
SlAlarmEventlistChanged Pointer to the callback method
implementation for reporting the state
change. That is, this pointer points to the
ISlAlarmSvcEventsCb class where the
callback method
SlAlarmEventlistChanged() to be
implemented is located.
Return SlAlarmSvcError

5.3.5 Notification about a change in an individual event

subscribeEvents
Creates a notification for new alarm events, i.e. state changes (coming, going,
acknowledgment) of the alarms. The call returns as soon as the setup request has
been forwarded to the server. Notification is performed by implementing the
callback method SlAlarmNewEvent().The first notification returns the content of
the event ring buffer at the time of creation. Subsequently, newly occurred alarm
events are returned individually.

Table 5-10: subscribeEvents – creating a subscription.

public SlAlarmSvcError subscribeEvents(
ISlAlarmSvcEventsCb* SlAlarmNewEvent)

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-101
5 Access to alarms and events 11/2019
5.3 SlAlarmSvc reference

Parameter Meaning
SlAlarmNewEvent Pointer to the callback method
implementation for reporting the state
change. That is, this pointer points to the
ISlAlarmSvcEventsCb class where the
callback method SlAlarmNewEvent() to be
implemented is located.
Return SlAlarmSvcError

Table 5-11: SlAlarmNewEvent – specification for the callback implementation

public void SlAlarmNewEvent(SlVector<SlAlarm>& alarms)
Parameter Meaning
alarms Array of alarm objects. It contains the new
alarm events.
Return -

unSubscribeEvents
Unsubscribes a running subscription.

Table 5-12:unSubscribeEvents
Public SlAlarmSvcError unSubscribeEvents(
ISlAlarmSvcEventsCb* SlAlarmNewEvent)
Parameter Meaning
SlAlarmNewEvent Pointer to the callback method
implementation for reporting the state
change. That is, this pointer points to the
ISlAlarmSvcEventsCb class where the
callback method SlAlarmNewEvent() to be
implemented is located.
Return SlAlarmSvcError

Unrestricted © Siemens AG 2019 All Rights Reserved

5-102 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.3 SlAlarmSvc reference

5.3.6 Additional functions

getSources
Provides an array of AlarmSource objects.
(see Chapter 5.5 "Reference SlAlarmSource")

Table 5-13: getSources

public SlAlarmSvcError getSources(SlVector<SlAlarmSource>& alarmSources)
alarmSources Array of alarm sources
Return SlAlarmSvcError

setAlarm
Sets an alarm.

Table 5-14: setAlarm

public SlAlarmSvcError setAlarm(SlAlarm alarm);
alarm Alarm
Return SlAlarmSvcError

resetAlarm
Resets an alarm.

Table 5-15: resetAlarm

public SlAlarmSvcError resetAlarm(SlAlarm alarm);
alarm Alarm
Return SlAlarmSvcError

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-103
5 Access to alarms and events 11/2019
5.4 SlAlarm reference

5.4 SlAlarm reference

5.4.7 Definitions

Overview
An instance of the alarm class represents a pending alarm. The alarm class
contains only functions that provide access to all available attributes.

The class is defined in sloperatecppapi.h.

5.4.8 Functions

getId / setId
Gets or sets an alarm ID (alarm number) that identifies an alarm in the context of a
particular source (alarm source), i.e. the source and alarm ID determine the
appropriate alarm text.

! Important
It is possible to reuse the same alarm ID within different alarm sources (source
IDs) and to provide it with different alarm texts. That is, the alarm IDs no longer
have to be unique across all alarm sources. This means that (unique) assignment
between an alarm and alarm text is only possible with the tuple alarm ID plus
source ID.

Table 5-16: getId / setId

public long getId()
Return Alarm ID

public void setId(long id)

id Alarm ID
Return -

A separate number range is reserved for each of the alarm sources. The following
table lists the number ranges:

Table 5-17: Alarm number ranges

Number range Sourc Description
e
000.000 – 009.999 NCK General alarms
010.000 – 019.999 Channel alarms
020.000 – 029.999 Axis / spindle alarms
030.000 – 039.999 Functional alarms General information
040.000 – 059.999 Reserved
060.000 – 064.999 Cycle alarms SIEMENS
065.000 – 069.999 Cycle alarms user
070.000 – 079.999 Compile cycle
manufacturer and OEM
080.000 – 081.999 Messages standard cycles
082.000 – 082.999 Messages Shopmill & CMT
cycles
083.000 – 084.999 Messages, measurement
cycles

Unrestricted © Siemens AG 2019 All Rights Reserved

5-104 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.4 SlAlarm reference

Number range Sourc Description

e
085.000 – 089.999 Messages, user cycles
090.000 – 099.999 Reserved
100.000 – 129.000 HMI System
130.000 – 139.000 OEM
140.000 – 199.999 Reserved
200.000 – 299.999 NCK SINAMICS drive
300.000 – 399.999 611D drive
400.000 – 499.999 PLC General alarms
500.000 – 599.999 Channel alarms
600.000 – 699.000 Axis / spindle alarms
700.000 – 799.999 User area
800.000 – 899.999 Sequencers/graphs
(810.000 – 810.009) System error messages
900.000 – 999.999 NCK 611U drive

getSource / setSource
Gets or sets an alarm source (Source) of the alarm.

Table 5-18: getSource / setSource

public SlAlarmSource getSource ()
Return SlAlarmSource

public void setSource (SlAlarmSource source)

source Alarm source
Return -

getMessage / setMessage
Gets or sets an alarm text in the specified language.

Table 5-19: getMessage / setMessage

public SlString getMessage ()
Return Alarm text

public void setMessage (SlString message)

message Alarm text
Return -

getWCharMessage / setWCharMessage
Gets or sets an alarm text in the specified language. The alarm text is of type
wchar_t.

To use the function, the following project setting must be checked and corrected if
necessary.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-105
5 Access to alarms and events 11/2019
5.4 SlAlarm reference

Fig. 5-4: Project setting for use of getWCharMessage / setWCharMessage

Table 5-20: getWCharMessage / setWCharMessage

public const wchar_t* getWCharMessage ()
Return Alarm text of type wchar_t

public void setWCharMessage (wchar_t* message)

message Alarm text of type wchar_t
Return -

getInstance / setInstance
Gets or sets the alarm instance ID. Several alarms can occur at the same time
within one alarm source. The alarm instance ID is used to differentiate between
these alarm instances.

Table 5-21: getInstance / setInstance

public int getInstance ()
Return Alarm instance ID

public void setInstance (int instance)

instance Alarm instance ID
Return -

getParameters / setParameters
Gets or sets the dynamic parameters (associated values, process values) of an
alarm.

Table 5-22: getParameters / setParameters

public SlVector<SlString> getParameters ()
Return Array of parameters

public void setParameters (SlVector<SlString> parameters)

parameters Array of parameters
Return -

Unrestricted © Siemens AG 2019 All Rights Reserved

5-106 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.4 SlAlarm reference

getTimeStamp
Gets the timestamp.

Table 5-23: getTimeStamp

public time_t getTimeStamp ()
Return Time stamp

getComment / setComment
Gets or sets a comment on the alarm.

Table 5-24: getComment / setComment

public SlString getComment ()
Return Comment

public void setComment (SlString comment)

comment Comment
Return -

getHelpFileUrl / setHelpFileUrl
Gets or sets the URL address of an HTML file locally or on a server in the network.

Table 5-25: getHelpFileUrl / setHelpFileUrl

public SlString getHelpFileUrl()
Return URL address

public void setHelpFileUrl(SlString url)

url URL address
Return -

getCancelGroup / setCancelGroup
Alarms with the same CancelGroup for a collective cancellation group. When one
alarm is canceled, all alarms of the same group are automatically also canceled.

Table 5-26: getCancelGroup / setCancelGroup

public SlAlarmCancelGroup getCancelGroup()
Return Group

public void setCancelGroup(SlAlarmCancelGroup group)

group Group
Return -

Possible values:
SlAlarmCancelGroup.NONE
Value not assigned.

SlAlarmCancelGroup.HMI
Cancels all HMI alarms.

SlAlarmCancelGroup.HMI_AND_NCU
Cancels all NCU and HMI alarms.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-107
5 Access to alarms and events 11/2019
5.4 SlAlarm reference

getCategory / setCategory
Gets or sets the category of the alarm.

Table 5-27: getCategory / setCategory

public SlAlarmCategory getCategory()
Return Category

public void setCategory(SlAlarmCategory cat)

cat Category
Return -

Possible values:
SlAlarmCategory.NONE
Value not assigned.

SlAlarmCategory.SINUMERIK
Alarm is a general SINUMERIK alarm.

SlAlarmCategory.PARTPROG_MESSAGE
Alarm is a part program message (MSG() call in the part program).

getClearInfo / setClearInfo
The ClearInfo (clear criterion) identifies a group of alarms. The value provides
information about the action (e.g. "NC Reset") that can cancel an alarm (and
therefore all of the alarms of this group). Unlike SlAlarmCancelGroup, the clear
operation for these alarms is not performed by the alarm service. It is performed
directly in the alarm source (e.g. NC kernel). This means that the NC kernel sends
a going event as an alarm source for every alarm.

Table 5-28: getClearInfo / setClearInfo

public SlAlarmClearInfo getClearInfo()
Return About

public void setClearInfo(SlAlarmClearInfo info)

info About
Return -

The following table contains all predefined values for SlAlarmClearInfo. At present,
the SlAlarmClearInfo structure has not yet been assigned and the numerical values
are saved.

Unrestricted © Siemens AG 2019 All Rights Reserved

5-108 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.4 SlAlarm reference

Table 5-29: Overview of the cancel criteria

Cancel Alarm source Description
criterion (source)
(ClearInfo)
0 HMI Alarms that are canceled by the HMI.
1 NCK Alarms that are canceled by power-on of the NCU.
2 Conditions are canceled by a hardware reset of the
NCU.
3 Conditions are canceled by a cancel command to
the NCU.
4 Conditions are canceled by the NCK itself.
5 Conditions are canceled by an "NC Start" command
of the NCU.
6 Conditions are canceled by a reset of the mode
group.
7 Conditions are canceled by an "NC Reset"
command on the NCU.
8 PLC PLC messages of the FB15 (basic program).
9 PLC alarm of the FB15 (basic program).
10 Dialog alarms of the HMI that are canceled by the
"Recall" key [^].
11 Reserved
12 S7-PDiag, S7-Graph, S7-HiGraph or other
Alarm_S(Q) alarms of the PLC (SFC17/18) with
alarm state "not acknowledged".
13 S7-PDiag, S7-Graph, S7-HiGraph or other
Alarm_S(Q) alarms of the PLC (SFC17/18) with
alarm state "acknowledged".
14 Drive (NCK) Drive alarms via NCK.

getPriority
Gets the priority of an alarm. The priority is assigned when configuring the alarm
attributes.

Table 5-30: getPriority

public int getPriority ()
Return Priority

getDisplayLocation / setDisplayLocation
Gets or sets the display location at which an alarm is displayed. This is, for
example, the alarm line in the header or a message window at the center of the
screen.

Table 5-31: getDisplayLocation / setDisplayLocation

public SlAlarmDisplayLocation getDisplayLocation()
Return Display location

public void setDisplayLocation(SlAlarmDisplayLocation loc)

loc Display location
Return -

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-109
5 Access to alarms and events 11/2019
5.4 SlAlarm reference

Possible values:

SlAlarmDisplayLocation.NONE
Value not assigned.

SlAlarmDisplayLocation.HEADER
Alarm is displayed in the alarm line.

SlAlarmDisplayLocation.SCREEN
Alarm is displayed as a "message box" in the center of the screen.

getQuality / setQuality
Gets or sets the quality that provides information about the reliability of an alarm.

Table 5-32: getQuarity / setQuarity

public SlAlarmQuality getQuarity ()
Return Quality

public void setQuarity (SlAlarmQuality quality)

Quality Quality
Return -

Possible values:

SlAlarmQuality.QUALITY_BAD
The quality of the alarm received is poor, i.e. the data should not be used.

SlAlarmQuality.QUALITY_GOOD
The quality of the alarm received is good, i.e. the data can be used.

SlAlarmQuality.QUALITY_UNCERTAIN
AlarmSvc cannot ascertain whether the data received is good or poor.

getState / setState
Gets or sets the alarm state.

Table 5-33: getState / setState

public SlAlarmState getState ()
Return Alarm state

public void setState (SlAlarmState state)

state Alarm state
Return -

Unrestricted © Siemens AG 2019 All Rights Reserved

5-110 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.4 SlAlarm reference

Possible values:

SlAlarmState.UNKNOWN
Unknown state.

SlAlarmState.ALARM_STATE_ACTIVE
Alarm is active.

SlAlarmState.ALARM_STATE_ACKED
Alarm is acknowledged.

SlAlarmState.ALARM_STATE_ENABLED
Alarm is enabled.

SlAlarmState.ALARM_CHANGE_ACTIVE
The active flag has changed.

SlAlarmState.ALARM_CHANGE_ACKED
The acknowledged flag has changed.

SlAlarmState.ALARM_CHANGE_ENABLED
The enabled flag has changed.

SlAlarmState.ALARM_ACK_REQUIRED
The alarm requires an acknowledgment.

SlAlarmState.ALARM_HMI_CANCEL_BTN
HMI alarm with automatic cancellation by the cancel key ("BigMac" key) of the HMI.

SlAlarmState.ALARM_HMI_CANCEL_TIME
HMI alarm with automatic cancellation by timeout.

Alarm states of alarms not requiring acknowledgment:

SlAlarmState.ALARM_COMING
Alarm not requiring acknowledgment is coming.
(ALARM_STATE_ENABLED + ALARM_STATE_ACTIVE +
ALARM_CHANGE_ACTIVE)

SlAlarmState.ALARM_CAME_GOING
Alarm not requiring acknowledgment came and is now going.
(ALARM_STATE_ENABLED + ALARM_CHANGE_ACTIVE)

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-111
5 Access to alarms and events 11/2019
5.4 SlAlarm reference

Alarm states of HMI alarms not requiring acknowledgment with cancellation

using the cancel key ("BigMac" key):

SlAlarmState.ALARM_HMI_CANCEL_BTN_COMING
An HMI alarm not requiring acknowledgment with cancellation using the cancel key
("BigMac" key) is coming.
(ALARM_HMI_CANCEL_BTN + ALARM_COMING)

SlAlarmState.ALARM_HMI_CANCEL_BTN_CAME_GOING
An HMI alarm not requiring acknowledgment with cancellation using the cancel key
("BigMac" key) is going.
(ALARM_HMI_CANCEL_BTN + ALARM_CAME_GOING)

Alarm states of HMI alarms not requiring acknowledgment with cancellation

by timeout:

SlAlarmState.ALARM_HMI_CANCEL_TIME_COMING
An HMI alarm not requiring acknowledgment with cancellation by timeout is
coming.
(ALARM_HMI_CANCEL_TIME + ALARM_COMING)

SlAlarmState.ALARM_HMI_CANCEL_TIME_CAME_GOING
An HMI alarm not requiring acknowledgment with cancellation by timeout is going.
(ALARM_HMI_CANCEL_TIME + ALARM_CAME_GOING)

Alarm states of alarms requiring acknowledgment:

SlAlarmState.ALARM_COMING_TOACK
Alarm requiring acknowledgment is coming and still has to be acknowledged.
(ALARM_ACK_REQUIRED + ALARM_COMING)

SlAlarmState.SLAE_ALARM_CAME_GOING_TOACK
Alarm requiring acknowledgment came and is going but still has to be
acknowledged.
(ALARM_ACK_REQUIRED + ALARM_CAME_GOING)

SlAlarmState.ALARM_CAME_GONE_ACKING
Alarm requiring acknowledgment came, went, and is being acknowledged.
(ALARM_ACK_REQUIRED + ALARM_STATE_ENABLED + ALARM_STATE_ACKED
+ ALARM_CHANGE_ACKED)

SlAlarmState.ALARM_CAME_ACKING
Alarm requiring acknowledgment came and is being acknowledged.
(ALARM_ACK_REQUIRED + ALARM_STATE_ENABLED +
ALARM_STATE_ACTIVE + ALARM_STATE_ACKED + ALARM_CHANGE_ACKED)

SlAlarmState.ALARM_CAME_ACKED_GOING
Alarm requiring acknowledgment came, was acknowledged, and is going.
(ALARM_ACK_REQUIRED + ALARM_STATE_ENABLED + ALARM_STATE_ACKED
+ ALARM_CHANGE_ACTIVE)

Unrestricted © Siemens AG 2019 All Rights Reserved

5-112 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 5 Access to alarms and events
5.5 SlAlarmSource reference

5.5 SlAlarmSource reference

5.5.1 Definitions

Overview
An instance of the SlAlarmSource class represents an alarm source. An alarm
source is defined using an identification number (ID) and a name. The class is
defined in sloperatecppapi.h.

5.5.2 Functions

getId / setId
Gets or sets an alarm ID (alarm number) of the alarm source.

Table 5-34: getId / setId

public long getId()
Return Alarm ID

public void setId(long id)

id Alarm ID
Return -

getName / setName
Gets or sets the name of the alarm source.

Table 5-35: getName / setName

public SlString getName() const
Return Name of the alarm source.

public void setName(SlString source)

source Name of the alarm source.
Return -

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 5-113
5 Access to alarms and events 11/2019
5.5 SlAlarmSource reference

Unrestricted © Siemens AG 2019 All Rights Reserved

5-114 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.1 Introduction

6 Directory and file services

6
Objective of the chapter
This chapter describes the interface of the file service. This service is used for file
and directory operations.

6.1 Introduction
6.1.1 Class model

Overview
The class model of the file service consists primarily of the following classes:
• SlFileSvc
• SlNode
• SlFileSvcStatus

The SlNode class also uses the following class:

• SlAccessRights

All classes are defined in sloperatecppapi.h.

#include "sloperatecppapi.h"

Class SlFileSvc
File and directory operations can be implemented using SlFileSvc objects. These
are especially:
• Creating files/directories
• Copying files/directories
• Moving files/directories
• Deleting files/directories
• Renaming files/directories
• Listing files/directories
• Setting up a notification for drives
• Unsubscribing a notification for drives
• Block-by-block data transfer

In addition, functions for SINUMERIK-specific tasks are available. For example,

access rights can be modified and part programs can be selected for execution.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-115
6 Directory and file services 11/2019
6.1 Introduction

Many calls are available in both synchronous and asynchronous

forms. Synchronous calls block the thread in which the call takes place,
until the request has been completed. For asynchronous calls, after completing the
operation, an implementation of the callback method is called.

Class SlNode
The SlNode class represents a file or a directory. The corresponding attributes of
the file or the directory can be accessed via the various functions of the class.
These include, for example: Access rights, timestamp of the last access or size.

Class SlAccessRights
The SlAccessRights class is used by the SlNode class for the
getAccessRights()/setAccessRights() functions and contains the data for
the access rights as required for SINUMERIK (access level for reading, writing,
displaying, executing, and deleting).

Class SlSlFileSvcStatus
The SlSlFileSvcStatus object contains information about the status of a request.
This is essentially an error number.

6.1.2 Explanation of terms

Synchronous calls
Synchronous calls return only after the request has been completed, i.e. the calling
thread is blocked until this is the case. This can interfere with event processing
since control inputs and displays are withheld during a synchronous call. For this
reason, calls that may take a long time should be performed asynchronously.

Table 6-1: Synchronous calls

FileSvc call Description
copy Copies directories or files
create Creates files or directories
remove Deletes files or directories
list Accesses the contents of a directory
move Moves files or directories
rename Renames files or directories
select Selects a part program for processing
cancel Cancels an asynchronous request

Asynchronous calls
Asynchronous calls return as soon as the request has been sent to the file service.
The returned error code cannot therefore indicate whether the request has been
completed successfully; it can only indicate whether or not the request has been
sent successfully. For example, an error occurs if call parameters are not correctly
assigned. The actual request status is supplied in the return calls of the file service
(call of the implemented callback method).
Table 6-2: Asynchronous calls
FileSvc call Description
copyAsync Copies directories or files

Unrestricted © Siemens AG 2019 All Rights Reserved

6-116 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.1 Introduction

FileSvc call Description

removeAsync Deletes files or directories
listAsync Accesses the contents of a directory
moveAsync Moves files or directories
renameAsync Renames files or directories
cancelAsync Cancels an asynchronous request
startBlockTransferReadAsync Starts block-by-block data transfer from the NC
startBlockTransferWriteAsync Starts block-by-block data transfer to the NC
writeBlockTransferDataAsync Writes to data block

! Important
Only one asynchronous service can run on an SlFileSvc object at any one time. If
an attempt is made to set up a second asynchronous request, this is prevented
with an error return value.

Files and directories

The following information (attributes) can be queried for each addressable file and
directory.

Table 6-3: Attributes of files and directories

Characteristic Meaning
Logical path The logical path of the file or directory.
(Example: "//NC/MPF.DIR/TEST.MPF")
Real path The real path of the file or directory.
(Example: "/_N_MPF_DIR/_N_TEST_MPF")
Type Defines whether an object is a file or a directory.
Name Name of the file. (Example: "TEST.MPF")
Access rights Access rights for the file/directory. (Example: "77777")
Size File size, in bytes. For a directory, this value is –1.
Time stamp Timestamp of last change.

Files can be stored in one of the following locations:

1. On the PCU, e.g. "C:\tmp\test.mpf" or "C:/tmp/test.mpf"
2. On the CF card, e.g. "//NC/CF_CARD/oem/sinumerik/hmi/appl/test.mpf"
3. In the file structure of the NC, e.g. "//NC/mpf.dir/test.mpf"
4. On a USB drive, e.g. "//USB:/mpf.dir/test.mpf"
5. On a network drive, e.g. "//NET:/mpf.dir/test.mpf"

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-117
6 Directory and file services 11/2019
6.1 Introduction

Access rights
There are eight access levels for files and directories.

Table 6-4: Access rights

Access level Can be accessed with User group
S0 System password SIEMENS
S1 Machine manufacturer Machine manufacturer
password
S2 Service password Commissioning engineer, service
(machine manufacturer)
S3 End user password Privileged end user (in-house service)
S4 Key switch position 3 Programmers
S5 Key switch position 2 Trained operator
S6 Key switch position 1 Operator
S7 Key switch position 0 Semi-skilled operator
(NC Start / NC Stop, MCP)

S0 denotes the access level with the highest rights and S7 the access level with
the most restrictive rights.

The keyswitch position is enabled by the current keyswitch position or by entry of a

password.

Access rights
The following rights can be assigned:

READ  for reading

WRITE  for writing
EXECUTE  for executing
SHOW  for listing
DELETE  for deleting

Unrestricted © Siemens AG 2019 All Rights Reserved

6-118 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.2 Step-by-step examples

6.2 Step-by-step examples

Overview
The following chapters show the various application areas of the file service. An
executable example is included in the SINUMERIK Integrate Create MyHMI /3GL
for each "step-by-step example".

These and all other examples are shown in the following overview of examples.

Table 6-5: Overview of the examples

Application Type Example Chapter
Lists the contents of a synchrono SlFileSvcListSync 6.2.2
directory us
asynchron SlFileSvcListAsync 6.2.3
ous
Creates, copies, and synchrono SlFileSvcCreateCopyRemoveSyn 6.2.4
deletes a file us c
asynchron SlFileSvcCreateCopyRemoveAsy 6.2.5
ous nc
Gets file or directory attributes SlFileSvcFileAttributes 6.2.6
Block-by-block reading and writing of SlFileSvcBlockTransfer 6.2.7
data
Setting up a notification when a USB SlFileSvcUSBNotification -
stick was inserted or removed.

Only the items relevant for the FileService are explained or described in each
example. The comments for the sources contain more detailed information (e.g.
screen layout, outputs, etc.).

6.2.1 Preparation

Overview
Preparatory measures are described in Chapter 2.1  "New Project". All of the
items described there must be executed first.

6.2.2 Listing the contents of a folder (synchronous)

Overview
The following step-by-step example shows how to read out the content of a
directory synchronously.

In the example, you can specify a path whose contents you can display by clicking
the "list folder" button. The status bar indicates whether the call has been
successful.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-119
6 Directory and file services 11/2019
6.2 Step-by-step examples

Fig. 6-1: Synchronously listing a directory

Step 1
Create a type SlFileSvc variable:

SlFileSvc fs;

For synchronous calls, it is not absolutely necessary to create the SlFileSvc object
as a member variable. It can also be created locally in the specific function.

Step 2
Create an SlNode object that represents the directory to be read out. The contents
of the text box are transferred as a path.

SlNode SlNode(sFolder);

Step 3
Read out the content. The result is returned as an array of SlNode objects.

SlVector<SlNode> SlNodelist;

SlFileSvcError err = fs.list(node, SlNodelist);

Step 4
Process the data that has been read. In the example, the data is written to a
ListBox. The data is read from the array and written to the ListBox using a "for"
loop.

if (err == SL_FILESVC_OK)

Unrestricted © Siemens AG 2019 All Rights Reserved

6-120 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.2 Step-by-step examples

{
SlString s;
// get items
for(int i = 0; i < SlNodelist.size(); i++)
{
s.append(nodelist.at(i).getName().c_str());
s.append("\r\n");
}
// display items
}
else
{
// display error
}

6.2.3 Listing the contents of a folder (asynchronous)

Overview
The following step-by-step example shows how to read out the content of a
directory asynchronously.

In the example, you can specify a path whose contents you can display by clicking
the "list folder" button. The status bar indicates whether the call has been
successful.

Fig. 6-2: Asynchronously listing a directory

Step 1
Create the required member variables. On the one hand, a type SlFileSvc variable
is required, and on the other hand, a type ISlFileSvcCb:

SlFileSvc m_fs;
ISlFileSvcCb* m_pFsCb;

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-121
6 Directory and file services 11/2019
6.2 Step-by-step examples

Step 2
Create an SlNode object that represents the directory to be read out. The contents
of the text box are transferred as a path.

SlNode SlNode(folder);

Step 3
Initiate asynchronous readout. Here, a pointer (m_pFsCb) is transferred to the
callback object, which is used to call the implemented callback method. The
SlFileSvcListCompleted () function is called if the request has ended. The
SlFileSvcListProgress () function cyclically provides information about
progress. In the following, only the implementation of the
SlFileSvcListCompleted () function is described.

long nRequestId;
SlFileSvcError err = m_fs.listAsync(node, m_pFsCb, nRequestId);

Step 4
Implement the callback method.

void SlFileSvcListCompleted(long nID, SlVector<SlNode>& SlNodes,

SlSlFileSvcStatus& status)
{
error = status.error;
SlNodeList.clear();
for(int i = 0; i < SlNodes.size(); i++)
{
SlNodeList.push_back(nodes.at(i));
}
// call main window to show result
PostMessage(msgWindow, WM_COMMAND, 10, 0);
}

Step 5
Implement the display of the file and directory names of the directory to be listed.

Unrestricted © Siemens AG 2019 All Rights Reserved

6-122 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.2 Step-by-step examples

LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM

lParam)
{
.. .
switch (message)
{
case WM_COMMAND:
{
int wmId = LOWORD(wParam);
.. .
switch (wmId)
{
case 10:
// call function to show list
ShowList();
break;
.. .
}
}
}
.. .
}

void ShowList()
{
// this function shows the list of existing directories and files
}

6.2.4 Generating, copying and deleting a file (synchronous)

Overview
The following example shows step-by-step how a file is created, synchronously
copied, and then synchronously deleted again.

In the example, a part program with contents can be created using the "create
source" button. The "copy source" softkey can be used to copy this file to the
specified destination path. The two files can then be deleted again using the
"remove source" or "remove destination" buttons. The status bar indicates whether
the calls have been successful.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-123
6 Directory and file services 11/2019
6.2 Step-by-step examples

Fig. 6-3: Synchronously creating, copying, and deleting a file

Step 1
Create a type SlFileSvc variable:

SlFileSvc fs;

Step 2
Create a file. A SlNode object is created for this purpose. The sSource path
(source path) is taken from the text field. The file is created using the create()
function of the SlFileSvc. In this example, the "overwrite" parameter of the
create() function is set (true) so that the file is overwritten if it already exists.

// Assume: get file names of source from input field

char sSource[MAX_LOADSTRING];

// create an SlNode for the source file

SlNode SlNode(sSource);

// create the file, if it exists --> overwrite

SlFileSvcError err = fs.create(node, true);

Then fill the created file with contents.

Step 3
Copy file. Two SlNode objects are required for copying. One represents the file that
should be copied; the other, the destination file. The overwrite parameter of the
copy() function is set (true) so that an existing file is overwritten.

// Assume: get file names of source and destination from input fields
char sSrc[MAX_LOADSTRING];

Unrestricted © Siemens AG 2019 All Rights Reserved

6-124 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.2 Step-by-step examples

char sDst[MAX_LOADSTRING];

// create an SlNode for the source file

SlNode nodeSrc(sSrc);

// create an SlNode for the destination file

SlNode nodeDst(sDst);

// copy the file, if destination exists --> overwrite

SlFileSvcError err = fs.copy(nodeSrc, nodeDst, true);

Step 4
Delete a file. It will only be shown how the destination file is deleted. To start, an
SlNode object of the file to be deleted is created. Then this file is deleted.

// Assume: get file names from input field

char sSrc[MAX_LOADSTRING];

// create an SlNode for this file name

SlFileSvc fs;
SlNode nodeSrc(sSrc);

// delete the file

SlFileSvcError err = fs.remove(nodeSrc);

6.2.5 Generating, copying and deleting a file (asynchronous)

Overview
The following step-by-step example shows how to create, asynchronously copy,
and then asynchronously delete a file again.

In the example, a part program with contents can be created using the "create
source" button. This file can be asynchronously copied to the specified destination
path using "copy source". Both files can then be asynchronously deleted again
using the "remove source" or "remove destination" buttons. The status bar
indicates whether the calls have been successful.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-125
6 Directory and file services 11/2019
6.2 Step-by-step examples

Fig. 6-4: Asynchronously creating, copying, and deleting a file

Step 1
Create the required member variables. On the one hand, an SlFileSvc type
variable is required, and on the other hand, various ISlFileSvcCb type
variables. ISlFileSvcCb is required to identify asynchronous calls:

SlFileSvc m_fs;
ISlFileSvcCb* m_pFsCb;

Step 2
Create and write a file in the same way as in the synchronous step-by-step
example, as there is no asynchronous function for creating a file or a directory.

Step 3
Copy file. Two SlNode objects are required for copying. One represents the file that
should be copied; the other, the destination file. The overwrite parameter of the
copyAsync() function is set (true) so that an existing file is overwritten. The
SlFileSvcCompleted () function is called if the request has ended. The
SlFileSvcListProgress () function cyclically provides information about
progress. In the following, only the implementation of the SlFileSvcCompleted
() function is described.

Unrestricted © Siemens AG 2019 All Rights Reserved

6-126 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.2 Step-by-step examples

// Assume: get file names of source and destination from input fields
char sSrc[MAX_LOADSTRING];
char sDst[MAX_LOADSTRING];

// create an SlNode for the source file

SlNode nodeSrc(sSrc);

// create an SlNode for the destination file

SlNode nodeDst(sDst);

// copy the file, if destination exists --> overwrite

SlFileSvcError err = m_fs.copy(nodeSrc, nodeDst, m_pFsCb, nRequestId, false,
true);

Step 4
Implement the callback method.

void SlFileSvcCompleted(long nID, SlSlFileSvcStatus& status)

{
error = status.error;
// call main window to show result
PostMessage(msgWindow, WM_COMMAND, 10, 0);
}

Step 5
Delete a file. It will only be shown how the destination file is deleted. To start, an
SlNode object of the file to be deleted is created. Then the file is deleted.

// create an SlNode to the file would be removed

SlNode nodeSrc(src);

// delete file
SlFileSvcError err = m_fs.removeAsync(nodeSrc, m_pFsCb, nRequestId, false);

Step 6
Implement the callback method. (as in step 4)

6.2.6 Determining file or folder attributes

Overview
Attributes of a directory or a file are displayed in this example. The path of the
required directory or the file can be entered into a text box. The associated
attributes are read out and displayed by pressing the "get attributes" button.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-127
6 Directory and file services 11/2019
6.2 Step-by-step examples

Fig. 6-5: Displaying attributes

Step 1
Create an SlNode object that represents the object to be read out (file or directory).
The contents of the text box are transferred as sPath path.

SlNode SlNode((SlString) sPath);

Step 2
"Extract" and output attributes from the SlNode object. All attributes are displayed
in text boxes.

if (node.exists())
{
...

SlAccessRights rights = node.getAccessRights();

sprintf(buffer, "r=%d, w=%d, x=%d, l=%d, d=%d", rights.getRead(),

rights.getWrite(), rights.getExecute(),
rights.getShow(), rights.getDelete());

...
}

6.2.7 Block-by-block reading and writing of data

Overview
In this example, data is written block-by-block to a part program on the NC.
logbook. In a further step, the part program is read block-by-block from the
NC.

Click the "start blocktransfer write" button to start the block transfer to the
destination
specified as "filename". Click the "write new datablock" button to make the contents
of the "content" text box available for transfer. Click the "end blocktransfer write"
button to close the data transfer to the NC.

Unrestricted © Siemens AG 2019 All Rights Reserved

6-128 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.2 Step-by-step examples

Click the "read datablock async" button to export the data block-by-block from the
source
defined as "filename" and display it in "content". Click the "cancel running async
service" button to cancel an
active asynchronous request of the FileService.

Fig. 6-6: Block transfer of data

Step 1
Create the required member variables. On the one hand, a type SlFileSvc variable
is required, and on the other hand, a type ISlFileSvcBlockTransferCb:

SlFileSvc m_fs;
ISlFileSvcBlockTransferCb* m_pFsCb;
...
m_pFsCb = new SlFileSvcCb();

Step 2
Start block-by-block data transfer. The data source is transferred as SlNode. The
created callback object is required for the callbacks.

SlNode nodeFileName(szFileName);
SlFileSvcError err = m_fs.startBlockTransferWriteAsync(nodeFileName,
m_pFsCb, m_nRequestId);

Step 3
Implement the required callback method SlFileSvcProvideBlockTransferData. If this
is called, data can be written.

class SlFileSvcCb : public ISlFileSvcBlockTransferCb

{
void SlFileSvcProvideBlockTransferData(long lID, SlFileSvcStatus status)
{
...
}
};

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-129
6 Directory and file services 11/2019
6.2 Step-by-step examples

Step 4
Write data. The data transfer is completed by setting the parameter eof=true.

SlFileSvcError err =
m_fs.writeBlockTransferDataAsync((char*)szContent.c_str(),
szContent.length(), false);

Step 5
Implement the required callback method SlFileSvcBlockTransferCompleted. If this
is called, the data transfer is completed.

class SlFileSvcCb : public ISlFileSvcBlockTransferCb

{
void SlFileSvcBlockTransferCompleted(long lID, SlFileSvcStatus status)
{
...
}
};

Step 6
Start reading block-by-block. The data source is transferred as SlNode. The created
callback object is required for the callbacks.

SlNode nodeFileName(szFileName);
SlFileSvcError err = m_fs.startBlockTransferReadAsync(nodeFileName, m_pFsCb,
m_nRequestId, true);

Step 7
Implement the required callback method SlFileSvcReadBlockTransferData. The
read data is transferred in this method.

class SlFileSvcCb : public ISlFileSvcBlockTransferCb

{
void SlFileSvcReadBlockTransferData(long lID, char* data, int lenData)
{
...
}
};

Step 8
Implement the required callback method SlFileSvcBlockTransferCompleted. If this
is called, the data transfer is completed.

class SlFileSvcCb : public ISlFileSvcBlockTransferCb

{
void SlFileSvcBlockTransferCompleted(long lID, SlFileSvcStatus status)
{
...
}
};

Step 9
A data transfer can be canceled with the cancelAsync function. For this purpose,
the RequestID returned when starting the data transfer must be specified.

Unrestricted © Siemens AG 2019 All Rights Reserved

6-130 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.2 Step-by-step examples

SlFileSvcError err = m_fs.cancelAsync(m_pFsCb, m_nRequestId);

Step 10
Implement the required callback method SlFileSvcBlockTransferCanceled. If this is
called, the data transfer has been canceled successfully.

class SlFileSvcCb : public ISlFileSvcBlockTransferCb

{
void SlFileSvcBlockTransferCanceled(long lID)
{
...
}
};

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-131
6 Directory and file services 11/2019
6.3 Reference SlNode

6.3 Reference SlNode

6.3.1 Definitions

Overview
A SlNode object represents a file or a directory. The SlNode class contains
attributes that describe the particular directory or the particular file in more detail.
These attributes are provided as functions. This class is defined in
sloperatecppapi.h.

Path structure
The following examples show the structure of the logical paths to be used for the
functions of the SlNode class.

Table 6-6: Logical paths

Logical path Description
//NC/mpf.dir/test.mpf NC path
//NC/act.dir NC path (active file system)
G:/test/test.mpf Windows path
//USB:/tmp/test.mpf Local TCU-USB drive with symbolic
specification
(The symbolic name 'USB' is assigned during
the setup of the drive in the
‘commissioning/HMI/Log.drive' operating
area)
//NET:/test.mpf Network drive with symbolic name
(The symbolic name 'NET' is assigned during
the setup of the drive in the
‘commissioning/HMI/Log.drive' operating
area)
//NC/CF_CARD/oem/sinumerik/hmi/ Linux or CF card path
appl/test.mpf

Note
When using a network drive or a USB drive, a corresponding drive must first be
set up from the commissioning/HMI/Log.drive operating area.

Note
Only the logical paths can be used to call the interface FileSvc. Real paths (e.g.
"/_N_MPF_DIR/_N_TEST_MPF") cannot be used.

6.3.2 Creating an SlNode object

A number of constructors are available for creating an SlNode object. If you use the
default constructor, the values can also be set or overwritten later using the
functions.

Unrestricted © Siemens AG 2019 All Rights Reserved

6-132 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.3 Reference SlNode

Table 6-7: Constructors of the SlNode class

public SlNode.SlNode(SlString path)
Parameter Meaning
path File or directory to be represented

6.3.3 Functions

getAccessRights / setAccessRights
Gets and sets the access rights as required for the SINUMERIK protection level
concept for reading, writing, deleting, executing, and listing.

Table 6-8: getAccessRights / setAccessRights

public SlAccessRights getAccessRights()
Parameter Meaning
Return Access level

public void setAccessRights(SlAccessRights accessRights)

Parameter Meaning
accessRights Access levels
Return -

exists
Defines whether the file or the directory exists.

Table 6-9: exists

public bool exists ()
Parameter Meaning
Return true: exists. false: does not exist

IsDirNode
Defines whether the object is a directory or a file.

Table 6-10: IsDirNode

public bool IsDirNode()
Parameter Meaning
Return true: it is a Dir node (directory)

IsNcNode
Defines whether the object is located in the NC.

Table 6-11: IsNcNode

public bool IsNcNode()
Parameter Meaning
Return true: It is an NC node

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-133
6 Directory and file services 11/2019
6.3 Reference SlNode

getPath / setPath
Gets and sets the logical path of the object.

Table 6-12: getPath / setPath

public SlString getPath()
Parameter Meaning
Return Path

public void setPath(SlString path)

Parameter Meaning
path Path
Return -

getName
Gets the name of the file or the directory (without path).

Table 6-13: getName

public SlString getName()
Parameter Meaning
Return Name

getRealPath
Gets the real (NC) path of the object.

Table 6-14: getRealPath

public SlString getRealPath()
Parameter Meaning
Return Path

size
Gets the size of the object.

Table 6-15: size

public long size()
Parameter Meaning
Return Size

lastAccess
Gets the timestamp of last change.

Table 6-16: lastAccess

public time_t lastAccess ()
Parameter Meaning
Return Time stamp

Unrestricted © Siemens AG 2019 All Rights Reserved

6-134 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.4 SlFileSvc reference

6.4 SlFileSvc reference

6.4.1 Definitions

Overview
File and directory operations can be implemented using SlFileSvc objects. These
are especially:
• Creating files/directories
• Copying files/directories
• Moving files/directories
• Deleting files/directories
• Renaming files/directories
• Setting up a notification which is issued when a new device is connected or
a device is removed

In addition, functions for SINUMERIK-specific tasks are available. For example,

access rights can be modified and part programs can be selected for execution.

Many calls are available in both synchronous and asynchronous

forms. Synchronous calls block the thread in which the call takes place,
until the request has been completed. For asynchronous calls, after completing the
operation, an implementation of the associated callback method is called.

This class is defined in sloperatecppapi.h.

6.4.2 Creating an SlFileSvc object

The SlFileSvc class only has one default constructor.

Table 6-17: Constructors of the SlFileSvc class

public SlFileSvc.SlFileSvc ()
Parameter Meaning
- -

6.4.3 Administration functions

list / listAsync
These functions list the content of a directory. The results are returned as an array
of the SlNode class. A SlNode object describes a file or a directory.

With large directories, the call can take a long time. In such cases, the
asynchronous version (listAsync) should be used to avoid blocking the thread in
which the call is made.

Table 6-18: list

public SlFileSvcError list(SlNode node, SlVector<SlNode>& nodeList)
Parameter Meaning
Node Directory to be listed.
nodeList List of the files and directories.
Return Success status of the call

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-135
6 Directory and file services 11/2019
6.4 SlFileSvc reference

Example: See Chapter 6.2.2

In the asynchronous version, a request ID is received after the call to identify the
call later.

The function calls the implementation of the following callback methods:

• SlFileSvcListCompleted ()
• SlFileSvcListProgress ()
• SlFileSvcListCanceled ()

Table 6-19: listAsync

public SlFileSvcError listAsync(SlNode node, ISlFileSvcCb* cb, long& nRequestId,
bool reportProgress = false)
Parameter Meaning
Node Directory to be listed.
cb Callback method
nRequestId This variable is used to identify the asynchronous call later
reportProgress With progress reporting (true/false). Default: false
Return Success status of the call

Example: See Chapter 6.2.3

create
Creates a file. The file can be created either in the NCU or on the hard disk of the
PCU. You can decide whether to overwrite the file if it already exists.

Table 6-20: create

public SlFileSvcError create(SlNode sourceNode, bool overwrite = false)
Parameter Meaning
sourceNode File to be created
overwrite = true: the file is to be overwritten. Default: false
Return Success status of the call

createFolder
Creates a directory. The directory can be created either in the NCU or on the PCU.

Table 6-21: createFolder

public SlFileSvcError createFolder(SlNode sourceNode, bool createParent = false)
Parameter Meaning
sourceNode File to be created
createParent = true:. Default: false
Return Success status of the call

Example: See Chapter 6.2.4

Unrestricted © Siemens AG 2019 All Rights Reserved

6-136 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.4 SlFileSvc reference

rename / renameAsync
Renames a file or directory.

Table 6-22: rename

public SlFileSvcError rename(SlNode sourceNode, SlNode destNode, bool
overwrite = false)
Parameter Meaning
sourceNode File or directory to be renamed
destNode New name (file or directory)
overwrite = true: the existing file or the existing directory is to be
overwritten. Default: false
Return Success status of the call

Example: See Chapter 6.2.4

In the asynchronous version, a request ID is received after the call to identify the
call later.

The function calls the implementation of the following callback methods:

• SlFileSvcCompleted ()
• SlFileSvcProgress ()
• SlFileSvcCanceled ()

Table 6-23: renameAsync

public SlFileSvcError renameAsync(SlNode sourceNode, SlNode destNode,
ISlFileSvcCb* cb, long& nRequestId, bool reportProgress = false, bool overwrite =
false)
Parameter Meaning
sourceNode File or directory to be renamed
destNode New name (file or directory)
cb Callback method
nRequestId This variable is used to identify the asynchronous call later
reportProgress With progress reporting (true/false). Default: false
overwrite = true: the existing file or the existing directory is to be
overwritten. Default: false
Return Success status of the call

copy / copyAsync
Copies a file. You can decide whether to overwrite the file if it already exists.

Table 6-24: copy

public SlFileSvcError copy(SlNode sourceNode, SlNode destNode, bool overwrite =
false)
Parameter Meaning
sourceNode Source file; file to be copied
destNode Destination file.
overwrite Overwrite file if it already exists
Return Success status of the call

Example: See Chapter 6.2.4

In the asynchronous version, a request ID is received after the call to identify the
call later.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-137
6 Directory and file services 11/2019
6.4 SlFileSvc reference

The function calls the implementation of the following callback methods:

• SlFileSvcCompleted ()
• SlFileSvcProgress ()
• SlFileSvcCanceled ()´

Table 6-25: copyAsync

public SlFileSvcError copyAsync(SlNode sourceNode, SlNode destNode,
ISlFileSvcCb* cb, long& nRequestId, bool reportProgress = false, bool overwrite =
false)
Parameter Meaning
sourceNode Source file; file to be copied
destNode Destination file
cb Callback method
nRequestId This variable is used to identify the asynchronous call later
reportProgress With progress reporting (true/false). Default: false
overwrite Overwrite file if it already exists
Return Success status of the call

Example: See Chapter 6.2.5

move / moveAsync
Moves a file. You can decide whether to overwrite the file if it already exists.

Table 6-26: move

public SlFileSvcError move(SlNode sourceNode, SlNode destNode, bool overwrite
= false)
Parameter Meaning
sourceNode Source file; file that should be moved
destNode Destination file
overwrite Overwrite file if it already exists
Return Success status of the call

Example: See Chapter 6.2.4

In the asynchronous version, a request ID is received after the call to identify the
call later.

The function calls the implementation of the following callback methods:

• SlFileSvcCompleted ()
• SlFileSvcProgress ()
• SlFileSvcCanceled ()

Unrestricted © Siemens AG 2019 All Rights Reserved

6-138 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.4 SlFileSvc reference

Table 6-27: moveAsync

public SlFileSvcError moveAsync(SlNode sourceNode, SlNode destNode,
ISlFileSvcCb* cb, long& nRequestId, bool reportProgress = false, bool overwrite =
false)
Parameter Meaning
sourceNode Source file; file that should be moved
destNode Destination file
cb Callback method
nRequestId This variable is used to identify the asynchronous call later
reportProgress With progress reporting (true/false). Default: false
overwrite Overwrite file if it already exists
Return Success status of the call

Example: See Chapter 6.2.5

remove / removeAsync
Deletes a directory or a file.

Table 6-28: remove

public SlFileSvcError remove(SlNode sourceNode)
Parameter Meaning
sourceNode Source file; file to be deleted
destNode Destination file.
overwrite Overwrite file if it already exists
Return Success status of the call

Example: See Chapter 6.2.4

In the asynchronous version, a request ID is received after the call to identify the
call later.

The function calls the implementation of the following callback methods:

• SlFileSvcCompleted ()
• SlFileSvcProgress ()
• SlFileSvcCanceled ()

Table 6-29: removeAsync

public SlFileSvcError removeAsync(SlNode sourceNode, ISlFileSvcCb* cb, long&
nRequestId, bool reportProgress = false)
Parameter Meaning
sourceNode Source file; file to be deleted
cb Callback method
nRequestId This variable is used to identify the asynchronous call later
reportProgress With progress reporting (true/false). Default: false
Return Success status of the call

Example: See Chapter 6.2.4

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-139
6 Directory and file services 11/2019
6.4 SlFileSvc reference

select
The function selects a program saved on the NC for the addressed channel for
processing. This is only possible if the file is an executable file (e.g. a part
program).

Table 6-30: select

public SlFileSvcError select(SlNode sourceNode, unsigned long channel)
Parameter Meaning
sourceNode Part program to be selected for processing
channel Channel in which the part program is selected
Return Success status of the call

selectExtern
The function selects an externally saved program (e.g. hard disk) for the addressed
channel for execution. This is only possible if the file is an executable file (e.g. a
part program).

Table 6-31: selectExtern

public SlFileSvcError selectExtern (SlNode node, unsigned long channel)
Parameter Meaning
sourceNode Part program to be selected for processing
channel Channel in which the part program is selected
Return Success status of the call

cancel / cancelAsync
Cancels an asynchronous operation.

Table 6-32: cancel

public SlFileSvcError cancel(long& nRequestID)
Parameter Meaning
nRequestId This variable is used to identify the asynchronous call later
Return Success status of the call

The asynchronous function calls the implementation of the following callback

method:
• SlFileSvcCanceled ()

Table 6-33: cancelAsync

public SlFileSvcError cancelAsync(ISlFileSvcCb* cb, long& nRequestID);
Parameter Meaning
cb Callback method
nRequestId This variable is used to identify the asynchronous call later
Return Success status of the call

Unrestricted © Siemens AG 2019 All Rights Reserved

6-140 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.4 SlFileSvc reference

startBlockTransferReadAsync
This function starts the block-by-block data transfer from a specified NC source.

Table 6-34: startBlockTransferReadAsync

public SlFileSvcError startBlockTransferReadAsync(SlNode source,
ISlFileSvcBlockTransferCb* dest,
long& requestId,
bool reportProgress = false);
Parameter Meaning
source Data source from which the data is to be read.
E.g. //NC/MPF.DIR/TEST.MPF
dest Callback method
requestId This variable is used to identify the asynchronous call later
reportProgress With progress reporting (true/false). Default: false
Return Success status of the call

The function calls the implementation of the following callback methods:

• SlFileSvcReadBlockTransferData()
• SlFileSvcBlockTransferProgress()
• SlFileSvcBlockTransferCompleted()

Example: See Chapter 6.2.7

startBlockTransferWriteAsync
This function starts the block-by-block data transfer to a specified NC destination.

Table 6-35: startBlockTransferWriteAsync

public SlFileSvcError startBlockTransferWriteAsync(SlNode dest,
ISlFileSvcBlockTransferCb* source,
long& requestId);
Parameter Meaning
dest Data destination in which data should be written.
E.g. //NC/MPF.DIR/TEST.MPF
source Callback method
requestId This variable is used to identify the asynchronous call later
Return Success status of the call

The function calls the implementation of the following callback methods:

• SlFileSvcProvideBlockTransferData ()
• SlFileSvcBlockTransferCompleted()

Example: See Chapter 6.2.7

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-141
6 Directory and file services 11/2019
6.4 SlFileSvc reference

writeBlockTransferDataAsync
This function provides a data block for the transfer to a specified
NC destination.

Table 6-36: startBlockTransferWriteAsync

public SlFileSvcError writeBlockTransferDataAsync(char* data, int len, bool eof);
Parameter Meaning
data Data to be transferred to the data destination.
len Length of the data.
eof Specifies whether the data transfer has completed (true)
or whether additional data blocks will be transferred (false).
Return Success status of the call

Example: See Chapter 6.2.7

Subscribe
Setting up a notification if drives are inserted/connected or
removed. The call returns as soon as the setup request
has been forwarded to the server.

Table 6-37: Subscribe

SlFileSvcError subscribe(SlString strLogicalPath, ISlFileSvcCb* cb);
Parameter Meaning
strLogicalPath Drive to be monitored.
e.g. //USB:/
cb Callback method
Return Success status of the call

The function calls the implementation of the following callback methods:

• SlFileSvcDeviceMounted()
• SlFileSvcDeviceUnmounted()

An example of this can be found under "SlFileSvc\SlFileSvcUSBNotification" in the

example directory.
unSubscribe
Canceling the notification if drives are inserted/connected or
removed.

Table 6-38: Subscribe

SlFileSvcError unSubscribe();
Parameter Meaning
Return Success status of the call

Unrestricted © Siemens AG 2019 All Rights Reserved

6-142 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.4 SlFileSvc reference

6.4.4 Callback methods

SlFileSvcCompleted
Table 6-39: SlFileSvcCompleted – specification for the callback implementation
public void SlFileSvcCompleted(long nID, SlFileSvcStatus& status);
Parameter Meaning
nID Request ID to identify the asynchronous call
status Success status of the call

SlFileSvcProgress
Table 6-40: SlFileSvcProgress – specification for the callback implementation
public void SlFileSvcProgress(long nID, int percentage);
Parameter Meaning
nID Request ID to identify the asynchronous call
percentage Percentage value of how far the request has progressed.

SlFileSvcCanceled
Table 6-41: SlFileSvcCanceled – specification for the callback implementation
Public void SlFileSvcCanceled(long nID);
Parameter Meaning
nID Request ID to identify the asynchronous call

SlFileSvcListCompleted
Table 6-42: SlFileSvcListCompleted – specification for the callback implementation
public void SlFileSvcListCompleted(long nID, SlVector<SlNode>& nodes,
SlFileSvcStatus& status);
Parameter Meaning
nID Request ID to identify the asynchronous call
nodes List of the files and directories
status Success status of the call

SlFileSvcListProgress
Table 6-43: SlFileSvcListProgress – specification for the callback implementation
public void SlFileSvcListProgress(long nID, int percentage);
Parameter Meaning
nID Request ID to identify the asynchronous call
percentage Percentage value of how far the request has progressed.

SlFileSvcListCanceled
Table 6-44: SlFileSvcListCanceled – specification for the callback implementation
public void SlFileSvcListCanceled(long nID);
Parameter Meaning
nID Request ID to identify the asynchronous call

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-143
6 Directory and file services 11/2019
6.4 SlFileSvc reference

SlFileSvcBlockTransferCompleted
This callback is called if a block-by-block data transfer has been completed.

Table 6-45: SlFileSvcBlockTransferCompleted – specification for the callback

implementation
public void SlFileSvcBlockTransferCompleted(long lID, SlFileSvcStatus status);
Parameter Meaning
lID Request ID to identify the asynchronous call
status Success status of the call

SlFileSvcBlockTransferCanceled
This callback is called if the requested cancellation of a block-by-block data
transfer has been completed.

Table 6-46: SlFileSvcBlockTransferCanceled – specification for the callback implementation

public void SlFileSvcBlockTransferCanceled(long lID);
Parameter Meaning
lID Request ID to identify the asynchronous call

SlFileSvcBlockTransferProgress
This callback returns the progress of the request for a block-by-block data transfer
from a specified NC source.

Table 6-47: SlFileSvcBlockTransferProgress – specification for the callback implementation

public void SlFileSvcBlockTransferProgress(long lID, int percentage);
Parameter Meaning
lID Request ID to identify the asynchronous call
percentage Percentage value of how far the request has progressed.

SlFileSvcReadBlockTransferData
This function is called when the data that was requested with the
startBlockTransferReadAsync function has been provided.

Table 6-48: SlFileSvcReadBlockTransferData – specification for the callback implementation

public void SlFileSvcReadBlockTransferData(long lID, char* data, int lenData);
Parameter Meaning
lID Request ID to identify the asynchronous call
data Data that has been read from the data source
lenData Length of the data.

Unrestricted © Siemens AG 2019 All Rights Reserved

6-144 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.4 SlFileSvc reference

SlFileSvcProvideBlockTransferData
This callback is called as request for the provision of data after a block-by-block
data transfer has been initiated with the startBlockTransferWriteAsync function.

Table 6-49: SlFileSvcProvideBlockTransferData – specification for the callback

implementation
public void SlFileSvcProvideBlockTransferData(long lID, SlFileSvcStatus status);
Parameter Meaning
lID Request ID to identify the asynchronous call
status Success status of the call

SlFileSvcDeviceMounted
This callback is called if a new drive was connected/attached.

Table 6-50: SlFileSvcDeviceMounted – Specification for the callback implementation

public void SlFileSvcDeviceMounted(SlString strLogicalPath);
Parameter Meaning
strLogicalPath Path of the attached/connected drive

SlFileSvcDeviceUnmounted
This callback is called if the previously attached/connected drive was removed.

Table 6-51: SlFileSvcDeviceUnmounted – Specification for the callback implementation

public void SlFileSvcDeviceUnmounted(SlString strLogicalPath);
Parameter Meaning
strLogicalPath Path of the withdrawn drive

6.4.5 FileSvc in 1:N constellations

By default, file operations are performed on the NCU which Operate is viewing. In a
1:N constellation, a file operation can be performed on a specific NCU (an NCU
other than the one displayed in Operate) as follows:

1. Addition of keyword and NCU name to the file path.

A file operation can be performed on a specific NCU by prefixing the file
path with the keyword NCU and the name of the NCU.

Examples:
Part program path in NCU2 - //NCU/NCU2/NC/MPF.DIR

Note
NCU names are listed in MMC.INI (see also Fig. 6.6).
Entry:
[GLOBAL]
NcddeMachineNames=NCU1,NCU2

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-145
6 Directory and file services 11/2019
6.4 SlFileSvc reference

Fig. 6-7: NCU names for 1 : N

Unrestricted © Siemens AG 2019 All Rights Reserved

6-146 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.5 SlAccessRights reference

6.5 SlAccessRights reference

6.5.1 Definitions

Overview
A SlAccessRights object contains the access authorizations in the sense of the
SINUMERIK protection level concept of a file or a directory.
These authorizations are available for:
• Read
• Write
• Delete
• List
• Execute
The class only contains functions for these 5 access rights and is defined in
sloperatecppapi.h.

6.5.2 Functions

Enumerator SlAccessLevel
All of the functions described in the following supply an enumerator value of type
SlAccessLevel. The possible values are described in the following table:

Table 6-52: Values of the SlAccessLevel enumerator

Value Access level Can be accessed with
AccessLevel.SIEMENS S0 System password
AccessLevel.MANUFACT S1 Machine manufacturer password
AccessLevel.SERVICE S2 Service password
AccessLevel.USER S3 End user password
AccessLevel.KEY_3 S4 Key switch position 3
AccessLevel.KEY_2 S5 Key switch position 2
AccessLevel.KEY_1 S6 Key switch position 1
AccessLevel.KEY_0 S7 Key switch position 0

getRead / setRead
Gets or sets the access level required to read a file or a directory.

Table 6-53:getRead / setRead

public SlAccessLevel getRead()
Parameter Meaning
Return SlFileSvcError

public void setRead(SlAccessLevel accessLevel)

Parameter Meaning
accessLevel Access level
Return -

getWrite / setWrite
Gets or sets the access level required to write a file or a directory.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-147
6 Directory and file services 11/2019
6.5 SlAccessRights reference

Table 6-54:getWrite / setWrite

public SlAccessLevel getWrite()
Parameter Meaning
Return SlFileSvcError

public void setWrite(SlAccessLevel accessLevel)

Parameter Meaning
accessLevel Access level
Return -

getDelete / setDelete
Gets or sets the access level required to delete a file.

Table 6-55:getDelete / setDelete

public SlAccessLevel getDelete()
Parameter Meaning
Return SlFileSvcError

public void setDelete(SlAccessLevel accessLevel)

Parameter Meaning
accessLevel Access level
Return -

getShow / setShow
Gets or sets the access level required to list a file.

Table 6-56:getShow / setShow

public SlAccessLevel getShow()
Parameter Meaning
Return SlFileSvcError

public void setShow(SlAccessLevel accessLevel)

Parameter Meaning
accessLevel Access level
Return -

getExecute / setExecute
Gets or sets the access level required to execute a file (execute refers to executing
a part program in the NC).

Table 6-57:getExecute / setExecute

public SlAccessLevel getExecute()
Parameter Meaning
Return SlFileSvcError

public void setExecute (SlAccessLevel accessLevel)

Parameter Meaning
accessLevel Access level
Return -

Unrestricted © Siemens AG 2019 All Rights Reserved

6-148 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 6 Directory and file services
6.6 SlFileSvcStatus reference

6.6 SlFileSvcStatus reference

6.6.1 Definitions

Overview
A SlFileSvcStatus object contains the result of a completed asynchronous request.
The object contains an error number:

• SL_FILESVC_OK: No error

Example:

// delete file
SlFileSvcError err = m_fs.removeAsync(.. .);

err == SL_FILESVC_OK means "no error"

err != SL_FILESVC_OK means "error"

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 6-149
6 Directory and file services 11/2019
6.6 SlFileSvcStatus reference

Unrestricted © Siemens AG 2019 All Rights Reserved

6-150 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 7 Infrastructure services
7.1 Introduction

7 Infrastructure services
7
Objective of the chapter
This chapter describes the interface of the InfrastructureService. This can be used
in order to access global data - such as the current resolution, current language,
current channel or current access level. It is also possible to obtain a notification if
one of these values has changed.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 7-151
7 Infrastructure services 11/2019
7.1 Introduction

7.1 Introduction
7.1.1 Class model

Overview
The class model of the InfrastructureService consists primarily of the
SlInfraStructSvc class.

class SlInfraStructSvc
This class is defined in sloperatecppapi.h:
#include "sloperatecppapi.h"

SlInfraStructSvc objects can be used to monitor the following data:

• Current resolution
• Current channel number
• Current language
• Current access level

You can also switch the current NCU to change to a different operating area and
shutdown Operate.

7.1.2 Explanation of terms

Completeness of signaled value changes

Setting up a hotlink (subscribe calls) does not guarantee that all changes are
signaled. The reasons for this are as follows:

1. The values are read cyclically by the NCK. Value changes continue to be
signaled if the read value differs from the previously signaled value. Value
changes are not detected by this mechanism if a value changes and then
changes back to the starting value between two consecutive sampling
points.

2. The sampling points do not have to be equidistant with respect to time.

NCK/PLC may suppress the continued signaling of value changes if the
real-time area would otherwise be disturbed or if the communication
connection is overloaded.

3. An attempt is made to combine the largest possible number of values in

one communication protocol unit (PDU) in order to reduce the data volume
for the applications.

4. Changes can be suppressed if a processing backup is detected on the

client side.

Unrestricted © Siemens AG 2019 All Rights Reserved

7-152 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 7 Infrastructure services
7.1 Introduction

In summary, the following is applicable:

The InfrastructureService is not in a position to detect all value changes of a
variable. In addition, the required sampling rates are not guaranteed; rather, they
should be viewed as a target specification. However, the InfrastructureService will
attempt to continue sending the client all value changes it has detected provided
the response capability of the client is sufficient. In this case, the client has no real-
time requirements, but it must prevent an ever-increasing backup from occurring.
The InfrastructureService guarantees that the final value of a series of value
changes is always signaled after a certain time delay.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 7-153
7 Infrastructure services 11/2019
7.2 Step-by-step examples

7.2 Step-by-step examples

Overview
The following chapters show the various applications for the
InfrastructureService step-by-step. For every "step-by-step example," there is an
executable example in SINUMERIK Integrate Create MyHMI /3GL.

These and all other examples are shown in the following overview of examples.

Table 7-1: Overview of the examples

Application Example Chapter
Notification of a change to the current language. SlInfrastructureSvc 7.2.2
Read out and switch the current language.
Notification about the change to the current SlInfrastructureSvc -
resolution. Read out and switch the current
resolution.
Notification about a change to the current access SlInfrastructureSvc -
level. Read out and switch the current access level.
Notification about a change to the current channel SlInfrastructureSvc -
number. Read out and switch the current channel
number.
Read and set the current NCU and the current SlInfrastructureSvc -
operating area.
Shutdown the HMI Operate software. SlInfrastructureSvc -

Only the items relevant for the InfrastructureService are explained or described in
each example. The comments for the sources contain more detailed information
(e.g. screen layout, outputs, etc.).
7.2.1 Preparation

Overview
Preparatory measures are described in Chapter 2.1  "New Project". All of the
items described there must be executed first.
7.2.2 Current language - read, switchover, notify for change

Overview
The "SlInfrastructureSvc" example contains almost all functions of the
InfrastructureService. However, only the part of the current language is shown
step-by-step.

The "start subscription" button sets up an automatic notification for changes to the
current language. Click "stop subscription" to end this mechanism. The current
language is explicitly read-out using the "get actual values" button. "set language
deu" and "set language eng" toggle the current display language to German or to
English.

Unrestricted © Siemens AG 2019 All Rights Reserved

7-154 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 7 Infrastructure services
7.2 Step-by-step examples

Fig. 7-1: SlInfrastructureSvc example

Step 1
Create the member variable of type SlInfraStructSvc.

SlInfraStructSvc m_InfraStructureSvc;

The SlInfraStructSvc object does not necessarily need to be created as member

variable. It can also be created locally in the specific function.
Step 2
Read out the current language.

SlString sLanguage = m_InfraStructureSvc.getCurrentLanguage();

Step 3
Set the current language. In this case, the display language changes to German.

SlInfraStructSvcError err = m_InfraStructureSvc.setCurrentLanguage("deu");

if ( SL_INFRASTRUCTSVC_OK == err )
{
// successful
}
else
{
// error
}

Step 4
The subscribeLanguage function creates the notification when the current language
is changed. A pointer of type ISlInfraStructSvcCb* that points to the required
callback function is transferred.

// pointer to callback interface

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 7-155
7 Infrastructure services 11/2019
7.2 Step-by-step examples

ISlInfraStructSvcCb* m_pCb;

// create instance of callback object

m_pCb = new SlInfraStructureSvcCb();

// subscribe language
SlInfraStructSvcError err = m_InfraStructureSvc.subscribeLanguage(m_pCb);
if ( SL_INFRASTRUCTSVC_OK == err )
{
// successful
}
else
{
// error
}

Step 5
Implement the callback function. The SlInfraStructSvcLanguageChanged function is
already defined as virtual void. The
user must implement the desired function to evaluate the language
value.

SlString m_sLanguage;

class SlInfraStructureSvcCb : public ISlInfraStructSvcCb

{
// Callback for language changed
void SlInfraStructSvcLanguageChanged(SlString language)
{
// new value
m_sLanguage = language;
}
};

Step 6
Unsubscribe the notification regarding the change to the current language.

// unSubscribe language
SlInfraStructSvcError err = m_InfraStructureSvc.unSubscribeLanguage(m_pCb);
if ( SL_INFRASTRUCTSVC_OK == err )
{
// successful
}
else
{
// error
}

// delete instance of callback object

delete m_pCb;

Unrestricted © Siemens AG 2019 All Rights Reserved

7-156 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 7 Infrastructure services
7.3 SlInfraStructSvc reference

7.3 SlInfraStructSvc reference

7.3.1 Definitions

Overview
SlInfraStructSvc objects can be used to monitor the following data:
• Current resolution
• Current channel number
• Current language
• Current access level

You can also switch the current NCU to change to a different operating area and
shutdown Operate.

Success status / return value

Most InfrastructureService functions return an SlInfraStructSvcError type as
return value. If this equals 0 (SL_INFRASTRUCTSVC_OK), the call was successful.

7.3.2 Creating a SlInfraStructSvc object

The SlInfraStructSvc class has only a default constructor.

7.3.3 Current resolution

The following structure is used to represent the resolution:

Table 7-2: struct SlScreenResolution

struct SlScreenResolution
{
int X;
int Y;
};
Parameter Meaning
X Number of horizontal pixels
Y Number of vertical pixels

Valid resolutions are:

• 640x480 (e.g. OP010)
• 800x600 (e.g. OP012)
• 1024x768 (e.g. OP015)
• 1280x1024 (e.g. OP019)

Read out current resolution

Read out the current resolution.

Table 7-3: getCurrentResolution

SlScreenResolution getCurrentResolution();
Parameter Meaning
Return Current resolution

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 7-157
7 Infrastructure services 11/2019
7.3 SlInfraStructSvc reference

Set current resolution

Set the current resolution.

When setting the resolution, the following parameter must be set in

systemconfiguration.ini:
[miscellaneous]
adaptHmiResolutionToActiveUnit=false

Table 7-4: setCurrentResolution

SlInfraStructSvcError setCurrentResolution (SlScreenResolution resolution);
Parameter Meaning
resolution Resolution to be set
Return Success status of the call

Notification for resolution switchover

Activate a notification for a change to the resolution. If the
resolution on the HMI is changed, this is notified in the associated callback
function.

Table 7-5: subscribeResolution

SlInfraStructSvcError subscribeResolution (ISlInfraStructSvcCb* cb);
Parameter Meaning
cb Pointer to the callback class
Return Success status of the call

Specification for the callback implementation:

Table 7-6: SlInfraStructSvcResolutionChanged

void ISlInfraStructSvcCb::SlInfraStructSvcResolutionChanged
(SlScreenResolution resolution);
Parameter Meaning
resolution Current resolution

Deactivation of such a notification.

Table 7-7: unSubscribeResolution

SlInfraStructSvcError unSubscribeResolution (ISlInfraStructSvcCb* cb);
Parameter Meaning
cb Pointer to the callback class
Return Success status of the call

7.3.4 Current channel number

Read out current channel number

Read out the active channel.

Table 7-8: getCurrentChannelNo

int getCurrentChannelNo();
Parameter Meaning
Return Current channel number

Unrestricted © Siemens AG 2019 All Rights Reserved

7-158 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 7 Infrastructure services
7.3 SlInfraStructSvc reference

Set current channel number

Set the active channel.

Table 7-9: setChannelNo

SlInfraStructSvcError setChannelNo (int channelNo);
Parameter Meaning
channelNo Channel number to be set
Return Success status of the call

Notification for channel switchover

Activate a notification for a change to the channel number. If the active channel on
the HMI is changed, this is notified in the associated callback function.

Table 7-10: subscribeChannelNo

SlInfraStructSvcError subscribeChannelNo (ISlInfraStructSvcCb* cb);
Parameter Meaning
cb Pointer to the callback class
Return Success status of the call

Specification for the callback implementation:

Table 7-11: SlInfraStructSvcChannelNumberChanged

void ISlInfraStructSvcCb::SlInfraStructSvcChannelNumberChanged (int channelNo)
Parameter Meaning
channelNo Current channel number

Deactivation of such a notification.

Table 7-12: unSubscribeChannelNo

SlInfraStructSvcError unSubscribeChannelNo (ISlInfraStructSvcCb* cb);
Parameter Meaning
cb Pointer to the callback class
Return Success status of the call

7.3.5 Current language

The associated language code is used:
• DEU (German)
• CHS (Chinese)
• ENG (English)
• ESP (Spanish)
• FRA (French)
• ITA (Italian)
• etc.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 7-159
7 Infrastructure services 11/2019
7.3 SlInfraStructSvc reference

Read out current language

Read out the current language.

Table 7-13: getCurrentLanguage

SlString getCurrentLanguage();
Parameter Meaning
Return Language code of the current language

Set current language

Set the current language.

Table 7-14: setCurrentLanguage

SlInfraStructSvcError setCurrentLanguage (SlString language);
Parameter Meaning
language Language code of the language to be used
Return Success status of the call

Notification for language switchover

Activate a notification for a change to the language. If the language on the HMI is
changed, this is notified in the associated callback function.

Table 7-15: subscribeLanguage

SlInfraStructSvcError subscribeLanguage (ISlInfraStructSvcCb* cb);
Parameter Meaning
cb Pointer to the callback class
Return Success status of the call

Specification for the callback implementation:

Table 7-16: SlInfraStructSvcLanguageChanged

void ISlInfraStructSvcCb::SlInfraStructSvcLanguageChanged (SlString language)
Parameter Meaning
language Language code of the current language

Deactivation of such a notification.

Table 7-17: unSubscribeLanguage

SlInfraStructSvcError unSubscribeLanguage (ISlInfraStructSvcCb* cb);
Parameter Meaning
cb Pointer to the callback class
Return Success status of the call

7.3.6 Current access level

The control has eight different access levels defined by the SlAccessLevel enum.

Unrestricted © Siemens AG 2019 All Rights Reserved

7-160 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 7 Infrastructure services
7.3 SlInfraStructSvc reference

Table 7-18: struct SlAccessLevel

enum SlAccessLevel
{
SIEMENS = 0,
MANUFACT = 1,
SERVICE = 2,
USER = 3,
KEY_3 = 4,
KEY_2 = 5,
KEY_1 = 6,
KEY_0 = 7,
NOTHING = 10
};
Meaning
SIEMENS  S0
MANUFACT  S1
…
KEY_0  S7

Table 7-19: The eight access authorization levels

Access level Can be accessed with User group
S0 System password SIEMENS
S1 Machine manufacturer Machine manufacturer
password
S2 Service password Commissioning engineer, service
(machine manufacturer)
S3 End user password Privileged end user
(own service)
S4 Key switch position 3 Programmers
S5 Key switch position 2 Trained operator
S6 Key switch position 1 Operator
S7 Key switch position 0 Semi-skilled operator
(NC Start / NC Stop, MCP)

S0 denotes the access level with the highest rights and S7 the access level with
the most restrictive rights. The keyswitch position is enabled by the current
keyswitch position or by entry of a password.

Read out current access level

Read out the current access level.

Table 7-20: getCurrentAccessLevel

SlAccessLevel getCurrentAccessLevel();
Parameter Meaning
Return Current access level

Notification for change of the access level

Activate a notification for a change to the access level. If the access level on the
HMI is changed, this is notified in the associated callback function.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 7-161
7 Infrastructure services 11/2019
7.3 SlInfraStructSvc reference

Table 7-21: subscribeAccessLevel

SlInfraStructSvcError subscribeAccessLevel (ISlInfraStructSvcCb* cb);
Parameter Meaning
cb Pointer to the callback class
Return Success status of the call

Specification for the callback implementation:

Table 7-22: SlInfraStructSvcAccessLevelChanged

void ISlInfraStructSvcCb::SlInfraStructSvcAccessLevelChanged
(SlAccessLevel accesslevel)
Parameter Meaning
accesslevel Current access level

Deactivation of such a notification.

Table 7-23: unSubscribeAccessLevel

SlInfraStructSvcError unSubscribeAccessLevel (ISlInfraStructSvcCb* cb);
Parameter Meaning
cb Pointer to the callback class
Return Success status of the call

7.3.7 Current NCU

Read out current NCU

Read out the NCU in an M:N configuration.

Table 7-24: getActiveNcu

SlString getActiveNcu();
Parameter Meaning
Return Current NCU

Set current NCU

Set the NCU in an M:N configuration.

Table 7-25: setActiveNcu

SlInfraStructSvcError setActiveNcu(SlString ncu, int chanNo=1);
Parameter Meaning
ncu NCU to be set
chanNo Channel number to be set
Return Success status of the call

7.3.8 Current operating area and area switchover

Read out current operating area

Read out the current operating area.

Table 7-26: getActiveArea

SlString getActiveArea();
Parameter Meaning
Return Current operating area

Unrestricted © Siemens AG 2019 All Rights Reserved

7-162 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 7 Infrastructure services
7.3 SlInfraStructSvc reference

Set current operating area

Select a specific operating area and optionally a specific dialog.

Table 7-27: switchToArea / switchToDialog

SlInfraStructSvcError switchToArea ( SlString area,
SlString dialog="",
SlString args="");

SlInfraStructSvcError switchToDialog ( SlString dialog,

SlString args="");
Parameter Meaning
area Operating area to be set
dialog Dialog in the operating area to be set
args Further arguments
Return Success status of the call

7.3.9 Shutdown Operate

Shutdown the HMI Operate software.

Table 7-28: shutdownHmi

SlInfraStructSvcError shutdownHmi (bool force);
Parameter Meaning
force True: Force shutdown
Return Success status of the call

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 7-163
7 Infrastructure services 11/2019
7.3 SlInfraStructSvc reference

Unrestricted © Siemens AG 2019 All Rights Reserved

7-164 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 8 Archive service
8.1 Introduction

8 Archive service
8
Objective of the chapter
This chapter describes the interface of the archive service. The archive service
allows different archive types to be generated and read-in. The following types are
supported:

• Series commissioning archive

• User archive
• PLC upgrade archive
• Paper-tape archive

Note
The archive service can only be used for SINUMERIK 840. This interface cannot
be used for SINUMERIK One and SINUMERIK 828D.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 8-165
8 Archive service 11/2019
8.1 Introduction

8.1 Introduction
8.1.1 Class model

Overview
The class model of the DrivesService consists primarily of the following classes
and enums:
• SlArchivingSvc
• SlArchivingSvcStatus
• SlArchiveType_Enum
• SlSetupArchivingComponent_Enum
• SlArchivingSvcRequest_Enum
• ISlArchivingSvcCb

All are defined in sloperatecppapi.h.

#include "sloperatecppapi.h"

Class SlArchiveSvc
SlArchiveSvc objects are used to:
• Create and fetch archives

struct SlArchivingSvcStatus
struct SlArchivingSvcStatus
{
SlString ArchiveItem;
SlVector<StatusError> Errors;
bool OK;
long Percentage;
SlArchivingSvcRequest_Enum Request;
};

SlArchiveType_Enum
Enum values identifying the archive types:

enum SlArchiveType_Enum
{
AT_UNDEFINED = 0,
AT_SETUP = 1,
AT_PLCUPGRADE = 2,
AT_PAPERTAPE = 3,
AT_USER = 4,
AT_OTHER = 5
};

Unrestricted © Siemens AG 2019 All Rights Reserved

8-166 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 8 Archive service
8.1 Introduction

SlSetupArchivingComponent_Enum

enum SlSetupArchivingComponent_Enum
{
AC_NOTSPECIFIED = 0,
AC_NCU = 1,
AC_NCUANDCOMPENSATIONDATA = 2,
AC_PLC = 3,
AC_COMPILECYCLES = 4,
AC_DRIVESBINARY = 5,
AC_DRIVESASCII = 6,
AC_HMI = 7
};

SlArchivingSvcRequest_Enum

enum SlArchivingSvcRequest_Enum
{
A_RQ_NOREQUEST = 0,
A_RQ_LISTCOMPLETED = 1,
A_RQ_PROGRESS = 2,
A_RQ_CANCELED = 3,
A_RQ_INFO = 4,
A_RQ_ERROR = 5,
A_RQ_CONFIRMOVERWRITE = 6,
A_RQ_CONFIRMREADARCHIVE = 7,
A_RQ_CONFIRM = 8,
A_RQ_CONFIRMNCUVERSION = 9,
A_RQ_NEWFILENAME = 10
};

ISlArchivingSvcCb

Callback interface class.

The following functions must be overridden:
class ISlArchivingSvcCb
{
public:
virtual void ArchivingSvcActionCanceled()=0;
virtual void ArchivingSvcActionCompleted(SlArchivingSvcStatus status)=0;
virtual void ArchivingSvcActionProgress( long percentage,
SlString archiveItem) = 0;
virtual void ArchivingSvcStatusChanged( SlArchivingSvcStatus status,
bool& confirm) = 0;
};

SlArchiveSvcError
Long value for error feedback signals.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 8-167
8 Archive service 11/2019
8.2 Step-by-step examples

8.2 Step-by-step examples

Overview
The following chapters show the various applications of the archive service step-
by-step. An executable example is included in the SINUMERIK Integrate Create
MyHMI /3GL for each "step-by-step example".

These examples are shown in the following overview of examples.

Table 8-1: Overview of the examples

Application Example Chapte
r
Create archives SlArchiveSvcCreateArchive 8.2.2
Reading-in archives and SlArchiveSvcReadArchive 8.2.3
reading-out supplementary
information

Only the points relevant to ArchiveService are described. The comments for the
sources contain more detailed information.

8.2.1 Preparation

Overview
Preparatory measures are described in Chapter 2.1  "New Project". All of the
items described there must be executed first.

8.2.2 Creating archives

Overview
The following example shows the individual steps required to create archives.

In the example, the "create setup archive" button creates a setup archive with the
above settings.

The "create user archive" button creates a user archive with the
above read out part programs.

"archive path" and "archive name" are used to specify the storage path and the
name of the archive file, respectively.

These specifications apply to each of the two buttons. The currently edited item is
displayed in the lower box and the current progress is displayed as percentage in
the status line.

Unrestricted © Siemens AG 2019 All Rights Reserved

8-168 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 8 Archive service
8.2 Step-by-step examples

Fig. 8-1: Create archives

Step 1
Create the required variables of type SlArchivingSvc, ISlArchivingSvcCb and
SlSetupArchivingComponent_Enum.

// create an instance of SlArchivingSvc

SlArchivingSvc m_ArchiveSvc;

// create SlVector for component types

SlVector<SlSetupArchivingComponent_Enum> types;

// create callback interface

ISlArchivingSvcCb* m_pCb;

Step 2
Group components.

// fill SlVector with components enum

SlSetupArchivingComponent_Enum tmpType = AC_NCUANDCOMPENSATIONDATA;
types.push_back(tmpType);

Step 3
Generate setup archive.

m_ArchiveSvc.createSetupArchiveAsync(filepath,types,addFiles,
SlString("Creator"),SlString("Comment"),m_pCb,true);

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 8-169
8 Archive service 11/2019
8.2 Step-by-step examples

Step 4
Implement the callback method.

void SlArchivingSvcCb::ArchivingSvcActionCompleted(SlArchivingSvcStatus
status)
{
SlArchivingSvcStatus mystatus = status;

// call main window to show result

PostMessage(msgWindow, WM_COMMAND, 12, 0);
}

8.2.3 Reading-in archives and reading-out supplementary information

Overview
The following example shows the individual steps required to read-in archives and
read-out supplementary information for the archives.

Clicking the "read info" button displays the supplementary information for the
marked archive in the left-hand text box.

Clicking the "read-in archive file" button imports the marked archive; the status and
the current imported percentage value are displayed in the right-hand text box and
in the status line, respectively.

Fig. 8-2: Read-in archives

Unrestricted © Siemens AG 2019 All Rights Reserved

8-170 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 8 Archive service

Step 1
Create the required variables of type SlArchivingSvc and ISlArchivingSvcCb.

// create callback interface

ISlArchivingSvcCb* m_pCb;

// create an instance of SlArchivingSvc

SlArchivingSvc m_ArchiveSvc;

Step 2
Read-in archives.
Transfer the path and the callback.

// read archive file in

SlArchivingSvcError err = m_ArchiveSvc.readArchiveAsync(filepath, m_pCb,
true, true);

Step 3
Implement the callback method.

void SlArchivingSvcCb::ArchivingSvcActionCompleted(SlArchivingSvcStatus
status)
{
SlArchivingSvcStatus mystatus = status;

// call main window to show result

PostMessage(msgWindow, WM_COMMAND, 12, 0);
}

Step 4
Read-out the archive information.

SlString value;
SlArchiveType_Enum archivetype;
time_t timestamp;
SlArchivingSvcError err;

err = m_ArchiveSvc.getComment(filepath, value);

err = m_ArchiveSvc.getCreator(filepath, value);
err = m_ArchiveSvc.getNcuSystemSoftwareVersion(filepath, value);
err = m_ArchiveSvc.getTimeStampInternal(filepath, timestamp);
err = m_ArchiveSvc.getType(filepath, archivetype);

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 8-171
8 Archive service 11/2019
8.3 SlArchivingSvc reference

8.3 SlArchivingSvc reference

8.3.1 Definition

Overview
SlArchivingSvc objects can be used to create and read-in existing archives.

8.3.2 Creating an SlArchivingSvc object

Table 8-2: Constructor SlArchivingSvc
public SlArchivingSvc()
public SlArchivingSvc(SlString ncu)
Parameter Meaning
ncu Name of the NCU to be used

8.3.3 Functions

createSetupArchiveAsync
Creates a series commissioning archive.

Table 8-3: Create a series commissioning archive

public SlArchivingError createSetupArchiveAsync (
SlString archive,
SlVector<SlSetupArchivingComponent_Enum>& components,
SlVector<SlString>& additionalFiles,
SlString creator,
SlString comment,
ISlArchivingSvcCb* pCb,
bool reportProgress);
Parameter Meaning
Archives Absolute file name of the archive
components List with components to be considered for the creation of the
archive.
SlSetuoArchivingComponent_Enum
additionalFiles List with the absolute names of the files to be considered for the
creation of the archive.
creator Creator of the archive
comment Comment for the archive
pCb Pointer to the Callbackinterface class
reportProgress True: Percentage progress is returned
False: Percentage progress is not returned
Return Error number

Unrestricted © Siemens AG 2019 All Rights Reserved

8-172 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 8 Archive service

createPlcUpgradeArchiveAsync
Creates a PLC upgrade archive.

Table 8-4: Create a PLC upgrade archive

public SlArchivingError createPlcUpgradeArchiveAsync (
SlString archive,
SlString creator,
SlString comment,
ISlArchivingSvcCb* pCb,
bool reportProgress);
Parameter Meaning
Archives Absolute file name of the archive
creator Creator of the archive
comment Comment for the archive
pCb Pointer to the Callbackinterface class
reportProgress True: Percentage progress is returned
False: Percentage progress is not returned
Return Error number

createUserArchiveAsync
Creates a user archive.

Table 8-5: Create a user archive

public SlArchivingError createUserArchiveAsync (
SlString archive,
SlVector<SlString>& components,
bool includeHmi,
bool includeCompileCycles,
SlString creator,
SlString comment,
ISlArchivingSvcCb* pCb,
bool reportProgress);
Parameter Meaning
Archives Absolute file name of the archive
components List with the absolute names of the files to be considered for the
creation of the archive.
includeHMI True: With HMI files
False: Without HMI files
includeCompileCycles True: With compile cycles
False: Without compile cycles
creator Creator of the archive
comment Comment for the archive
pCb Pointer to the Callbackinterface class
reportProgress True: Percentage progress is returned
False: Percentage progress is not returned
Return Error number

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 8-173
8 Archive service 11/2019

createPaperTapeArchiveAsync
Creates a paper-tape archive.

Table 8-6: Create a paper-tape archive

public SlArchivingError createPaperTapeArchiveAsync (
SlString archive,
SlVector<SlString>& components,
bool iso,
bool crlf,
ISlArchivingSvcCb* pCb,
bool reportProgress);
Parameter Meaning
Archives Absolute file name of the archive
components List with the absolute names of the files to be considered for the
creation of the archive.
Iso True: Write in ISO format
False: Write in DIN format
crlf Mode for line break
True: "\r\n"
False: "\n"
pCb Pointer to the Callbackinterface class
reportProgress True: Percentage progress is returned
False: Percentage progress is not returned
Return Error number

readArchiveAsync
Reads-in an archive.

Table 8-7: Read-in an archive

public SlArchivingError readArchiveAsync ( SlString archive,
ISlArchivingSvcCb* pCb,
bool reportProgress,
bool reportStatusChanged);
Parameter Meaning
Archives Absolute file name of the archive
pCb Pointer to the Callbackinterface class
reportProgress True: Percentage progress is returned
False: Percentage progress is not returned
reportStatusChanged True: Status changes are returned
False: Status changes are not returned
Return Error number

cancelAsync
Cancels a running asynchronous request.

Table 8-8: Cancel a request

public SlArchivingError cancelAsync (ISlArchivingSvcCb* pCb);
Parameter Meaning
pCb Pointer to the Callbackinterface class
Return Error number

Unrestricted © Siemens AG 2019 All Rights Reserved

8-174 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 8 Archive service

getType
Reads-out the archive type.

Table 8-9: Read-out the archive type

public SlArchivingError getType (SlString archive, SlArchiveType_Enum& type);

Parameter Meaning
Archives Absolute file name of the archive
Type Returned archive type.
SlArchiveType_Enum
Return Error number

getEntries
Reads-out the entries of an archive.
If the reading of the entries takes longer than 60 seconds, it will be canceled with
the following error number:
SL_ARCHIVING_GET_ENTRIES_TIMEOUT = 160000

Table 8-10: Read-out the archive entries

public SlArchivingError getEntries (SlString archive, SlVector<SlString>& entries);

Parameter Meaning
Archives Absolute file name of the archive
entries Returned entries of the archive.
Return Error number

getComment
Reads-out the comment of an archive.

Table 8-11: Read-out the comment

public SlArchivingError getEntries (SlString archive, SlString& comment);

Parameter Meaning
Archives Absolute file name of the archive
Comment The returned comment
Return Error number

getCreator
Reads-out the creator of an archive.

Table 8-12: Read-out the creator

public SlArchivingError getCreator (SlString archive, SlString& creator);

Parameter Meaning
Archives Absolute file name of the archive
creator The returned comment
Return Error number

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 8-175
8 Archive service 11/2019

getTimeStampInternal
Reads-out the time of creating an archive.

Table 8-13: Read-out the timestamp

public SlArchivingError getTimeStampInternal(SlString archive, time_t& timestamp);

Parameter Meaning
Archives Absolute file name of the archive
timestamp The returned time when the archive was created
Return Error number

getNcuSystemSoftwareVersion
Reads-out the NCU version of an archive.

Table 8-14: Read-out the NCU version

public SlArchivingError getCreator (SlString archive, SlString& creator);

Parameter Meaning
Archives Absolute file name of the archive
creator The returned comment
Return Error number

Unrestricted © Siemens AG 2019 All Rights Reserved

8-176 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 9 Drive machine data service
9.1 Introduction

9 Drive machine data service

9
Objective of the chapter
This chapter describes the interface of the drive machine data service. This service
is used when accessing drives.

Note
Do not read drive parameters faster than in a 1 second cycle, slower is better.
Otherwise, an excessively high communication load is created - that can result in
blocking communication between the HMI and realtime system, and can therefore
block the HMI itself.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 9-177
9 Drive machine data service 11/2019
9.1 Introduction

9.1 Introduction
9.1.1 Class model

Overview
The class model of the DrivesService consists primarily of the following classes
and enums:
• SlDrivesSvc
• SlDrive
• SlDriveType

All are defined in sloperatecppapi.h.

#include "sloperatecppapi.h"

Class SlDrivesSvc
SlDrivesSvc objects are used to:
• Query the list of all drive objects.
Class SlDrive
The Drive class is a separate Drive object which represents one of the following
SINAMICS components:

• Control Unit
• Com Module
• Drive
• Line Module
• I/O

The class contains attributes which describe the corresponding object in more
detail, along with functions for reading, writing, and saving drive parameters.

SlDriveType
Enum values identifying the types of drive:

enum SlDriveType
{
NotSpecified = 0,
ControlUnit = 2,
ComModule,
Drive,
LineModule,
I/O
};

SlDrivesSvcError
Long value for error feedback signals: SL_DRIVESSVC_OK == no errors

Unrestricted © Siemens AG 2019 All Rights Reserved

9-178 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 9 Drive machine data service
9.2 Step-by-step examples

9.2 Step-by-step examples

Overview
The following chapters show the various applications of the drive machine data
service step-by-step. An executable example is included in the SINUMERIK
Integrate Create MyHMI /3GL for each "step-by-step example".

These examples are shown in the following overview of examples.

Table 9-1: Overview of the examples

Application Example Chapte
r
Listing the drive objects of a SlDrivesSvcListDrives 9.2.2
control
Reading-out drive parameters SlDrivesSvcReadDriveParameter 9.2.3

Only the points relevant to DrivesService are described. The comments for the
sources contain more detailed information.

9.2.1 Preparation

Overview
Preparatory measures are described in Chapter 2.1  "New Project". All of the
items described there must be executed first.

9.2.2 Listing the drive objects of a control

Overview
The following example provides a step-by-step guide to listing the drive objects of a
control.

In the example, the listing of the drive objects is initialized with the "list drives"
button. The status bar indicates whether the call has been successful.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 9-179
9 Drive machine data service 11/2019
9.2 Step-by-step examples

Fig. 9-1: Listing of drive objects

Step 1
Create the required variables: one (array) type SlDrive and a type
SlDrivesSvc.

// vector for drives

SlVector<SlDrive> drives;
// create an instance of SlDrivesSvc
SlDrivesSvc drvSvc;

Step 2
List the data.

// list
SlDrivesSvcError err = drvSvc.listDrives(drives);

The listDrives function returns the error SlDrivesSvcError.

SL_DRIVESSVC_OK means that no errors are pending.

9.2.3 Reading-out drive parameters

Overview
The next example provides a step-by-step guide to reading-out drive parameters.
Sequence of operations:

Enter "Drives No" and "Param No" and confirm with the "read param" button.

Unrestricted © Siemens AG 2019 All Rights Reserved

9-180 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 9 Drive machine data service
9.2 Step-by-step examples

Fig. 9-2: Reading-out drive parameters

Step 1
Create the required variables: one (array) type SlDrive and a type
SlDrivesSvc.

// vector for drives

SlVector<SlDrive> drives;
// create an instance of SlDrivesSvc
SlDrivesSvc drvSvc;

Step 2
Start by listing the drive objects. Once the list has been generated, read-out the
required parameter. Assuming: Parameter 35 (motor temperature) of drive 2 is to
be read-out:

// list
SlDrivesSvcError err = drvSvc.listDrives(drives);

// if OK
if (err == SL_DRIVESSVC_OK)
{
// get drive number and parameter number
int nDrivesNo = 2;
int nParamNo = 35;

// create an SlDrive object for drive number 2

SlDrive d = drives.at(nDrivesNo - 1);

// … then read the parameter

double value;
d.readParameter(nParamNo, value);
}
else
{
// display error
}

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 9-181
9 Drive machine data service 11/2019
9.3 Reference SlDrivesSvc

9.3 Reference SlDrivesSvc

9.3.1 Definition

Overview
SlDrivesSvc objects are used to list available SlDrive objects.
9.3.2 Creating an SlDrivesSvc object

Table 9-2: Constructor of class SlDrivesSvc

public SlDrivesSvc()

9.3.3 Functions

listDrives
Returns an array with the SlDrive objects found in the NCU. The driveType
parameter is used to define the corresponding drive type for the array.

Table 9-3: Listing of SIDrive objects

public SlDrivesSvcError listDrives(SlDriveType driveType,
SlVector<SlDrive>& drive)
public SlDrivesSvcError listDrives(SlVector<SlDrive>& drive)

public Drive[] ListDrives(DriveType driveType)

Parameter Meaning
driveType Drive object type to be associated with the drive objects in the list
drive Returned array with drive objects
Return SlDrivesSvcError

Unrestricted © Siemens AG 2019 All Rights Reserved

9-182 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 9 Drive machine data service
9.4 Reference SlDrive

9.4 Reference SlDrive

9.4.1 Definition

Overview
A SlDrive object represents one of the following SINAMICS components:

• Control Unit
• Com Module
• Drive
• Line Module
• I/O

The SIDrive class contains attributes which describe the corresponding object in
more detail. Attributes and actions (e.g. reading/writing parameters, etc.) can be
defined and performed by functions.

This class is defined in sloperatecppapi.h.

9.4.2 Creating an SlDrive object

Table 9-4: Constructor of class SlDrive

public SlDrive ()

9.4.3 Functions

readParameter
Reads an individual drive parameter (parameter specified as integer).

Table 9-5: readParameter

public SlDrivesSvcError readParameter (int parameterNo, double& value)
public SlDrivesSvcError readParameter (int parameterNo, int index, double& value)
Parameter Meaning
parameterNo Number of the drive parameter
index Index of the drive parameter for arrays
value Returned value of the drive parameter
Return SlDrivesSvcError

writeParameter
Writes an individual drive parameter (parameter specified as integer).

Table 9-6: writeParameter

public SlDrivesSvcError writeParameter (int parameterNo, double value)
public SlDrivesSvcError writeParameter (int parameterNo, int index, double value)
Parameter Meaning
parameterNo Number of the drive parameter
index Index of the drive parameter for arrays
value Written value of the drive parameter
Return SlDrivesSvcError

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 9-183
9 Drive machine data service 11/2019
9.4 Reference SlDrive

getDriveType
Reads the drive type.

Table 9-7: getDriveType / setDriveType

public SlDriveType getDriveType()
Parameter Meaning
Return Drive type

getDriveObjectId
Reads the SlDrive object ID.

Table 9-8: getDriveObjectId / setDriveObjectId

public long getDriveObjectId()
Parameter Meaning
Return SlDrive object ID

getDriveObjectName
Reads the SlDrive object name.

Table 9-9: getDriveObjectName / setDriveObjectName

public SlString getDriveObjectName()
Parameter Meaning
Return SlDrive object ID

getAxisNumber
Reads the axis number.

Table 9-10: getAxisNumber / setAxisNumber

public long getAxisNumber()
Parameter Meaning
Return Axis number

getAxisName
Reads the axis name.

Table 9-11: getAxisName / setAxisName

public SlString getAxisName()
Parameter Meaning
Return Axis number

getBusAddress
Reads the drive bus address.

Table 9-12: getBusAddress / setBusAddress

public long getBusAddress()
Parameter Meaning
Return Bus address

Unrestricted © Siemens AG 2019 All Rights Reserved

9-184 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 9 Drive machine data service
9.4 Reference SlDrive

getSlaveAddress
Reads the slave address.

Table 9-13: getSlaveAddress / setSlaveAddress

public long getSlaveAddress()
Parameter Meaning
Return Slave address

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 9-185
9 Drive machine data service 11/2019
9.4 Reference SlDrive

Unrestricted © Siemens AG 2019 All Rights Reserved

9-186 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 10 TraceDataRecorder service
10.1 Introduction

10 TraceDataRecorder service
10
Objective of the chapter
This chapter describes the interface of the trace recorder. The Trace recorder is
used if control data needs to be recorded at high frequency. It is based on the
"sITrace" component included in SINUMERIK Operate.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 10-187
10 TraceDataRecorder service 11/2019
10.1 Introduction

10.1 Introduction
10.1.1 Class model

Overview
The class model of the recorder consists of the following classes, structures and
enums:

• class SlTraceDataRecorder
• struct SlTraceDataRecorderErrorInterval
• struct SlTraceDataRecorderDataset
• struct SlTraceDataRecorderBinData
• struct SlTraceDataRecorderErr
• enum SlTraceDataRecorderState
• enum SlTraceDataOptions
• class ISlTraceDataRecorderCb
• class ISlTraceDataRecorderDataCb

All are defined in sloperatecppapi.h.

#include "sloperatecppapi.h"

Two scenarios are possible with the recorder.

Procedure for scenario 1:

• Start data recording

• Recorded data is buffered
• Feedback after recording is completed
• Recorded data can be read

Procedure for scenario 2:

• Start data recording

• Data is received continuously during recording, the data is not buffered
• Feedback after recording is completed

Scenario 1 can be used for recording smaller data volumes. Scenario 2 is suitable
for long recording sessions.

An object of the class SlTraceDataRecorder can have the state "Stopped",

"Waiting for Trigger", or "Recording". The transition from one state to the next is
shown in the figure below:

Unrestricted © Siemens AG 2019 All Rights Reserved

10-188 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 10 TraceDataRecorder service
10.1 Introduction

Fig. 10-1: State graph

Class SlTraceDataRecorder
Objects that permit high-frequency recording of the time characteristics of NC
variables and PLC variables can be created with class TraceDataRecorder.

struct SlTraceDataRecorderErrorInterval

struct SlTraceDataRecorderErrorInterval
{
long ErrorNo;
double TimeOffset;
};

struct SlTraceDataRecorderDataset
struct SlTraceDataRecorderDataset
{
double TimeOffset;
SlVector<int> Ids;
SlVector<SlValue> Values;
};

struct SlTraceDataRecorderBinData
struct SlTraceDataRecorderBinData
{
SlVector<SlTraceDataRecorderDataset> Data;
SlVector<SlTraceDataRecorderErrorInterval> Error;
};

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 10-189
10 TraceDataRecorder service 11/2019
10.1 Introduction

struct SlTraceDataRecorderErr
struct SlTraceDataRecorderErr
{
int ErrorNo;
SlString Message;
};

enum SlTraceDataRecorderState
enum SlTraceDataRecorderState
{
Stopped = 0,
WaitingForTrigger = 1,
Recording = 2
};

enum SlTraceDataOptions
enum SlTraceDataOptions
{
None = 0,
IncludeHeader = 1,
IncludeSignalDefinition = 2,
IncludeHeaderAndSignalDefinition = 3
};

class ISlTraceDataRecorderCb
Callback interface class.

class ISlTraceDataRecorderCb
{
public:
virtual void
TraceDataRecorderStateChanged(SlTraceDataRecorderState state) = 0;

virtual void
TraceDataRecorderDataCollectionAborted(SlTraceDataRecorderErr error) = 0;

virtual void TraceDataRecorderDataCollectionCompleted() = 0;

};

class ISlTraceDataRecorderDataCb
Callback interface class.

class ISlTraceDataRecorderDataCb
{
public:
virtual void TraceDataRecorderNewBinaryData(SlTraceDataRecorderBinData
DataBin) = 0;

virtual void TraceDataRecorderNewXmlData(SlString dataXml) = 0;

};

Unrestricted © Siemens AG 2019 All Rights Reserved

10-190 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 10 TraceDataRecorder service
10.2 Step-by-step examples

10.2 Step-by-step examples

Overview
The following chapters provide a step-by-step demonstration of how the recorder is
used in the two application scenarios.

These examples are shown in the following overview of examples.

Table 10-1: Overview of the examples

Application Example Chapte
r
Recording of data with buffering TraceDataRecorder_Scenario1 10.2.2
according to scenario 1
Continuous recording of data TraceDataRecorder_Scenario2 10.2.3
according to scenario 2

Only the points relevant for the TraceService are described. The comments for the
sources contain more detailed information.

10.2.1 Preparation

Overview
Preparatory measures are described in Chapter 2.1  "New Project". All of the
items described there must be executed first.

Determining the XML setup

An XML setup file is required to parameterize the data recording. It can be created
with the SinuComNC software or the trace application in the "Diagnosis" area of
the SINUMERIK Operate user interface. A session with the required parameters is
configured and stored for this (e.g. "TenSeconds_Session.xml").

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 10-191
10 TraceDataRecorder service 11/2019
10.2 Step-by-step examples

Fig. 10-2: Generating an XML structure for the trace recorder

The node "traceCaptureSetup" of this session file is required.

Fig. 10-3: Example of a stored trace session

Unrestricted © Siemens AG 2019 All Rights Reserved

10-192 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 10 TraceDataRecorder service
10.2 Step-by-step examples

The remaining entries must be deleted. After this, the file should look like this:

Fig. 10-4: XML setup for use in the TraceDataRecorder

! Important
In order to be able to receive data while recording, parameter "deferOffload" =
false must be set in the XML configuration.

Such an XML setup (TenSeconds_Def.xml) is included with the examples. With it,
the positions of the tool holders with axis indices 1, 2, and 3 are recorded in the
IPO cycle clock in channel 1 for ten seconds.

Note
The following points should be observed:

1. The attributes "ipo1SampleRate" and "ipo2SampleRate" in the XML

setup must be an integer multiple of the IPO cycle clock of the control.
2. The attribute "servoSampleRate" in the XML setup must be an integer
multiple of the servo cycle clock of the control.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 10-193
10 TraceDataRecorder service 11/2019
10.2 Step-by-step examples

10.2.2 Example 1

Overview
The following example shows step-by-step how to trace and buffer control data
with the trace recorder and subsequently read out data after completing trace
operation.

In the example, you choose whether the data is to be traced as XML or binary
format via the two radio buttons. If you choose the option binary, the data will be
processed as a CSV file, for example. In two text fields, you define the setup XML
that contains the definitions for the trace operation and the destination directory for
the file containing the traced data. Using the six buttons on the left-hand side of the
form, you can execute the individual steps of the trace procedure.

The status bar at the lower edge informs you about the success of the calls.

Fig. 10-5: Data recording with the trace recorder according to scenario 1

Unrestricted © Siemens AG 2019 All Rights Reserved

10-194 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 10 TraceDataRecorder service
10.2 Step-by-step examples

The diagram below shows the sequence of calls in example 1:

Fig. 10-6: Sequence of the calls in example 1

Step 1
Create the required variables of type SlTraceDataRecorder and
ISlTraceDataRecorderCb.

// create an instance of SlTraceDataRecorder

SlTraceDataRecorder* m_pTraceDataRecorder;

// create callback interface

ISlTraceDataRecorderCb* m_pCbStatus;

Step 2
"Start session"
Create object, specify the data to be recorded in XML format and set up the status
callback.

// create trace data recorder

m_pTraceDataRecorder = new SlTraceDataRecorder();

m_pTraceDataRecorder->setReportsXml(bReportsXML);

// subscribe status callback (no data callback)

retVal = m_pTraceDataRecorder->subscribe(m_pCbStatus, true, 0);

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 10-195
10 TraceDataRecorder service 11/2019
10.2 Step-by-step examples

Step 3
Read-in the setup.

// capture setup
retVal = m_pTraceDataRecorder->setup(xmlSetup);

Step 4
Start the trace.

// start trace
retVal = m_pTraceDataRecorder->start();

Step 5
Stop the trace.

// start trace
retVal = m_pTraceDataRecorder->stop();

Step 6
Start the trace.

// start trace
retVal = m_pTraceDataRecorder->start();

Step 7
Implement the status callback.

void TraceDataRecorderStateChanged(SlTraceDataRecorderState state)

{
// save value
if (Recording == state)
m_sStatus = "Recording";
else if (Stopped == state)
m_sStatus = "Stopped";
else if (WaitingForTrigger == state)
m_sStatus = "WaitingForTrigger";
else
m_sStatus = "nn";

// call main window to show result

PostMessage(msgWindow, WM_COMMAND, 23, 0);
}

Step 8
Implement the abort callback.

// Callback for abort

void TraceDataRecorderDataCollectionAborted(SlTraceDataRecorderErr error)
{
// call main window to show result
PostMessage(msgWindow, WM_COMMAND, 24, 0);
}

Unrestricted © Siemens AG 2019 All Rights Reserved

10-196 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 10 TraceDataRecorder service
10.2 Step-by-step examples

Step 9
Implement the complete callback.

// Callback for complete

void TraceDataRecorderDataCollectionCompleted()
{
// call main window to show result
PostMessage(msgWindow, WM_COMMAND, 25, 0);
}

Step 10
Read-out the buffered data.

// initial return value

SlTraceDataRecorderError retVal = -1;

if ( 0 != m_pTraceDataRecorder )
{
// get binary data
SlTraceDataRecorderBinData binTracedData;
retVal = m_pTraceDataRecorder->getDataBin(binTracedData);
rsBinTracedData = convertBINtoString(binTracedData);
}

10.2.3 Example 2

Overview
The following example shows how to continuously record control data with the
trace recorder. Example 2 is structured in the same way as the previous example
1. Therefore, only the additional steps that deal with continuous recording are
described below.

In the example, you choose whether the data is to be traced as XML or binary
format via the two radio buttons. If you choose the option binary, the data will be
processed as a CSV file, for example. In two text fields, you define the setup XML
that contains the definitions for the trace operation and the destination directory for
the file containing the traced data. Using the five buttons on the left-hand side of
the form, you can execute the individual steps of the trace procedure.

The status bar at the lower edge informs you about the success of the calls.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 10-197
10 TraceDataRecorder service 11/2019
10.2 Step-by-step examples

Fig. 10-7: Data recording with the trace recorder according to scenario 2

Unrestricted © Siemens AG 2019 All Rights Reserved

10-198 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 10 TraceDataRecorder service
10.2 Step-by-step examples

The diagram below shows the sequence of calls in example 2:

Fig. 10-8: Sequence of the calls in example 1

Step 1
"Start session"
Create object, specify the data to be recorded in XML format and set up the status
and data callback.

// create trace data recorder

m_pTraceDataRecorder = new SlTraceDataRecorder();
if ( 0 != m_pTraceDataRecorder )
{
// subscribe data and status callback
m_pTraceDataRecorder->setReportsXml(bReportsXML);
retVal = m_pTraceDataRecorder->subscribe(m_pCbStatus, true, m_pCbData);
}

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 10-199
10 TraceDataRecorder service 11/2019

Step 2
Implement the callback method for binary data.

// Callback for binary data

void TraceDataRecorderNewBinaryData(SlTraceDataRecorderBinData DataBin)
{
// convert binary data to string
ostringstream streamRetVal;
for (int nIndex = 0; nIndex < DataBin.Data.size(); nIndex++)
{
// single dataset
SlTraceDataRecorderDataset dataSet = DataBin.Data.at(nIndex);

// timeOffset
streamRetVal << dataSet.TimeOffset;

// IDs
for (int iCountIds = 0; iCountIds < dataSet.Ids.size();
iCountIds++)
{
streamRetVal << ";";
streamRetVal << dataSet.Ids.at(iCountIds);
}

// values
for (int iCountValues = 0; iCountValues < dataSet.Values.size();
iCountValues++)
{
streamRetVal<<";";
streamRetVal <<
dataSet.Values.at(iCountValues).toString().c_str();
}
// CRLF
streamRetVal << "\r\n";
}

// append new data

SlString sBINData = streamRetVal.str().c_str();
m_sBINData.append(sBINData);

// call main window to show result

PostMessage(msgWindow, WM_COMMAND, 26, 0);
}

Step 3
Implement the callback method for XML data.

// Callback for XML data

void TraceDataRecorderNewXmlData(SlString dataXml)
{
// append new data
m_sXMLData.append(dataXml);

// call main window to show result

PostMessage(msgWindow, WM_COMMAND, 27, 0);
}

Unrestricted © Siemens AG 2019 All Rights Reserved

10-200 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 10 TraceDataRecorder service
10.3 Reference SlTraceDataRecorder

10.3 Reference SlTraceDataRecorder

10.3.1 Definition

Overview
SlTraceDataRecorder objects are used to record control data at high frequency via
the trace server.

10.3.2 Creating an SlTraceDataRecorder object

Table 10-2: Constructor SlTraceDataRecorder
public SlTraceDataRecorder()
public SlTraceDataRecorder(SlString xmlSetup)
public SlTraceDataRecorder(SlString xmlSetup, SlString ncu)
Parameter Meaning
xmlSetup Definition in XML format that specifies the
data to be recorded
ncu Name of the NCU to be used for the data
recording

10.3.3 Functions

Reset()
Reset the SlTraceDataRecorder.

Table 10-3: Reset the SlTraceDataRecorder

public SlTraceDataRecorderError reset()
Parameter Meaning
Return value Error number

Setup()
Setup the SlTraceDataRecoder for the data to be recorded.

Table 10-4: Setup the SlTraceDataRecorder

public SlTraceDataRecorderError setup(SlString xmlSetup)
Parameter Meaning
xmlSetup Definition in XML format that specifies the data to be recorded
Return value Error number

Start()
Start the recording.

Table 10-5: Start the recording

public SlTraceDataRecorderError start()
Parameter Meaning
Return value Error number

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 10-201
10 TraceDataRecorder service 11/2019
10.3 Reference SlTraceDataRecorder

Stop()
Stop the recording.

Table 10-6: Stop the recording

public SlTraceDataRecorderError stop()
Parameter Meaning
Return value Error number

Subscribe()
Setup the callback.

Table 10-7: Setup the callback

public SlTraceDataRecorderError subscribe( ISlTracedataRecorderCb*
pTraceDataRecorderCb,
bool stateChanged = false,
ISlTraceDataRecorderDataCb* pTraceDataRecorderDataCb = NULL,
int minimumRecords = -1)
Parameter Meaning
pTraceDataRecorder Pointer to the callback interface for status change, cancellation or
Cb completion of the data recording
stateChanged Should status changes of the trace recorder be reported using the
appropriate interface (default: false)
pTraceDataRecorder Pointer to the callback interface that returns the recorded data
DataCb when present (default: NULL)
minimumRecords The number of data records that should be present before the data
is supplied via the interface
Return value Error number

unSubcribe()
Unsubscribe the callback.

Table 10-8: Unsubscribe the callback

public SlTraceDataRecorderError unSubscribe()
Parameter Meaning
Return value Error number

getDataBin()
Read-out the recorded data in binary format.

Table 10-9: Read-out binary data

public SlTraceDataRecorderError getDataBin(
SlTraceDataRecorderBinData& binData)
Parameter Meaning
binData Recorded data in structured form
Return value Error number

Unrestricted © Siemens AG 2019 All Rights Reserved

10-202 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 10 TraceDataRecorder service
10.3 Reference SlTraceDataRecorder

getDataXML()
Read-out the recorded data in XML format.

Table 10-10: Read-out recorded data in XML format

public SlTraceDataRecorderError getDataXml(SlString& xmlData)
Parameter Meaning
xmlData String with recorded data in XML format
Return value Error number

getReportsXML()
Determine the format in which the data is recorded.

Table 10-11: Determine the recorded data format

public bool getReportsXml()
Parameter Meaning
Return value Boolean value that specifies whether the data is recorded in XML
format (true) or in structured format (false)

setReportsXML()
Set the format in which the data is recorded.

Table 10-12: Set the recorded data format

public void setReportsXml(bool reportsXml)
Parameter Meaning
reportsXml Specifies whether the data is recorded in XML format (true) or in
structured format (false)
Return value -

getState()
Determine the current state of the SlTraceDataRecoder.

Table 10-13: Determine the current state

public SlTraceDataRecorderState getState()
Parameter Meaning
Return value Current state of the data recorder

getXMLSetup()
Read-out the currently used XML data.

Table 10-14: Read-out the data currently recorded

public SlString getXmlSetup()
Parameter Meaning
Return value Returns the currently used XML definition of the recorded data

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 10-203
10 TraceDataRecorder service 11/2019
10.3 Reference SlTraceDataRecorder

getTraceDataOptions()
Determine the current option settings.

Table 10-15: Read-out the option settings

public SlTraceDataOptions getTraceDataOptions()
Parameter Meaning
Return value Returns the current option settings for the additional XmlData

setTraceDataOptions()
Set the option settings.

Table 10-16: Set the option settings

public void setTraceDataOptions(SlTraceDataOptions options)
Parameter Meaning
options Option settings for the additional XmlData
Return value -

getLastRecordingHeaderXml()
Return the frame header, if present.

Table 10-17: Read-out the frame header

public SlString getLastRecordingHeaderXml()
Parameter Meaning
Return value Returns the most recently determined frame header in XML format
provided the appropriate option is set active

getLastRecordingSignalsXml()
Return the signal definitions, if present.

Table 10-18: Read-out the frame header

public SlString getLastRecordingSignalsXml()
Parameter Meaning
Return value Returns the most recently determined signal definition in XML
format provided the appropriate option is set active

Unrestricted © Siemens AG 2019 All Rights Reserved

10-204 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 11 ToolManagement service
11.1 Introduction

11 ToolManagement service
11
Objective of the chapter
This chapter describes the interface of the ToolManagement service. It enables
changes to be tracked with regard to tools.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 11-205
11 ToolManagement service 11/2019
11.1 Introduction

11.1 Introduction
11.1.1 Class model

Overview
The class model of the ToolManagement service consists of the following classes,
structures and enums:

• class SlToolMngmntSvc
• struct SlToolInfo
• enum SlToolAction
• class ISlNewToolInfoCb

All are defined in sloperatecppapi.h.

#include "sloperatecppapi.h"

class SlToolMngmntSvc
It is possible to subscribe to changes with regard to tools using SlToolMngmntSvc
objects:

• Creating/deleting tools
• Value or status changes on tools
• Loading/unloading/relocating tools

struct SlToolInfo
Structure of the checkback data:

struct SlToolInfo
{
SlToolAction action;
SlString toolIdent;
long duploNo;
long tNo;
};

Table 11-1: Checkback data

Value Meaning
action Type of performed action
toolIdent Tool name
duploNo Duplo number of the tool
tNo T number of the tool

Unrestricted © Siemens AG 2019 All Rights Reserved

11-206 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 11 ToolManagement service
11.1 Introduction

enum SlToolAction
Enum values identifying the current action:

typedef enum
{
NO_ACTION = 0,
TOOL_CREATED,
TOOL_DELETED,
TOOL_DATA_CHANGED,
TOOL_MOVED
} SlToolAction;

Table 11-2: Actions

Value Meaning
NO_ACTION No tool-related activity
TOOL_CREATED New tool created
TOOL_DELETED Tool deleted
TOOL_DATA_CHANGED Tool data has been changed
TOOL_MOVED Tool loaded, unloaded or relocated

class ISlNewToolInfoCb
Callback interface class. The following function must be overwritten:

class ISlNewToolInfoCb
{
public:
virtual void onNewToolInfo(SlVector<SlToolInfo> toolInfos) = 0;
};

Table 11-3: Parameter

Value Meaning
toolInfos List of the change information.

SlToolMngmntSvcError
Long value for error feedback signals.

Table 11-4: Error feedback signals

Value Meaning
SL_TOOLMNGMNTSVC_OK No error
SL_TOOLMNGMNTSVC_NOT_AVAILABLE SlToolMngmntSvc not accessible
(SINUMERIK Operate may not have run
up completely yet)

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 11-207
11 ToolManagement service 11/2019
11.2 Step-by-step examples

11.2 Step-by-step examples

Overview
The following chapters show the use of the ToolManagement service step-by-step.

Table 11-5: Overview of the examples

Application Example Chapte
r
Tracking changes SlToolMngmntSvcToolAction 11.2.2

Only the points relevant for the ToolManagement service are described. The
comments for the sources contain more detailed information.

11.2.1 Preparation

Overview
Preparatory measures are described in Chapter 2.1  "New Project". All of the
items described there must be executed first.

11.2.2 Tracking changes

Overview
The following example shows step-by-step how changes with regard to tools can
be tracked with the ToolManagement service.

In the example, the notifications are activated after "Subscribe" has been pressed.
All changes with regard to tools are displayed in a list and updated accordingly.
Pressing "Unsubscribe" ends the subscription.

The status bar at the lower edge informs you about the success of the calls.

Unrestricted © Siemens AG 2019 All Rights Reserved

11-208 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 11 ToolManagement service
11.2 Step-by-step examples

Fig. 11-1: SlToolMngmntSvcToolAction

Step 1
Definition of a class which is derived from ISlNewToolInfoCb and serves as
callback.

class ToolMngmntCb : public ISlNewToolInfoCb

{
void onNewToolInfo(SlVector<SlToolInfo> toolInfo);
};

Step 2
Create the following private member variables. The first one involves an object of
the actual interface class SlToolMngmntSvc. The latter, a pointer to the callback
class defined in step 1.

SlToolMngmntSvc m_ToolMngmnt;
ToolMngmntCb* m_pToolMngmntCb;

Step 3
The object of class SlToolMngmntSvc requires the TO area to be monitored as
parameter.

SinumerikToolAccessProvider::SinumerikToolAccessProvider(void)
: m_ToolMngmnt(1)
{
...

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 11-209
11 ToolManagement service 11/2019
11.2 Step-by-step examples

Step 4
Create an object of the callback class.

m_pToolMngmntCb = new ToolMngmntCb();

Step 5
Call the subscribe function to receive changes with regard to tools.

SlToolMngmntSvcError err = m_ToolMngmnt.subscribe(m_pToolMngmntCb);

if ( err == SL_TOOLMNGMNTSVC_OK )
{
...
}

Step 6
All changes in TO area 1 are now signaled in the callback class in the overwritten
onNewToolInfo function.

void ToolMngmntCb::onNewToolInfo(SlVector<SlToolInfo> toolInfo)

{
for(int nIndex = 0; nIndex < toolInfo.size(); nIndex++)
{
SlToolInfo info = toolInfo.at(nIndex);
...
}
...
};

Step 7
If the functionality is no longer required, unSubscribe is called.

SlToolMngmntSvcError err = m_ToolMngmnt.unSubscribe(m_pToolMngmntCb);

Step 8
At the end, the allocated resources are released again.

delete m_pToolMngmntCb;
m_pToolMngmntCb = 0;

Unrestricted © Siemens AG 2019 All Rights Reserved

11-210 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 11 ToolManagement service
11.3 Reference SlToolMngmntSvc

11.3 Reference SlToolMngmntSvc

11.3.1 Definition

Overview
It is possible to subscribe to changes with regard to tools using SlToolMngmntSvc
objects:

• Creating/deleting tools
• Value or status changes on tools
• Loading/unloading/relocating tools

11.3.2 Creating an SlToolMngmntSvc object

An object of the class monitors a selected TO area. If several TO areas are
monitored, an SlToolMngmntSvc object must be created for each TO area.

Table 11-6: Constructor SlToolMngmntSvc

public SlToolMngmntSvc(int nTOAreaNo);
Parameter Meaning
nTOAreaNo TO area

11.3.3 Functions

subscribe()
Subscribe to the tool events.

Table 11-7: subscribe

public SlToolMngmntSvcError subscribe(ISlNewToolInfoCb* pCallback)
Parameter Meaning
pCallback Pointer to the callback interface
Return value Error number

unSubscribe()
Unsubscribing the tool events.

Table 11-8: unSubscribe

public SlToolMngmntSvcError unSubscribe(ISlNewToolInfoCb* pCallback);
Parameter Meaning
pCallback Pointer to the callback interface
Return value Error number

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 11-211
11 ToolManagement service 11/2019
11.3 Reference SlToolMngmntSvc

11.3.4 Notification

onNewToolInfo
Notifications about changes with regard to tools are signaled in the callback object
(data type ISlNewToolInfoCb)

Table 11-9: unSubscribe

public void onNewToolInfo(SlVector<SlToolInfo> toolInfos);
Parameter Meaning
toolInfos List of the change information.

Unrestricted © Siemens AG 2019 All Rights Reserved

11-212 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 12 Action log service
12.1 Introduction

12 Action log service

12
Objective of the chapter
This chapter describes the interface of the action log service. The
action log service allows the action log of SINUMERIK Operate to be
accessed.

Further, for the user it is possible to extend this log by several

entries. As a consequence, there is a link with respect to time between
the actual entries and the events monitored by the action log.
For instance, user IDs can be included in the action log
and therefore operator actions can be precisely assigned
to a user.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 12-213
12 Action log service 11/2019
12.1 Introduction

12.1 Introduction
12.1.1 Class model

Overview
Using the action log it is possible to log various operator sequences
in order to subsequently be able to track them. In so doing, various
events can be monitored:

• Alarm state changes

• Keyboard actions
• Channel state changes
• Window switchover
• Writing NCK/PLC data
• File access
• Function calls
• Current program status

The class model of the action log service consists of the following classes,
structures and enums:

• class SlTripRecorder
• enum SlTripEvent
• class ISlTripRecorderCb
• class ISlTripRecorderStateCb

All are defined in sloperatecppapi.h.

#include "sloperatecppapi.h"

Class SlTripRecorder
Using TripRecorder objects, you can read-out the current action log. It is also
possible to add your own entries to the log.

To read-out the action log, there is a synchronous as well as

an asynchronous call.

Unrestricted © Siemens AG 2019 All Rights Reserved

12-214 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 12 Action log service
12.1 Introduction

enum SlTripEvent
The events that can be logged.

enum SlTripEvent
{
NoEvent = 0,
HmiStartup,
HmiShutdown,
PlcCrash,
KeyPressed,
KeyReleased,
AlarmComing,
AlarmAcknowledge,
AlarmGoing,
OpenWindowArea,
NcuChannelStatus,
NcuToolChange,
NcuToolChangeName,
NcuOverride,
WriteVariable,
NcuConnectionState,
NcuOperationMode,
PiCmd,
FileUpDownload
};

class ISlTripRecorderCb
Callback interface class for progress and completion.

class ISlTripRecorderCb
{
public:
virtual void TripLogProgress(int progress) = 0;
virtual void TripLogCompleted() = 0;
virtual void CrashLogProgress(int progress) = 0;
virtual void CrashLogCompleted() = 0;
};

class ISlTripRecorderStateCb
Callback interface class for status changes.

class ISlTripRecorderStateCb
{
public:
virtual void TripRecorderStatusChanged(bool isRecording) = 0;
};

12.1.2 Explanation of terms

Synchronous calls
Synchronous calls return only after the request is performed, i.e. the calling thread
is blocked in the meantime. This can interfere with event processing since control
inputs and displays are withheld during a synchronous call. For this reason, calls
that may take a long time should be performed asynchronously.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 12-215
12 Action log service 11/2019
12.1 Introduction

Asynchronous calls
Asynchronous calls return as soon as the request has been transferred to the
archive service. The returned error code cannot therefore indicate whether the
request has been completed successfully; it can only indicate whether or not the
request has been sent successfully. For example, an error occurs if call parameters
are not correctly assigned. The actual request status is returned in the callback of
the action log service (callback functions).

Log types
Table 12-1: Log types
Log type Description
Current log This log contains the current entries. It is implemented as ring
buffer; this means that old entries are
automatically overwritten.
Crash log For critical events, the action log saves the contents of the
current log in the so-called crash log. The entries backed up can
therefore no longer be overwritten by new entries. The crash log
can only be overwritten if an additional critical event occurs.
.

Unrestricted © Siemens AG 2019 All Rights Reserved

12-216 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 12 Action log service
12.2 Step-by-step examples

12.2 Step-by-step examples

Overview
The following chapters show the various applications for the
action log service. For every "step-by-step example," there is an
executable example in SINUMERIK Integrate Create MyHMI /3GL.

Table 12-2: Overview of the examples

Application Example Chapte
r
Synchronously reading out the SlTripSvcSync 12.2.2
action log
Asynchronously reading out SlTripSvcAsync 12.2.3
the action log

Only the points relevant for the action log service are explained or described in
each example. The comments for the sources contain more detailed information
(e.g. screen layout, outputs, etc.).

12.2.1 Preparation

Overview
Preparatory measures are described in Chapter 2.1  "New Project". All of the
items described there must be executed first.

12.2.2 Synchronously reading out the action log

The following example shows, step-by-step, which actions are required to start and
stop the action log, synchronously read out the log and add your own entry. The
matching executable example in the SINUMERIK Integrate Create MyHMI /3GL is
the example "SlTripSvcSync".

The action log can be started and stopped in the example. You can add your own
entries to the action log using the "Make TripEntry" button. The current log is
displayed with "GetTripLog". The status bar displays the status of the action log.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 12-217
12 Action log service 11/2019
12.2 Step-by-step examples

Fig. 12-1: SlTripSvcSync

Step 1
Create the required member variables.

SlTripRecorder* m_pTripRecorder;

Step 2
Create the TripRecorder object in the constructor. The user name under which own
entries are entered subsequently is specified as parameter.

m_pTripRecorder = new SlTripRecorder("MyOwnUser");

Step 3
The notification for status changes is set up with the subscribe function. A pointer
of the type
ISlTripRecorderStateCb which points to the required callback function, is
transferred here.
// pointer to callback interface
ISlTripRecorderStateCb* m_pCbStatus;

Unrestricted © Siemens AG 2019 All Rights Reserved

12-218 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 12 Action log service
12.2 Step-by-step examples

// create instance of callback object

m_pCbStatus = new SlTripSvcSyncStatusCb();

// subscribe state
SlTripRecorderError retVal = m_pTripRecorder->subscribe(m_pCbStatus);
if (SL_TRIPRECORDER_OK == err)
{
// successful
}
else
{
// error
}

Step 4
Implement the callback function. Function
TripRecorderStatusChanged is already defined as virtual void. The
user must implement the desired function to evaluate the isRecording
value.

bool m_bRecordingState = false;

class SlTripSvcSyncStatusCb : public ISlTripRecorderStateCb

{
// Callback for state changed
void TripRecorderStatusChanged(bool isRecording)
{
// save state
m_bRecordingState = isRecording;
}
};

Step 5
Start the action log. The events to be logged are transferred in the form of an
SlVector. If an empty object is transferred, only your own entries are logged.

SlTripEvent trip1 = AlarmComing;

SlTripEvent trip2 = WriteVariable;

SlVector<SlTripEvent> tripIDs;
tripIDs.push_back(trip1);
tripIDs.push_back(trip2);

SlTripRecorderError retVal = m_pTripRecorder->start(tripIDs);

Step 6
Add your own entry to the action log. The user name used when creating the
TripRecorder object is taken as user name.

SlTripRecorderError err = m_pTripRecorder->write("my entry.");

Step 7
Stop the action log.

SlTripRecorderError err = m_pTripRecorder->stop();

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 12-219
12 Action log service 11/2019
12.2 Step-by-step examples

Step 8
Write the current action log to a file.
SlTripRecorderError ret = m_pTripRecorder->getTripLog("C:\\tmp\\log.txt");

Note
The synchronous function "getTripLog" can take a very long time to return
depending on the size of the current action log file and therefore block the
complete SINUMERIK Operate. An alternative to this is the
asynchronous version "getTripLogAsync".

Step 9
If the notification for the status change of the action log is no longer required,
unSubscribe is called.

SlTripRecorderError retVal = m_pTripRecorder->unSubscribe();

12.2.3 Asynchronously reading out the action log

The following example shows, step-by-step, which actions are required to start and
stop the action log, asynchronously read out the log and add your own entry. The
matching executable example in the SINUMERIK Integrate Create MyHMI /3GL is
the example "SlTripSvcAsync".

The action log can be started and stopped in the example. You can add your own
entries to the action log using the "Make TripEntry" button. The current log is
displayed with "GetTripLogAsync". The status bar displays the status of the action
log.

Unrestricted © Siemens AG 2019 All Rights Reserved

12-220 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 12 Action log service
12.2 Step-by-step examples

Fig. 12-2: SlTripSvcAsync

Note
With the exception of Step 8, the procedure is identical to that of example
"SlTripSvcSync", and is therefore not explained again.

Steps 1 to 7
See example "Synchronously reading out the action log" (SlTripSvcAsync)

Step 8a
Request the current action log. A pointer of the type
ISlTripRecorderCb that points to the required callback function is transferred and
informs about the completion of the request.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 12-221
12 Action log service 11/2019
12.2 Step-by-step examples

// pointer to callback interface

ISlTripRecorderCb* m_pCbComplete;

// create instance of callback object

m_pCbComplete = new SlTripSvcAsyncCompleteCb();

// get trip log asynchronous

SlTripRecorderError retVal =
m_pTripRecorder->getTripLogAsync("C:\\tmp\\log.txt", m_pCbComplete);

Step 8b
Implement the callback function. Function
TripLogCompleted is already defined as virtual void. The
user must implement the desired function in order to be informed about the
completion.

class SlTripSvcAsyncCompleteCb : public ISlTripRecorderCb

{
// Callback for progress during getting trip log file
void TripLogProgress(int progress) {};

// Callback for complete getting trip log file

void TripLogCompleted()
{
// load written trip log file to textbox
...
}

// Callback for progress during getting crash log file

void CrashLogProgress(int progress) {};

// Callback for complete getting crash log file

void CrashLogCompleted() {};
};

Step 9
See example "Synchronously reading out the action log" (SlTripSvcAsync)

Unrestricted © Siemens AG 2019 All Rights Reserved

12-222 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 12 Action log service
12.3 Reference SlTripRecorder

12.3 Reference SlTripRecorder

12.3.1 Definition

Overview
Using TripRecorder objects, you can read-out the current action log. It is also
possible to add your own entries to the log.

To read-out the action log, there is a synchronous as well as

an asynchronous call.

This class is defined in sloperatecppapi.h.

12.3.2 Creating an SlTripRecorder object

Several constructors are available to create an SlTripRecorder object.

Table 12-3: constructor SlTripRecorder

SlTripRecorder(void);
SlTripRecorder(SlString username);
SlTripRecorder(SlString username, SlVector<SlTripEvent> events);
Parameter Meaning
username User name for own entries
events Events to be recorded

A user name already set when creating the SlTripRecorder object can be queried
with the following function.

Table 12-4: Set user name

SlString getUsername();

12.3.3 Starting and stopping the recording

Starting the recording

Starts a recording.

Table 12-5: Starting the recording

SlTripRecorderError start();
SlTripRecorderError start(SlVector<SlTripEvent > events);
Parameter Meaning
events Events to be recorded
Return value Error number

If the events to be recorded were already specified when creating the object, the
function is used without parameters. The already set events to be recorded can be
queried with the following function.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 12-223
12 Action log service 11/2019
12.3 Reference SlTripRecorder

Table 12-6: Set events

SlTripRecorderError getTripEvents(SlVector<SlTripEvent > &events);
Parameter Meaning
events Set events
Return value Error number

Stopping the recording

Stops an already started recording.

Table 12-7: Generation of log entries

SlTripRecorderError stop();
Parameter Meaning
Return value Error number

12.3.4 Generating log entries

Writing an entry to the action log.

Table 12-8: Generation of log entries

SlTripRecorderError write(SlString info);
SlTripRecorderError write(SlString info, SlString username);
Parameter Meaning
info Log entry
username User name for own entries
Return value Error number

12.3.5 Reading out the log

Request current log synchronously

Generates an ASCII file with the current entries of the action log. The call is
synchronous and blocks SINUMERIK Operate
until the file has been completely generated.

Table 12-9: Request current log synchronously

SlTripRecorderError getTripLog(SlString logFilename);
Parameter Meaning
logFilename File path and file name of the file to be generated
Return value Error number

Request current log asynchronously

Generates an ASCII file with the current entries of the action log. The call is an
asynchronous call and returns immediately. The transferred callback method
contains information about the progress and completion.

The function calls the implementation of the following callback methods:

• TripLogProgress()
• TripLogProgress()

Unrestricted © Siemens AG 2019 All Rights Reserved

12-224 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 12 Action log service
12.3 Reference SlTripRecorder

Table 12-10: Request current log asynchronously

SlTripRecorderError getTripLogAsync( SlString logFilename,
ISlTripRecorderCb* pCb);
Parameter Meaning
logFilename File path and file name of the file to be generated
pCb Callback method
Return value Error number

Request crash log synchronously

Generates an ASCII file with the current entries of the crash log. The
call is synchronous and blocks SINUMERIK Operate until the file has been
completely generated.

Table 12-11: Request crash log asynchronously

SlTripRecorderError getCrashLog(SlString logFilename);
Parameter Meaning
logFilename File path and file name of the file to be generated
Return value Error number

Request crash log asynchronously

Generates an ASCII file with the current entries of the crash log. The call is an
asynchronous call and returns immediately. The transferred callback method
contains information about the progress and completion.

The function calls the implementation of the following callback methods:

• TripLogProgress()
• TripLogProgress()

Table 12-12: Request crash log synchronously

SlTripRecorderError getCrashLogAsync( SlString logFilename,
ISlTripRecorderCb* pCb);
Parameter Meaning
logFilename File path and file name of the file to be generated
pCb Callback method
Return value Error number

12.3.6 Status of the recording

Subscribe to the status of the recording

Table 12-13: Subscribe to the status of the recording
SlTripRecorderError subscribe(ISlTripRecorderStateCb* pStateCb);
Parameter Meaning
pStateCb Callback method
Return value Error number

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 12-225
12 Action log service 11/2019
12.3 Reference SlTripRecorder

Unsubscribing
Table 12-14: Unsubscribing
SlTripRecorderError unSubscribe();
Parameter Meaning
Return value Error number

Querying the status of the recording

Table 12-15: Querying the status of the recording
bool getIsRecording();

12.3.7 Canceling a request that is being executed

Canceling an already started asynchronous request.

Table 12-16: Canceling a request that is being executed

SlTripRecorderError cancel();
Parameter Meaning
Return value Error number

12.3.8 Callback methods

Notification for status of the recording

Table 12-17: Notification for status of the recording
void TripRecorderStatusChanged(bool isRecording);
Parameter Meaning
isRecording True if currently a recording is in progress.

Notification about the progress of an asynchronous request

Table 12-18: Notification about the progress of an asynchronous request
void TripLogProgress(int progress);

void CrashLogProgress(int progress);

Parameter Meaning
progress Progress as a percentage

Notification about the end of an asynchronous request

Table 12-19: Notification about the end of an asynchronous request
void TripLogCompleted();

void CrashLogCompleted();

12.3.9 Events
The following events can be logged. The events to be logged are transferred in the
form of an SlVector either in the constructor or when starting a recording.

Unrestricted © Siemens AG 2019 All Rights Reserved

12-226 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 12 Action log service
12.3 Reference SlTripRecorder

Table 12-20: TripEvents

TripEvents Description
HmiStartup Logs the HMI startup
HmiShutdown Logs the HMI shutdown
PlcCrash Logs the PLC crash (setting of
DB19.DBX0.6 generates an entry with the
current program status and then writes the
crash log)
KeyPressed Logs when a key is pressed
KeyReleased Logs when a key is released
AlarmComing Logs an alarm coming event
AlarmAcknowledge Logs an alarm acknowledge event
AlarmGoing Logs an alarm going event
OpenWindowArea Logs when a window is opened
NcuChannelStatus Logs the channel status
NcuToolChange Logs a tool change
NcuToolChangeName Logs a tool change
NcuOverride Logs override changes
WriteVariable Logs write accesses of NCK/PLC variables
NcuConnectionState Logs the status of the NC connection
NcuOperationMode Logs an operating mode change
PiCmd Logs PI services
FileUpDownload Logs file transfers in the NC

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 12-227
12 Action log service 11/2019
12.3 Reference SlTripRecorder

Unrestricted © Siemens AG 2019 All Rights Reserved

12-228 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 13 Display Manager
13.1 Introduction

13 Display Manager
13
Objective of the chapter
You can find a description of the Display Manager in the
"SinumerikOperate_QT.pdf" document in Chapter 4.27.

If frames are assigned OEMFrame applications, which use the SINUMERIK

Operate CPP Api described in this document, then the following options are
available to influence the Display Manager.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 13-229
13 Display Manager 11/2019
13.1 Introduction

13.1 Introduction
13.1.1 Class model

Overview
The class model of the Display Managers essentially comprises the
SlDisplayManager class.

SlDisplayManager class
This class is defined in sloperatecppapi.h:
#include "sloperatecppapi.h"

The following actions can be executed using SlDisplayManager objects:

• Display, change and hide application components
• Display, change and hide menu components
• Activate/deactivate the mirror mode
• Switch over displays
• Notification for the mirror mode, actual display and actual display
configuration

Unrestricted © Siemens AG 2019 All Rights Reserved

13-230 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 13 Display Manager
13.2 SlDisplayManager reference

13.2 SlDisplayManager reference

13.2.1 Definitions

Overview
The following actions can be executed using SlDisplayManager objects:
• Display, change and hide application components
• Display, change and hide menu components
• Activate/deactivate the mirror mode
• Switch over displays
• Notification for the mirror mode, actual display and actual display
configuration

Success status / return value

Most Display Manager functions return a type SlDisplayManagerError value. If this
is equal to 0 (SL_DISPLAYMANAGER_OK), then the call was successful.

13.2.2 Creating an SlDisplayManager object

The SlDisplayManager class only has a default constructor.

Table 13-1: SlDisplayManager constructor

public SlDisplayManager(ISlDisplayManagerCb* cb)
Parameter Meaning
cb Pointer to the callback interface class

13.2.3 API functions

Table 13-2: showDisplay
Changes to another display.
SlDisplayManagerError showDisplay( const SlString& sDisplay,
bool noRefresh = false);
Parameter Meaning
sDisplay Target display (from the same display configuration)
noRefresh true  The display is not directly shown – but only after
refreshDisplay() is called.

Table 13-3: getActiveDisplay

Supplies the actual display names.
SlDisplayManagerError getActiveDisplay(SlString& sDisplay);
Parameter Meaning
sDisplay (out) Actual display name

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 13-231
13 Display Manager 11/2019
13.2 SlDisplayManager reference

Table 13-4: showApp

Displays an application component in a certain frame.

Application exchange:
If the application component is already visible in another frame of the display, it is moved
from there to the frame specified here. If possible, the freed frame is filled with the
application displaced from szDestFrame.

You can also attach a display name in front of a frame name (displayname.framename),
therefore changing the frame assignment into invisible displays.

framename.currentApp or displayname.framename.currentApp can be used. Here, the

application component displayed in the particular frame is shifted into a new frame.
SlDisplayManagerError showApp(const SlString& sDestFrame,
const SlString& sApp,
bool noRefresh = false);
Parameter Meaning
sDestFrame Target frame
aApp Application component
noRefresh true  The display is not directly shown – but only after
refreshDisplay() is called.

Table 13-5: showPopup

Essentially corresponds to the showApp() function. However, the target frame cannot be
located in a display. It is automatically displayed when showPopup() is called - and placed
over the currently active display.

Only your own HMI dialogs can be used as appname. The window to be displayed is
declared as top-level window (Qt::WindowStaysOnTopHint).

Only one popup can be open at a time.

SlDisplayManagerError showPopup( const SlString& sDestFrame,
const SlString& sApp,
bool noRefresh = false);
Parameter Meaning
sDestFrame Target frame
aApp Application component
noRefresh true  The display is not directly shown – but only after
refreshDisplay() is called.

Table 13-6: hidePopup

Hides a component displayed with showPopup() or togglePopup().
SlDisplayManagerError hidePopup(const SlString& sApp,
bool noRefresh = false);
Parameter Meaning
sApp Application component
noRefresh true  The display is not directly shown – but only after
refreshDisplay() is called.

Unrestricted © Siemens AG 2019 All Rights Reserved

13-232 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 13 Display Manager
13.2 SlDisplayManager reference

Table 13-7: togglePopup

If the popup frame is already displayed as a popup, this frame is hidden. Otherwise, it is
displayed. This function is therefore a combination of showPopup() and hidePopup().
SlDisplayManagerError togglePopup( const SlString& sPopupFrame,
const SlString& sApp,
bool noRefresh = false);
Parameter Meaning
sPopupFrame Popup frame
aApp Application component
noRefresh true  The display is not directly shown – but only after
refreshDisplay() is called.

Table 13-8: showMenu

Displays a menu in the specified frame. Otherwise, this command corresponds to the
showApp() function.
SlDisplayManagerError showMenu(const SlString& sDestFrame,
const SlString& sMenu,
bool noRefresh = false);
Parameter Meaning
sDestFrame Target frame
sMenu menu to be displayed
noRefresh true  The display is not directly shown – but only after
refreshDisplay() is called.

Table 13-9: showPopupMenu

Displays a menu as popup in the specified frame. Otherwise, this command corresponds
to the showPopup() function.
SlDisplayManagerError showPopupMenu(const SlString& sDestFrame,
const SlString& sMenu,
bool noRefresh = false);
Parameter Meaning
sDestFrame Target frame
sMenu menu to be displayed
noRefresh true  The display is not directly shown – but only after
refreshDisplay() is called.

Table 13-10: hidePopupMenu

Hides a menu displayed with showPopupMenu() or togglePopup().
SlDisplayManagerError hidePopupMenu(const SlString& sMenu,
bool noRefresh = false);
Parameter Meaning
sMenu menu to be hidden
noRefresh true  The display is not directly shown – but only after
refreshDisplay() is called.

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 13-233
13 Display Manager 11/2019
13.2 SlDisplayManager reference

Table 13-11: togglePopupMenu

Hides a menu already displayed as popup. Otherwise, it is displayed. This function is
therefore a combination of showPopupMenu() and hidePopupMenu().
SlDisplayManagerError togglePopupMenu(const SlString& sPopupFrame,
const SlString& sMenu,
bool noRefresh = false);
Parameter Meaning
sPopupFrame Popup frame
sMenu Menu
noRefresh true  The display is not directly shown – but only after
refreshDisplay() is called.

Table 13-12: setMirrorMode / getMirrorMode

Activates or deactivates the mirror mode. When activated, it means that all display frames
are displayed horizontally mirrored, if enableMirrorMode: is set = true for the
display.
SlDisplayManagerError setMirrorMode(bool mirror, bool noRefresh = false);
SlDisplayManagerError getMirrorMode(bool& mirror);
Parameter Meaning
mirror true  Activates the mirror mode
false  Deactivates the mirror mode
mirror (out) Status of the mirroring mode
noRefresh true  The display is not directly shown – but only after
refreshDisplay() is called.

13.2.4 Notifications
Table 13-13: displayConfigurationChanged
This is callback is initiated if, after a TCU switchover, the active display configuration
changes.
void displayConfigurationChanged(const SlString& sDisplayConfig);
Parameter Meaning
sDisplayConfig Name of the display configuration
(empty, if a display configuration has not been defined for the
actual resolution)

Table 13-14: displayChanged

This signal is initiated if the actual display and/or the application components visible there
change.
void displayChanged(const SlString& sDisplay,
const SlVector<SlString>& sVisibleApps,
const SlVector<SlString>& sVisibleFrames);
Parameter Meaning
sDisplay New display names
sVisibleApps Name of the visible components
sVisibleFrames Name of the visible frame

Table 13-15: mirrorModeChanged

This signal is initiated if the mirror mode is switched over.
void mirrorModeChanged(bool mirrorMode);
Parameter Meaning
mirrorMode New mirroring mode

Unrestricted © Siemens AG 2019 All Rights Reserved

13-234 SINUMERIK 840D sl / 828D / One - 11/2019
11/2019 I Index

I Index
I
I.1 Keyword index

A O

Action log service ............................. 12-213 OEM subdirectories .............................. 2-34

Alarm Service ....................................... 5-91 oemframe.ini ......................................... 2-26
Architecture .......................................... 1-9
Archive service ................................... 8-165
P

D Paths file access ................................. 6-132

PiService ............................................... 4-83
Data Service ......................................... 3-49 PLC access .......................................... 3-71
Debugging ............................................ 2-38
Drive machine data service ................ 9-177
R

E Reference SlAccessRights ................. 6-147

Reference SlAlarm .............................. 5-104
Error evaluation .................................... 2-17 Reference SlAlarmSource .................. 5-113
Reference SlAlarmSvc .......................... 5-99
Reference SlArchivingSvc .................. 8-172
F Reference SlDataSvc............................ 3-61
Reference SlDataSvcItem .................... 3-70
File Service ......................................... 6-115 Reference SlDataSvcStatus ................. 3-81
Reference SlDrive ............................... 9-183
G Reference SlDrivesSvc ....................... 9-182
Reference SlFileSvc ........................... 6-135
GUD ...................................................... 3-70 Reference SlFileSvcStatus ................. 6-149
Reference SlInfraStructSvc ................ 7-157
Reference SlNode............................... 6-132
I Reference SlPiSvc ................................ 4-87
Reference SlToolMngmntSvc ........... 11-211
Infrastructure services ........................ 7-151 Reference SlTraceDataRecorder ..... 10-201
Integrating the application .................... 2-19 Reference SlTripRecorder ................ 12-223

Machine data ....................................... 3-70

Unrestricted © Siemens AG 2019 All Rights Reserved

SINUMERIK 840D sl / 828D / One - 11/2019 I-235
I Index 11/2019

T V

Toolmanagement ............................. 11-205 Versioning ............................................. 2-34

TraceDataRecorder .......................... 10-187
TripEvents ........................................ 12-227
two-dimensional GUDs ......................... 3-82

Unrestricted © Siemens AG 2019 All Rights Reserved

I-236 SINUMERIK 840D sl / 828D / One - 11/2019