SIMATIC NET

S7 Programming Interface

Volume 1 of 1

1 The SAPI-S7 Interface

2 Principles of the Programming Interface

3 The Programming Interface

4 Trace and Mini-DB

5 Configuration

6 SAPI-S7 Under MS-DOS/Windows

7 Appendix

Glossary

Index

C79000-G8976-C077 Release 7

SIMATIC NET is a trademark of Siemens

Siemens Aktiengesellschaft
Wir haben den Inhalt der Druckschrift auf Überein- Weitergabe sowie Vervielfältigung dieser Unterlage,
stimmung mit der beschriebenen Hard- und Software Verwertung und Mitteilung ihres Inhalts nicht gestattet,
geprüft. Dennoch können Abweichungen nicht ausge- soweit nicht ausdrücklich zugestanden. Zuwiderhand-
schlossen werden, so daß wir für die vollständige lungen verpflichten zu Schadenersatz. Alle Rechte
Übereinstimmung keine Gewähr übernehmen. Die vorbehalten, insbesondere für den Fall der Patentertei-
Angaben in der Druckschrift werden jedoch regelmä- lung oder GM-Eintragung.
ßig überprüft. Notwendige Korrekturen sind in den
nachfolgenden Auflagen enthalten. Für Verbesse- C79000-G8976-C077
rungsvorschläge sind wir dankbar. Copyright © Siemens AG 1995 to 2001
Technische Änderungen vorbehalten. All Rights Reserved

We have checked the contents of this manual for The reproduction, transmission or use of this
agreement with the hardware described. Since document or its contents is not permitted without
deviations cannot be precluded entirely, we cannot express written authority. Offenders will be liable for
guarantee full agreement. However, the data in this damages. All rights, including rights created by patent
manual are reviewed regularly and any necessary grant or registration of a utility or design, are reserved.
corrections included in subsequent editions.
Suggestions for improvement are welcome. C79000-G8976-C077
Technical data subject to change. Copyright © Siemens AG 1995 to 2001
All Rights Reserved

Nous avons vérifié la conformité du contenu du Toute communication ou reproduction de ce support

présent manuel avec le matériel et le logiciel qui y sont d'informations, toute exploitation ou communication de
décrits. Or, des divergences n'étant pas exclues, nous son contenu sont interdites, sauf autorisation expresse.
ne pouvons pas nous porter garants pour la conformité Tout manquement à cette règle est illicite et expose
intégrale. Si l'usage du manuel devait révéler des son auteur au versement de dommages et intérêts.
erreurs, nous en tiendrons compte et apporterons les Tous nos droits sont réservés, notamment pour le cas
corrections nécessaires dès la prochaine édition. de la délivrance d'un brevet ou celui de l'enregistrement
Veuillez nous faire part de vos suggestions. d'un modèle d'utilité.

Nous nous réservons le droit de modifier les C79000-G8976-C077

caractéristiques techniques. Copyright © Siemens AG 1995 à 2001
All Rights Reserved

Siemens Aktiengesellschaft Elektronikwerk Karlsruhe

Printed in the Federal Republic of Germany
SIMATIC NET
S7 Programming Interface

Description C79000-B8976-C077/07

3
Note

We would point out that the contents of this product documentation shall not become a part of or modify any prior or existing
agreement, commitment or legal relationship. The Purchase Agreement contains the complete and exclusive obligations of Siemens.
Any statements contained in this documentation do not create new warranties or restrict the existing warranty.

We would further point out that, for reasons of clarity, these operating instructions cannot deal with every possible problem arising
from the use of this device. Should you require further information or if any special problems arise which are not sufficiently dealt with
in the operating instructions, please contact your local Siemens representative.

General
This device is electrically operated. In operation, certain parts of this device carry a dangerously high voltage.

WARNING !
Failure to heed warnings may result in serious physical injury and/or material damage.
!
Only appropriately qualified personnel may operate this equipment or work in its vicinity. Personnel must be
familiar with all warnings and maintenance measures in accordance with these operating instructions.

Correct and safe operation of this equipment requires proper transport, storage and assembly as well as careful
operator control and maintenance.

Personnel qualification requirements

Qualified personnel as referred to in the operating instructions or in the warning notes are defined as persons who are familiar with
the installation, assembly, startup and operation of this product and who possess the relevant qualifications for their work, e.g.:

− Training in or authorization for connecting up, grounding or labeling circuits and devices or systems in accordance with current
standards in safety technology;

− Training in or authorization for the maintenance and use of suitable safety equipment in accordance with current standards in
safety technology;

− First Aid qualification.

C79000-G8976-C077-07 S7 Programming Interface

S7 Programming Interface

SIMATIC S7 system components communicate with each other using the S7 communications
protocol. To allow programming device/PC application programs access to SIMATIC S7 system
components, the SAPI-S7 programming interface was developed. With its C programming
interface, you have flexible and simple access to the data of SIMATIC S7 system components.
This volume describes the S7 protocol and how to program it.

5
S7 Programming Interface C79000-G8976-C077-07

Notes

6
C79000-G8976-C077-07 S7 Programming Interface

1 The SAPI-S7 Interface ........................................................................................................11

1.1 Advantages of S7 Compared With Other Protocols...............................................12
1.2 Advantages of the SAPI-S7 Programming Interface..............................................13

2 Principles of the Programming Interface..........................................................................15

2.1 Synchronous and Asynchronous Job Handling ......................................................16
2.2 Advantages of Asynchronous Operation ...............................................................17
2.3 Receive Call and Processing Functions ................................................................18
2.4 Handling S7 Connection Management Services....................................................20
2.5 Error Message Concept ........................................................................................21
2.6 The Trace .............................................................................................................22
2.7 The Mini-DB..........................................................................................................23
2.8 Multi-CP and Multi-User Operation........................................................................24
2.8.1 Assigning VFDs and the S7 Connection List.......................................................25
2.9 Installation and Requirements for Operation .........................................................26

3 The Programming Interface...............................................................................................27

3.1 Overview of the Programming Interface................................................................28
3.1.1 Administrative Services .....................................................................................29
3.1.2 Receive Service.................................................................................................30
3.1.3 S7 Connection Management Services ...............................................................30
3.1.4 Variable Services...............................................................................................32
3.1.5 Block-Oriented Services ....................................................................................35
3.1.6 Message Services..............................................................................................36
3.1.7 VFD Services.....................................................................................................37
3.1.8 Diagnostic Services for Fault-Tolerant Connections ...........................................38
3.2 Administrative Services ........................................................................................39
3.2.1 s7_get_device....................................................................................................43
3.2.2 s7_get_vfd .........................................................................................................45
3.2.3 s7_init ................................................................................................................47
3.2.4 s7_get_cref ........................................................................................................49
3.2.5 s7_get_conn ......................................................................................................50
3.2.6 s7_shut ..............................................................................................................52
3.3 Receive service ....................................................................................................53
3.3.1 s7_receive .........................................................................................................55
3.4 S7 connection management services....................................................................58
3.4.1 s7_initiate_req ...................................................................................................63
3.4.2 s7_get_initiate_cnf .............................................................................................64
3.4.3 s7_await_initiate_req .........................................................................................65
3.4.4 s7_get_await_initiate_cnf ...................................................................................66
3.4.5 s7_get_initiate_ind .............................................................................................67
3.4.6 s7_initiate_rsp....................................................................................................68
3.4.7 s7_abort.............................................................................................................70
3.4.8 s7_get_abort_ind ...............................................................................................71
3.5 Variable Services..................................................................................................72
3.5.1 s7_read_req.......................................................................................................79

7
S7 Programming Interface C79000-G8976-C077-07

3.5.2 s7_get_read_cnf ................................................................................................81

3.5.3 s7_write_req ......................................................................................................83
3.5.4 s7_write_long_req..............................................................................................86
3.5.5 s7_get_write_cnf................................................................................................89
3.5.6 s7_multiple_read_req.........................................................................................90
3.5.7 s7_get_multiple_read_cnf ..................................................................................93
3.5.8 s7_multiple_write_req ........................................................................................96
3.5.9 s7_get_multiple_write_cnf..................................................................................99
3.5.10 s7_cycl_read_init_req ....................................................................................101
3.5.11 s7_get_cycl_read_init_cnf..............................................................................104
3.5.12 s7_cycl_read_start_req ..................................................................................105
3.5.13 s7_get_cycl_read_start_cnf............................................................................106
3.5.14 s7_get_cycl_read_ind ....................................................................................107
3.5.15 s7_get_cycl_read_abort_ind...........................................................................109
3.5.16 s7_cycl_read_stop_req ..................................................................................110
3.5.17 s7_get_cycl_read_stop_cnf ............................................................................111
3.5.18 s7_cycl_read_delete_req ...............................................................................112
3.5.19 s7_get_cycl_read_delete_cnf .........................................................................113
3.5.20 s7_cycl_read..................................................................................................114
3.6 Block-Oriented Services .....................................................................................117
3.6.1 s7_bsend_req ..................................................................................................123
3.6.2 s7_get_bsend_cnf............................................................................................125
3.6.3 s7_brcv_init .....................................................................................................126
3.6.4 s7_get_brcv_ind...............................................................................................128
3.6.5 s7_brcv_stop ...................................................................................................130
3.7 Message Services...............................................................................................131
3.7.1 s7_msg_initiate_req .........................................................................................135
3.7.2 s7_get_msg_initiate_cnf ..................................................................................136
3.7.3 s7_msg_abort_req ...........................................................................................137
3.7.4 s7_get_msg_abort_cnf.....................................................................................138
3.7.5 s7_get_scan_ind ..............................................................................................139
3.7.6 s7_get_alarm_ind ............................................................................................146
3.8 VFD Services......................................................................................................153
3.8.1 s7_vfd_state_req .............................................................................................156
3.8.2 s7_get_vfd_state_cnf.......................................................................................157
3.9 Diagnostic Services for Fault-Tolerant Connections ............................................159
3.9.1 s7_diag_init......................................................................................................161
3.9.2 s7_get_diag_ind...............................................................................................162
3.9.3 s7_diag_stop....................................................................................................164

4 Trace and Mini-DB ...........................................................................................................165

4.1 s7_trace..............................................................................................................166
4.2 s7_write_trace_buffer..........................................................................................167
4.3 s7_mini_db_set...................................................................................................168
4.4 s7_mini_db_get ..................................................................................................174
4.5 s7_last_iec_err_no..............................................................................................176
4.6 s7_last_iec_err_msg ...........................................................................................178
4.7 s7_last_detailed_err_no ......................................................................................179
4.8 s7_last_detailed_err_msg ...................................................................................183

8
C79000-G8976-C077-07 S7 Programming Interface

4.9 s7_discard_msg..................................................................................................184

5 Configuration ...................................................................................................................185
5.1 Significance of Configuration ..............................................................................186
5.2 Services With Configuration Data .......................................................................187
5.3 Configuring with STEP 7 V5................................................................................188

6 SAPI-S7 Under MS-DOS/Windows ..................................................................................189

6.1 General Information ............................................................................................190
6.2 Translating and Linking for MS-DOS...................................................................192
6.3 Translating and Linking for Windows 3.x.............................................................194
6.4 Translating and Linking for Windows 95 and Windows NT ..................................197
6.5 Environment Variables........................................................................................198
6.6 The Trace for MS-DOS or Windows....................................................................200
6.7 Special Features for Windows.............................................................................201
6.7.1 s7_set_window_handle_msg............................................................................202

7 Appendix ..........................................................................................................................203
7.1 Range of Functions of SAPI-S7 ..........................................................................204
7.2 Special Notes......................................................................................................206
7.3 Formulas for Calculating Data Lengths for the Variable Services ........................207
7.4 Representation of S7 Variables...........................................................................209
7.5 Representation of the Standard Data Types........................................................210
7.5.1 Representation of the 'Boolean' Data Type.......................................................210
7.5.2 Representation of the Data Type 'Integer'.........................................................211
7.5.3 Representation of the 'Unsigned' Data Type.....................................................214
7.5.4 Representation of the 'Floating Point' Data Type..............................................216
7.5.5 Representation of the 'Visible String' Data Type...............................................218
7.5.6 Representation of the 'Octet String' Data Type.................................................219
7.5.7 Representation of the 'Bit String' Data Type .....................................................220

Glossary ..............................................................................................................................221

Index ....................................................................................................................................223

9
S7 Programming Interface C79000-G8976-C077-07

10
C79000-G8976-C077-07 S7 Programming Interface

1 The SAPI-S7 Interface

This chapter explains the advantages of the S7 communications protocol compared

with other protocols and the S7 programming interface for PC/programming devices
(SAPI-S7).

11
S7 Programming Interface C79000-G8976-C077-07

1.1 Advantages of S7 Compared With Other Protocols

Advantages of S7 The advantages of S7 compared with other protocols are as follows:

➢ Low load on the processor and bus.
The S7 protocol is optimized for SIMATIC communication.
➢ Simplicity
The S7 protocol elements are adapted to the requirements of
SIMATIC and are therefore simple to use.
➢ Speed
Compared with other layer 7 automation protocols, such as
MMS, S7 provides a high performance.
➢ Compatibility.
Fail-safe communication with S7 H systems with the same pro-
gramming interface as to the standard SIMATIC S7 systems.

12
C79000-G8976-C077-07 S7 Programming Interface

1.2 Advantages of the SAPI-S7 Programming Interface

What Does SAPI-S7 The acronym SAPI-S7 stands for the following:
Mean?
➢ SAPI - Simple Application Programmers Interface,
➢ S7 - the layer 7 communications protocol of SIMATIC S7 sy-
stems.

What is SAPI-S7? SAPI-S7

➢ is a simple C programming interface,
➢ provides access to the S7 services on PCs and PGs and
➢ is available as a C library and is operated with Siemens drivers
and communications processors.

13
S7 Programming Interface C79000-G8976-C077-07

Advantages of the The SAPI-S7 programming interface has the following advantages:
SAPI-S7 Pro-
➢ SAPI-S7 is a simple but nevertheless flexible and high-
gramming Interface performance interface that requires only one transferred parame-
ter field per job and allows simple buffer management. SAPI-S7
is easy to learn.
➢ The SAPI-S7 programming interface is designed for asynchro-
nous operation since asynchronous calls are more efficient
(more jobs can be processed at the same time). It allows status
messages to be received at any time and is ideally suited for
creating event-driven programs, for example under Windows.
➢ SAPI-S7 handles sequential services automatically, such as
active or passive connection establishment that consists of se-
veral individual steps. The user does not need to worry about
sequences and error handling in the individual steps. Writing a
program is therefore made much simpler.
➢ SAPI-S7 supports troubleshooting with an integrated trace
function that writes the most important transfer parameters and
return values to a file. The trace can be activated and deactiva-
ted for each individual service class.
➢ The SAPI-S7 programming interface is compatible with other
SAPI programming interfaces, in other words porting SAPI-S7
applications to applications of other SAPI programming inter-
faces (for example SAPI-FMS) requires little effort.
➢ The structures of the SAPI-S7 programming interface are de-
signed so that user programs translated with byte or word align-
ment can access the individual components without problems.
➢ Consistent configuration of SIMATIC S7 and SAPI-S7 from
STEP 7 V5 and higher.
➢ Diagnostic interface for fail-safe communication so that the
application is informed at all times of the state of the redundant
connection.

14
C79000-G8976-C077-07 S7 Programming Interface

2 Principles of the Programming Interface

This chapter introduces you to the principles of the SAPI-S7 programming interface, as
follows:
➢ Implementation of asynchronous calls for improved performance and the creati-
on of event-driven applications.
➢ Separation of receive calls and event-specific processing functions to simplify
the SAPI-S7 programming interface.
➢ Library-internal processing of sequential services to simplify the user programs.
➢ Introduction of a logon and logoff function allowing multi-CP and multi-user ope-
ration.
➢ Implementation of a trace for debugging the program and to allow the functions
of the library and user programs to be checked.

When you have worked through this chapter, you will be familiar with the principles of
the S7 programming interface and will be in a position to understand the interface for
creating programs.

15
S7 Programming Interface C79000-G8976-C077-07

2.1 Synchronous and Asynchronous Job Handling

Synchronous Job When jobs are handled synchronously (Figure 2.1), the user program is
Handling blocked from the time of the request to the reception of the confirmati-
on. Events occurring in the meantime can only be processed if the
program is interrupt-driven. This mode is not implemented in SAPI-S7.

Client Communication system Server

1. Call request
indication
2. Program
waits
response
3. Resume
confirmation
program

Figure 2.1: Synchronous Operation

Asynchronous Job In asynchronous job handling (Figure 2.2) a user program is not blok-
Handling ked following a request and can receive any event and react to it. The
confirmation is fetched explicitly with a receive call.

Client Communication system Server

request
1. Call
indication
2. Continue
program

3. Receive
call
response
4. Continue
program
confirmation

Figure 2.2: Asynchronous Operation

16
C79000-G8976-C077-07 S7 Programming Interface

2.2 Advantages of Asynchronous Operation

Asynchronous The SAPI-S7 programming interface is designed for asynchronous

Jobs as a Basic operation.
Principle of the ➢ Asynchronous calls allow a higher data throughput (several jobs
SAPI-S7 Pro- can be processed at the same time).
gramming Interface
➢ An application is not blocked and is free for other tasks such as
receiving status messages.
➢ Asynchronous mechanisms are ideal for creating event-driven
programs, for example under Windows.

From the point of view of the application, you must decide whether or
not the services used are dependent on each other. If they are interde-
pendent, the execution of a job must be confirmed before the next job
can be sent. For example, a connection must be established before
data can be transferred on the connection.

17
S7 Programming Interface C79000-G8976-C077-07

2.3 Receive Call and Processing Functions

How is a Received A message received from the lower protocol layers is processed by the
Message Proces- user program in the two following steps (Figure 2.3):
sed? ➢ The 's7_receive()' function first fetches an existing message.
The return value provides information about the received event.
Per event, a constant is defined in the header file 'SAPI_S7.H',
such as 'S7_INITIATE_IND' that shows that the partner station
wants to establish an S7 connection. If 'S7_NO_MSG' is entered,
no message was received.
➢ In the next step, the user must call the appropriate processing
function for the received message: an event identified by
'S7_INITIATE_IND' requires the processing function
's7_get_initiate_ind()' to be called.
Using the receive function, the application program can poll an event.
However, between the reception of the event and calling the proces-
sing function, no further event can be fetched from the communicati-
ons system.

User program SAPI-S7 Remote partner

Initiate connection

s7_receive()

= S7_INITIATE_IND

Process indication
s7_get_initiate_ind()

= S7_OK

Figure 2.3: Receiving and Processing Messages

18
C79000-G8976-C077-07 S7 Programming Interface

Advantages of Separating the event processing into a receive function and an event-
Separating the specific processing function achieves the following:
Receive Call and ➢ Allows a simpler and clearer programming interface. Only the
Processing data and parameters relevant to the received event are transfer-
Function red to the processing functions.
➢ Allows the SAPI-S7 programming interface to be extended by
additional events by making appropriate processing functions
available.
➢ Separates the indication (receive call) and response (processing
function). This allows user data to be prepared for the response.

19
S7 Programming Interface C79000-G8976-C077-07

2.4 Handling S7 Connection Management Services

Support by the S7 The SAPI-S7 library supports you during active and passive connection
Library establishment that consists of several individual steps. Each step is
checked for success or failure. If an error occurs, the library makes
sure that steps that have already been executed are corrected. After
sending a request, you only need to call the receive function repeatedly
until the confirmation of completion is received (see Figure 2.4).

User program SAPI-S7 Remote partner

Initiate connection
s7_initiate_req()

= S7_OK

Repeat n times

s7_receive()

= S7_NO_MSG

Repeat n times Repeat n times

s7_receive()

= S7_INITIATE_CNF Message (confirmation) there!

Fetch confirmation
s7_get_initiate_cnf()

= S7_OK

Figure 2.4: Active Connection Establishment

20
C79000-G8976-C077-07 S7 Programming Interface

2.5 Error Message Concept

The Three-Stage The SAPI-S7 programming interface supports a three-stage error mes-
Error Message sage concept:
Concept of the ➢ Success or failure is only indicated by the return value of the call
SAPI-S7 Pro- to simplify error handling.
gramming Interface
➢ The causes of errors are standardized in compliance with IEC
1131 (International Electrotechnical Commission) and the num-
ber of error identifiers has been reduced to a more practical size
➢ For more precise error analyses, more detailed error codes and
messages are available.

The Return Values Defines are located in the header file 'SAPI_S7.H' for the return values
of the SAPI-S7 of each SAPI-S7 call, as follows:
Programming Inter- ➢ The value 'S7_OK' indicates error-free execution of a job.
face
➢ The entry 'S7_ERR_RETRY' indicates that an error occurred
when executing a required service. This is a temporary problem
such as a brief memory shortage. The call can be repeated
without modifying the transferred parameters.
➢ The entry 'S7_ERR' also indicates an error in the execution of
the required service. In this case, however, the error does not
allow the service to be repeated. Here, steps must be taken to
eliminate the error such as assigning new parameters for the
call.

The IEC Error The S7 library provides the functions 's7_last_iec_err_no()' and
Identifiers 's7_last_iec_err_msg()' for reading out an error number and an error
message. The causes of the errors are standardized complying with
IEC 1131 (International Electrotechnical Commission) and reduce the
number of error identifiers necessary.

The Detailed Error For more detailed error analyses, the functions
Codes 's7_last_detailed_err_no()' and 's7_last_detailed_err_msg()' functions
are implemented on the SAPI-S7 programming interface. These
describe the error sources in greater detail and also provide informati-
on about eliminating the errors.

21
S7 Programming Interface C79000-G8976-C077-07

2.6 The Trace

What Does Trace The trace is a simple and yet effective aid to debugging for the S7
Mean? library. This function enters data and events in a ring buffer and a trace
file.
The trace can be adapted to a wide range of applications, as follows:
➢ The trace file can be given any name to suit your application.
➢ The service classes for which the trace will be activated can be
selected.
➢ The trace depth (trace off, trace only for negative events etc.)
can be selected.
➢ The target of the trace indicates whether a trace file should be
created, an old trace file used or whether the information should
be written to the internal ring buffer.

Uses of the Trace During operation, the S7 library writes important data to the trace file.
The content of the file
➢ is used as a log of all actions performed by the S7 library,
➢ permits the sequence of events to be checked both in the appli-
cation and the library itself,
➢ allows simple debugging and checking of the data and parame-
ters on the SAPI-S7 programming interface.
You can also write to the trace file yourself. With such entries, it is
possible to save important data for test purposes, to check the se-
quence of the program or to synchronize it with the entries by the
library.

Time Required The trace and saving the data in the trace file slows down the user
program. For this reason, it is also possible to write the ring buffer to a
file as a “snapshot”.

22
C79000-G8976-C077-07 S7 Programming Interface

2.7 The Mini-DB

Purpose of the Using the mini-DB (mini-database), settings different from the standard
Mini-DB operating situation can be made and detailed information read out. The
mini-DB is a data area within the S7 library
➢ in which repeatedly required data (normally unchanged data) can
be stored,
➢ in which protocol-specific data can be stored or saved during
operation,
➢ in which identifiers of the last error to occur are saved,
➢ that can be read out and modified using functions such as
's7_mini_db_get()', 's7_mini_db_set()' etc.

Advantages of the The S7 library allows operation with default setting for the trace, the
Mini-DB establishment of S7 connections (active and passive), for uploading an
OD from the partner station etc. These default settings are adequate
for the majority of applications but can be modified and adapted to
special requirements at any time by calling the mini-DB.
The use of a mini-DB in the S7 library has the following advantages for
the user:
➢ The programming interface can be simplified to a few transfer
parameters. Values required (possibly always exactly the same
values) can be read from the mini-DB. This increases the per-
formance and simplifies the handling of the SAPI-S7 program-
ming interface.
➢ The high degree of flexibility provided by the S7 protocol is re-
tained. Changes in the settings and adapting them to the user’s
requirements are possible at any time by calling a mini-DB.

23
S7 Programming Interface C79000-G8976-C077-07

2.8 Multi-CP and Multi-User Operation

What is Multi-CP Multi-CP operation means the capability of addressing

Operation?
➢ several CPs
➢ the partner stations networked with the various CPs

What Does Multi- In multi-user operation, the services and resources of a computer can
User Operation be used by several applications without interfering with each other.
Mean?

Requirements The main condition for using multi-CP and multi-user operation is that
the requests and confirmations as well as indications and responses
must be unambiguously assigned to each other and to the correspon-
ding application.
This condition is achieved by a logon function implemented on the
SAPI-S7 programming interface. There is a logon for
➢ a CP and
➢ for a VFD of the CP.
The VFD provides VFD-specific S7 connections for the application
(Figure 2.5). A further logon for the VFD cannot be made either by the
same application or by a different application although multiple logons
for a CP are possible.

24
C79000-G8976-C077-07 S7 Programming Interface

2.8.1 Assigning VFDs and the S7 Connection List

Relationship bet- An application can log on at several VFDs on one or more CPs. multi-
ween VFDs and the CP and multi-user operation is, however, only possible when a VFD
S7 Connection List can be assigned unequivocally to an application after the logon (1:n
assignment). When the application logs on at the CP and the selected
VFD, the connections assigned to the VFD during configuration are
available from the S7 connection list of the CP. For example, in the
following diagram, communication is possible on connections 'C1', 'C2'
and 'C3' after a logon at 'CP 1' and 'VFD 1'.

Application 1 Application 2 Application 3

VFD 1 VFD 2 VFD 3 VFD 4

C1 C2 C3 C4 C5 C6 C7 C8

S7 connection list S7 connection list

CP 1 CP 2

Figure 2.5: Assignment of the S7 Connection List with a Logon at VFD 1 on CP 1

25
S7 Programming Interface C79000-G8976-C077-07

2.9 Installation and Requirements for Operation

Installation The procedure for installation is described in the documentation for the
particular products and is not part of this manual.

Requirements for To operate the S7 library, the communication system must be ready for
Operation operation, for example, VFDs and S7 connections must be configured.
These tasks are not supported by the SAPI-S7 programming interface.

26
C79000-G8976-C077-07 S7 Programming Interface

3 The Programming Interface

This section introduces you to the practical use of the S7 programming interface for the
'C' programming language.

How to use the calls on the programming interface that provide you with access to S7
services and objects is described in the subsections based on example programs. The
examples
➢ clearly describe the order that must be maintained for successful communicati-
on,
➢ introduce the programming interface step by step,
➢ supplement each other whereby new functions or modified program segments of
the previous example are printed in bold face,
➢ implement an error handling routine that you can adapt to your own require-
ments.
The S7 functions are not called directly in the example programs but are separated into
their own functions (for example 'my_init()' for 's7_init()'). This is not mandatory, but
makes the program more suitable for debugging, error output and subsequent extensi-
ons.

At the end of this chapter you will be familiar with the following:
➢ Which services are available on a host system,
➢ Which services are required for which tasks,
➢ Which communications sequences occur as a result of a service request and
service confirmation,
➢ Which call and sequence structure exists generally on the S7 programming inter-
face.

You will then be familiar with the basics of the S7 programming interface and be in a
position to start programming a SAPI-S7 application.

27
S7 Programming Interface C79000-G8976-C077-07

3.1 Overview of the Programming Interface

Distribution of the The S7 programming interface provides the following services:

Services
➢ Administrative Services
➢ Receive Service
➢ S7 Connection Management Services
➢ Variable Services
➢ Block-oriented Services
➢ Message Services
➢ VFD Services
➢ Diagnostic Services for Fault-Tolerant Connections

28
C79000-G8976-C077-07 S7 Programming Interface

3.1.1 Administrative Services

Description The administrative services provide functions for reading out configu-
ration information and for logging on and logging off at the communi-
cations system. There are also functions that provide the references for
symbolic S7 connection names:
The following table provides you with an overview of the administrative
services. For a more detailed description, refer to Section 3.2 page 43.

s7_get_device() With this function, the user program

can query the names of all the in-
stalled CPs.
s7_get_vfd() With this function, the user program
can query all the configured VFDs of
a CP that were assigned connecti-
ons.
s7_init() With this function, the user program
logs on at the communications sy-
stem.
s7_get_cref() This function provides a reference to
a symbolic S7 connection name.
This identifier selects the real con-
nection on the network and is easier
to use than the symbolic name.
s7_get_conn() This function returns all symbolic S7
connection names of the logged on
VFD and their references.
s7_shut() With this function, the user program
logs off at the communications sy-
stem.

29
S7 Programming Interface C79000-G8976-C077-07

3.1.2 Receive Service

Description Service for fetching messages.

For a detailed description, refer to Section 3.3.1 page 55.

s7_receive() With this function, the user program

fetches received messages from the
communications system.

3.1.3 S7 Connection Management Services

Description The S7 connection management services are required to establish and

close S7 connections.

Active Connection The following table provides you with an overview of the connection
Establishment management services for active connection establishment. For a more
detailed description refer to Section 3.4.1 page 63.

s7_initiate_req() This function passes a request for

the active establishment of an S7
connection to the communications
system.
s7_get_initiate_cnf() This function receives the result of
the above call.

30
C79000-G8976-C077-07 S7 Programming Interface

Passive Connecti- The following table provides you with an overview of the connection
on Establishment management services for passive connection establishment. For a
detailed description refer to Section 3.4.3 page 65.

s7_await_initiate_req() This function prepares the commu-

nications system to receive a passi-
ve S7 connection establishment re-
quest.
s7_get_await_initiate_cnf() This function receives the result of
the above call.
s7_get_initiate_ind() This function completes the recepti-
on of an initiate indication.
s7_initiate_rsp() The connection request can be ac-
cepted or rejected with this function.

Aborting a Con- The following table provides you with an overview of the connection
nection management services for aborting a connection. For a detailed
description refer to Section 3.4.7 page 70.

s7_abort() This function aborts an established

S7 connection.
s7_get_abort_ind() This function completes the recepti-
on of an abort indication.

31
S7 Programming Interface C79000-G8976-C077-07

3.1.4 Variable Services

Description The variable services contain functions for reading and writing one or
more variables.

Reading and The following table provides you with an overview of the variable ser-
Writing a Variable vices for reading and writing a variable. For a detailed description refer
to Section 3.5.1 page 79.

s7_read_req() This function initiates a read va-

riable job.
s7_get_read_cnf() This function receives the value
of the variable that was read.
s7_write_req() This function initiates a write va-
riable job
s7_get_write_cnf() This function receives the result
of the above call.

Reading and The following table provides you with an overview of the variable ser-
Writing more than vices for reading and writing more than one variable. For a detailed
One Variable description refer to Section 3.5.6 page 90.

s7_multiple_read_req() This function initiates a job to

read multiple variables.
s7_get_multiple_read_cnf() This function receives the value
of the variables that were read.
s7_multiple_write_req() This function initiates a job to
write multiple variables.
s7_get_multiple_write_cnf() This function receives the result
of the above call.

32
C79000-G8976-C077-07 S7 Programming Interface

Initiating Cyclic The following table provides you with an overview of the variable ser-
Reading with Mul- vices for cyclic reading with multiple calls. For a detailed description
tiple Calls refer to Section 3.5.10 page 101.

s7_cycl_read_init_req() This function instructs the server

to prepare for the cyclic reading
of variables.
s7_get_cycl_read_init_cnf() This function receives the result
of the above call.
s7_cycl_read_start_req() This function instructs the server
to start the cyclic reading of va-
riables.
s7_get_cycl_read_start_cnf() This function receives the result
of the above call.

Receiving Data The following table provides you with an overview of the variable ser-
Cyclically vices for receiving data cyclically. For a detailed description refer to
Section 3.5.14 page 107.

s7_get_cycl_read_ind() This function receives the data

sent by the server.

Stopping and The following table provides you with an overview of the variable ser-
Aborting Cyclic vices for stopping and aborting cyclic reading. For a detailed descripti-
Reading on refer to Section 3.5.15 page 109.

s7_get_cycl_read_abort_ind() This function completes the

reception of a cyclic read abort
indication.
s7_cycl_read_stop_req() This function instructs the server
to stop cyclic reading of varia-
bles.
s7_get_cycl_read_stop_cnf() This function receives the result
of the above call.
s7_cycl_read_delete_req() This function stops cyclic reading
and logs off at the server.
s7_get_cycl_read_delete_cnf() This function receives the result
of the above call.

33
S7 Programming Interface C79000-G8976-C077-07

Initiating Cyclic The following table provides you with an overview of the variable ser-
Reading with one vice "initiate cyclic reading with one call“. For a detailed description
Call refer to Section 3.5.20 page 114.

s7_cycl_read() This function instructs the ser-

ver to prepare for cyclic reading
of variables and to start reading
immediately.

34
C79000-G8976-C077-07 S7 Programming Interface

3.1.5 Block-Oriented Services

Description The block-oriented services provide functions for data exchange of up

to 65534 bytes. With these services, the connection must be configu-
red at both ends (STEP 7, COML S7).
The following table provides an overview of block-oriented services.
For a detailed description refer to Section 3.6.1 page 123.

s7_bsend_req() With this function, a client

application can send up to
64 Kbytes of data to a remote
station.
s7_get_bsend_cnf() With this function, the result of
the BSEND job is received.
s7_brcv_init() This function provides a buffer
dynamically to be ready to
receive BSEND data sent by
the remote station.
s7_get_brcv_ind() This function copies the user
data sent by the partner to the
specified memory area.
s7_brcv_stop() This function releases the buf-
fers occupied by s7_brcv_init,
in other words, communication
with the remote BSEND is no
longer possible.

35
S7 Programming Interface C79000-G8976-C077-07

3.1.6 Message Services

Description With these services, messages can be received from SIMATIC S7

programmable controllers and further processed.
The SCAN service belongs to the configured or symbol-related messa-
ge services, the ALARM service belongs the programmed or block-
related message services. For a detailed description refer to Section
3.7 page 131.
The incoming frames have a time stamp, the message number (event
ID) as well as the event or acknowledgment status of the event. As an
option, associated values can be sent with the messages.
The following table provides an overview of the message services.

s7_msg_initiate_req() With this function, a client

application informs the remote
station that it wants to receive
messages.
s7_get_msg_initiate_cnf() The result of the
s7_msg_initiate_req job is
received with this function.
s7_msg_abort_req() With this function, a client
application informs the remote
station that it does not want to
receive any more messages.
s7_get_msg_abort_cnf() The result of the
s7_get_msg_abort_cnf job is
received with this function.
s7_get_scan_ind() This function receives the data
sent by the remote station if the
s7_receive call produced the
"S7_SCAN_IND“ indication.
s7_get_alarm_ind() This function receives the data
sent by the remote station if the
s7_receive call produced the
"S7_ALARM_IND“ indication.

36
C79000-G8976-C077-07 S7 Programming Interface

3.1.7 VFD Services

Description The following table provides an overview of the VFD services. For a
detailed description refer to Section 3.8.1 page 156.

s7_vfd_state_req() This function queries the de-

vice/user status.
s7_get_vfd_state_cnf() This function receives the de-
vice/user status.

37
S7 Programming Interface C79000-G8976-C077-07

3.1.8 Diagnostic Services for Fault-Tolerant Connections

Definition A fault-tolerant connection is the communication connection between a

fault-tolerant system and another fault-tolerant or standard system.
In contrast to a standard connection, a fault-tolerant connection con-
sists of at least two redundant connections (depending on the configu-
ration, there can be up to four redundant connections).
The currently active connection is known as the productive connection
and the other connection or connections as the standby connection(s).

Description With the SAPI-S7 functions, not only standard S7 connections but also
fault-tolerant connections to SIMATIC S7 H systems can be establis-
hed provided that S7 H CPUs and approved SIMATIC NET products
are used. The fault-tolerant connections must be configured with
STEP 7, downloaded to the SIMATIC S7 PLC and copied to the PC in
the form of an XDB file.
The following table provides you with an overview of the diagnostic
services for fault-tolerant connections. For a detailed description refer
to Section 3.9 page 159.

s7_diag_init Logon for diagnostics

Diagnostic messages are recei-
ved.
s7_get_diag_ind Fetch diagnostic data
s7_diag_stop Logoff for diagnostics
No more diagnostic messages
are received.

The diagnostic services are also available on standard connections,

but are less useful.

38
C79000-G8976-C077-07 S7 Programming Interface

3.2 Administrative Services

Description of the The following example describes the administrative services for log-
Example ging on ('s7_init()') and logging off ('s7_shut()') an S7 application with
the communications system.. Communication with a local CP and the-
refore also with a remote CP is only possible after a successful logon.
When an application logs on at the local VFD, the VFD-specific resour-
ces are reserved for the application so that before the program is ter-
minated, every logon must also be terminated by a logoff.
The transfer parameters required to log on such as the CP name and
the VFD name are queried by the communications system using the
functions 's7_get_device()' or 's7_get_vfd()'.

39
S7 Programming Interface C79000-G8976-C077-07

Example

#include "sapi_s7.h"

/* prototypings */
static void my_exit(ord32 cp_descr,char *msg,int32 ret);
static void my_get_cref(ord32 cp_descr,ord16 *cref_ptr);
static void my_init(ord32 *cp_descr_ptr);
static void my_shut(ord32 cp_descr);

/* exit application */
static void my_exit(ord32 cp_descr,char *msg,int32 ret)
{
printf("\n%s = %lx",msg,ret);
my_shut(cp_descr);
}

/* get reference for connection 'TEST' */

static void my_get_cref(ord32 cp_descr,ord16 *cref_ptr)
{ int32 ret;

ret=s7_get_cref(cp_descr,“TEST“,cref_ptr);
if(ret!=S7_OK)
{
my_exit(cp_descr,“Error s7_get_cref“,ret);
}
}

/* initialize s7 */
static void my_init(ord32 *cp_descr_ptr)
{ int32 ret;
char vfd_name[S7_MAX_NAMLEN+1];
char dev_name[S7_MAX_DEVICELEN+1];
ord16 number;

/* only use first device */

ret=s7_get_device(0,&number,dev_name);
if((ret!=S7_OK)||(number==0))
{ /* something has gone wrong */
printf("\ns7_get_device = %lx, number = %d", ret,number);
exit(-1);
}

/* only use first vfd of first device */

ret=s7_get_vfd(dev_name,0,&number,vfd_name);
if((ret!=S7_OK)||(number==0))
{ /* something has gone wrong */
printf( "\ns7_get_vfd = %lx, number = %d", ret,number);
exit(-2);
}

/* initialize s7 */
ret=s7_init(dev_name,vfd_name,cp_descr_ptr);
if(ret!=S7_OK)
{ /* something has gone wrong */
printf( "\ns7_init = %lx",ret);
exit(-3);
}
}

40
C79000-G8976-C077-07 S7 Programming Interface

/* end communication */
static void my_shut(ord32 cp_descr)
{ int32 ret;

ret=s7_shut(cp_descr);
if(ret!=S7_OK)
{ /* error has occurred -> exit */
printf( "\ns7_shut = %lx",ret);
}

/* no error has occurred */

}

/* main */
void main(void)
{ ord32 cp_descr;
ord16 cref;

/* initialize s7 */
my_init(&cp_descr);

/* get reference for connection 'TEST' */

my_get_cref(cp_descr,&cref);

/* end communication */
my_shut(cp_descr);
}

41
S7 Programming Interface C79000-G8976-C077-07

Flowchart

User program SAPI-S7 Remote partner

s7_get_device()

= S7_OK,
number!=0

s7_get_vfd()

= S7_OK,
number!=0

s7_init()

= S7_OK

s7_get_cref()

= S7_OK

s7_shut()

= S7_OK

Figure 3.1: Flowchart of the Example

42
C79000-G8976-C077-07 S7 Programming Interface

3.2.1 s7_get_device

Description With this call, the user program can query all the configured names of
the communications processors installed in the communications sy-
stem. The names are relevant for logging on with 's7_init()'.

Declaration int32 s7_get_device(

ord16 index, /* In call */
ord16 *number_ptr, /* Returned */
char *dev_name /* Returned */
)

Parameters index The 'index' parameter selects one of the existing CPs
that are numbered continuously starting at 0.

number_ptr Address of a variable of the type 'ord16' provided by

the user program. The number of installed CPs is
returned here.

dev_name Start address of a memory area provided by the user

program in which the configured CP name is entered.
The memory area should be at least
(S7_MAX_DEVICELEN + 1) bytes long for the ma-
ximum S7_MAX_DEVICELEN bytes long CP name
including the string end identifier.

Querying All CPs To query all CPs, it is best to use a program loop. The 'index' parame-
ter is used as the loop variable and runs from 0 to '*number_ptr-1'. The
'*number_ptr' has the default 1.

43
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

44
C79000-G8976-C077-07 S7 Programming Interface

3.2.2 s7_get_vfd

Description With this call, the user program can query all the configured VFDs of a
communications processor that were assigned connetions. The VFD
names are relevant for the logon with 's7_init()'.

Declaration int32 s7_get_vfd(

char *dev_name, /* In call */
ord16 index, /* In call */
ord16 *number_ptr, /* Returned */
char *vfd_name /* Returned */
)

Parameters dev_name Configured name of the communications processor

via which you want to communicate. For this parame-
ter a CP name read out with 's7_get_device()' is
usually used. It must match a configured CP name
(for example 'CP_L2_1:').

index The 'index' parameter selects one of the existing CPs

that are numbered continuously starting at 0.

number_ptr Address of a variable of the type 'ord16' provided by

the user program. The number of configured VFDs is
returned here.

vfd_name Start address of a memory area provided by the user

program in which the configured VFD name is ente-
red. The memory area should be at least
(S7_MAX_NAMLEN + 1) bytes long for the maxi-
mum S7_MAX_NAMLEN byte long VFD name in-
cluding the string end identifier.

Querying All VFDs To query all VFDs, it is best to use a program loop. The 'index' para-
meter is used as the loop variable and runs from 0 to '*number_ptr-1'.
The '*number_ptr' has the default 1.

45
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

46
C79000-G8976-C077-07 S7 Programming Interface

3.2.3 s7_init

Description With this call, the user program logs on at a VFD of an underlying
communications system.
As input parameters, the user program specifies the configured name
of the communications processor via which communication will take
place and the configured name of the VFD whose resources and servi-
ces will be used.
The user program receives a descriptor 'cp_descr' that must be speci-
fied for all subsequent calls as an addressing parameter for the se-
lected CP and VFD until the application logs off.
When the program logs on, the configuration information (for example,
the list of all S7 connections) is read from a file with a name derived
from the name of the CP as follows: The colon completing the CP na-
me is removed and the name extension '.LDB' is added. This assumes
that the file exists in the current working directory. As an alternative,
the name of the configuration file can also be assigned (using any na-
me) in the environment variable.
If several VFDs are being used at the same time in one or more com-
munications processors by one application, a corresponding number of
's7_init()' calls are necessary.

Declaration int32 s7_init(

char *cp_name, /* In call */
char *vfd_name, /* In call */
ord32 *cp_descr_ptr /* Returned */
)

47
S7 Programming Interface C79000-G8976-C077-07

Parameters cp_name Configured name of the communications proces-

sor with which communication will take place. To
address a specific module, the user program uses
a CP name configured with the SIMATIC NET in-
stallation tool (for example 'CP_L2_1:'). Normally
a CP name read out with 's7_get_device()' is
used.

vfd_name Configured name of the local VFD at which the

application logs on. To address a particular VFD,
the user program uses a VFD name specified with
the SIMATIC NET configuration tool. By selecting
the VFD, the configured S7 connections are also
selected. Here, a VFD name read out with
's7_get_vfd()' is normally used.

cp_descr_ptr Address of a variable of the type 'ord32' provided

by the user program. Here, a descriptor for ad-
dressing the selected communications processor
and VFD is entered. This parameter must be used
for further communication via the selected com-
munications processor and VFD.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

48
C79000-G8976-C077-07 S7 Programming Interface

3.2.4 s7_get_cref

Description From the communication system, the S7 application only sees the
symbolic name of the S7 connection that is cumbersome during opera-
tion. For this reason, the application uses the 's7_get_cref()' call to
obtain a reference to a symbolic connection name.

Declaration int32 s7_get_cref(

ord32 cp_descr, /* In call */
char *conn_name, /* In call */
ord16 *cref_ptr /* Returned */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

conn_name Symbolic name of the S7 connection on which

communication will take place.

cref_ptr Address of a variable of the type 'ord16' provided

by the user program. The connection reference is
returned here.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

49
S7 Programming Interface C79000-G8976-C077-07

3.2.5 s7_get_conn

Description With this call, the user program can query all the configured S7 con-
nections of a VFD and their references on a communications proces-
sor. This identifier selects the real connection on the network and is
easier to use than the symbolic name.

Declaration int32 s7_get_conn(

ord32 cp_descr, /* In call */
ord16 index, /* In call */
ord16 *number_ptr, /* Returned */
ord16 *cref_ptr, /* Returned */
char *conn_name /* Returned */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

index The 'index' parameter selects one of the existing S7

connections that are numbered continuously starting
at 0.

number_ptr Address of a variable of the type 'ord16' provided by

the user program. The number of configured S7 con-
nections is returned here.

cref_ptr Address of a variable of the type 'ord16' provided by

the user program. The connection reference is re-
turned here.

conn_name Start address of a memory area provided by the user

program in which the configured S7 connection name
is entered. The memory area should be at least
(S7_MAX_NAMLEN + 1) bytes long for the maxi-
mum S7_MAX_NAMLEN byte long connection name
including string end identifier.

Querying all S7 To query all S7 connections, it is best to use a program loop. The 'in-
Connections dex' parameter is used as the loop variable and runs from 0 to
'*number_ptr-1'. The '*number_ptr' has the default 1.

50
C79000-G8976-C077-07 S7 Programming Interface

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

51
S7 Programming Interface C79000-G8976-C077-07

3.2.6 s7_shut

Description With the 's7_shut()' call, the application cancels the logon ('s7_init()') at
the communications processor identified by the CP descriptor. All the
resources of the communications system are returned and established
connections are terminated. This call must therefore be made once for
every logon before the program is terminated.

Declaration int32 s7_shut(

ord32 cp_descr /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call. This

identifies the logon to be canceled.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

52
C79000-G8976-C077-07 S7 Programming Interface

3.3 Receive service

Description of the To extend the example in Section 3.2 the receive call 's7_receive()' is
Example used to check whether a message exists. In this simple case, a messa-
ge is not expected ('S7_NO_MSG' as return value); the example is
simply in preparation for programs coming later.

Example

:
:
/* additional prototypings */
static void my_receive(ord32 cp_descr,int32 last_event_expected);

/* receive any message from communication system */

static void my_receive(ord32 cp_descr,int32 last_event_expected)
{ ord16 cref,orderid;
int32 ret;

do
{ ret=s7_receive(cp_descr,&cref,&orderid);
switch(ret)
{ case S7_NO_MSG:
break;
default:
s7_discard_msg();
printf("\nEvent unexpected: %lx", ret);
break;
}
} while(ret!=last_event_expected);
}

/* main */
void main(void)
{ ord32 cp_descr;
ord16 cref;

/* initialize s7 */
my_init(&cp_descr);

/* get reference for connection 'TEST' */

my_get_cref(cp_descr,&cref);

/* receive message */
my_receive(cp_descr,S7_NO_MSG);

/* end communication */
my_shut(cp_descr);
}

53
S7 Programming Interface C79000-G8976-C077-07

Flowchart

User program SAPI-S7 Remote partner

s7_receive()

= S7_NO_MSG

Figure 3.2: Flowchart of the Example

54
C79000-G8976-C077-07 S7 Programming Interface

3.3.1 s7_receive

Description The receive function of the S7 library has the central task of analyzing
events received from the underlying communications system and to
report these directly to the application without any further processing.
The 's7_receive()' call is absolutely necessary when the client
➢ has sent acknowledged calls and is waiting for the acknow-
ledgment from the server,
➢ wishes to receive unacknowledged messages from the network,
➢ has sent sequential jobs (for example establishing an S7 con-
nection) to ensure processing of the service sequence until it is
completed.
The return value of the 's7_receive()' function provides a service iden-
tifier when a message is received. This identifies the type of service of
the received response (for example 'S7_READ_CNF' when a variable
was read). After receiving a message with 's7_receive()', the call for
the corresponding processing function is mandatory (for example
's7_get_read_cnf()'). Further receive calls are otherwise rejected with
an error message.

Declaration int32 s7_receive(

ord32 cp_descr, /* In call */
ord16 *cref_ptr, /* Returned */
ord16 *orderid_ptr /* Returned */
)

55
S7 Programming Interface C79000-G8976-C077-07

Parameters cp_descr Handle as return value of the 's7_init()' call. This

identifies the communications processor and the
VFD via which an event will be fetched.

cref_ptr Address of a variable of the type 'ord16' provided

by the user program. The reference of the S7
connection on which an indication or a confirmati-
on was received is entered here. This corresponds
to the S7 connection reference with which the job
was sent.

orderid_ptr Address of a variable of the type 'ord16' provided

by the user program. The job identifier of the
received acknowledgment is entered here. This
identifies the previously sent job for the user pro-
gram. The order ID is irrelevant for unacknowled-
ged services or services to establish an S7 con-
nection and is assigned a default value.

56
C79000-G8976-C077-07 S7 Programming Interface

Return Values S7_NO_MSG No message was received.

S7_UNKOWN_MSG An invalid message was received; error on the

connection partner or a service not supported
in this version of the programming interface.

S7_ERR_RETRY This value indicates that an error occurred

executing the requested service. This is a tem-
porary problem such as a brief memory shor-
tage. The call can be repeated without mo-
difying the transferred parameters.

S7_ERR This value also indicates an error in the execu-

tion of the requested service. In this case,
however, the error does not allow the service
to be repeated. Here, steps must be taken to
eliminate the error such as assigning new pa-
rameters for the call.
Apart from these values, further service identi-
fiers such as 'S7_READ_CNF' are also re-
turned depending on the message received.
You will find the definitions in the 'SAPI_S7.H'
file.

If unexpected values occur the s7_discard_msg function must be cal-

led (for example, in the default branch of the corresponding switch
instruction).

Type of Call In single-tasking operating systems such as MS-DOS, the receive

function is polled. In multitasking operating systems such as Windows,
it is possible to include the receive function at a central waiting point
allowing all the events to be received.

57
S7 Programming Interface C79000-G8976-C077-07

3.4 S7 connection management services

Description of the To extend the example from Section 3.3, an S7 connection with the
Example symbolic name 'TEST' is established ('s7_initiate_req()') and then
aborted ('s7_abort()') after the confirmation ('s7_get_initiate_cnf()') is
received.

Example :
:
/* additional prototypings */
static void my_abort(ord32 cp_descr,ord16 cref);
static void my_get_abort_ind(ord32 cp_descr);
static void my_get_initiate_cnf(ord32 cp_descr);
static void my_initiate_req(ord32 cp_descr,ord16 cref);

/* abort connection */
static void my_abort(ord32 cp_descr,ord16 cref)
{ int32 ret;

if((ret=s7_abort(cp_descr,cref))!=S7_OK)
{
my_exit(cp_descr,"Error s7_abort",ret);
}
}

/* get abort indication */

static void my_get_abort_ind(ord32 cp_descr)
{ int32 ret;

if((ret=s7_get_abort_ind())!=S7_OK)
{
my_exit( cp_descr,
}
}

/* get initiate confirmation */

static void my_get_initiate_cnf(ord32 cp_descr)
{ int32 ret;

if((ret=s7_get_initiate_cnf())!=S7_OK)
{
my_exit( cp_descr,
}
}

/* initiate connection "TEST" */

static void my_initiate_req(ord32 cp_descr,ord16 cref)
{ int32 ret;

if((ret=s7_initiate_req( cp_descr,cref))!=S7_OK)
{
my_exit(cp_descr,"Error
s7_initiate_req",ret);
}
}

58
C79000-G8976-C077-07 S7 Programming Interface

/* receive any message from communication system */

static void my_receive(ord32 cp_descr,int32
last_event_expected)
{ ord16 cref,orderid;
int32 ret;

do
{ ret=s7_receive(cp_descr,&cref,&orderid);
switch(ret)
{
:
:
case S7_INITIATE_CNF:
my_get_initiate_cnf(cp_descr);
my_abort(cp_descr,cref);
break;
case S7_ABORT_IND:
my_get_abort_ind(cp_descr);
break;
default:
printf( "Event
unexpected", ret);
break;
}
} while( (ret!=last_event_expected)&&
}

/* main */
void main(void)
{ ord32 cp_descr;
ord16 cref;

/* initialize s7 */
my_init(&cp_descr);

/* get reference for connection 'TEST' */

my_get_cref(cp_descr,&cref);

/* initiate connection */
my_initiate_req(cp_descr,cref);

/* receive initiate confirmation */

my_receive(cp_descr,S7_INITIATE_CNF);

/* end communication */
my_shut(cp_descr);
}

59
S7 Programming Interface C79000-G8976-C077-07

Flowchart for
Active Connection
Establishment

User program SAPI-S7 Remote partner

S7 connection establishment
request
s7_initiate_req()

= S7_OK

s7_receive()

= S7_NO_MSG

Repeat several times Repeat several times

s7_receive()

= S7_INITIATE_CNF
Message (confirmation) there!

Fetch confirmation
s7_get_initiate_cnf()

= S7_OK

Figure 3.3: Flowchart for Active S7 Connection Establishment

60
C79000-G8976-C077-07 S7 Programming Interface

Flowchart for
Preparing for
Passive
Connection
Establishment (not
part of example)

User program SAPI-S7 Remote partner

Preparing for S7 connection
establishment
s7_await_initiate_req()

= S7_OK

s7_receive()

= S7_NO_MSG

Repeat several times Repeat several times

s7_receive()

= S7_AWAIT_INITIATE_CNF
Message (confirmation) there!
Fetch confirmation
s7_get_await_initiate_cnf()

= S7_OK

Figure 3.4: Flowchart for Preparing for Passive S7 Connection Establishment

61
S7 Programming Interface C79000-G8976-C077-07

Flowchart for
Passive
Connection
Establishment (not
part of example)

User program SAPI-S7 Remote partner

s7_receive()

= S7_NO_MSG

Repeat several times Repeat several times

Initiates S7 connection
establishment

s7_receive()

= S7_INITIATE_IND

s7_get_initiate_ind()

= S7_OK Message (indication) there!

Fetch indication

s7_initiate_rsp()

= S7_OK

Figure 3.5: Flowchart for Passive S7 Connection Establishment

62
C79000-G8976-C077-07 S7 Programming Interface

3.4.1 s7_initiate_req

Description The 's7_initiate_req()' call initiates the establishment of an S7 con-

nection. The initiative for establishing a connection comes from the
user program, the required parameters are read from the mini-DB.
They can be read, modified and adapted to the current requirements
by the user program.
On the partner (passive side), the configured capability parameters are
compared with the received values of the job. The capability of the S7
connection (send credit, receive credit, PDU size..) that can be imple-
mented is determined by the lowest values of these parameters on
either station.

Declaration int32 s7_initiate_req(

ord32 cp_descr, /* In call */
ord16 cref /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference to the S7 connection that will be

established.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

63
S7 Programming Interface C79000-G8976-C077-07

3.4.2 s7_get_initiate_cnf

Description The 's7_get_initiate_cnf()' call, receives the result of the S7 connection

establishment.
With the 's7_receive()' call, the user program receives the
'S7_INITIATE_CNF' confirmation if the establishment request was
processed. Following this, the corresponding processing function
's7_get_initiate_cnf()' must be called for internal processing in the
library.
The negotiated capability parameters (send credit, receive credit, PDU
length) are entered in the mini-DB and can then be read out with mini-
DB calls.

Declaration int32 s7_get_initiate_cnf(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

64
C79000-G8976-C077-07 S7 Programming Interface

3.4.3 s7_await_initiate_req

Description The 's7_await_initiate_req()' call prepares the communications system

for connection requests from the remote partner. The initiative for
establishing the connection comes from the partner station and the
required parameters are read from the mini-DB. They can be read,
modified and adapted to the current requirements by the user program.

Declaration int32 s7_await_initiate_req(

ord32 cp_descr, /* In call */
ord16 cref /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference to the S7 connection that will be

established.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

65
S7 Programming Interface C79000-G8976-C077-07

3.4.4 s7_get_await_initiate_cnf

Description The 's7_get_await_initiate_cnf()' call receives the result of the

's7_await_initiate_req()' job .
With the 's7_receive()' call, the user program receives the confirmation
'S7_AWAIT_INITIATE_CNF' if the communications system was prepa-
red for a connection establishment. Following this, the corresponding
processing function 's7_get_initiate_cnf()' must be called for internal
processing in the library.

Declaration int32 s7_get_await_initiate_cnf(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

66
C79000-G8976-C077-07 S7 Programming Interface

3.4.5 s7_get_initiate_ind

Description The 's7_get_initiate_ind()' call receives a request to establish an S7

connection from the remote side.
With the 's7_receive()' call , the user program receives the
'S7_INITIATE_IND' indication if the remote partner wants to establish
an S7 connection. Following this, the corresponding processing functi-
on 's7_get_initiate_ind()' must be called for internal processing in the
library.
The 's7_get_initiate_ind()' call enters the capability parameters of the
S7 connection in the mini-DB. Following this, further events can be
received from the communication system (for example via other S7
connections). An acceptance or rejection of the establishment request
can be delayed with the 's7_initiate_rsp()' call.
By dividing the passive establishment into two parts the following is
possible:
➢ With a simple call structure, the capability parameters can be
checked before the connection is established and
➢ The establishment request can be passed on to a different appli-
cation that decides whether or not the connection is established
(the application has gateway functions).

Declaration int32 s7_get_initiate_ind(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

67
S7 Programming Interface C79000-G8976-C077-07

3.4.6 s7_initiate_rsp

Description Using the 's7_initiate_rsp()' call, the user program decides about a
passive establishment request.
The passive establishment of an S7 connection is in two parts as fol-
lows:
➢ With the 's7_get_initiate_ind()' call, the capability parameters are
entered in the mini-DB and can be read out. It is then possible to
receive further events from the communications system (for ex-
ample via other S7 connections).
➢ The establishment request is granted or rejected with the
's7_initiate_rsp()' call.

Declaration int32 s7_initiate_rsp(

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 accept /* In call */
)

Parameters cp_descr Descriptor of the CP with which the request to

establish an S7 connection was indicated.

cref Reference to the S7 connection that will be

established.

accept The establishment request can be accepted with

this parameter ('accept=S7_ACCEPT') or rejected
('accept= S7_NON_ACCEPT').

68
C79000-G8976-C077-07 S7 Programming Interface

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

69
S7 Programming Interface C79000-G8976-C077-07

3.4.7 s7_abort

Description With the 's7_abort()' call, an existing S7 connection is aborted without

confirmation and without any negotiation.
Fetching a response with 's7_receive()' is unnecessary since this is an
unacknowledged service. You should also bear in mind that acknow-
ledgments may still arrive later or may not be received at all.

Declaration int32 s7_abort(

ord32 cp_descr, /* In call */
ord16 cref /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection to be aborted.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

70
C79000-G8976-C077-07 S7 Programming Interface

3.4.8 s7_get_abort_ind

Description The 's7_get_abort_ind()' call receives the abort of an S7 connection by

a remote station or the CP.
With the 's7_receive()' call , the user program receives the
'S7_ABORT_IND' indication from the remote partner station or from
the subordinate communications processor that the S7 connection was
aborted. Following this, the corresponding processing function
's7_get_abort_ind()' must be called for internal processing in the
library.
In S7, aborting an S7 connection is an unacknowledged service. Jobs
that have not yet been acknowledged on this S7 connection will no
longer be confirmed.

Declaration int32 s7_get_abort_ind(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

71
S7 Programming Interface C79000-G8976-C077-07

3.5 Variable Services

Description of the To extend the example from Section 3.4, a job to read a variable cycli-
Example cally ('s7_cycl_read()') is sent on the established S7 connection. The
received data are copied to the user memory with the function
's7_get_cycl_read_ind()'. The cycle is completed with
's7_cycl_read_delete_req()'.

Symbolic Variable S7 variables are addressed symbolically. This type of access is orien-
Addressing ted on the notation of S7 tools. You do not need to learn different nota-
tions for variable addresses.

Examples:
DB5,X12.1 data block 5, data byte 12, data bit 1
DB5,B12 data block 5, data byte 12
DB5,W10 data block 5, data word 10
MB9,3 3 memory bytes starting at memory byte 9
DB5,W10,9 9 words in data block 5 starting at data word 10

Syntax:
The syntax is defined as follows (upper and lower case irrelevant):

DB<no>, <typ> <index> ,<number>

DI<no>, <index>.<bitnr>
<range>

mandatory optional mandatory optional

Parameter Description:

DB or DI data block or instance block

<no> number of the data block or instance block

72
C79000-G8976-C077-07 S7 Programming Interface

<range> Q output
C Counter - Detailed information on this
parameter can be found below in a se-
parate paragraph.
I input
M memory bit
PQ peripheral output
PI peripheral input
T Timer - Detailed information on this pa-
rameter can be found below in a sepa-
rate paragraph.
C Counter - Detailed information on this
parameter can be found below in a se-
parate paragraph.

<typ> B byte (unsigned)

BYTE byte (unsigned)
CHAR byte (signed)
D double word (unsigned)
DINT double word (signed)
DWORD double word (unsigned)
INT word (signed)
REAL floating point
W word (unsigned)
WORD word (unsigned)
X byte for area DB and DI.

<index> element number relative to start of block.

<bitno> bit within the element number.

<number> number of variables of one type, whose values are

addressed starting at <address> in the <area>.

73
S7 Programming Interface C79000-G8976-C077-07

Explanation of the The following table illustrates the meaning of the individual bits of the
Type 'T' of the result data of type 'T' of the 'area' parameter.
'Area' Parameter

Bit no. 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0

Meaning 0 0 x x t t t t t t t t t t t t

Symbol '0' not relevant

Symbol 'x' time resolution

The table below explains the meaning of the pos-
sible values of bits 13 and 12.

Bit 13 and 12 Time resolution in seconds

00 0,01
01 0,1
10 1
11 10

Symbol 't' BCD-coded time value (0 to 999)

Explanantions of The following table illustrates the meaning of the individual bits of the
the type 'C' or 'Z' of result data of type 'C' or 'Z' of the 'area' parameter.
the 'area'
parameter
Bit no. 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0

Meaning 0 0 0 0 t t t t t t t t t t t t

Symbol '0' not relevant

Symbol 't' BCD-coded counter value (0 to 999)

74
C79000-G8976-C077-07 S7 Programming Interface

Example

:
:
/* additional prototypings */
static void my_cycl_read(ord32 cp_descr,ord16 cref,ord16 orderid);
static void my_cycl_read_delete_req( ord32 cp_descr,
ord16 cref,
ord16 orderid);
static void my_get_cycl_read_delete_cnf(ord32 cp_descr);
static void my_get_cycl_read_ind(ord32 cp_descr);

/* start cyclic read */

static void my_cycl_read(ord32 cp_descr,ord16 cref,ord16 orderid);
{ struct S7_READ_PARA read_para;
int32 ret;

read_para.access=S7_ACCESS_SYMB_ADDRESS;
strcpy(read_para.var_name,“e0,10“);

ret=s7_cycl_read(cp_descr,cref,orderid,200,1,&read_para);
if(ret!=S7_OK)
{
my_exit( cp_descr,
"Error s7_cycl_read",
ret);
}
}

/* delete cyclic read */

static void my_cycl_read_delete_req( ord32,cp_descr,ord16 cref,
ord16 orderid)
{ int32 ret;

ret=s7_cycl_read_delete_req(cp_descr,cref,orderid);
if(ret!=S7_OK)
{
my_exit( cp_descr,
"Error s7_cycl_read",
ret);
}
}

/* get cyclic read delete confirmation */

static void my_get_cycl_read_delete_cnf(ord32 cp_descr)
{ int32 ret;

if((ret=s7_get_cycl_read_delete_cnf())!=S7_OK)
{
my_exit( cp_descr,
"Error s7_get_cycl_read_delete_cnf",
ret);
}
}

75
S7 Programming Interface C79000-G8976-C077-07

/* get cyclic read indication */

static void my_get_cycl_read_ind(ord32 cp_descr)
{ int32 ret;
ord16 var_length=10,result;
char data_buffer[10];
char *value_array[1];

value_array[0]=data_buffer;

if((ret=s7_get_cycl_read_ind(( void *)0,

&result,
&var_length,
(void *)value_array))!=S7_OK)
{
my_exit( cp_descr,
"Error s7_get_cycl_read_ind",
ret);
}
}

/* receive any message from communication system */

static void my_receive(ord32 cp_descr,int32 last_event_expected)
{ ord16 cref,orderid;
int32 ret;

do
{ ret=s7_receive(cp_descr,&cref,&orderid);
switch(ret)
{
:
:
case S7_INITIATE_CNF:
my_get_initiate_cnf(cp_descr);
my_cycl_read(cp_descr,cref,0);
break;
case S7_CYCL_READ_IND:
my_get_cycl_read_ind(cp_descr);
my_cycl_read_delete_req(
cp_descr,
cref,
orderid);
break;
case S7_CYCL_READ_DELETE_CNF:
my_get_cycl_read_delete_cnf(
cp_descr);
my_abort(cp_descr,cref);
break;
default:
printf( "Event unexpected",
ret);
break;
}
} while( (ret!=last_event_expected)&&
(ret!=S7_ABORT_IND));
}

76
C79000-G8976-C077-07 S7 Programming Interface

/* main */
void main(void)
{ ord32 cp_descr;
ord16 cref;

/* initialize s7 */
my_init(&cp_descr);

/* get reference for connection 'TEST' */

my_get_cref(cp_descr,&cref);

/* initiate connection */
my_initiate_req(cp_descr,cref);

/* receive cyclic read delete confirmation */

my_receive(cp_descr,S7_CYCL_READ_DELETE_CNF);

/* end communication */
my_shut(cp_descr);
}

77
S7 Programming Interface C79000-G8976-C077-07

Flowchart

User program SAPI-S7 Remote partner

Initiates cyclic reading of
an S7 variable
s7_cycl_read()

= S7_OK

s7_receive()

= S7_NO_MSG

Repeat several times Repeat several times

s7_receive()

= S7_CYCL_READ_IND
Message (indication) there!
Fetch indication
s7_get_cycl_read_ind

= S7_OK

Figure 3.6: Flowchart of the Example

78
C79000-G8976-C077-07 S7 Programming Interface

3.5.1 s7_read_req

Description With the 's7_read_req()' call, a client application can read a variable on
the server. The variables can only be accessed using their symbolic
addresses. The data are transferred to the client in the confirmation
from the server and entered in the user buffer by the corresponding
processing function ('s7_get_read_cnf()').

Declaration int32 s7_read_req(

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid, /* In call */
struct S7_READ_PARA *read_para_ptr
/* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection on which the job will

be sent.

orderid Job identifier to identify the job to be sent and the

corresponding confirmation.

read_para_ptr Pointer to a buffer provided by the user program for

the following structure:

struct S7_READ_PARA
{
ord16 access;
char var_name[S7_MAX_NAMLEN+2];
ord16 index;
ord16 subindex;
ord16 address_len;
ord8 address[S7_MAX_ADDRESSLEN];
}
The 'access' parameter indicates the type of access.
With 'S7_ACCESS_SYMB_ADDRESS', the symbolic
address in the 'var_name' field is expected.
The 'var_name' parameter specifies the symbolic
address of the variable to be read and is evaluated if
the variable is to be accessed by its symbolic ad-
dress ('access=S7_ACCESS_SYMB_ADDRESS').
(Please refer to the general information about varia-
ble addressing at the start of this section.)

The 'index' parameter is irrelevant and only im-

plemented for reasons of compatibility with other
SAPI interfaces.

79
S7 Programming Interface C79000-G8976-C077-07

The 'subindex' parameter is irrelevant and only

implemented for reasons of compatibility with
other SAPI interfaces.

The 'address_len' parameter is irrelevant and

only implemented for reasons of compatibility with
other SAPI interfaces.

The 'address' parameter is irrelevant and only

implemented for reasons of compatibility with
other SAPI interfaces.

Return Values
S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

Amounts of Data The maximum length of the result data depends on the negotiated
PDU size. For details of the PDU size, refer to Section 3.4.2,
's7_get_initiate_cnf', page 64 (formulas for calculating intermediate
values in Section 7.3, page 207).
The following table shows examples:

PDU Size (bytes) Maximum Length of the Result Data

(bytes)
240 222
256 238
480 462
960 942

80
C79000-G8976-C077-07 S7 Programming Interface

3.5.2 s7_get_read_cnf

Description The 's7_get_read_cnf()' call receives a variable value that has be read.
With the 's7_receive()' call, the user program receives the
'S7_READ_CNF' confirmation if the read job could be executed. Fol-
lowing this, the corresponding processing function 's7_get_read_cnf()'
must be called for internal processing in the library so that the values
can be copied to the user buffer.

Declaration int32 s7_get_read_cnf(

void *od_ptr, /* In call */
ord16 *var_length_ptr, /* Call and */
/* Returned */
void *value_ptr /* Returned */
)

Parameters od_ptr The 'od_ptr' parameter is implemented to ensure

compatibility with other SAPI interfaces and must be
assigned the NULL pointer, in other words, the va-
riable values are transferred on the SAPI-S7 pro-
gramming interface in the network representation.

var_length_ptr Address of a variable of the type 'ord16' provided by

the user program. Here, the length of the data buffer
is specified. After the call, the parameter contains the
length of the variable that was read.

value_ptr Pointer to a buffer provided by the user program.

Here, the variable content that was read is saved in
the network representation. When evaluating the
content of the buffer, the data type of the variable
must be taken into account.

It is also important to take into account that the

☞ variable values are saved byte aligned, in other
words without padding bytes between two com-
ponents.

81
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

82
C79000-G8976-C077-07 S7 Programming Interface

3.5.3 s7_write_req

Description With the 's7_write_req()' call, a client application can write to a variable
of a server. The variables can only be accessed using their symbolic
addresses. The data are transferred in the request from the client to
the server.

Declaration int32 s7_write_req(

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid, /* In call */
struct S7_WRITE_PARA *write_para_ptr
/* In call */
void *od_ptr /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection on which the job will

be sent.

orderid Job identifier to identify the job to be sent and the

corresponding confirmation.

write_para_ptr Pointer to a buffer provided by the user program for

the following structure:

struct S7_WRITE_PARA
{ ord16 access;
char var_name[S7_MAX_NAMLEN+2];
ord16 index;
ord16 subindex;
ord16 address_len;
ord8 address[S7_MAX_ADDRESSLEN];
ord16 var_length;
ord8 value[S7_MAX_BUFLEN];
}

The 'access' parameter indicates the type of access.

With 'S7_ACCESS_SYMB_ADDRESS', the symbolic
address in the 'var_name' field is expected.
The 'var_name' parameter specifies the symbolic
address of the variable to be written and is evaluated
if the variable is to be accessed by its symbolic ad-
dress ('access=S7_ACCESS_SYMB_ADDRESS').
(Please refer to the general information about varia-
ble addressing at the start of this section.)

83
S7 Programming Interface C79000-G8976-C077-07

The 'index' parameter is irrelevant and only imple-

mented for reasons of compatibility with other SAPI
interfaces.
The 'subindex' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address_len' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address' parameter is irrelevant and only im-
plemented for reasons of compatibility with other
SAPI interfaces.
The 'var_length' parameter specifies the number of
relevant and valid bytes in the data buffer 'value'.
The 'value' buffer contains the value of the variable
to be written in the network representation. When
evaluating the content of the buffer, the data type of
the variable must be taken into account.
It is also important to take into account that the
☞ variable values are saved byte aligned, in other
words without padding bytes between two com-
ponents.

od_ptr The 'od_ptr' parameter is implemented to ensure

compatibility with other SAPI interfaces and must be
assigned the NULL pointer, in other words, the va-
riable values are transferred on the SAPI-S7 pro-
gramming interface in the network representation.

84
C79000-G8976-C077-07 S7 Programming Interface

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

The maximum length of the user data depends on the negotiated PDU
size. For details of the PDU size, refer to Section 3.4.2,
's7_get_initiate_cnf', page 64 (formulas for calculating intermediate
Amounts of Data values in Section 7.3, page 207).
The following table shows examples:

PDU Size (bytes) Maximum Length of the User Data

240 212
256 228
480 256 *)
960 256 *)

*) Note
With the 's7_write_long_req' call, longer data are possible.

85
S7 Programming Interface C79000-G8976-C077-07

3.5.4 s7_write_long_req

Description With the 's7_write_long_req()' call, a client application can write to a

variable of a server. The variables can only be accessed using their
symbolic addresses. The data are transferred in the request from the
client to the server.

Declaration int32 s7_write_long_req

(
ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid, /* In call */
struct S7_WRITE_PARA_LONG *write_para_ptr
/* In call */
void *od_ptr /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection on which the job will

be sent.

orderid Job identifier to identify the job to be sent and the

corresponding confirmation.

write_para_ptr Pointer to a buffer provided by the user program for

the following structure:

struct S7_WRITE_PARA
{ ord16 access;
char var_name[S7_MAX_NAMLEN+2];
ord16 index;
ord16 subindex;
ord16 address_len;
ord8 address[S7_MAX_ADDRESSLEN];
ord16 var_length;
ord8 value[S7_MAX_BUFLEN_LONG];
}

The 'access' parameter indicates the type of access.

With 'S7_ACCESS_SYMB_ADDRESS', the symbolic
address in the 'var_name' field is expected.
The 'var_name' parameter specifies the symbolic
address of the variable to be written and is evaluated
if the variable is to be accessed by its symbolic ad-
dress ('access=S7_ACCESS_SYMB_ADDRESS').
(Please refer to the general information about varia-
ble addressing at the start of this section.)

86
C79000-G8976-C077-07 S7 Programming Interface

The 'index' parameter is irrelevant and only imple-

mented for reasons of compatibility with other SAPI
interfaces.
The 'subindex' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address_len' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address' parameter is irrelevant and only im-
plemented for reasons of compatibility with other
SAPI interfaces.
The 'var_length' parameter specifies the number of
relevant and valid bytes in the data buffer 'value'.
The 'value' buffer contains the value of the variable
to be written in the network representation. When
evaluating the content of the buffer, the data type of
the variable must be taken into account.
It is also important to take into account that the
☞ variable values are saved byte aligned, in other
words without padding bytes between two com-
ponents.

od_ptr The 'od_ptr' parameter is implemented to ensure

compatibility with other SAPI interfaces and must be
assigned the NULL pointer, in other words, the va-
riable values are transferred on the SAPI-S7 pro-
gramming interface in the network representation.

87
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

The maximum length of the user data depends on the negotiated PDU
size. For details of the PDU size, refer to Section 3.4.2,
's7_get_initiate_cnf', page 64 (formulas for calculating intermediate
Amounts of Data values in Section 7.3, page 207).
The following table shows examples:

PDU Size (bytes) Maximum Length of the User Data

240 212
256 228
480 452
960 932

88
C79000-G8976-C077-07 S7 Programming Interface

3.5.5 s7_get_write_cnf

Description The 's7_get_write_cnf()' call receives the result of the write variable
job.
With the 's7_receive()' call, the user program receives the
'S7_WRITE_CNF' confirmation if the write job was executed. Following
this, the corresponding processing function 's7_get_write_cnf()' must
be called for internal processing in the library.

Declaration int32 s7_get_write_cnf(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

89
S7 Programming Interface C79000-G8976-C077-07

3.5.6 s7_multiple_read_req

Description With the 's7_multiple_read_req()' call, a client application can read one
or more variables on the server at the same time. The variables can
only be accessed using their symbolic addresses. The data are trans-
ferred in the confirmation from the server to the client and transferred
to the user buffer by the corresponding processing function
('s7_get_multiple_read_cnf()').

Declaration int32 s7_multiple_read_req(

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid, /* In call */
ord16 number, /* In call */
struct S7_READ_PARA *read_para_array
/* In call */
)

90
C79000-G8976-C077-07 S7 Programming Interface

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection via which the job will

be sent.

orderid Job identifier to identify the job to be sent and the

corresponding confirmation.

number Number of variables to be read.

read_para_array Pointer to an array provided by the user program with

a total of 'number' elements of the following structu-
re, where the nth element describes the nth variable:

struct S7_READ_PARA
{ ord16 access;
char var_name[S7_MAX_NAMLEN+2];
ord16 index;
ord16 subindex;
ord16 address_len;
ord8 address[S7_MAX_ADDRESSLEN];
}

The 'access' parameter indicates the type of access.

With 'S7_ACCESS_SYMB_ADDRESS', the symbolic
address in the 'var_name' field is expected.
The 'var_name' parameter specifies the symbolic
address of the variable to be read and is evaluated if
the variable is to be accessed by its symbolic ad-
dress ('access=S7_ACCESS_SYMB_ADDRESS').
(Please refer to the general information about varia-
ble addressing at the start of this section.)
The 'index' parameter is irrelevant and only imple-
mented for reasons of compatibility with other SAPI
interfaces.
The 'subindex' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address_len' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address' parameter is irrelevant and only im-
plemented for reasons of compatibility with other
SAPI interfaces.

91
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

Amounts of Data The maximum length of the variable addresses and result data de-
pends on the negotiated PDU size. For details of the PDU size, refer to
Section 3.4.2, 's7_get_initiate_cnf', page 64 (formulas for calculating
intermediate values in Section 7.3, page 207).
The following table shows examples:

PDU Size Maximum Number Maximum Length of the

(bytes) of Variable Result Data with the
Addresses Maximum Number of
Variable Addresses
240 19 150
256 20 162
480 39 310
960 79 630

92
C79000-G8976-C077-07 S7 Programming Interface

3.5.7 s7_get_multiple_read_cnf

Description The 's7_get_multiple_read_cnf()' call receives the variable values that

have been read.
With the 's7_receive()' call, the user program receives the
'S7_MULTIPLE_READ_CNF' confirmation if the read job was execu-
ted. Following this, the corresponding processing function
's7_get_multiple_read_cnf()' must be called for internal processing in
the library. The call copies the values that were read into the user buf-
fer.

Declaration int32 s7_get_multiple_read_cnf(

void *od_ptr, /* In call */
ord16 *result_array, /* Returned */
ord16 *var_length_array,
/* Call and */
/* Returned */
void *value_array /* Returned */
)

Parameters od_ptr The 'od_ptr' parameter is implemented to ensure

compatibility with other SAPI interfaces and must be
assigned the NULL pointer, in other words, the va-
riable values are transferred on the SAPI-S7 pro-
gramming interface in the network representation.

result_array Address of an array of the type 'ord16' provided by

the user program. The array must contain at least as
many elements as variables that were read. The ar-
ray elements contain the results of the read job in the
order in which the variables were specified in the re-
quest. The following results are possible:

S7_RESULT_OK
This value indicates that the access was possible and
no error occurred.

S7_RESULT_HW_ERROR
A hardware problem occurred.

S7_RESULT_OBJ_ACCESS_DENIED
Access to a variable was denied.

S7_RESULT_OBJ_ADDRESS_INVALID
The specified address is invalid.

93
S7 Programming Interface C79000-G8976-C077-07

S7_RESULT_OBJ_TYPE_NOT_SUPPORTED
The server does not support the data type.

S7_RESULT_OBJ_TYPE_INCONSISTENT
The data type of the variable is not consistent.

S7_RESULT_OBJ_NOT_EXISTS
The variable does not exist.

var_length_array Address of an array of the type 'ord16' provided by

the user program. The array must contain at least as
many elements as variables that were read. The in-
dividual array elements contain the length of the data
buffer. After the call, the elements of this array con-
tain the lengths of the variables that were read. The
value '0' means that the corresponding variable could
not be read.

value_array Pointer to buffers provided by the user program. The

variable values that were read are entered in the
buffers. Once again the order is the same as speci-
fied in the request. When evaluating the buffer con-
tents, the data type must be taken into account.
It is also important to take into account that the
☞ variable values are saved byte aligned, in other
words without padding bytes between two com-
ponents.

94
C79000-G8976-C077-07 S7 Programming Interface

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

95
S7 Programming Interface C79000-G8976-C077-07

3.5.8 s7_multiple_write_req

Description With the 's7_multiple_write_req()' call, a client application can write to

one or more variables of a server at the same time. The variables can
only be accessed using their symbolic addresses. The data are trans-
ferred in the request from the client to the server.

Declaration int32 s7_multiple_write_req(

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid, /* In call */
ord16 number, /* In call */
struct S7_MULTIPLE_WRITE_PARA
*write_para_array, /* In call */
void *od_ptr /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection via which the job will

be sent.

orderid Job identifier to identify the job to be sent and the

corresponding confirmation.

number Number of variables to be written.

write_para_array Pointer to an array provided by the user program with

a total of 'number' elements of the following structu-
re, where the nth element describes the nth variable:

struct S7_WRITE_PARA
{
ord16 access;
char var_name[S7_MAX_NAMLEN+2];
ord16 index;
ord16 subindex;
ord16 address_len;
ord8 address[S7_MAX_ADDRESSLEN];
ord16 var_length;
ord8 value[S7_MAX_BUFLEN_MULTIPLE];
}

The 'access' parameter indicates the type of access.

With 'S7_ACCESS_SYMB_ADDRESS', the symbolic
address in the 'var_name' field is expected.

96
C79000-G8976-C077-07 S7 Programming Interface

The 'var_name' parameter specifies the symbolic

address of the variable to be read and is evaluated if
the variable is to be accessed by its symbolic ad-
dress ('access=S7_ACCESS_SYMB_ADDRESS').
(Please refer to the general information about varia-
ble addressing at the start of this section.)
The 'index' parameter is irrelevant and only imple-
mented for reasons of compatibility with other SAPI
interfaces.
The 'subindex' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address_len' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address' parameter is irrelevant and only im-
plemented for reasons of compatibility with other
SAPI interfaces.
The 'var_length' parameter specifies the number of
relevant and valid bytes in the data buffer 'value'.
The 'value' buffer contains the value of the variable
to be written in the network representation. When
evaluating the content of the buffer, the data type of
the variable must be taken into account.
It is also important to take into account that the
☞ variable values are saved byte aligned, in other
words without padding bytes between two com-
ponents.

od_ptr The 'od_ptr' parameter is implemented to ensure

compatibility with other SAPI interfaces and must be
assigned the NULL pointer; in other words, the va-
riable values are transferred on the SAPI-S7 pro-
gramming interface in the network representation.

97
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

Amounts of Data The maximum number of variable addresses and maximum length of
the user data depends on the negotiated PDU size. For details of the
PDU size, refer to Section 3.4.2, 's7_get_initiate_cnf', page 64
(formulas for calculating intermediate values in Section 7.3, page 208).
The following table shows examples:

PDU Size Maximum Number Maximum Length of the User

(bytes) of Variable Data with the Maximum
Addresses Number of Variable Addresses
240 12 36
256 13 36
480 26 52
960 52 116

98
C79000-G8976-C077-07 S7 Programming Interface

3.5.9 s7_get_multiple_write_cnf

Description The 's7_get_multiple_write_cnf()' call receives the result of the write

variable job.
With the 's7_receive()' call, the user program receives the
'S7_MULTIPLE_WRITE_CNF' confirmation if the write job was
executed. Following this, the corresponding processing function
's7_get_multiple_write_cnf()' must be called for internal processing in
the library.

Declaration int32 s7_get_multiple_write_cnf(

ord16 *result_array /* Returned */
)

Parameters result_array Address of an array of the type 'ord16' provided by

the user program. The array must contain at least as
many elements as variables that were read. The ar-
ray elements contain the results of the read job in the
order in which the variables were specified in the re-
quest. The following results are possible:

S7_RESULT_OK
This value indicates that the access was possible and
no error occurred.

S7_RESULT_HW_ERROR
A hardware problem occurred.

S7_RESULT_OBJ_ACCESS_DENIED
Access to a variable was denied.

S7_RESULT_OBJ_ADDRESS_INVALID
The specified address is invalid.

S7_RESULT_OBJ_TYPE_NOT_SUPPORTED
The server does not support the data type.

S7_RESULT_OBJ_TYPE_INCONSISTENT
The data type of the variable is not consistent.

S7_RESULT_OBJ_NOT_EXISTS
The variable does not exist.

99
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

100
C79000-G8976-C077-07 S7 Programming Interface

3.5.10 s7_cycl_read_init_req

Description With this request, an S7 application instructs the server to prepare for
cyclic reading of variables. The request contains the cycle time, the
number of variables and the variables to be read.

Declaration int32 s7_cycl_read_init_req(

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid, /* In call */
ord16 cycl_time, /* In call */
ord16 number, /* In call */
struct S7_READ_PARA *read_para_array
/* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call

cref Reference of the S7 connection via which the job will

be sent. The variable values are transferred on this
connection.

orderid Job identifier to identify the job to be sent and the

corresponding confirmation. This job identifier must
be used for further jobs such as start
('s7_cycl_read_start_req()'), stop
('s7_cycl_read_stop_req()') and delete
('s7_cycl_read_delete_req()') the cyclic reading.

cycl_time Cycle time as a multiple of 10ths of seconds. SAPI-

S7 rounds down to a permitted value
(1, 2 to 9 and 10, 20 to 90 and 100, 200 to 900.

number Number of variables whose values will be read cycli-

cally.

101
S7 Programming Interface C79000-G8976-C077-07

read_para_array Pointer to an array provided by the user program with

a total of 'number' elements of the following structu-
re, where the nth element describes the nth variable:
struct S7_READ_PARA
{ ord16 access;
char var_name[S7_MAX_NAMLEN+2];
ord16 index;
ord16 subindex;
ord16 address_len;
ord8 address[S7_MAX_ADDRESSLEN];
}

The 'access' parameter indicates the type of access.

With 'S7_ACCESS_SYMB_ADDRESS', the symbolic
address in the 'var_name' field is expected.
The 'var_name' parameter specifies the symbolic
address of the variable to be read and is evaluated if
the variable is to be accessed by its symbolic ad-
dress ('access=S7_ACCESS_SYMB_ADDRESS').
(Please refer to the general information about varia-
ble addressing at the start of this section.)
The 'index' parameter is irrelevant and only imple-
mented for reasons of compatibility with other SAPI
interfaces.
The 'subindex' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address_len' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address' parameter is irrelevant and only im-
plemented for reasons of compatibility with other
SAPI interfaces.

102
C79000-G8976-C077-07 S7 Programming Interface

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

Amounts of Data The maximum length of the variable addresses and result data de-
pends on the negotiated PDU size. For details of the PDU size, refer to
Section 3.4.2, 's7_get_initiate_cnf', page 64 (formulas for calculating
intermediate values in Section 7.3, page 208).
The following table shows examples:

PDU Maximum Number Maximum Length of the Result

Size of Variable Data with the Maximum Number
(bytes) Addresses of Variable Addresses
240 17 144
256 19 152
480 37 304
960 77 624

103
S7 Programming Interface C79000-G8976-C077-07

3.5.11 s7_get_cycl_read_init_cnf

Description The 's7_get_cycl_read_init_cnf()' call receives the result of a

's7_cycl_read_init_req()' job .
With the 's7_receive()' call, the user program receives the
'S7_CYCL_READ_INIT_CNF' confirmation if the remote partner
executed the job to prepare for cyclic reading of a variable. Following
this, the corresponding processing function
's7_get_cycl_read_init_cnf()' must be called for internal processing in
the library.

Declaration int32 s7_get_cycl_read_init_cnf(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

104
C79000-G8976-C077-07 S7 Programming Interface

3.5.12 s7_cycl_read_start_req

Description With this request, an S7 application instructs the server to start cyclic
reading of variables. The server must already have been prepared with
the 's7_cycl_read_init_req()' call.

Declaration int32 s7_cycl_read_start_req(

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call. This

parameter must match the corresponding parame-
ter of the 's7_cycl_read_init_req()' call.

cref Reference of the S7 connection via which the job

will be sent. This parameter must match the cor-
responding parameter of the
's7_cycl_read_init_req()' call.

orderid Job identifier to identify the job to be sent and the

corresponding confirmation. This parameter must
match the corresponding parameter of the
's7_cycl_read_init_req()' call.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

105
S7 Programming Interface C79000-G8976-C077-07

3.5.13 s7_get_cycl_read_start_cnf

Description The 's7_get_cycl_read_start_cnf()' call receives the result of a

's7_cycl_read_start_req()' job .
With the 's7_receive()' call, the user program receives the
'S7_CYCL_READ_START_CNF' confirmation if the remote partner
executed the job to start cyclic reading of the variable. Following this,
the corresponding processing function 's7_get_cycl_read_start_cnf()'
must be called for internal processing in the library.

Declaration int32 s7_get_cycl_read_start_cnf(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

106
C79000-G8976-C077-07 S7 Programming Interface

3.5.14 s7_get_cycl_read_ind

Description The 's7_get_cycl_read_ind()' call receives the data sent by the server.
With the 's7_receive()' call, the user program receives the
'S7_CYCL_READ_IND' indication if a remote partner read a variable
cyclically. Following this, the corresponding processing function
's7_get_cycl_read_ind()' is called to copy the values that were read into
the user buffer.

Declaration int32 s7_get_cycl_read_ind(

void *od_ptr, /* In call */
ord16 *result_array, /* Returned */
ord16 *var_length_array,
/* Call and */
/* Returned */
void *value_array /* Returned */
)

Parameters od_ptr The 'od_ptr' parameter is implemented to ensure

compatibility with other SAPI interfaces and must be
assigned the NULL pointer, in other words, the va-
riable values are transferred on the SAPI-S7 pro-
gramming interface in the network representation.
result_array Address of an array of the type 'ord16' provided by
the user program. The array must contain at least as
many elements as variables that were read. The ar-
ray elements contain the results of the read job in the
order in which the variables were specified in the re-
quest. The following results are possible:

S7_RESULT_OK
This value indicates that the access was possible and
no error occurred.

S7_RESULT_HW_ERROR
A hardware problem occurred.

S7_RESULT_OBJ_ACCESS_DENIED
Access to a variable was denied.

S7_RESULT_OBJ_ADDRESS_INVALID
The specified address is invalid.

107
S7 Programming Interface C79000-G8976-C077-07

S7_RESULT_OBJ_TYPE_NOT_SUPPORTED
The server does not support the data type.

S7_RESULT_OBJ_TYPE_INCONSISTENT
The data type of the variable is not consistent.
S7_RESULT_OBJ_NOT_EXISTS
The variable does not exist.

var_length_array Address of an array of the type 'ord16' provided by

the user program. The array must contain at least
as many elements as variables that were read.
The individual array elements contain the length
of the data buffer. After the call, the elements of
this array contain the lengths of the variables that
were read. The value '0' means that the corre-
sponding variable could not be read.

value_array Pointer to buffers provided by the user program.

The variable values that were read are entered in
the buffers. Once again the order is the same as
specified in the request. When evaluating the
buffer contents, the data type must be taken into
account.

☞ It is also important to take into account that

the variable values are saved byte aligned, in
other words without padding bytes between
two components.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

108
C79000-G8976-C077-07 S7 Programming Interface

3.5.15 s7_get_cycl_read_abort_ind

Description The 's7_get_cycl_read_abort_ind()' receives a cyclic read abort indica-

tion.
With the 's7_receive()' call, the user program receives the
'S7_CYCL_READ_ABORT_IND' indication if the cyclic reading of the
variable was aborted. Following this, the corresponding processing
function 's7_get_cycl_read_delete_cnf()' must be called for internal
processing in the library.
Using the functions describes in the previous sections, cyclic reading of
variables can be initiated again.

Declaration int32 s7_get_cycl_read_abort_ind(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

109
S7 Programming Interface C79000-G8976-C077-07

3.5.16 s7_cycl_read_stop_req

Description With this request, an S7 application instructs the server to stop cyclic
reading of variables. The server must already have been requested to
read variables cyclically.

Declaration int32 s7_cycl_read_stop_req(

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call. This

parameter must match the corresponding parame-
ter of the 's7_cycl_read_init_req()'- or
's7_cycl_read()' call .

cref Reference of the S7 connection via which the job

will be sent. This parameter must match the cor-
responding parameter of the
's7_cycl_read_init_req()'- or 's7_cycl_read()' call .

orderid Job identifier to identify the job to be sent and the

corresponding confirmation. This parameter must
match the corresponding parameter of the
's7_cycl_read_init_req()'- or 's7_cycl_read()' call .

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

110
C79000-G8976-C077-07 S7 Programming Interface

3.5.17 s7_get_cycl_read_stop_cnf

Description The 's7_get_cycl_read_stop_cnf()' call receives the result of a

's7_cycl_read_stop_req()' call.
With the 's7_receive()' call, the user program receives the
'S7_CYCL_READ_STOP_CNF' confirmation if the remote partner
executed the job to stop cyclic reading of variables. Following this, the
corresponding processing function 's7_get_cycl_read_stop_cnf()' must
be called for internal processing in the library.

Declaration int32 s7_get_cycl_read_stop_cnf(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

111
S7 Programming Interface C79000-G8976-C077-07

3.5.18 s7_cycl_read_delete_req

Description This function stops cyclic reading and logs off at the server.

Declaration int32 s7_cycl_read_delete_req(

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call. This

parameter must match the corresponding parame-
ter of the 's7_cycl_read_init_req()'- or
's7_cycl_read()' call .

cref Reference of the S7 connection via which the job

will be sent. This parameter must match the cor-
responding parameter of the
's7_cycl_read_init_req()'- or 's7_cycl_read()' call .

orderid Job identifier to identify the job to be sent and the

corresponding confirmation. This parameter must
match the corresponding parameter of the
's7_cycl_read_init_req()'- or 's7_cycl_read()' call .

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

112
C79000-G8976-C077-07 S7 Programming Interface

3.5.19 s7_get_cycl_read_delete_cnf

Description The 's7_get_cycl_read_delete_cnf()' call receives the result of a

's7_cycl_read_delete_req()' job.
With the 's7_receive()' call, the user program receives the
'S7_CYCL_READ_DELETE_CNF' confirmation if the remote partner
executed the job to delete cyclic reading of variables. Following this,
the corresponding processing function 's7_get_cycl_read_delete_cnf()'
must be called for internal processing in the library.

Declaration int32 s7_get_cycl_read_delete_cnf(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

113
S7 Programming Interface C79000-G8976-C077-07

3.5.20 s7_cycl_read

Description With this job, an S7 application instructs the server to read variables
cyclically. This job includes the sequence consisting of the calls
's7_cycl_read_init_req()' (logon at server) and
's7_cycl_read_start_req()' (start reading variables). The cycle time, the
number of variables and the variables to be read are specified.
Important: in S7, this is an unacknowledged service (in contrast to the
individual jobs that make up this call).

Declaration int32 s7_cycl_read(

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid, /* In call */
ord16 cycl_time, /* In call */
ord16 number, /* In call */
struct S7_READ_PARA *read_para_array
/* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call

cref Reference of the S7 connection via which the job will

be sent. The variable values are transferred on this
connection.

orderid Job identifier to identify the job to be sent and the

corresponding confirmation. This job identifier must
be used for further jobs such as stop
('s7_cycl_read_stop_req()'), start
('s7_cycl_read_start_req()') and delete
('s7_cycl_read_delete_req()') cyclic reading.

cycl_time Cycle time as a multiple of 10ths of seconds. SAPI-

S7 rounds down to a permitted value 1, 2 to 9 and
10, 20 to 90 and 100, 200 to 900.
number Number of variables whose values will be read cycli-
cally.

114
C79000-G8976-C077-07 S7 Programming Interface

read_para_array Pointer to an array provided by the user program with

a total of 'number' elements of the following structu-
re, where the nth element describes the nth variable:

struct S7_READ_PARA
{ ord16 access;
char var_name[S7_MAX_NAMLEN+2];
ord16 index;
ord16 subindex;
ord16 address_len;
ord8 address[S7_MAX_ADDRESSLEN];
}

The 'access' parameter indicates the type of access.

With 'S7_ACCESS_SYMB_ADDRESS', the symbolic
address in the 'var_name' field is expected.
The 'var_name' parameter specifies the symbolic
address of the variable to be read and is evaluated if
the variable is to be accessed by its symbolic ad-
dress ('access=S7_ACCESS_SYMB_ADDRESS').
(Please refer to the general information about varia-
ble addressing at the start of this section.)
The 'index' parameter is irrelevant and only imple-
mented for reasons of compatibility with other SAPI
interfaces.
The 'subindex' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address_len' parameter is irrelevant and only
implemented for reasons of compatibility with other
SAPI interfaces.
The 'address' parameter is irrelevant and only im-
plemented for reasons of compatibility with other
SAPI interfaces.

115
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

116
C79000-G8976-C077-07 S7 Programming Interface

3.6 Block-Oriented Services

Description Block-oriented services are available to the application programmer

both on the programming device/PC and on the SIMATIC S7 PLC.
These services have the following advantages:
➢ Transfer of larger amounts of data
➢ The transfer can be triggered by SIMATIC S7 PLCs.

Restrictions The block-oriented services are not available under MS-DOS and
Windows 3.x.

Standard Functi- The blocks BSEND and BRCV are available on the SIMATIC S7 PLC.
ons This functionality takes the form of 'block-oriented services' on the
programming device/PC.

Data Exchange A connection must be configured to allow data exchange between two
communication partners. With the block-oriented services, the block
pair BSEND and BRCV belong together. The connection must be con-
figured at both ends (COML S7 and STEP 7 NETPRO).
From the SIMATIC NET CD, November 99 onwards, configuration with
COML S7 is no longer necessary. The configuration file for the PC is
created by STEP 7; see Installation Instructions of your product.
In contrast to the non block-oriented services, the configured connecti-
on created with STEP 7 NETPRO must be downloaded to the PLC.
Several pairs of blocks can exchange data via one connection.
When configuring the connections, follow the instructions in the rele-
vant product information bulletins.

Amount of Data With this type of data transfer, up to 65534 bytes can be transferred
regardless of the size of the CPU. The data is segmented automatically
by the functions.

Address Parameter The address parameter R_ID is fixed for a block pair (BSEND/ BRCV)
and defined uniquely within a connection. This means that several
BSEND blocks can transmit via one connection with each using a diffe-
rent R_ID. The same R_IDs can be used for other connections.

117
S7 Programming Interface C79000-G8976-C077-07

Grouping of the The following table divides the block-oriented services into two groups:
Functions
➢ The 'bsend' group
➢ The 'brcv' group

Block-Oriented Services Functions

bsend s7_bsend_req()
s7_get_bsend_cnf()
brcv s7_brcv_init()
s7_get_brcv_ind()
s7_brcv_stop()

The following sections describe the functions listed above.

118
C79000-G8976-C077-07 S7 Programming Interface

Example of 'bsend'

void main(int argc,char **argv)

{ ord32 cp_descr;
ord16 cref;
ord16 orderid;
ord32 r_id=1;
int32 ret;
char send_buffer[100];
ord16 err_no;
const char *err_msg_ptr;
...
Connection established
...

/* first BSEND request*/

ret = s7_bsend_req( cp_descr,cref,orderid,r_id,
(void*)send_buffer,sizeof(send_buffer));
printf( "s7_bsend_req =0x%x, r_id = 0x%x, len = %d Byte\n",
ret, r_id, sizeof(send_buffer));
while (ret == S7_NO_MSG )
{
ret = s7_receive(cp_descr,&cref,&orderid);
printf( "s7_receive = 0x%x\n", ret);
switch(ret)
{

/* BSEND confirmation */
case S7_BSEND_CNF:
{
ret = s7_get_bsend_cnf();
printf("s7_get_bsend_cnf = 0x%x\n",ret );
if(ret == S7_OK)
{

/* next BSEND request */

ret = s7_bsend_req( cp_descr,cref,orderid,
r_id,
(void*)send_buffer,
sizeof(send_buffer));
printf( "s7_bsend_req =0x%x,
r_id = 0x%x,
len = %d Byte\n",ret,r_id,
sizeof(send_buffer));
}
break;
}
default:
{
...
break;
}
}
}

/* end communication */
my_shut(cp_descr);
}

119
S7 Programming Interface C79000-G8976-C077-07

Flowchart for
'bsend'

User program SAPI-S7 Remote partner

s7_bsend_req()

= S7_OK

s7_receive()

= S7_NO_MSG

Repeat several times Repeat several times

s7_receive()

= S7_BSEND_CNF

s7_get_bsend_cnf

= S7_OK

Figure 3.7: Flowchart for 'bsend'

120
C79000-G8976-C077-07 S7 Programming Interface

Example of 'brcv'

void main(int argc,char **argv)

{ ord32 cp_descr;
ord16 cref;
ord16 orderid;
ord32 r_id=1;
int32 ret;
ord32 ret_id;
ord16 ret_len;
char receive_buffer[65540];
ord16 err_no;
const char *err_msg_ptr;
...
Connection established
...

/* BRCV initialize */
ret = s7_brcv_init( cp_descr,cref,r_id);
printf("s7_brcv_init =0x%x, r_id = 0x%x\n",ret, r_id;
while (ret == S7_NO_MSG )
{
ret = s7_receive(cp_descr,&cref,&orderid);
printf( "s7_receive = 0x%x\n", ret);
switch(ret)
{

/* BRCV indication */
case S7_BRCV_IND:
{
ret = s7_get_brcv_ind(
receive_buffer,
(ord32)sizeof(receive_buffer),
&ret_id,&ret_len);
printf( "s7_get_brcv_ind = 0x%x, r_id = 0x%x,
rec_len = %d Byte\n",ret, ret_id,
ret_len);
break;
}
default:
{
...
break;
}
}
}

/* BRCV stop */
ret = s7_brcv_stop( cp_descr,cref,r_id);
printf("s7_brcv_stop = 0x%x",ret);

/* end communication */
my_shut(cp_descr);
}

121
S7 Programming Interface C79000-G8976-C077-07

Flowchart for 'brcv'

User program SAPI-S7 Remote partner

s7_brcv_init()

= S7_OK

s7_receive()

= S7_NO_MSG

Repeat several times Repeat several times

s7_receive()

= S7_BRCV_IND
Receive all net data from
Partner (BSEND)!

s7_get_brcv_ind

= S7_OK

s7_brcv_stop
Stop brcv explicitly
= S7_OK

Figure 3.8: Flowchart for 'brcv'

122
C79000-G8976-C077-07 S7 Programming Interface

3.6.1 s7_bsend_req

Description With the s7_bsend_req call, a client application can send up to 65534
bytes of data to a remote station.

Declaration int32 s7_bsend_req (

ord32 cp_descr, /* In call
*/
ord16 cref, /* In call
*/
ord16 orderid, /* In call
*/
ord32 r_id, /* In call
*/
void *buffer_ptr, /* In call
*/
ord32 buffer_len /* In call
*/
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection on which the job

will be sent.

orderid Job identifier to identify the job to be sent and

the corresponding confirmation.

r_id Data are only sent to the partner on this con-

nection without problems when the address pa-
rameter r_id is unique for the connection and
matches the remote R_ID of the BRCV .
Range of values (hexadecimal): 0 to FFFF FFFF

*buffer_ptr Pointer to the address area to be sent.

buffer_len Explicitly specified length of the net data in

bytes;
Range of values (hexadecimal): 1 to FFFE

123
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred

executing the requested service. This is a
temporary problem such as a brief memory
shortage. The call can be repeated without
modifying the transferred parameters.

S7_ERR This value also indicates an error in the

execution of the requested service. In this case,
however, the error does not allow the service to
be repeated. Here, steps must be taken to
eliminate the error such as assigning new para-
meters for the call.

124
C79000-G8976-C077-07 S7 Programming Interface

3.6.2 s7_get_bsend_cnf

Description The s7_get_bsend_cnf receives the result of the BSEND job.

With the s7_receive call, the user program receives the
S7_BSEND_CNF confirmation when the send job has been executed.
Following this, the corresponding processing function
's7_get_bsend_cnf()' must be called for internal processing in the
library.

Declaration int32 s7_get_bsend_cnf (void)

None
Parameters

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

125
S7 Programming Interface C79000-G8976-C077-07

3.6.3 s7_brcv_init

Description With this call, the application logs on to receive BSEND jobs from the
connection partner. Each BSEND job with a specific R_ID of the con-
nection partner must correspond to exactly one s7_brcv_init with the
same R_ID.

Declaration int32 s7_brcv_init

(
ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord32 r_id /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection on which the job

will be sent.

r_id Data are only received from the partner on this

connection, when the address parameter r_id is
unique for the connection and matches the re-
mote R_ID in BSEND.

The content of the r_id parameter of your

☞ application and the content of the r_id para-
meter of the program of the connection part-
ner must be the same!
You can only receive BSEND data when the
r_id parameters of both partners are the sa-
me.

126
C79000-G8976-C077-07 S7 Programming Interface

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred

executing the requested service. This is a tem-
porary problem such as a brief memory shorta-
ge. The call can be repeated without modifying
the transferred parameters.

S7_ERR This value also indicates an error in the executi-

on of the requested service. In this case, howe-
ver, the error does not allow the service to be
repeated. Here, steps must be taken to eliminate
the error such as assigning new parameters for
the call.

127
S7 Programming Interface C79000-G8976-C077-07

3.6.4 s7_get_brcv_ind

Description With the s7_get_brcv_ind call, the net data sent by the partner are
copied to the specified memory area.

Declaration int32 s7_get_brcv_ind

(
void *buffer_ptr, /* In call */
ord32 buffer_len, /* In call */
ord32 *r_id_ptr, /* Return */
ord32 *rec_buffer_len_ptr /* Return */
)

Parameters *buffer_ptr The pointer points to the destination address

where the received data will be entered.

buffer_len Maximum length of the receive buffer

(buffer_ptr); when the received data length is
greater than the buffer length specified here,
S7_ERR is returned. In this case, the required
buffer size is specified in the rec_buffer_len pa-
rameter and the "detailed error" is set to
S7_ERR_INVALID_DATARANGE_OR_TYPE.

*r_id_ptr *r_id_ptr points to a variable of the type ord32

that contains the R_ID of the received BSEND
job after the function is called.

rec_buffer_len_ptr The entire received data length when the return

value is S7_OK or the required buffer size when
the receive buffer is too small and the return
value is S7_ERR.

S7_OK The function was processed without errors.

128
C79000-G8976-C077-07 S7 Programming Interface

Return Values S7_ERR_RETRY This value indicates that an error occurred

executing the requested service. This is a tem-
porary problem such as a brief memory shorta-
ge. The call can be repeated without modifying
the transferred parameters.

S7_ERR This value also indicates an error in the executi-

on of the requested service. In this case, howe-
ver, the error does not allow the service to be
repeated. Here, steps must be taken to eliminate
the error such as assigning new parameters for
the call.

129
S7 Programming Interface C79000-G8976-C077-07

3.6.5 s7_brcv_stop

Description With this call, the application logs off at the connection partner.

Declaration int32 s7_brcv_stop (

ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord32 r_id /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection on which the job

will be sent.

r_id The R_ID specified with the corresponding

brcv_init.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred

executing the requested service. This is a tem-
porary problem such as a brief memory shorta-
ge. The call can be repeated without modifying
the transferred parameters.

S7_ERR This value also indicates an error in the executi-

on of the requested service. In this case, howe-
ver, the error does not allow the service to be
repeated. Here, steps must be taken to eliminate
the error such as assigning new parameters for
the call.

130
C79000-G8976-C077-07 S7 Programming Interface

3.7 Message Services

Description Using the message service, the application programmer can receive
messages from a SIMATIC S7 programmable controller.
These services have the following advantages:
➢ Transfer of monitored data only when changed!
➢ Any associated values can be added to the transferred data.

Restrictions The message services are not available under MS-DOS and Win-
dows 3...

Standard Functi- In SAPI S7, the following two types of message are processed:
ons
➢ configured messages (SCAN)
➢ programmed messages (ALARM, ALARM_8, ALARM_8P,
NOTIFY)

Configured With configured messages, data on the SIMATIC S7 programmable

Messages (SCAN) controller are checked by its operating system at fixed intervals
(100 ms, 500 ms, or 16 ms), to see whether they have changed com-
pared with the last check.
If a change is detected, they are sent by the SIMATIC S7 programma-
ble controller to the registered PC/PG. Here, they are written to a buf-
fer provided by the user.
A message is configured in the 'Symbol Editor' of STEP 7 by assigning
the special object property 'message' to a variable ('address').
The assignment of symbolic names of the monitored variables to the
message number is displayed in the 'Message Configuration' dialog
box. (The message configuration, of course, only becomes active after
it has been downloaded to the PLC.)

Programmed Mes- To use programmed messages, the user must include an S7 block
sages (ALARM) (ALARM, ALARM_8, ALARM_8P, NOTIFY) in the S7 user program.
This block queries signals every cycle to check whether or not they
have changed and then immediately sends a frame with the event
state of the signals, time of day and associated values. Messages can
also be received from PCS 7 blocks with message capability, for ex-
ample technological functions.

131
S7 Programming Interface C79000-G8976-C077-07

Logon Before messages can be sent by the SIMATIC S7 PLC, a

PC/programming device must log on with the required SIMATIC S7
programmable controller. The function 's7_msg_initiate_req' can be
used for both types of message.
You can log on either for all SCAN or all ALARM, ALARM_8,
ALARM_8P or NOTIFY messages for specific connections.

132
C79000-G8976-C077-07 S7 Programming Interface

Flowchart for
'scan'

User program SAPI-S7 Remote partner

ogon
s7_msg_initiate_req()
Logon for SCAN
=S7_OK

s7_receive() + acknowledge

=S7_MSG_INITIATE_CNF

s7_get_msg_initiate_cnf()

Receive messages
s7_receive()
SCAN_to_all
=S7_NO_MSG Acyclic frames

Repeat several times

Repeat several times

s7_receive()

=S7_SCAN_IND
Receive messages from
partner!
s7_get_scan_ind()

=S7_OK

Logoff

s7_msg_abort_req()
Logoff for SCAN
=S7_OK

s7_receive() + acknowledge

=S7_MSG_ABORT_CNF

s7_get_msg_abort_cnf()

Figure 3.9: Flowchart for 'SCAN'

133
S7 Programming Interface C79000-G8976-C077-07

Flow diagram for

'alarm'
User program SAPI-S7 Remote partner
Logon
s7_msg_initiate_req()
Logon for
=S7_OK ALARM_8P

s7_receive() + Acknowledge

=S7_MSG_INITIATE_CNF

s7_get_msg_initiate_cnf()

Receive messages

s7_receive()
ALARM_8P frames
=S7_NO_MSG acyclic

Repeat several times

Repeat several times

s7_receive()

=S7_ALARM_IND
Receive messages from
partner!
s7_get_alarm_ind()

=S7_OK

Logoff

s7_msg_abort_req() Logoff for

ALARM_8
=S7_OK

s7_receive() + Acknowledge

=S7_MSG_ABORT_CNF

s7_get_msg_abort_cnf()

Figure 3.10: Flow diagram 'alarm'

134
C79000-G8976-C077-07 S7 Programming Interface

3.7.1 s7_msg_initiate_req

Description With this call, a client application logs on at a SIMATIC S7 pro-

grammable controller for one of the services SCAN or ALARM. The
result of the initiate request is received with the
s7_get_msg_initiate_cnf function.

Declaration int32 s7_msg_initiate_req(

ord32 cp_descr, /* In call
*/
ord16 cref, /* In call
*/
ord16 orderid, /* In call
*/
ord16 fct_code /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection on which the job

will be sent.

orderid Job identifier to identify the job to be sent and

the corresponding confirmation.

fct_code Function code to log on for

S7_SCAN_ALL_INITIATE or
S7_ALARM_ALL_INITIATE; other codes are
ignored.

Return Values S7_OK The function was processed without errors.

S7_ERR This value indicates that an error occurred

executing the requested service. Here, steps
must be taken to eliminate the error such as
assigning new parameters for the call.

S7_ERR_RETRY This value indicates that an error occurred

executing the requested service. This is a
temporary problem such as a brief memory
shortage. The call can be repeated without
modifying the transferred parameters.

135
S7 Programming Interface C79000-G8976-C077-07

3.7.2 s7_get_msg_initiate_cnf

Description With the 's7_receive' call, the user program receives the confirmation
S7_MSG_INITIATE_CNF when the logon is completed. The function
's7_get_msg_initiate_cnf' described here must then be called to obtain
the result of an ALARM or SCAN logon.

Declaration int32 s7_get_msg_initiate_cnf(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR This value indicates that an error occurred execu-

ting the requested service. Here, steps must be
taken to eliminate the error such as assigning new
parameters for the call.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

136
C79000-G8976-C077-07 S7 Programming Interface

3.7.3 s7_msg_abort_req

Description With this call, the application logs off for receiving message services.

Declaration int32 s7_msg_abort_req

(
ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid, /* In call */
ord16 fct_code /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection on which the job

will be sent.

orderid Job identifier to identify the job to be sent and

the corresponding confirmation.

fct_code function code for logging off for

S7_SCAN_ALL_ABORT or
S7_ALARM_ALL_ABORT.

Return Values S7_OK The function was processed without errors.

S7_ERR This value indicates that an error occurred

executing the requested service. Here, steps
must be taken to eliminate the error such as as-
signing new parameters for the call.

S7_ERR_RETRY This value indicates that an error occurred

executing the requested service. This is a tem-
porary problem such as a brief memory shorta-
ge. The call can be repeated without modifying
the transferred parameters.

137
S7 Programming Interface C79000-G8976-C077-07

3.7.4 s7_get_msg_abort_cnf

Description With the 's7_receive' call, the user program receives the confirmation
S7_MSG_ABORT_CNF when the logoff is completed. The function
's7_get_msg_abort_cnf' described here must then be called to obtain
the result of an ALARM or SCAN logoff.

Declaration int32 s7_get_msg_abort_cnf(void)

Parameters None

Return Values S7_OK The function was processed without errors.

S7_ERR This value indicates that an error occurred

executing the requested service. Here, steps
must be taken to eliminate the error such as as-
signing new parameters for the call.

S7_ERR_RETRY This value indicates that an error occurred

executing the requested service. This is a tem-
porary problem such as a brief memory shorta-
ge. The call can be repeated without modifying
the transferred parameters.

138
C79000-G8976-C077-07 S7 Programming Interface

3.7.5 s7_get_scan_ind

Description The 's7_get_scan_ind' call copies the net data sent by the SIMATIC S7
programmable controller to the specified memory areas. When a mes-
sage is sent by the remote partner, the user program receives the indi-
cation 'S7_SCAN_IND' using the 's7_receive()' call.
Acknowledgment of SCAN messages is not currently possible with
SAPI-S7.

Declaration int32 s7_get_scan_ind

(
void *od_ptr, /* In call */
ord16 *no_scan_objects_ptr, /* Returned */
struct S7_TIME_STAMP *time_stamp_ptr,
/* Returned */
struct S7_SCAN_OBJECT *scan_objects_array
/* Returned */
)

Parameters od_ptr This parameter is intended for later extensions

and must be assigned NULL at present.

no_scan_objects_ptr Address of the data value with the number of

received SCAN objects.

time_stamp_ptr Address of a buffer of a structure for the time

stamp of the event provided by the user pro-
gram. Detailed information on this parameter
can be found below in a separate paragraph.

scan_objects_array Address of an array of SCAN object structures

provided by the user program. Detailed informa-
tion on this parameter can be found below in a
separate paragraph.

139
S7 Programming Interface C79000-G8976-C077-07

Explanation of the Address of a buffer of a structure for the time stamp of the event pro-
'time_stamp_ptr' vided by the user program; the time from the SIMATIC S7 pro-
Parameter grammable controller is used.

struct S7_TIME_STAMP
{
ord16 year;
ord16 month;
ord16 day;
ord16 week_day;
ord16 hour;
ord16 minute;
ord16 second;
ord16 millisecond;
}

year The parameter specifies the year (1950 to 2049);

Example: 1999 is represented as 1999.
month This parameter specifies the month;
Example: March is represented as 3.
day This parameter specifies the day;
Example: The 30th day of the month is represen-
ted as 30.
week_day This parameter specifies the weekday.
The following table shows the assignment of the
parameter value to the weekday.

Parameter Value Weekday

1 Sunday
2 Monday
etc. to etc. to
7 Saturday

hour This parameter specifies the hour; the range is

from 0 to 23.
minute This parameter specifies the minutes; the range
is from 0 to 59.
second This parameter specifies the seconds; the range
is from 0 to 59.
millisecond This parameter specifies the milliseconds; the
range is from 0 to 999.

140
C79000-G8976-C077-07 S7 Programming Interface

Explanation of the Address of a buffer of an array provided by the user program with the
'scan_objects_ number of S7_MAX_SCAN_OBJECT elements. The number of rele-
array' Parameter vant elements is returned in the 'no_scan_objects_ptr' parameter.

struct S7_SCAN_OBJECT
{
ord16 state;
ord16 ack_state;
ord16 event_state;
ord32 event_id;
ord16 no_add_value;
struct
{
ord16 data_type;
ord16 add_value_len;
ord8 value
[S7_MAX_SCAN_ADD_VALUE_LEN+2];
} add_value[S7_MAX_ADD_VALUES];
}

state Indicates the general status whether or not the

message exists:
Parameter Value Description
S7_SCAN_MSG_EXIST OK
S7_SCAN_NO_MSG Message does not exist
)*

)* The object monitored with Scan does not

exist on the S7 CPU, for example, data block
with the data to be monitored was deleted.

ack_state Acknowledgment state of the Scan object:

Bit Description
0 Acknowledgment entered state
1 to 7 irrelevant
8 Acknowledgment left state
9 to 15 irrelevant

☞ SAPI-S7 does not yet acknowledge messa-

ges. It may be possible to acknowledge mes-
sages using other systems.

141
S7 Programming Interface C79000-G8976-C077-07

event_state
Bit Description
0 Current state of the event
1 to 15 irrelevant

event_id Normalized message number

no_add_value Number of associated values.

add_value Array of associated values - The associated
value is stored in the array 'value' with a length
of 'S7_MAX_SCAN_ADD_VALUE_LEN+2'.
The number of relevant bytes in this array de-
pends on the data type of the associated value
configured on the SIMATIC S7 programmable
controller. It is specified in the 'add_value_len'
parameter.

data_type Data type of the associated value:

Parameter Value Description
S7_DATATYPE_ERROR ERROR
S7_DATATYPE_BOOLEAN BOOLEAN
S7_DATATYPE_BITSTRING BITSTRING -
Note: Length
specified in
bytes instead
of bits!
S7_DATATYPE_INTEGER INTEGER
S7_DATATYPE_OCTET_STRING STRING

add_value_len Number of relevant bytes of the associated va-

lue.

value Transferred associated value

Return Values S7_OK The function was processed without errors.

S7_ERR This value also indicates an error in the executi-

on of the requested service. In this case, howe-
ver, the error does not allow the service to be
repeated. Here, steps must be taken to eliminate
the error such as assigning new parameters for
the call.

142
C79000-G8976-C077-07 S7 Programming Interface

S7_ERR_RETRY This value indicates that an error occurred

executing the requested service. This is a tem-
porary problem such as a brief memory shorta-
ge. The call can be repeated without modifying
the transferred parameters.

143
S7 Programming Interface C79000-G8976-C077-07

Example of calling
the
's7_get_scan_ind'
function

void my_get_scan_ind(void)
{
int32 iRet; /* Return Value */
struct S7_SCAN_OBJECT
scan_objects[NO_SCAN_OBJ_PER_TG];
/* SCAN Objects, depends on TPDU size */
ord16 no_scan_objects = 0;
/* returns number of SCAN objects received */
/* NO_SCAN_OBJ_PER_TG depends on TPDU size */
struct S7_TIME_STAMP time_stamp; /* Time stamp */
int i,j,l,len; /* loop variables */
char TempBuffer[1024]; /* Buffer for output string */
char *TempBufferPtr;

/* SAPI-S7 call to get the SCAN data */

iRet = s7_get_scan_ind
(
NULL, /* IN: od_ptr */
&no_scan_objects, /* OUT: Number of SCAN objects */
&time_stamp, /* OUT: Time stamp */
(struct S7_SCAN_OBJECT*) &scan_objects
); /* OUT: SCAN objects */

MYPRINTF("s7_get_scan_ind = %04x",iRet);

/* ERROR? */
if(iRet != S7_OK)
my_error_handler();
else
{
MYPRINTF(" Number of received scan objects : %d ",
no_scan_objects);
/* loop over all scan objects received */
for (i = 0; i < no_scan_objects ; i++ )
{
/* general info of scan object */
MYPRINTF(" %d. Scan object ",i );
MYPRINTF(" Ack state = %04x",scan_objects[i].ack_state);
MYPRINTF
(" event state = %04x",
scan_objects[i].event_state);
MYPRINTF(" event id = %04x",scan_objects[i].event_id);

MYPRINTF("Number of associated values = %d",

scan_objects[i].no_add_value);

/* loop over all associated values */

for ( j= 0; j < scan_objects[i].no_add_value;j++ )
{
/* prepare string buffer for associated value */
TempBufferPtr = TempBuffer;
TempBufferPtr += sprintf(TempBuffer,
" %d. associated value = ",j );

144
C79000-G8976-C077-07 S7 Programming Interface

/* Length of associated value */

len = scan_objects[i].add_value[j].add_value_len;

for (l = 0; l < len ; l++ )

{
/* displaying associated value
as byte array */
TempBufferPtr += sprintf(TempBufferPtr,
" %02x",
scan_objects[i].add_value[j].value[l]);
}
/* Output the whole string */
MYPRINTF("%s",TempBuffer );
}

} /* End of my_get_scan_ind */

145
S7 Programming Interface C79000-G8976-C077-07

3.7.6 s7_get_alarm_ind

Description The 's7_get_alarm_ind' call copies the net data sent by the
SIMATIC S7 programmable controller to the specified memory areas.
When an alarm is sent by the remote partner, the user program recei-
ves the indication 'S7_ALARM_IND' using the 's7_receive()' call.
Acknowledgment of alarms is not currently possible with SAPI-S7.

Declaration int32 s7_get_alarm_ind

(
void *od_ptr, /* In call */
ord16 *state_ptr, /* Returned */
ord16 *ack_state_ptr, /* Returned */
ord16 *event_state_ptr, /* Returned */
ord32 *event_id_ptr, /* Returned */
struct S7_TIME_STAMP *time_stamp_ptr,
/* Returned */
ord16 *no_add_value_ptr, /* Returned */
struct S7_ADD_VALUE *add_value_ptr,
/* Returned */
)

Parameters od_ptr This parameter is intended for later extensions

and must be assigned NULL at present.

state_ptr Pointer to the status - The status specifies the

general status:
Bit Description
0 Init startup
1 Overflow signal
2 Overflow instance
3 to 5 reserved
6 Associated value cannot be
entered (size)
7 Associated value not obtainable

146
C79000-G8976-C077-07 S7 Programming Interface

ack_state_ptr Pointer to the acknowledgment state of the

alarm object:
Bit Description
0 to 7 Acknowledgment entered
state
8 to 15 Acknowledgment left state

☞ SAPI-S7 does not yet acknowledge messa-

ges. It may be possible to acknowledge mes-
sages using other systems.

event_state_ptr Pointer to the event state of the 8 signals:

Signal Bit Description
1 0 Current state of the event
2 1 Current state of the event
etc. to etc. to etc. to
8 7 Current state of the event

event_id_ptr Pointer to the normalized message number.

time_stamp_ptr Pointer to the address of the structure for the

time stamp alarm message. Detailed information
on this parameter can be found below in a sepa-
rate paragraph.

no_add_value_ptr Pointer to an element describing the number of

received associated values.

add_value_ptr Pointer to an array of associated values; Detai-

led information on this parameter can be found
below in a separate paragraph.

147
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR This value indicates that an error occurred

executing the requested service. Here, steps
must be taken to eliminate the error such as as-
signing new parameters for the call.

S7_ERR_RETRY This value indicates that an error occurred

executing the requested service. This is a tem-
porary problem such as a brief memory shorta-
ge. The call can be repeated without modifying
the transferred parameters.

148
C79000-G8976-C077-07 S7 Programming Interface

Explanation of the Address of a buffer of a structure for the time stamp of the event pro-
'time_stamp_ptr' vided by the user program.
Parameter
struct S7_TIME_STAMP
{
ord16 year;
ord16 month;
ord16 day;
ord16 week_day;
ord16 hour;
ord16 minute;
ord16 second;
ord16 millisecond;
}

year The parameter specifies the year (1950 to 2049);

Example: 1999 is represented as 1999.

month This parameter specifies the month;

Example: March is represented as 3.

day This parameter specifies the day;

Example: The 30th day of the month is represen-
ted as 30.

week_day This parameter specifies the weekday.

The following table shows the assignment of the
parameter value to the weekday.

Parameter Value Weekday

1 Sunday
2 Monday
etc. to etc. to
7 Saturday

hour This parameter specifies the hour; the range is

from 0 to 23.

minute This parameter specifies the minutes; the range

is from 0 to 59.

second This parameter specifies the seconds; the range

is from 0 to 59.

millisecond This parameter specifies the milliseconds; the

range is from 0 to 999.

149
S7 Programming Interface C79000-G8976-C077-07

Explanation of the Pointer to an array of associated values with the following structure.
'add_value_ptr'
Allocate memory for the number of elements specified in the
Parameter 'S7_MAX_ADD_VALUE' constant.
The associated value is stored in the array 'value' with a length of
'S7_MAX_ALARM_ADD_VALUE_LEN+2'. The number of relevant
bytes in this array depends on the data type of the associated value
configured on the SIMATIC S7 programmable controller. It is specified
in the 'add_value_len' parameter.

struct S7_ADD_VALUE
{
ord16 data_type;
ord16 add_value_len;
ord8 value
[S7_MAX_ALARM_ADD_VALUE_LEN+2];
} add_value[S7_MAX_ADD_VALUES];

data_type This parameter specifies the data type of the

associated value:
Parameter Value Description
S7_DATATYPE_ERROR ERROR
S7_DATATYPE_BOOLEAN BOOLEAN
S7_DATATYPE_BITSTRING BITSTRING -
Note: Length
specified in
bytes instead
of bits!
S7_DATATYPE_INTEGER INTEGER
S7_DATATYPE_OCTET_STRING STRING
S7_DATATYPE_FLOAT Floating-point
number
S7_DATATYPE_DATE Number of
days since
1.1.1990
S7_DATATYPE_TIME_OF_DAY Milliseconds
since the day
began
S7_DATATYPE_TIME Duration in
milliseconds
S7_DATATYPE_S5_TIME S5 time format

add_value_len Number of relevant bytes of the associated va-

lue.

value Transferred associated value

150
C79000-G8976-C077-07 S7 Programming Interface

Example of calling
the
's7_get_alarm_ind'
function

void my_get_alarm_ind(void)
{

int32 iRet; /* Return Value */

struct S7_ADD_VALUE
add_value[S7_MAX_ADD_VALUES]; /* Add value objects */
ord16 no_add_value = 0; /* returns number of SCAN objects
received */
ord16 state = 0; /* state of alarm object */
ord16 ack_state = 0; /* acknowledge state */
ord16 event_state = 0; /* event state */
ord32 event_id; /* event id */
struct S7_TIME_STAMP time_stamp; /* time stamp */
int j,l,len; /* loop variables */
char TempBuffer[1024]; /* Buffer for output string */
char *TempBufferPtr;

iRet = s7_get_alarm_ind
(
NULL, /* IN: od_ptr */
&state, /* OUT: Status */
&ack_state, /* OUT: acknowledge state */
&event_state,
&event_id, /* OUT: event id */
&time_stamp, /* OUT: time stamp */
&no_add_value, /* OUT: number of associated values */
add_value /* OUT: start address of associated values */
);
/* ERROR? */
if(iRet != S7_OK)
my_error_handler();
else
{
/* general info of alarm */
MYPRINTF(" Ack state = %04x",ack_state);
MYPRINTF(" event state = %04x",event_state);
MYPRINTF(" event id = %04x",event_id);

MYPRINTF("Number of associated values = %d",no_add_value);

/* loop over all associated values */

for ( j= 0; j < no_add_value;j++ )
{
/* prepare string buffer for associated value */
TempBufferPtr = TempBuffer;
TempBufferPtr += sprintf(TempBuffer,
" %d. associated value = ",j );

/* Length of associated value */

len = add_value[j].add_value_len;

151
S7 Programming Interface C79000-G8976-C077-07

for (l = 0; l < len ; l++ )

{
/* displaying associated value as byte array */
TempBufferPtr += sprintf
(
TempBufferPtr," %02x",add_value[j].value[l]
);
}
/* Output the whole string */
MYPRINTF("%s",TempBuffer );
}
}
}

152
C79000-G8976-C077-07 S7 Programming Interface

3.8 VFD Services

Description of the To extend the example from Section 3.5, after stopping the cyclic rea-
Example ding of variables, the status of the remote VFD is queried. The status
provides information about whether or not the remote communication
partner is ready for operation.

Example

:
:
/* additional prototypings */
static void my_get_vfd_state_cnf(ord32 cp_descr);
static void my_vfd_state_req(ord32 cp_descr,ord16 cref);

/* get vfd state confirmation */

static void my_get_vfd_state_cnf(ord32 cp_descr)
{ ord16 log_state,phy_state;
ord8 local_detail[3];
int32 ret;

ret=s7_get_vfd_state_cnf( &log_state,
&phy_state,
local_detail);
if(ret!=S7_OK)
{
my_exit( cp_descr,
"Error s7_get_vfd_state_cnf",
ret);
}
}

/* send vfd state request */

static void my_vfd_state_req(ord32 cp_descr,ord16 cref)
{ int32 ret;

ret=s7_vfd_state_req(
cp_descr, /* cp_descr */
cref,0 /* cref,orderid */);
if(ret!=S7_OK)
{
my_exit( cp_descr,
"Error s7_vfd_state_req",
ret);
}
}

153
S7 Programming Interface C79000-G8976-C077-07

/* receive any message from communication system */

static void my_receive(ord32 cp_descr,int32 last_event_expected)
{ ord16 cref,orderid;
int32 ret;

do
{ ret=s7_receive(cp_descr,&cref,&orderid);
switch(ret)
{
:
:
case S7_CYCL_READ_DELETE_CNF:
my_get_cycl_read_delete_cnf(
cp_descr);
my_vfd_state_req(cp_descr,cref);
break;
case S7_VFD_STATE_CNF:
my_get_vfd_state_cnf(cp_descr);
my_abort(cp_descr,cref);
break;
default:
printf( "Event unexpected",
ret);
break;
}
} while( (ret!=last_event_expected)&&
(ret!=S7_ABORT_IND));
}

/* main */
void main(void)
{ ord32 cp_descr;
ord16 cref;

/* initialize s7 */
my_init(&cp_descr);

/* get reference for connection 'TEST' */

my_get_cref(cp_descr,&cref);

/* initiate connection */
my_initiate_req(cp_descr,cref);

/* receive vfd state confirmation */

my_receive(cp_descr,S7_VFD_STATE_CNF);

/* end communication */
my_shut(cp_descr);
}

154
C79000-G8976-C077-07 S7 Programming Interface

Flowchart

User program SAPI-S7 Remote partner

Request the reading of the
status of a remote VFD
s7_vfd_state_req()

= S7_OK

s7_receive()

= S7_NO_MSG

Repeat several times Repeat several times

s7_receive()

= S7_VFD_STATE_CNF
Message (confirmation) there!

Fetch confirmation
s7_get_vfd_state_cnf

= S7_OK

Figure 3.11: Flowchart of the Example

155
S7 Programming Interface C79000-G8976-C077-07

3.8.1 s7_vfd_state_req

Description With the 's7_vfd_state_req()' call, a client application can read the
logical and physical status of another (remote) virtual field device
(VFD).

Declaration int32 s7_vfd_state_req

(
ord32 cp_descr, /* In call */
ord16 cref, /* In call */
ord16 orderid /* In call */
)

Parameters cp_descr Handle as return value of the 's7_init()' call.

cref Reference of the S7 connection on which the job

will be sent.

orderid Job identifier to identify the job to be sent and the

corresponding confirmation.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

156
C79000-G8976-C077-07 S7 Programming Interface

3.8.2 s7_get_vfd_state_cnf

Description The 's7_get_vfd_state_cnf()' call receives the result of a VFD status

job.
With the 's7_receive()' call, the user program receives the
'S7_VFD_STATE_CNF' confirmation if the status job was executed.
Following this, the corresponding processing function
's7_get_vfd_state_cnf()' must be called for internal processing in the
library.
With the 's7_get_vfd_state_cnf()' call, the values that were read (the
physical and logical status of the VFD and the local status of the appli-
cation) are copied to the user buffer.

Declaration int32 s7_get_vfd_state_cnf

(
ord16 *log_state_ptr, /* Returned */
ord16 *phy_state_ptr, /* Returned */
ord8 *local_detail_ptr /* Returned */
)

Parameters log_state_ptr Address of a variable of the type 'ord16' provided

by the user program. The logical status of the VFD
is entered here. This parameter specifies which
services can currently be used.
'S7_STATE_CHANGES_ALLOWED' is the only
possible state meaning that all services are per-
mitted.

phy_state_ptr Address of a variable of the type 'ord16' provided

by the user program. The physical status of the
VFD is entered here. The value of this parameter
is derived from the states of the resources. If
'S7_OPERATIONAL' is set, the VFD is completely
functional. In the status
'S7_NEEDS_COMMISSIONING' local intervention
is necessary to change to an operable status.

local_detail_ptr Pointer to a buffer provided by the user program

that must have a minimum size of 3 bytes. The
local status of the application and device are ente-
red here. The meaning of the 3 bytes depends on
the particular VFD and can be found in the
description of the VFD.

157
S7 Programming Interface C79000-G8976-C077-07

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

158
C79000-G8976-C077-07 S7 Programming Interface

3.9 Diagnostic Services for Fault-Tolerant Connections

Description In conjunction with fault-tolerant SIMATIC S7 systems, it is possible to

establish fault-tolerant SAPI-S7 connections. These consist of more
than one redundant connections that lead to a fault-tolerant SIMATIC
S7 system via different routes. These fault-tolerant connections remain
established even when one of the redundant connections is no longer
functioning. The switchover is automatic.
If a further redundant connection fails, this can lead to termination of
the fault-tolerant connection.
With the diagnostic services, you can display the status of a fault-
tolerant connection and check the problem (partial or total failure). The
diagnostic services report every status change on a fault-tolerant con-
nection and indicate whether or not all redundant connections (routes)
are functioning
The diagnostic service also provide status information about standard
connections.

Restrictions The diagnostic functions are only available with the S7-REDCONNECT
product.
The diagnostic services can only be used on connections that were
configured with STEP 7 to a station of the type SIMATIC PC station.

159
S7 Programming Interface C79000-G8976-C077-07

Flowchart The logon function 's7_diag_init()' starts the diagnostic services. If

there is diagnostic information available, the application receives a
Windows message.
This triggers the 's7_receive()' function that returns 'S7_DIAG_IND'.
The return parameter must be evaluated by the user program before it
can accept the diagnostic information with the 's7_get_diag_ind()' read
function. This provides all the required information (for example the
status of the configured connections, which routes are being used,
which have failed etc.) in a data area that must be made available by
the user.
The 's7_diag_stop()' function stops the diagnostic services and relea-
ses the used resources.

User program SAPI-S7 Remote partner

Log on for diagnostics

s7_diag_init()

= S7_OK

Windows message

Windows message

s7_receive()
Diagnostic info is there

= S7_DIAG_IND

Fetch diagnostic info

s7_get_diag_ind()

= S7_OK

Log off for diagnostics

s7_diag_stop()

= S7_OK

Figure 3.12: Flowchart

160
C79000-G8976-C077-07 S7 Programming Interface

3.9.1 s7_diag_init

Description Logon for diagnostic messages.

All connections with the same cp_descr are monitored for changes. If
the status of one or more of these connections changes, a Windows
message defined by s7_set_window_handle_msg is generated. The
application must then call s7_receive to determine which event has
occurred.

Declaration int s7_diag_init

(
ord32 cp_descr, /* In call */
)

Parameters cp_descr The cp_descr returned at 's7_init()'. The diagnostic

data refer to all connections established with the
cp_descr obtained through 's7_init()'.

Return Values S7_OK The function was processed without errors.

S7_ERR Indicates an error requiring further steps before it can

be eliminated.

161
S7 Programming Interface C79000-G8976-C077-07

3.9.2 s7_get_diag_ind

Description Read the diagnostic information, when a message was received with
s7_receive. This function displays relevant diagnostic information only
for the required VFD (in STEP 7 known as the "application“) and
transfers it to a data area made available for this purpose.

Declaration int s7_get_diag_ind

(
ord16 number, /* In call */
CONN_INFO *info_ptr /* Returned */
)

Parameters number Number of configured connections, as can be ob-

tained, for example, with 's7_get_conn()'.

*info_ptr pointer to an array of structures of the type

CONN_INFO. In the array, the user must provide the
number of elements transferred in the 'number' pa-
rameter.

Return Values S7_OK The function was processed without errors.

S7_ERR Indicates an error requiring further steps before it can

be eliminated.

Detailed ErrMsg S7_ERR_INVALID_DATA_SIZE

Data buffer for diagnostic information too small.

162
C79000-G8976-C077-07 S7 Programming Interface

Structure of the typedef struct

CONN_INFO {
Structure ord16 cref; /* connection ID */
ord8 conn_type; /* connection type*/
ord8 conn_state; /* connection state*/
ord8 way state [S7_MAX_WEGE];
/* way state */
} CONN_INFO

Element of Possible values Explanation

the
CONN_INFO
Structure
cref Reference (handle) of the connecti-
on as already returned by
's7_get_cref()'.
conn_type Connection type
S7D_STD_TYPE Standard connection
S7D_H_TYPE fault-tolerant connection
conn_state Connection state (standard connection)
S7_DIAG_STD_DOWN Connection terminated deliberately
S7_DIAG_STD_ABORT Connection terminated due to pro-
blem
S7_DIAG_STD_NOT_USED Connection was never established
S7_DIAG_STD_OK Connection established
Connection state (fault-tolerant connection)
Ideally, a fault-tolerant connection consists of a productive connection on
which data exchange is handled and a standby connection that acts as the
reserve if the productive connection fails. This is known as redundancy.
S7_DIAG_H_OK_RED Connection established (redundant)
S7_DIAG_H_OK_RED_PATH_CHG Connection established (redundant
switchover was made)
S7_DIAG_H_OK_NOT_RED Connection not established with
redundancy
S7_DIAG_H_ABORT Connection terminated due to pro-
S7_DIAG_H_NOT_USED blem
S7_DIAG_H_DOWN Connection was never established
Connection terminated deliberately
way_state Status of the connection paths
S7_DIAG_HW_PROD Path is productive connection
S7_DIAG_HW_STBY Path is standby connection
S7_DIAG_HW_ABORT Path was terminated due to problem
S7_DIAG_HW_NOT_USED Path was never established
S7_DIAG_HW_DOWN Path was terminated deliberately
S7_DIAG_HW_CN_BREAK Path could not be established

163
S7 Programming Interface C79000-G8976-C077-07

3.9.3 s7_diag_stop

Description Logoff for Diagnostic Messages.

Declaration int s7_diag_stop

(
Ord32 cp_descr /* In call */
)

Parameters cp_descr The cp_descr returned at 's7_diag_init '.

Return Values S7_OK The function was processed without errors.

S7_ERR Indicates an error requiring further steps before it can

be eliminated.

164
C79000-G8976-C077-07 S7 Programming Interface

4 Trace and Mini-DB

In this chapter, you will learn how to use the trace and to call the mini-DB. You will le-
arn the following:
➢ How to enable entries in the library’s own trace.
➢ How to check or modify settings in the mini-DB.
➢ How to obtain information about the last error that occurred.

When you have worked through this chapter, you will be in a position to
➢ Use all the functions provided by S7 for your application while retaining a simple
SAPI-S7 programming interface.
➢ Recognize and eliminate errors using your application.

165
S7 Programming Interface C79000-G8976-C077-07

4.1 s7_trace

Description With this call, the user can make entries in the trace of the S7 library.
This makes it possible to save important data for analysis, to check the
program sequence or to synchronize with the trace entries.

Declaration void s7_trace

(
char *msg /* In call */
)

Parameters msg String with the user message to be entered in the

trace. A trace line can contain up to 78 characters of
which, however, 14 characters are reserved for the
time since the trace was initialized and the line num-
ber. This leaves a net data length of 64 characters
per trace call. Longer strings are truncated.

Return Values None

166
C79000-G8976-C077-07 S7 Programming Interface

4.2 s7_write_trace_buffer

Description With high-performance applications, writing the trace to a file is ineffi-

cient. Nevertheless, entries should be available in the trace, for examp-
le if errors occur. For this reason, it is possible to configure the trace
using the mini-DB so that all the trace entries are made in an internal
ring buffer. The total information can then be written to a file with the
's7_write_trace_buffer()' function and is therefore available for error
analysis and evaluation.

Declaration void s7_write_trace_buffer

(
char *filename /* In call */
)

Parameters filename Name of the file to which the internal ring buffer will
be written.

Return Values None

167
S7 Programming Interface C79000-G8976-C077-07

4.3 s7_mini_db_set

Description With this call, settings in the mini-DB are overwritten to be able to ad-
apt the establishment of an S7 connection, the trace and querying er-
rors in a wide range of differing situations. There is a limited number of
combinations of data and values as described below.

Declaration int32 s7_mini_db_set

(
ord16 type, /* In call */
char *value /* In call */
)

Parameters
type Identifier for the setting to be modified. The pos-
sible transfer values are described below.

value New value for the setting to be modified. The va-

lue is always transferred as a string. Defines are
available for this in the header file 'SAPI_S7.H'
that correspond to the numbers as ASCII cha-
racter strings. If you require combinations of indi-
vidual values, you must first convert the individual
defines into integers or perform logic operations
on them and then reconvert the result to a string.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

168
C79000-G8976-C077-07 S7 Programming Interface

Combinations of The trace is a simple and yet effective aid to debugging for the S7
Values for the library. It can be adapted to an extremely wide range of applications.
Trace The permitted combinations of values are described below starting with
the 'type' parameter.
With SAPI-S7 libraries from Version V 1.371.2002 onwards, it is pos-
sible to distribute the trace output among several files. This prevents
the trace file growing too large. The number and size of the files can be
set with the parameters S7_MINI_DB_TRACE_MAXFILES and S7_
MINI_DB _TRACE_MAXLINES.

S7_MINI_DB_TRACE_FILENAME
This parameter value specifies the name of the trace file. The file na-
me is transferred as 'value' (default: '[Link]' in the current
working directory).

S7_MINI_DB_TRACE_TARGET
This value specifies the target for the trace.

Parameter 'value' Description

S7_TRACE_TARGET_BUFFER The trace entries are written to
an internal ring buffer (default
setting).
S7_TRACE_TARGET_OLD_FILE The trace entries are written to
a file. Any trace file that already
exists remains unmodified.
Trace entries that follow are
appended to the trace file.
S7_TRACE_TARGET_NEW_FILE The trace entries are written to
a file. A new file is created.
Subsequent trace entries are
appended. It is possible with
this setting to avoid the trace
file becoming far too large.
S7_TRACE_TARGET_CONSOLE The trace entries are passed on
to another application. What
then takes place depends on
the operating system.

169
S7 Programming Interface C79000-G8976-C077-07

S7_ MINI_DB_TRACE_MAXFILES
The trace is a cyclic buffer with a number of files specified in the
S7_MINI_DB_TRACE_MAXFILES parameter. Once a file has reached
the maximum length, a new file is created. When all files have re-
ached the maximum length, the oldest is overwritten.
Values between 1 and 999 can be set. The default value is 2.

S7_MINI_DB_TRACE_MAXLINES
This sets the size of the S7_Trace files.
2
Values between 1 and 2 -1 can be set. The size should be adapted to
the available memory.
The default value is 10.000.

S7_MINI_DB_TRACE_DEPTH
This sets the trace depth.

Parameter 'value' Description

S7_TRACE_DEPTH_OFF Switches the trace off.
S7_TRACE_DEPTH_USER With this setting (default) only
the strings specified by the user
program with the 's7_trace()'
function are entered in the
trace.
S7_TRACE_DEPTH_EXCEPT This setting only allows trace
entries following error events or
incorrect results.
S7_TRACE_DEPTH_INTERFACE With this setting, parameters
transferred to the SAPI-S7 pro-
gramming interface are entered
in the trace. This allows incor-
rect parameters to be detected
quickly and without using a de-
bugger.
S7_TRACE_DEPTH_OTHER This setting provides further
information.

170
C79000-G8976-C077-07 S7 Programming Interface

S7_MINI_DB_TRACE_SELECT
To be able to activate the trace for specific service classes, a define is
available in the header file 'SAPI_S7.H' for each service class. The
defines can be combined as explained above.

Parameter 'value' Description

S7_TRACE_SELECT_ADMIN_SERVICES Activates the trace for the admini-
strative services.
S7_TRACE_SELECT_CONN_SERVICES Activates the trace for the S7 con-
nection management services.
S7_TRACE_SELECT_VAR_SERVICES Activates the trace for the variable
services.
S7_TRACE_SELECT_CYCL_VAR_SERVICES Activates the trace for the cyclic va-
riable services.
S7_TRACE_SELECT_RECEIVE_SERVICES Activates the trace for the receive
call.
S7_TRACE_SELECT_VFD_SERVICES Activates the trace for the VFD ser-
vices.
S7_TRACE_SELECT_OTHER_SERVICES Activates the trace for functions ac-
cessing the mini-DB.
S7_TRACE_SELECT_PBK_SERVICES Activates the trace for the block-
oriented services.
S7_TRACE_SELECT_ALL Activates the trace for all service
classes.

S7_MINI_DB_TRACE_NO_LINES
This parameter is used to modify the number of lines in the internal
ring buffer. For applications that require a lot of memory, the ring buf-
fer can be reduced in size or increased in size to record the history
when errors occur. The function 's7_write_trace_buffer()' allows the
ring buffer to be written to a file.

Changing this parameter is only effective if the change precedes

☞ the first S7 library call.

171
S7 Programming Interface C79000-G8976-C077-07

Possible Combi- For the S7 connection establishment, it is possible to assign defaults

nations of Values for various connection parameters negotiated by the stations. The
for Establishing S7 permitted combinations of values are described below starting with the
Connections 'type' parameter.

S7_MINI_DB_INIT_REQ_AMQ_CALLING
This value specifies how many acknowledged jobs can be received at
the same time on the connection by the active partner (default: '3').
The value is a proposal that can be accepted or reduced by the partner
station. The negotiated value can be read out by the function
's7_mini_db_get()'.

S7_MINI_DB_INIT_REQ_AMQ_CALLED
This value specifies how many acknowledged jobs can be sent at the
same time on the connection by the active partner (default: '3'). The
value is a proposal that can be accepted or reduced by the partner
station. The negotiated value can be read out by the function
's7_mini_db_get()'.

S7_MINI_DB_INIT_REQ_PDU_SIZE
This value specifies the maximum size of a PDU on this connection for
the active partner (default: '0x100'). The value is a proposal that can
be accepted or reduced by the partner station. The negotiated value
can be read out by the function 's7_mini_db_get()'.

S7_MINI_DB_INIT_RSP_AMQ_CALLING
This value specifies how many acknowledged jobs can be sent at the
same time on the connection by the passive partner (default: '3'). The
lower of the values set for the active or passive side is negotiated.

S7_MINI_DB_INIT_RSP_AMQ_CALLED
This value specifies how many acknowledged jobs can be received at
the same time on the connection by the passive partner (default: '3').
The lower of the values set for the active or passive side is negotiated.

172
C79000-G8976-C077-07 S7 Programming Interface

S7_MINI_DB_INIT_RSP_PDU_SIZE
This value specifies the maximum size of a PDU on this connection for
the passive partner (default: '0x100'). The lower of the values set for
the active or passive side is negotiated.

S7_MINI_DB_PERSISTANCE_COUNT
This value sets the number of attempts at active connection
establishment (default: '5'). When the partner station has rejected the
establishment request this number of times, the establishment is ter-
minated and a negative acknowledgment sent to the user program.
This value can have a different meaning with certain SIMATIC NET
products. In this case, the meaning is explained in the relevant product
information.

S7_MINI_DB_ABORT_TIMEOUT
This value specifies how long a station can attempt to establish a con-
nection if the remote station does not respond. The value is set in mul-
tiples of 51 ms (default: '3000'). The parameter applies both to the
connection establishment and to the data transfer phase.
This value can have a different meaning with certain SIMATIC NET
products. In this case, the meaning is explained in the relevant product
information.
This value is irrelevant for TCP/IP protocols.

173
S7 Programming Interface C79000-G8976-C077-07

4.4 s7_mini_db_get

Description With this call, the settings are read out of the mini-DB. The user speci-
fies an identifier for the setting to be read and receives a string that
must be interpreted depending on the identifier.

Declaration const char *s7_mini_db_get

(
ord16 type /* In call */
)

Parameters type Identifier for the data to be read. The possible values
are described below.

Return Values for The mini-DB allows all the modifiable settings of the trace to be read at
Trace Settings any time. These are as follows:

S7_MINI_DB_TRACE_FILENAME
With this parameter, the name of the trace file is returned.

S7_MINI_DB_TRACE_TARGET
With this parameter, the target of the trace is output.

S7_MINI_DB_TRACE_DEPTH
With this parameter, the trace depth can be queried.

S7_MINI_DB_TRACE_SELECT
With this parameter, the service classes that were activated for the
trace are indicated.
The return values correspond to the specified values in the
's7_mini_db_set()' call.

174
C79000-G8976-C077-07 S7 Programming Interface

Return Values for After receiving an initiate confirmation, the performance parameters
Establishing an S7 negotiated between client and server are entered in the mini-DB by the
Connection corresponding processing function 's7_get_initiate_cnf()'.

S7_MINI_DB_INIT_IND_AMQ_CALLING
After receiving the initiate indication, this value informs the passive
partner how many jobs the active partner on the connection can recei-
ve at the same time.

S7_MINI_DB_INIT_IND_AMQ_CALLED
After receiving the initiate indication, this value informs the passive
partner how many jobs the active partner on the connection can send
at the same time.

S7_MINI_DB_INIT_IND_PDU_SIZE
After receiving the initiate indication, this value informs the passive
partner how much data the active partner can receive on this connecti-
on.

S7_MINI_DB_INIT_CNF_AMQ_CALLING
After active connection establishment, this value indicates the number
of acknowledged jobs that can be received at the same time on this
connection. The value was negotiated by the partners when the con-
nection was established.

S7_MINI_DB_INIT_CNF_AMQ_CALLED
After active connection establishment, this value indicates the number
of acknowledged jobs that can be sent at the same time on this con-
nection. The value was negotiated by the partners when the connection
was established.

S7_MINI_DB_INIT_CNF_PDU_SIZE
After active connection establishment, this value indicates the maxi-
mum PDU size on this connection. The value was negotiated by the
partners when the connection was established.

175
S7 Programming Interface C79000-G8976-C077-07

4.5 s7_last_iec_err_no

Description The error identifiers are reduced to a practical number by the S7 library
to allow error handling to be implemented more simply in applications.
According to IEC 1131 (International Electrotechnical Commission),
there are standard error codes that can be read out with this call.

Declaration ord16 s7_last_iec_err_no(void)

Parameters None

Return Values The possible return values and their significance:

S7_ERR_IEC_NO
No error occurred.

S7_ERR_IEC_DATA_TYPE_MISMATCH
The data types do not match.

S7_ERR_IEC_INVALID_REF
The specified S7 connection reference does not exist.

S7_ERR_IEC_LOWER_LAYER
An error occurred in the lower layers.

S7_ERR_IEC_NEG_RESPONSE
The client has received a negative response from the communications
partner.

S7_ERR_IEC_NO_ACCESS_TO_REM_OBJECT
Access to an object was rejected.

S7_ERR_IEC_PARTNER_IN_WRONG_STATE
The partner station is in a status in which the requested job cannot be
processed.

176
C79000-G8976-C077-07 S7 Programming Interface

S7_ERR_IEC_RECEIVER_DISABLED
The server is not responding.

S7_ERR_IEC_RECEIVER_OVERRUN
The resources in the server are exhausted.

S7_ERR_IEC_RESET_RECEIVED
A reset request has been received.

177
S7 Programming Interface C79000-G8976-C077-07

4.6 s7_last_iec_err_msg

Description This call returns a string that describes the error indicated by the IEC
error code. This is an error string that can, for example, be displayed
on an operator console or written to a log file etc.

Declaration const char *s7_last_iec_err_msg(void)

Parameters None

178
C79000-G8976-C077-07 S7 Programming Interface

4.7 s7_last_detailed_err_no

Description With this call, the caller receives an error number that provides more
detailed information about the cause of the error than the standard IEC
error codes.

Declaration ord16 s7_last_detailed_err_no(void)

Parameters None

Return Values The possible return values and their significance:

S7_ERR_NO_ERROR
No error occurred.

S7_ERR_CONN_ABORTED
The S7 connection was aborted.

S7_ERR_CONN_CNF
The S7 connection could not be established.

S7_ERR_CONN_NAME_NOT_FOUND
The specified S7 connection name was not found.

S7_ERR_FW_ERROR
A firmware error has occurred on the communications processor.

S7_ERR_INSTALL
When installing the SIMATIC NET driver or initializing the communica-
tions processor an error occurred that makes communication impos-
sible.

S7_ERR_INTERNAL_ERROR
During communication, library-internal data were overwritten making it
impossible to continue operating the application.

179
S7 Programming Interface C79000-G8976-C077-07

S7_ERR_INVALID_CONN_STATE
The job that has been sent is not permitted in the current status of the
S7 connection.

S7_ERR_INVALID_CREF
The specified S7 connection reference is invalid.

S7_ERR_INVALID_CYCL_READ_STATE
The job is not permitted in the current status of the cyclic read job.

S7_ERR_INVALID_DATARANGE_OR_TYPE
Input parameter of the called function outside the valid range of valu-
es.

S7_ERR_INVALID_DATA_SIZE
The data buffer provided by the user program is too small.

S7_ERR_INVALID_ORDERID
There is no job with the specified job identifier (parameter 'orderid').

S7_ERR_INVALID_PARAMETER
A transferred parameter or a specified value in a transferred structure
is invalid.

S7_ERR_MAX_REQ
The maximum number of acknowledged jobs negotiated during con-
nection establishment has already been sent.

S7_ERR_MINI_DB_TYPE
The 'type' parameter is not permitted in a mini-DB call.

S7_ERR_MINI_DB_VALUE
The 'value' parameter is not permitted in a mini-DB call.

180
C79000-G8976-C077-07 S7 Programming Interface

S7_ERR_NO_LICENCE
The license required for the product could not be found.

S7_ERR_NO_RESOURCE
The resources available are currently exhausted.

S7_ERR_NO_SIN_SERV
The SIMATIC NET server required for S7 applications under Windows
that sends messages to the relevant application could not be started.

S7_ERR_OBJ_ACCESS_DENIED
Access to the required object was rejected.

S7_ERR_OBJ_ATTR_INCONSISTENT
The OD or the attributes of the addressed object are inconsistent.

S7_ERR_OBJ_UNDEFINED
The object to be accessed does not exist.

S7_ERR_ORDERID_USED
The job identifier transferred with the call (parameter 'orderid') is alrea-
dy being used.

S7_ERR_RECEIVE_BUFFER_FULL
A message was received however the corresponding processing
function has not yet been called.

S7_ERR_SERVICE_NOT_SUPPORTED
The requested service is not supported.

S7_ERR_SERVICE_VFD_ALREADY_USED
The application or a different process has already logged on at the
VFD.

181
S7 Programming Interface C79000-G8976-C077-07

S7_ERR_SYMB_ADDRESS
The symbolic address transferred in the job is incorrect.

S7_ERR_SYMB_ADDRESS_INCONSISTENT
The size of the user data contained in the symbolic address and the
size of the user buffer are contradictory.

S7_ERR_TOO_LONG_DATA
There are more data to be written than permitted by the standard.

S7_ERR_UNKNOWN_ERROR
An unknown error has occurred.

S7_ERR_WRONG_CP_DESCR
The CP descriptor in the call is incorrect.

S7_ERR_WRONG_IND_CNF
The wrong processing function was called for a received message.

182
C79000-G8976-C077-07 S7 Programming Interface

4.8 s7_last_detailed_err_msg

Description This call provides an error message about the detailed error number
that describes the error that has occurred and provides information
about eliminating the error. This is an error string that can, for examp-
le, be displayed on an operator console or written to a log file etc.

Declaration const char *s7_last_detailed_err_msg(void)

Parameters None

183
S7 Programming Interface C79000-G8976-C077-07

4.9 s7_discard_msg

Description With this call, the user program can discard a received message
without having called the corresponding processing function.
Per S7 connection, there is a maximum number of acknowledged jobs
that can be processed simultaneously, this maximum number is speci-
fied during configuration and is negotiated when the connection is
established. Ignoring (for example unexpected) events and the conse-
quent absence of responses therefore permanently reduces the num-
ber of acknowledged jobs that can be used at the same time.

Declaration void s7_discard_msg(void)

Parameters None

184
C79000-G8976-C077-07 S7 Programming Interface

5 Configuration

In this chapter
➢ you will learn the meaning of configuration,
➢ you will obtain an overview of the configuration parameters necessary for opera-
tion,
➢ you will find a list of the services that use configuration parameters.

When you have worked through this chapter, you will be in a position to match your
SAPI-S7 application to the configuration.

185
S7 Programming Interface C79000-G8976-C077-07

5.1 Significance of Configuration

Configuration In- To avoid involving applications in adaptations made necessary by

creases the Flexi- changes in the communications system (network), the creation and
bility of Your assignment of S7 connections is configured. Configuration is a stan-
Application dardized method of setting address parameters etc. for all applications.
Generally, the installation of software and its integration in the network
is not done by the software developer.
When you reconfigure a system, you must make sure that the configu-
ration parameters relevant to the applications are retained. The name
of an S7 connection, for example, must continue to exist even if a dif-
ferent partner station is addressed on this connection and under certain
circumstances even with a different S7 connection reference. By kee-
ping to these rules, modifications can be made using the appropriate
configuration tools at any time without needing to change user pro-
grams.
Accessing the configuration is described in Section 6.5.

186
C79000-G8976-C077-07 S7 Programming Interface

5.2 Services With Configuration Data

Administrative The logon function 's7_init()' requires two items of information from the
Services administrative services:
➢ Firstly, the CP name that identifies a CP must be specified and
must match the name selected during installation. The installati-
on is performed with SIMATIC NET products. The installation
procedures are described in the documentation accompanying
these products.
➢ Secondly, the name of the local VFD at which the user wants to
log on is required. The logon makes the VFD-specific S7 con-
nections and the VFD-specific objects accessible to the applica-
tion. The VFD name is specified during configuration.
The names of the installed CPs or the names of VFDs configured on a
CP that were assigned connetions can be queried with the
's7_get_device()' or 's7_get_vfd()' calls.

Management Ser- Only the 's7_get_cref()' call requires a configuration parameter from
vices for S7 Con- the management services for S7 connection lists in the form of the S7
nection Lists connection name. This function returns the configured reference for an
S7 connection. Once this reference has been obtained, the application
should continue to use the reference in future communication.
The names of all configured S7 connections can be read out with the
's7_get_conn()' call.

187
S7 Programming Interface C79000-G8976-C077-07

5.3 Configuring with STEP 7 V5

Procedure From STEP 7 V5 onwards, it is possible to configure the SAPI-S7

connections from PC to SIMATIC S7 PLC with STEP 7.
To use this function, select the station type SIMATIC PC station in
STEP 7.
The configuration file (XDB file) created by STEP 7 must be copied to
the PC. You can select the location of the XDB file using the program
'Setting the PG/PC Interface' (STEP 7 Configuration tab).
Fault-tolerant connections must be configured with STEP 7 V5. For
more information on configuring, refer to the STEP 7 V5 documentati-
on.
Read the product information bulletins of your SIMATIC NET product
to check whether configuration with STEP 7 V5 is supported.
If you decide to configure connections using STEP 7, all S7 connecti-
ons on a PC must be configured with STEP 7.

Restrictions Fault-tolerant connections are only available with the

S7-REDCONNECT product.

188
C79000-G8976-C077-07 S7 Programming Interface

6 SAPI-S7 Under MS-DOS/Windows

This chapter explains the characteristics of the SAPI-S7 programming interface specific
to MS-DOS and Windows. In this context Windows stands for the Microsoft operating
systems Windows 3.x (3.1 and 3.11) in enhanced 386 mode, Windows 95 and Win-
dows NT if not specified otherwise.

You will learn the following:

➢ The compilers and memory models for which the S7 library is available under
MS-DOS and Windows.
➢ Which compiler options are useful when translating your own applications.
➢ Which linker options are required when linking your program modules to the S7
library.
➢ How to control the trace using environment variables without having to change
your application.

When you have worked through this chapter, you will be in a position to
➢ translate your own program modules and to link them with the S7 library to form
an executable program,
➢ control the trace outputs of your application.

189
S7 Programming Interface C79000-G8976-C077-07

6.1 General Information

Memory Models The SAPI-S7 programming interface is available to the user in the form
of libraries. The definitions required to use the programming interface
are located in the 'SAPI_S7.H' file. Libraries are available for MS-DOS,
Windows 3.x, Windows 95 and Windows NT for various compilers.
The names of the libraries for MS-DOS and Windows 3.x are as fol-
lows:
<Memorymodel><Operatingsystem>s7<Compiler>.lib

The following table explains the components making up the library

names.

Format Name Format Entry Meaning

<Speichermodell> l Large model
h Huge model
<Betriebssystem> d MS DOS
w Windows 3.x
<Compiler> msc MSC compiler 7.0
tc Turbo C compiler 1.0
bc Borland C compiler 3.1

For example, the file '[Link]' is the library translated with the
Turbo C compiler in the 'Large' memory model for the MS-DOS opera-
ting system.
For the Windows 3.x operating system, the '[Link]' file provides a
DLL version (Dynamic Link Library) with the import libraries
'[Link]' and '[Link]' for the Microsoft C- or Borland C compi-
lers.
For Windows 95 and Windows NT, a 32-bit DLL '[Link]' and the
corresponding import library '[Link]' are available.

190
C79000-G8976-C077-07 S7 Programming Interface

Alignment Normally, compilers save variables in memory in a form that seems

the most suitable to the compiler. During this procedure, gaps can oc-
cur between the components of a variable (padding bytes).
The structures available on the SAPI-S7 programming interface are
designed so that they can access the individual components of user
programs translated with byte or word alignment. Double word align-
ment is not supported by the S7 library.

Program Abort To allow communication, user programs must log on at the communi-
cations system that occupies resources for management. If an applica-
tion is aborted with the key combination 'CTRL+C' the resources still
remain reserved for the process and the logon is still effective. To
avoid this, a 'CTRL+C' handler should be implemented in the user pro-
gram to handle all the logoffs at the communications system if the
program is aborted.

191
S7 Programming Interface C79000-G8976-C077-07

6.2 Translating and Linking for MS-DOS

Requirements The following sections list compilation examples that illustrate the re-
quired compiler and linker options for your applications.
You must adapt the compile instruction to suit the situation on your
system selecting the correct drive and path.

Working with the Under MS DOS, the S7 library for the MSC Compiler 7.0 has the name
MSC Compiler 7.0 '[Link]'. The following example shows how a sample program
'EXP.C' is compiled and linked with the 'Large' memory model for MS
DOS:

cl /c /AL /Os /Iinc src\exp.c

link @[Link]

The instructions for the linker are in the file '[Link]' :

[Link],
[Link],
[Link],
[Link]+
\msc70\lib\[Link]+
\msc70\lib\[Link]
;

192
C79000-G8976-C077-07 S7 Programming Interface

Working with the If you want to use the MS Visual C++ Compiler 1.0 for your MS-DOS
MS Visual C++ applications, you can use the same S7 library as for the MSC Compiler
Compiler 1.0 7.0. The compile instructions for the 'Large' memory model then ap-
pear as follows under MS-DOS:

cl /c /AL /Os /Iinc src\exp.c

link @[Link]

The instructions for the linker are in the file '[Link]':

[Link],
[Link],
[Link],
[Link]+
\msvc\lib\[Link]+
\msvc\lib\[Link]
;

Working With the For the Turbo C Compiler 1.0, there are two versions of the S7 library
Turbo C Compi- available for MS-DOS: '[Link]' for the 'Large' memory model
ler 1.0 and '[Link]' for the 'Huge' memory model. The following examp-
le shows how a typical program 'EXP.C' is translated and linked with
the 'Large' memory model for MS-DOS:

tcc -c -ml -Iinc src\exp.c

tlink @[Link].

The instructions for the linker are in the file '[Link]':

\tc10\lib\[Link] [Link]
[Link]
[Link]
\tc10\lib\[Link] \tc10\lib\[Link] \tc10\lib\[Link] [Link]

193
S7 Programming Interface C79000-G8976-C077-07

6.3 Translating and Linking for Windows 3.x

Requirements The following sections list compilation examples that illustrate the re-
quired compiler and linker options for your applications.
You must adapt the compile instruction to suit the situation on your
system selecting the correct drive and path.

Working with the Under Windows 3.x, the S7 library for the MSC Compiler 7.0 has the
MSC Compiler 7.0 name '[Link]'. The following example illustrates how a sample
program 'EXP.C' is translated and linked with the 'Large' memory mo-
del for Windows 3.x:

cl /c /AL /Os /Iinc src\exp.c

link @[Link]

The instructions for the linker are in the file '[Link]':

[Link],
[Link],
[Link],
[Link]+
\msc70\lib\[Link]+
\msc70\lib\[Link]+
\msc70\lib\[Link]
[Link];

The module definition file '[Link]' appears as follows:

NAME EXP
EXETYPE WINDOWS
CODE PRELOAD MOVEABLE DISCARDABLE
DATA PRELOAD MOVEABLE MULTIPLE
HEAPSIZE 1024
STACKSIZE 10240
EXPORTS

194
C79000-G8976-C077-07 S7 Programming Interface

If you want to use the MS Visual C++ Compiler 1.0 for your Windows
Working with the
applications, you can use the same S7 library as for the MSC Compiler
MS Visual C++ 7.0. The compile instructions for the 'Large' memory model then ap-
Compiler 1.0 pear as follows under MS-DOS:

cl /c /AL /Os /Iinc src\exp.c

link @[Link]

The instructions for the linker are in the file '[Link]':

[Link],
[Link],
[Link],
[Link]+
\msvc\lib\[Link]+
\msvc\lib\[Link]+
\msvc\lib\[Link]
[Link];

The module definition file '[Link]' appears as follows:

NAME EXP
EXETYPE WINDOWS
CODE PRELOAD MOVEABLE DISCARDABLE
DATA PRELOAD MOVEABLE MULTIPLE
HEAPSIZE 1024
STACKSIZE 10240
EXPORTS

195
S7 Programming Interface C79000-G8976-C077-07

Working with the The S7 library for the Borland C Compiler 3.1 has the name
Borland C Compi- '[Link]' under Windows 3.x . The following example shows
ler 3.1 how a typical program 'EXP.C' is translated and linked with the 'Large'
memory model for Windows:

bcc -c -ml -Os -Iinc src\exp.c

tlink /Twe @[Link]

The instructions for the linker are in the file '[Link]':

\bc31\lib\[Link] [Link]
[Link]
[Link]
[Link] \bc31\lib\[Link] \bc31\lib\[Link]
\bc31\lib\[Link]
[Link]

The module definition file '[Link]' appears as follows:

NAME EXP
EXETYPE WINDOWS
CODE PRELOAD MOVEABLE DISCARDABLE
DATA PRELOAD MOVEABLE MULTIPLE
HEAPSIZE 1024
STACKSIZE 10240
EXPORTS

SAPI-S7 as DLL Under the Windows 3.x operating system, in addition to the libraries
Version listed above, there is a DLL version (Dynamic Link Library) available
(file '[Link]') and the required import libraries for the MSC Compiler
7.0 and MS Visual C++ Compiler 1.0 (file '[Link]') or the Borland
C Compiler 3.1 (file '[Link]').
The compilation rules for SAPI-S7 applications that are based on the
DLL version of SAPI-S7 are similar to those for applications that use
the SAPI-S7 libraries. The SAPI-S7 libraries above '[Link]'
and '[Link]' must be replaced by the import libraries
'[Link]' and '[Link]. In addition to this, the define 'S7_DLL'
must be set when compiling source files that use the SAPI-S7 functi-
ons.
For using this DLL in other programming languages, such as BASIC or
Pascal, refer to the corresponding manuals.

196
C79000-G8976-C077-07 S7 Programming Interface

6.4 Translating and Linking for Windows 95 and Windows NT

Requirements The following sections list compilation examples that illustrate the re-
quired compiler and linker options for your applications.
You must adapt the compile instruction to suit the situation on your
system selecting the correct drive and path.

Working with the The S7 import library for the Microsoft Visual C++ compiler 2.2 has the
MSVC Compiler 2.2 name '[Link]' under Windows 95 and Windows NT. The
corresponding DLL has the name '[Link]'. The following Example
shows how a sample program 'EXP.C' is compiled and linked for
Windows 95. For Windows NT, simply replace the directory
'SAPI_S7.W95' with 'SAPI_S7.NT'.

cl /c /MT /W3 /GX /Zp1 /Od -DSTRICT -DWIN32

-DWINDOWS -I\sinec\sapi_s7.w95\include
-I\msvc20\include src\bsp.c
link /NODEFAULTLIB /OUT:"[Link]" @[Link]

The instructions for the linker are in the file '[Link]':

[Link],
\sinec\sapi_s7.w95\lib\[Link]
\msvc20\lib\[Link]
\msvc20\lib\[Link]
\msvc20\lib\[Link]
\msvc20\lib\[Link]
/SUBSYSTEM:windows /MACHINE:I386

197
S7 Programming Interface C79000-G8976-C077-07

6.5 Environment Variables

What Does Envi- The term environment means a memory area in which the parameters
ronment Mean? are saved that are set with the MS-DOS commands 'path', 'prompt' and
'set'. The area consists of a series of ASCII strings that are completed
by a NULL character. The area is used to hold information about the
entire computer system.

Environment Va- The values of the environment variables required for the SAPI-S7
riables of the library must be set using the configuration program "Setting the
SAPI-S7 Library PG/PC Interface“. This program sets the values under the key
under Windows 95 "HKEY_LOCAL_MACHINE\SOFTWARE\SIEMENS\SINEC\SAPI_S7“
and Windows NT in the Windows 95/NT registry. The variable is only searched for in the
program environment when no entry with the required name exists in
the registry.

Controlling the The S7 library can be controlled by a total of three environment varia-
Trace bles. Using the variables 'S7_TRACE_SELECT', 'S7_TRACE_DEPTH'
and 'S7_TRACE_TARGET' the service classes for which entries will be
made in the trace, the trace depth and the target of the trace can be
set (see file 'SAPI_S7.H').
Example: set S7_TRACE_DEPTH=104
The existence of the environment variable is checked and evaluated
when the trace is initialized. Trace settings made earlier are then over-
written.
It is advisable to set the trace using the environment variables and not
with mini-DB calls. This allows the default values to be overwritten for
debugging without the user having to modify his application and
retranslate it.
Under Windows 95 and Windows NT, you can also specify the value
of the variables by making entries with the names of the environment
variables in the registration database under the key
“HKEY_LOCAL_MACHINE\SOFTWARE\SIEMENS\SINEC\SAPI_S7”.

198
C79000-G8976-C077-07 S7 Programming Interface

How to Access the In the configuration program "Setting the PG/PC Interface“, you can
Configuration set the drive name, the and name of the configuration file.

Step Procedure
1 Select a module parameter set from the "Module Parame-
ter Set Used" list box.
2 Click the "Properties" button.
3 Select the "S7 Protocol" tab.
4 Check the "Activate S7" option box.
5 In the "SAPI S7 Database" input field, enter the drive na-
me, the path, and the name of the configuration file.

Under MS-DOS and Windows 3.x, the SAPI-S7 library attempts to read
the path of the configuration file from an environment variable. The
name of the environment variable corresponds to the entry in the regi-
stry under Windows 95 and Windows NT. For a CP with the name
'CP_L2_1:' this would be 'CP_L2_1:_S7LDB'.
If no corresponding environment variable is found either when the
's7_init()' function is called, the SAPI S7 library attempts to read out
the configuration data from a file in the currently active directory. |The
file name is obtained from the transfer parameter 'cp_name' by remo-
ving the colon completing the CP name and appending the extension
'.LDB'. If a CP with the name CP 'CP_L2_1:' logs on, for example, the
file 'CP_L2_1.LDB' is read out.

199
S7 Programming Interface C79000-G8976-C077-07

6.6 The Trace for MS-DOS or Windows

General It is possible to make a setting for a specific operating system for the
trace of the SAPI-S7 programming interface. Using a mini-DB call, the
target of the trace can be modified to the value
'S7_TRACE_TARGET_CONSOLE'. The way in which the trace then
reacts depends on the specific operating system and is explained be-
low.

The Trace Setting Under Windows, the trace setting described above means that the
for Windows entire trace is output on the monitor in its own window. You can then
adapt the window to suit your needs. How you configure the window
and the number of trace lines displayed can be found in the on-line
help texts.

The Trace Setting With the trace setting above, no trace entries whatsoever are made
for MS-DOS under the MS-DOS operating system. As a single-user operating sy-
stem, MS-DOS is not in a position to start a second application parallel
to the S7 user program that edits and represents the trace on the moni-
tor.

200
C79000-G8976-C077-07 S7 Programming Interface

6.7 Special Features for Windows

Differences Betwe- One of the differences between Windows applications and MS-DOS
en MS-DOS and programs is that they receive events at a central point in the main pro-
Windows Pro- gram and pass them on to a suitable Windows procedure ('WndProc')
grams for further processing. This Windows procedure must be made acces-
sible to Windows management when the program is started.

Example of a
Typical Windows :
Application :
#define MY_MSG_ID 1500

WndProc(hWnd,msg,...)
{
:
:
switch(msg)
{
case ....: /* init code */

s7_init("CP_L2_1:","MY_VFD",&cp_descr);
s7_set_window_handle_msg(
cp_descr,hWnd,MY_MSG_ID);
break;

case ....:
s7_....(cp_descr,...);
break;

case MY_MSG_ID:
s7_receive(cp_descr,&cref,
&orderid);
break;
}
}
:
:

In a Windows application, following 's7_init()', the routine

's7_set_window_handle_msg()' must be called with a window handle
and a message ID so that the underlying communications system can
send a message to the application. When a frame is received, the
application is informed by a message. The Windows procedure that is
then called in turn calls 's7_receive()' and the appropriate processing
function.

201
S7 Programming Interface C79000-G8976-C077-07

6.7.1 s7_set_window_handle_msg

Description In a Windows program, after a successful 's7_init()', the user must call
the routine 's7_set_window_handle_msg()'. This informs the underlying
communication system to which window and with which ID it should
send its messages.

Declaration int32 s7_set_window_handle_msg

(
ord32 cp_descr, /* In call */
ord32 hWnd, /* In call */
ord32 msgID /* In call */
)

Parameters
cp_descr Handle as return value of the 's7_init()' call.

hWnd Handle of the window to which the SIMATIC NET

message will be sent.

msgID ID of the SIMATIC NET message to be sent to the

window specified above.

Return Values S7_OK The function was processed without errors.

S7_ERR_RETRY This value indicates that an error occurred execu-

ting the requested service. This is a temporary
problem such as a brief memory shortage. The
call can be repeated without modifying the trans-
ferred parameters.

S7_ERR This value also indicates an error in the execution

of the requested service. In this case, however,
the error does not allow the service to be repea-
ted. Here, steps must be taken to eliminate the er-
ror such as assigning new parameters for the call.

202
C79000-G8976-C077-07 S7 Programming Interface

7 Appendix

This chapter introduces you to the following:

➢ Which S7 subset is covered by the SAPI-S7 library,
➢ Which conditions must be adhered to when operating the SAPI-S7 library.
➢ How S7 variables and the standard data types are represented by S7 (both on
the host and on the network).

At the end of the chapter you will find a list of the most common abbreviations used in
this manual and a list of documentation available for further reading.

203
S7 Programming Interface C79000-G8976-C077-07

7.1 Range of Functions of SAPI-S7

SAPI-S7 as a Sub- The SAPI-S7 programming interface provides access to the following
set of S7 services (abbreviation: 'req' for Request, 'ind' for Indication, 'con' for
Confirmation and 'rsp' for Response):

PICS Serial Number: 1

PICS Part 1
Implementation in the system
System Parameters Detail
Implementation's Vendor Name - (can be set by COML)
Implementation's Model Name VFD name (can be set by COML)
Implementation's Revision - (can be set by COML)
Identifier
Vendor Name of S7 Siemens AG
Controller Type of S7 ASPC2
Hardware Release of S7 A_._ (can be found on type plate)
Software Release of S7 V_._
Profile Number 0
Calling S7 User YES
(enter 'YES' or 'NO')
Called S7 User YES
(enter 'YES' or 'NO')

PICS Part 2
Supported Services
Service Primitive
Initiate req, con, ind, rsp
Abort req, ind
Status req, con
Unsolicited-Status ind
Read req, con
Write req, con

204
C79000-G8976-C077-07 S7 Programming Interface

PICS Part 3
S7 Parameters and Options Detail
Addressing by names YES
Maximum length for names 32
Access-Protection Supported -
Maximum length for Extension 32
Maximum length for Extension 0
Arguments

PICS Part 4
Local Implementation Values Detail
Maximum length of S7-PDU 1024
Maximum number of Services -
Outstanding Calling
Maximum number of Services -
Outstanding Called
Syntax and semantics of the Exe- -
cution Argument
Syntax and semantics of Exten- -
sion

Conditions for When operating the SAPI-S7 programming interface, remember the
Operation following restrictions:

The number of possible jobs and connections can be found in the

☞ product information of the relevant products (SIMATIC NET and
SIMATIC S7 CPU).

205
S7 Programming Interface C79000-G8976-C077-07

7.2 Special Notes

Data Consistency, For information about data consistency, user data size and cyclic rea-
User Data Size, ding refer to the SIMATIC communication manual (order number
Cyclic Reading 6ES7398-8EA00-8BA0).

206
C79000-G8976-C077-07 S7 Programming Interface

7.3 Formulas for Calculating Data Lengths for the Variable

Services

The following table shows the maximum length of the result/user data
depending on the PDU size as a formula.
In services with several variables, the maximum number of variables is
also shown dependent on the PDU size as a formula.

Service Formula Remark

S7_read_req Len = PDU size – 18
Len = The maximum length of
the result data dependent
on the negotiated PDU
size
s7_write_req Len = PDU size – 28 The length of the user data can-
Len = The maximum length of not exceed 256 bytes.
the user data dependent
on the negotiated PDU
size
s7_write_long_req Len = PDU size - 28
Len = The maximum length of
the user data dependent
on the negotiated PDU
size
s7_multiple_read_req Nvar = (PDU size – 12) / 12
Nvar = Maximum number of va-
riables in one job
SumResData = Caution
PDU size – 14 – Nvar * 4 Variables with an odd data length
SumResData = Maximum count as having the next higher
length of the re- even length in the job.
sult Example
data dependent on the PDU size PDU size = 112
and the number of variables Nvar = 8,3 becomes 8
SumResData =
(112 – 14 – 8 * 4) = 66
in other words, in one job, for ex-
ample, memory byte (MB) 1 to 33
can be read, since 1 memory
byte occupies 2 bytes (33 * 2 =
66).

Table continued on next page

207
S7 Programming Interface C79000-G8976-C077-07

Table continued from previous page

Service Formula Remark

s7_multiple_write_req Nvar = (PDU size – 12 ) / 18
Nvar = Maximum number of va-
riables in one job
SumResData = Caution
(PDU size – 12 – Nvar * 16) Variables with an odd data length
SumResData = Maximum count as having the next higher
length of the even length in the job.
user Example
data dependent on the PDU size PDU size = 480
and the number of variables Nvar = 26
SumResData =
(480 – 12 – 26 * 16 ) = 52
in other words, in one job, for ex-
ample, memory byte (MB) 1 to 26
can be written, since 1 memory
byte occupies 2 bytes (
26 * 2 = 52).
s7_cycl_read_init_req Nvar = ( PDU size – 26 ) / 12
Nvar = Maximum number of va-
riables in one job
SumResData = Caution
PDU size – 28 – Nvar * 4 Variables with an odd data length
SumResData = Maximum count as having the next higher
length of the even length in the job.
user Example
data dependent on the PDU size PDU size = 480
and the number of variables Nvar = 37,83 i.e. 37
SumResData =
(480 – 28 – 37 * 4 ) = 304
in other words, in one job, for ex-
ample, memory word (MW) 1 to
152 can be written, since 1 me-
mory word occupies 2 bytes
(152 * 2 = 304).

208
C79000-G8976-C077-07 S7 Programming Interface

7.4 Representation of S7 Variables

Byte Alignment The SAPI-S7 programming interface requires that variables are saved
byte aligned in main memory. This means that there must be no pad-
ding bytes, for example between the individual components of a
structure. This is achieved with suitable compiler options or by prag-
mas.

Network Represen- The SAPI-S7 library supplies data that have been read or variable
tation of Variable values to be written in the network representation. A conversion bet-
Values ween the host and network representation is intended for future versi-
ons of the library. For this reason, all the affected functions have been
extended by a transfer parameter 'od_ptr' that must be assigned the
NULL pointer in the current version of the library.
This parameter ('od_ptr') will control the representation of variables in a
later version of the library. The representation depends on the follo-
wing:
➢ Whether or not data should be converted from the host to the
network representation and vice versa (currently not implemen-
ted in the SAPI-S7 library), or whether the network representati-
on is required on the host.
➢ Which host CPU is being used (for example Intel).

209
S7 Programming Interface C79000-G8976-C077-07

7.5 Representation of the Standard Data Types

7.5.1 Representation of the 'Boolean' Data Type

Network Represen-
tation and Range
Bit MSB LSB
of Values
Octet 8 7 6 5 4 3 2 1
1 0 0 0 0 0 0 0 x

For 'FALSE', 'x' has the value '0', for 'TRUE' the value '1'.

Host Representati-
on and Range of
Bit MSB LSB
Values (Intel CPU)
Octet 8 7 6 5 4 3 2 1
1 x8 x7 x6 x5 x4 x3 x2 x1

If at least 1 bit of the bits 'x8' to 'x1' are set, the value 'TRUE' is assu-
med. For 'FALSE', all bits must be '0’

210
C79000-G8976-C077-07 S7 Programming Interface

7.5.2 Representation of the Data Type 'Integer'

Range of Values With the 'integer' data type, a distinction must be made according to
the length of the data type.

Data Type Range of Values Length

8-bit integer -128 ... 127 1 octet
16-bit integer - 32768 ... 32767 2 octets
32-bit integer -231 ... 231-1 4 octets

Network Represen- Network representation (2’s complement representation) for 8-bit inte-
tation gers ('SI' represents the sign bit and has the value '1' for negative
numbers, otherwise the value '0'):

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 SI 26 25 24 23 22 21 20

Network representation (2’s complement representation) for 16-bit in-

tegers ('SI' represents the sign bit and has the value '1' for negative
numbers, otherwise the value '0'):

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 SI 214 213 212 211 210 29 28
2 27 26 25 24 23 22 21 20

211
S7 Programming Interface C79000-G8976-C077-07

Network representation (2’s complement representation) for 32-bit in-

tegers ('SI' represents the sign bit and has the value '1' for negative
numbers, otherwise the value '0'):

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 SI 230 229 228 227 226 225 224
2 223 222 221 220 219 218 217 216
3 215 214 213 212 211 210 29 28
4 27 26 25 24 23 22 21 20

Host Representati- Host representation (2’s complement representation) for 8-bit integers
on (Intel CPU) ('SI' represents the sign bit and has the value '1' for negative numbers,
otherwise the value '0'):

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 SI 26 25 24 23 22 21 20

Host representation (2’s complement representation) for 16-bit integers

('SI' represents the sign bit and has the value '1' for negative numbers,
otherwise the value '0'):

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 27 26 25 24 23 22 21 20
2 SI 214 213 212 211 210 29 28

212
C79000-G8976-C077-07 S7 Programming Interface

Host representation (2’s complement representation) for 32-bit integers

('SI' represents the sign bit and has the value '1' for negative numbers,
otherwise the value '0'):

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 27 26 25 24 23 22 21 20
2 215 214 213 212 211 210 29 28
3 223 222 221 220 219 218 217 216
4 SI 230 229 228 227 226 225 224

213
S7 Programming Interface C79000-G8976-C077-07

7.5.3 Representation of the 'Unsigned' Data Type

Range of Values With the 'unsigned' data type, a distinction must be made according to
the length of the data type.

Data Type Range of Values Length

8-bit unsigned 0 ... 255 1 octet
16-bit unsigned 0 ... 65535 2 octets
32-bit unsigned 0 ... 232-1 4 octets

Network Represen- Network representation for 8-bit unsigned:

tation

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 27 26 25 24 23 22 21 20

Network representation for 16-bit unsigned:

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 215 214 213 212 211 210 29 28
2 27 26 25 24 23 22 21 20

Network representation for 32-bit unsigned:

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 231 230 229 228 227 226 225 224
2 223 222 221 220 219 218 217 216
3 215 214 213 212 211 210 29 28
4 27 26 25 24 23 22 21 20

214
C79000-G8976-C077-07 S7 Programming Interface

Host Representati- Host representation for 8-bit unsigned:

on (Intel CPU)

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 27 26 25 24 23 22 21 20

Host representation for 16-bit unsigned:

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 27 26 25 24 23 22 21 20
2 215 214 213 212 211 210 29 28

Host representation for 32-bit unsigned:

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 27 26 25 24 23 22 21 20
2 215 214 213 212 211 210 29 28
3 223 222 221 220 219 218 217 216
4 231 230 229 228 227 226 225 224

215
S7 Programming Interface C79000-G8976-C077-07

7.5.4 Representation of the 'Floating Point' Data Type

Range of Values Range of Values Length

-3.37*1038 ... -8.43*10-37 4 octets

8.43*10-37 ... 3.37*1038

Network Represen- Network representation ('SI' is the sign of the mantissa, the shaded
tation fields belong to the exponent, the remaining fields to the mantissa).

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 SI 27 26 25 24 23 22 21
2 20 2-1 2-2 2-3 2-4 2-5 2-6 2-7
3 2-8 2-9 2- 2- 2- 2- 2- 2-
10 11 12 13 14 15
4 2- 2- 2- 2- 2- 2- 2- 2-
16 17 18 19 20 21 22 23

Host Representati- Host representation ('SI' is the sign of the mantissa, the shaded fields
on (Intel CPU) belong to the exponent, the remaining fields to the mantissa).

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 2- 2- 2- 2- 2- 2- 2- 2-
16 17 18 19 20 21 22 23
2 2-8 2-9 2- 2- 2- 2- 2- 2-
10 11 12 13 14 15
3 20 2-1 2-2 2-3 2-4 2-5 2-6 2-7
4 SI 27 26 25 24 23 22 21

216
C79000-G8976-C077-07 S7 Programming Interface

Value Calculation The variable value is calculated as follows:

Exponent Variable Value

0 (-1)SI*(([Link])*2-126)

not equal (-1)SI*(([Link])*2(exponent-127))

to 0

Example of the representation of the variable value '0.5' in the host as

'C' data type 'float':

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 0 0 0 0 0 0 0 0
2 0 0 0 0 0 0 0 0
3 0 0 0 0 0 0 0 0
4 0 0 1 1 1 1 1 1

217
S7 Programming Interface C79000-G8976-C077-07

7.5.5 Representation of the 'Visible String' Data Type

Range of Values For variables of the type 'visible string', all letters (upper and lower
case), numbers, the underscore ('_') and the Dollar sign ('$') are permit-
ted.

Network Represen-
Bit MSB LSB
tation
Octet 8 7 6 5 4 3 2 1
1 1st character
2 2nd character
..
n nth character

Host Representati-
on (Intel CPU) Bit MSB LSB
Octet 8 7 6 5 4 3 2 1
1 1st character
2 2nd character
..
n nth character
n+1 NULL terminator

A variable of the type 'visible string' corresponds to a string of the pro-

gramming language 'C in the host, in other words it is terminated with
NULL.

218
C79000-G8976-C077-07 S7 Programming Interface

7.5.6 Representation of the 'Octet String' Data Type

Network Represen- A variable of the type 'octet string' is represented on the network like a
tation 'visible string'. In this case, however, all byte values are permitted.

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 1st character
2 2nd character
..
n nth character

Host Representati-
on (Intel CPU) Bit MSB LSB
Octet 8 7 6 5 4 3 2 1
1 Length information
2 1st character
..
n (n-1)th character
n+1 nth character

The host representation differs from the network representation in that

the length information is stored in the first byte.

219
S7 Programming Interface C79000-G8976-C077-07

7.5.7 Representation of the 'Bit String' Data Type

Network Represen- A variable of the type 'bit string' is represented on the network as fol-
tation lows:

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1
1 7 6 5 4 3 2 1 0
2 15 14 13 12 11 10 9 8
..

Host Representati-
on (Intel CPU) Bit MSB LSB
Octet 8 7 6 5 4 3 2 1
1 Length information
2 7 6 5 4 3 2 1 0
3 15 14 13 12 11 10 9 8
..

The host representation differs from the network representation in that

the length information is stored in the first byte.

220
C79000-G8976-C077-07 S7 Programming Interface

Glossary

ASCII American Standard Code of Information Interchange - coding rules for

1-byte characters.

Communication Underlying software and hardware for attachment to the communicati-

system ons network.

CP Communications Processor - communications module for installation in

a computer or programmable controller.

CREF Connection Reference.

DB Data block

default Standard setting as shipped by Siemens.

IEC International Electrotechnical Commission - international standards

committee.

Multi-CP operation More than one CP can be operated at one time in a programming de-
vice/PC.

Multi-user operati- More than one application on a programming device/PC

on

PBC Programmed Block Communication; the S7 PBC services include, for

example, BSEND, BRCV, SEND, RCV, PUT, GET

PCS 7 Process Control System - process control system based on

SIMATIC S7.

PDU Protocol Data Unit - message on an ISO/OSI layer.

PG Programming device.

PMC The PMC services include: SCAN, ALARM, NOTIFY, ALARM_S

221
S7 Programming Interface C79000-G8976-C077-07

PROFIBUS Process Field Bus - Network for the cell and field area of the mid per-
formance range with its main application in an industrial environment
complying with EN 50 170, Volume 2. PROFIBUS.

S7 SIMATIC S7 is an automation system from Siemens AG.

SAPI Simple Application Programmers Interface - simple programming inter-

face for communications protocols on the PG/PC.

SIMATIC NET Product range for industrial communication from Siemens.

SINEC L2 Old name of -> PROFIBUS.

VFD Virtual Field Device - simulation of a real programmable controller

allowing a uniform view of any device.

222
B89077/07 S7 Programming Interface

Index

s7_abort() .........................................31; 70 s7_get_msg_initiate_cnf() ............... 36; 136

s7_await_initiate_req() ......................31; 65 s7_get_multiple_read_cnf()............... 32; 93
s7_brcv_init() .................................. 35; 126 s7_get_multiple_write_cnf() ..............32; 99
s7_brcv_stop() ................................ 35; 130 s7_get_read_cnf() ............................. 32; 81
s7_bsend_req() ............................... 35; 123 s7_get_scan_ind()........................... 36; 139
s7_cycl_read() ................................ 34; 114 s7_get_vfd()...................................... 29; 45
s7_cycl_read_delete_req() .............. 33; 112 s7_get_vfd_state_cnf().................... 37; 157
s7_cycl_read_init_req() ................... 33; 101 s7_get_write_cnf()............................. 32; 89
s7_cycl_read_start_req()................. 33; 105 s7_init()............................................. 29; 47
s7_cycl_read_stop_req() ................. 33; 110 s7_initiate_req() ................................ 30; 63
s7_diag_init() .................................. 38; 161 s7_initiate_rsp() ................................ 31; 68
s7_diag_stop() ................................ 38; 164 s7_last_detailed_err_msg() ...................183
s7_discard_msg()..................................184 s7_last_detailed_err_no()......................179
s7_get_abort_ind() ............................31; 71 s7_last_iec_err_msg()...........................178
s7_get_alarm_ind() ......................... 36; 146 s7_last_iec_err_no()..............................176
s7_get_await_initiate_cnf()................31; 66 s7_mini_db_get() ..................................174
s7_get_brcv_ind() ........................... 35; 128 s7_mini_db_set() ..................................168
s7_get_bsend_cnf()......................... 35; 125 s7_msg_abort_req() ........................ 36; 137
s7_get_conn() ...................................29; 50 s7_msg_initiate_req()...................... 36; 135
s7_get_cref().....................................29; 49 s7_multiple_read_req() ..................... 32; 90
s7_get_cycl_read_abort_ind() ......... 33; 109 s7_multiple_write_req()..................... 32; 96
s7_get_cycl_read_delete_cnf()........ 33; 113 s7_read_req() ................................... 32; 79
s7_get_cycl_read_ind() ................... 33; 107 s7_receive()...................................... 30; 55
s7_get_cycl_read_init_cnf().............33; 104 s7_set_window_handle_msg()...............202
s7_get_cycl_read_start_cnf() .......... 33; 106 s7_shut()........................................... 29; 52
s7_get_cycl_read_stop_cnf()........... 33; 111 s7_trace()..............................................166
s7_get_device() ................................29; 43 s7_vfd_state_req() .......................... 37; 156
s7_get_diag_ind() ........................... 38; 162 s7_write_long_req().................................86
s7_get_initiate_cnf()..........................30; 64 s7_write_req() ................................... 32; 83
s7_get_initiate_ind()..........................31; 67 s7_write_trace_buffer() .........................167
s7_get_msg_abort_cnf().................. 36; 138

223
S7 Programming Interface B89077/07

224