SIMATIC NET - support.industry.siemens.com · SIMATIC NET S7-Programmierschnittstelle Band 1 von 1...

SIMATIC NET

S7-Programmierschnittstelle

Band 1 von 1

1 Die SAPI-S7-Schnittstelle

2 Prinzipien der Programmierschnittstelle

3 Die Programmierschnittstelle

4 Trace und Mini-DB

5 Projektierung

6 SAPI-S7 unter MS-DOS/Windows

7 Anhang

Glossar

Index

C79000-G8900-C077 Ausgabe 7

SIMATIC NET ist eine Marke von SiemensSiemens Aktiengesellschaft

Wir haben den Inhalt der Druckschrift auf Überein-stimmung mit der beschriebenen Hard- und Softwaregeprüft. Dennoch können Abweichungen nicht ausge-schlossen werden, so daß wir für die vollständigeÜbereinstimmung keine Gewähr übernehmen. DieAngaben in der Druckschrift werden jedoch regelmä-ßig überprüft. Notwendige Korrekturen sind in dennachfolgenden Auflagen enthalten. Für Verbesse-rungsvorschläge sind wir dankbar.

Technische Änderungen vorbehalten.

Weitergabe sowie Vervielfältigung dieser Unterlage,Verwertung und Mitteilung ihres Inhalts nicht gestattet,soweit nicht ausdrücklich zugestanden. Zuwiderhand-lungen verpflichten zu Schadenersatz. Alle Rechtevorbehalten, insbesondere für den Fall der Patentertei-lung oder GM-Eintragung.

C79000-G8900-C077Copyright © Siemens AG 1995 bis 2001All Rights Reserved

We have checked the contents of this manual foragreement with the hardware described. Sincedeviations cannot be precluded entirely, we cannotguarantee full agreement. However, the data in thismanual are reviewed regularly and any necessarycorrections included in subsequent editions.Suggestions for improvement are welcome.

Technical data subject to change.

The reproduction, transmission or use of thisdocument or its contents is not permitted withoutexpress written authority. Offenders will be liable fordamages. All rights, including rights created by patentgrant or registration of a utility or design, are reserved.

C79000-G8900-C077Copyright © Siemens AG 1995 to 2001All Rights Reserved

Nous avons vérifié la conformité du contenu duprésent manuel avec le matériel et le logiciel qui y sontdécrits. Or, des divergences n'étant pas exclues, nousne pouvons pas nous porter garants pour la conformitéintégrale. Si l'usage du manuel devait révéler deserreurs, nous en tiendrons compte et apporterons lescorrections nécessaires dès la prochaine édition.Veuillez nous faire part de vos suggestions.

Nous nous réservons le droit de modifier lescaractéristiques techniques.

Toute communication ou reproduction de ce supportd'informations, toute exploitation ou communication deson contenu sont interdites, sauf autorisation expresse.Tout manquement à cette règle est illicite et exposeson auteur au versement de dommages et intérêts.Tous nos droits sont réservés, notamment pour le casde la délivrance d'un brevet ou celui de l'enregistrementd'un modèle d'utilité.

C79000-G8900-C077Copyright © Siemens AG 1995 à 2001All Rights Reserved

Siemens Aktiengesellschaft Elektronikwerk KarlsruhePrinted in the Federal Republic of Germany

3

SIMATIC NETS7-Programmierschnittstelle

Beschreibung C79000-B8900-C077/07

Hinweis

Wir weisen darauf hin, daß der Inhalt dieser Betriebsanleitung nicht Teil einer früheren oder bestehenden Vereinbarung, Zusage odereines Rechtsverhältnisses ist oder diese abändern soll. Sämtliche Verpflichtungen von Siemens ergeben sich aus dem jeweiligenKaufvertrag, der auch die vollständige und allein gültige Gewährleistungsregel enthält. Diese vertraglichenGewährleistungsbestimmungen werden durch die Ausführungen dieser Betriebsanleitung weder erweitert noch beschränkt.

Wir weisen außerdem darauf hin, daß aus Gründen der Übersichtlichkeit in dieser Betriebsanleitung nicht jede nur erdenklicheProblemstellung im Zusammenhang mit dem Einsatz dieses Gerätes beschrieben werden kann. Sollten Sie weitere Informationenbenötigen oder sollten besondere Probleme auftreten, die in der Betriebsanleitung nicht ausführlich genug behandelt werden, könnenSie die erforderliche Auskunft über die örtliche Siemens-Niederlassung anfordern.

AllgemeinesDieses Gerät wird mit Elektrizität betrieben. Beim Betrieb elektrischer Geräte stehen zwangsläufig bestimmteTeile dieser Geräte unter gefährlicher Spannung.

WARNUNG !Bei Nichtbeachtung der Warnhinweise können deshalb schwere Körperverletzungen und/oder Sachschädenauftreten.

Nur entsprechend qualifiziertes Personal sollte an diesem Gerät oder in dessen Nähe arbeiten. Dieses Personalmuß gründlich mit allen Warnungen und Instandhaltungsmaßnahmen gemäß dieser Betriebsanleitung vertrautsein.

Der einwandfreie und sichere Betrieb dieses Gerätes setzt sachgemäßen Transport, fachgerechte Lagerungund Montage sowie sorgfältige Bedienung und Instandhaltung voraus.

Anforderung an die Qualifikation des Personals

Qualifiziertes Personal im Sinne dieser Betriebsanleitung bzw. der Warnhinweise sind Personen, die mit Aufstellung, Montage,Inbetriebsetzung und Betrieb dieses Produktes vertraut sind und über die ihrer Tätigkeit entsprechenden Qualifikation verfügen, wiez.B.:

− Ausbildung oder Unterweisung bzw. Berechtigung, Stromkreise und Geräte bzw. Systeme gemäß den aktuellen Standards derSicherheitstechnik ein- und auszuschalten, zu erden und zu kennzeichnen

− Ausbildung oder Unterweisung gemäß an den aktuellen Standards der Sicherheitstechnik in Pflege und Gebrauchangemessener Sicherheitsausrüstungen

− Schulung in Erster Hilfe

!

C79000-G8900-C077-07 S7-Programmierschnittstelle

5

S7-Programmierschnittstelle

SIMATIC S7-Systemkomponenten kommunizieren miteinander über das S7-Kommunikations-protokoll. Um PG-/PC-Anwenderprogrammen den Zugang zu SIMATIC S7-Systemkomponen-ten zu ermöglichen, wurde die SAPI-S7-Programmierschnittstelle entwickelt. Mit ihrer C-Pro-grammierschnittstelle können Sie einfach und flexibel auf die Daten von SIMATIC S7-System-komponenten zugreifen.

Der vorliegende Band beschreibt das S7-Protokoll und dessen Programmierung.

S7-Programmierschnittstelle C79000-G8900-C077-07

6

Notizen


7

1 Die SAPI-S7-Schnittstelle ..................................................................................................11

1.1 Vorteile von S7 gegenüber anderen Protokollen ...................................................12

1.2 Vorteile der SAPI-S7-Programmierschnittstelle .....................................................13

2 Prinzipien der Programmierschnittstelle ..........................................................................15

2.1 Synchrone und asynchrone Auftragsabwicklung....................................................16

2.2 Vorteile der asynchronen Betriebsart.....................................................................17

2.3 Empfangsaufruf und Bearbeitungsfunktionen........................................................18

2.4 Handhabung der S7-Verbindungsmanagementdienste..........................................20

2.5 Fehlermeldekonzept .............................................................................................21

2.6 Der Trace..............................................................................................................22

2.7 Die Mini-DB ..........................................................................................................23

2.8 Multi-CP- und Multi-User-Betrieb ..........................................................................242.8.1 Zuordnung von VFD und S7-Verbindungsliste....................................................25

2.9 Installation und Betriebsvoraussetzungen .............................................................26

3 Die Programmierschnittstelle............................................................................................27

3.1 Übersicht über die Programmierschnittstelle .........................................................283.1.1 Administrative Dienste .......................................................................................293.1.2 Empfangsaufrufdienst ........................................................................................303.1.3 S7-Verbindungsmanagementdienste..................................................................303.1.4 Variablendienste ................................................................................................323.1.5 Blockorientierte Dienste .....................................................................................353.1.6 Meldedienste .....................................................................................................363.1.7 VFD-Dienste ......................................................................................................373.1.8 Diagnosedienste für hochverfügbare Verbindungen ...........................................38

3.2 Administrative Dienste ..........................................................................................393.2.1 s7_get_device....................................................................................................433.2.2 s7_get_vfd .........................................................................................................453.2.3 s7_init ................................................................................................................473.2.4 s7_get_cref ........................................................................................................493.2.5 s7_get_conn ......................................................................................................503.2.6 s7_shut ..............................................................................................................52

3.3 Empfangsaufrufdienst ...........................................................................................533.3.1 s7_receive .........................................................................................................55

3.4 S7-Verbindungsmanagementdienste.....................................................................583.4.1 s7_initiate_req ...................................................................................................633.4.2 s7_get_initiate_cnf .............................................................................................643.4.3 s7_await_initiate_req .........................................................................................653.4.4 s7_get_await_initiate_cnf ...................................................................................663.4.5 s7_get_initiate_ind .............................................................................................673.4.6 s7_initiate_rsp....................................................................................................683.4.7 s7_abort.............................................................................................................703.4.8 s7_get_abort_ind ...............................................................................................71

3.5 Variablendienste ...................................................................................................723.5.1 s7_read_req.......................................................................................................793.5.2 s7_get_read_cnf ................................................................................................81


8

3.5.3 s7_write_req ......................................................................................................833.5.4 s7_write_long_req..............................................................................................863.5.5 s7_get_write_cnf................................................................................................893.5.6 s7_multiple_read_req.........................................................................................903.5.7 s7_get_multiple_read_cnf ..................................................................................933.5.8 s7_multiple_write_req ........................................................................................963.5.9 s7_get_multiple_write_cnf..................................................................................993.5.10 s7_cycl_read_init_req ....................................................................................1013.5.11 s7_get_cycl_read_init_cnf..............................................................................1043.5.12 s7_cycl_read_start_req ..................................................................................1053.5.13 s7_get_cycl_read_start_cnf............................................................................1063.5.14 s7_get_cycl_read_ind ....................................................................................1073.5.15 s7_get_cycl_read_abort_ind...........................................................................1093.5.16 s7_cycl_read_stop_req ..................................................................................1103.5.17 s7_get_cycl_read_stop_cnf ............................................................................1113.5.18 s7_cycl_read_delete_req ...............................................................................1123.5.19 s7_get_cycl_read_delete_cnf .........................................................................1133.5.20 s7_cycl_read..................................................................................................114

3.6 Blockorientierte Dienste ......................................................................................1173.6.1 s7_bsend_req ..................................................................................................1233.6.2 s7_get_bsend_cnf............................................................................................1253.6.3 s7_brcv_init .....................................................................................................1263.6.4 s7_get_brcv_ind...............................................................................................1283.6.5 s7_brcv_stop ...................................................................................................130

3.7 Meldedienste ......................................................................................................1313.7.1 s7_msg_initiate_req.........................................................................................1353.7.2 s7_get_msg_initiate_cnf ..................................................................................1363.7.3 s7_msg_abort_req ...........................................................................................1373.7.4 s7_get_msg_abort_cnf.....................................................................................1383.7.5 s7_get_scan_ind ..............................................................................................1393.7.6 s7_get_alarm_ind ............................................................................................146

3.8 VFD-Dienste .......................................................................................................1533.8.1 s7_vfd_state_req .............................................................................................1563.8.2 s7_get_vfd_state_cnf.......................................................................................157

3.9 Diagnosedienste für hochverfügbare Verbindungen ............................................1593.9.1 s7_diag_init......................................................................................................1613.9.2 s7_get_diag_ind...............................................................................................1623.9.3 s7_diag_stop....................................................................................................164

4 Trace und 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

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


9

5 Projektierung....................................................................................................................185

5.1 Bedeutung der Projektierung...............................................................................186

5.2 Dienste mit Projektierdaten .................................................................................187

5.3 Projektierung mit STEP 7 V5 ..............................................................................188

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

6.1 Allgemeines ........................................................................................................190

6.2 Übersetzen und Binden für MS-DOS...................................................................192

6.3 Übersetzen und Binden für Windows 3.x.............................................................194

6.4 Übersetzen und Binden für Windows 95 und Windows NT ..................................197

6.5 Environmentvariablen.........................................................................................198

6.6 Der Trace für MS-DOS oder Windows ................................................................200

6.7 Besonderheiten für Windows ..............................................................................2016.7.1 s7_set_window_handle_msg............................................................................202

7 Anhang .............................................................................................................................203

7.1 Funktionsumfang von SAPI-S7 ...........................................................................204

7.2 Besondere Hinweise ...........................................................................................206

7.3 Formeln zur Berechnung des Mengengerüstes bei Variablendiensten.................207

7.4 Darstellung von S7-Variablen..............................................................................209

7.5 Darstellung der Standard-Datentypen .................................................................2107.5.1 Darstellung des Datentyps 'Boolean''................................................................2107.5.2 Darstellung des Datentyps 'Integer' ..................................................................2117.5.3 Darstellung des Datentyps 'Unsigned'...............................................................2147.5.4 Darstellung des Datentyps 'Floating Point'........................................................2167.5.5 Darstellung des Datentyps 'Visible-String' ........................................................2187.5.6 Darstellung des Datentyps 'Octet-String' ..........................................................2197.5.7 Darstellung des Datentyps 'Bit-String'...............................................................220

Glossar ................................................................................................................................221

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


10


11

1 Die SAPI-S7-Schnittstelle

Im vorliegenden Kapitel lernen Sie die Vorteile des S7-Kommunikationsprotokolls ge-genüber anderen Protokollen und die S7-Programmierschnittstelle für PC/PG(SAPI-S7) kennen.


12

1.1 Vorteile von S7 gegenüber anderen Protokollen

Die Vorteile von S7 gegenüber anderen Protokollen liegen in der

➢ geringen Prozessor- und Busbelastung.Das S7-Protokoll ist für die SIMATIC-Kommunikation optimiert.

➢ Einfachheit.Die S7-Protokollelemente sind an die SIMATIC-Bedürfnisseangepaßt und daher einfach anwendbar.

➢ Schnelligkeit.S7 ist im Vergleich zu anderen Ebene-7-Automatisierungs-protokollen, wie z. B. MMS, sehr performant.

➢ Kompatibilität.Hochverfügbare Kommunikation zu S7-H-Systemen mit dergleichen Programmierschnittstelle wie zu den Standard-SIMATIC-S7-Systemen.

Vorteile von S7


13

1.2 Vorteile der SAPI-S7-Programmierschnittstelle

Die Abkürzung SAPI-S7 steht für:

➢ SAPI - Simple Application Programmers Interface - einfacheProgrammierschnittstelle,

➢ S7 - das Ebene-7-Kommunikationsprotokoll für SIMATICS7-Systeme.

SAPI-S7

➢ stellt eine einfache C-Programmierschnittstelle dar,

➢ bietet den Zugang zu den S7-Diensten auf PCs und PGs und

➢ ist verfügbar als C-Library und wird mit Siemens-Treibern und-Anschaltungen betrieben.

Was bedeutetSAPI-S7?

Was ist SAPI-S7?


14

Die SAPI-S7-Programmierschnittstelle bietet die nachfolgendenVorteile:

➢ SAPI-S7 ist eine einfache und zugleich flexible und mächtigeSchnittstelle, die pro Auftrag nur einen Übergabeparameterblockbenötigt und eine einfache Pufferverwaltung ermöglicht.SAPI-S7 bietet die Voraussetzungen für geringe Einarbeitungs-aufwände und -zeiten.

➢ Die SAPI-S7-Programmierschnittstelle ist asynchron ausgelegt,da asynchrone Aufrufe performanter sind (mehrere Aufträgekönnen gleichzeitig bearbeitet werden), jederzeit den Empfangvon Statusmeldungen erlauben und sich ideal für die Erstellungereignisgesteuerter Programme, z. B. unter Windows, eignen.

➢ SAPI-S7 wickelt Sequenzdienste, wie den aktiven oder passivenS7-Verbindungsaufbau, der aus vielen Einzelschritten besteht,automatisch ab. Man muß sich deshalb nicht um die einzelnenSequenzen und Fehlerbehandlung in den Einzelschritten küm-mern. Eine Programmerstellung wird damit erheblich einfacher.

➢ SAPI-S7 unterstützt die Fehlersuche mit Hilfe eines integriertenTrace, der die wichtigsten Übergabeparameter und Rückgabe-werte in eine Datei schreibt. Der Trace ist für jede einzelneDienstklasse ein- und ausschaltbar.

➢ Die SAPI-S7-Programmierschnittstelle ist kompatibel zu anderenSAPI-Programmierschnittstellen, d. h. der Portierungsaufwandvon SAPI-S7-Applikationen zu Applikationen anderer SAPI-Pro-grammierschnittstellen (z. B. SAPI-FMS) ist gering.

➢ Die Strukturen der SAPI-S7-Programmierschnittstelle sind soausgelegt, daß mit Byte- oder Word-Alignment übersetzte An-wenderprogramme problemlos auf die einzelnen Komponentenzugreifen können.

➢ Konsistente Projektierung von SIMATIC S7 und SAPI-S7 abSTEP 7 V5 .

➢ Diagnoseschnittstelle für hochverfügbare Kommunikation, sodaß die Applikation jederzeit über den Zustand der redundantenVerbindung informiert ist.

Vorteile der SAPI-S7-Programmier-schnittstelle


15

2 Prinzipien der Programmierschnittstelle

Im folgenden Kapitel lernen Sie die Prinzipien der SAPI-S7-Programmierschnittstellekennen:

➢ Mit asynchronen Aufrufen können Sie eine Performance-Steigerung erreichenund ereignisgesteuerte Applikationen erstellen.

➢ Durch die Trennung von Empfangsaufrufen und ereignisspezifischen Bearbei-tungsfunktionen wird die SAPI-S7-Programmierschnittstelle vereinfacht.

➢ Durch die Library-interne Abarbeitung von Sequenzdiensten werden Anwender-programme vereinfacht.

➢ Durch eine An- und eine Abmeldefunktion werden der Multi-CP- und der Multi-User-Betrieb gewährleistet.

➢ Durch einen integrierten Trace können Sie zu Debug-Zwecken den Pro-grammablauf und die Funktionsfähigkeit der Library und der Anwenderprogram-me kontrollieren.

Am Ende des Kapitels sind Sie mit den Prinzipien der S7-Programmierschnittstelle so-weit vertraut, daß Sie die Schnittstelle zur Programmerstellung verstehen können.


16

2.1 Synchrone und asynchrone Auftragsabwicklung

Bei der synchronen Auftragsabwicklung (Bild 2.1) bleibt ein Anwender-programm vom Zeitpunkt des Auftrags (Request) bis zum Zeitpunktder Auftragsbestätigung (Confirmation) blockiert. Zwischenzeitlich ein-treffende Ereignisse können nur bearbeitet werden, falls sie interrupt-gesteuert ablaufen. Diese Betriebsart ist bei SAPI-S7 nicht implemen-tiert.

Client Kommunikationssystem Server

1. Aufruf

2. Programmwartet

3. Programmfortsetzen

Bild 2.1: synchrone Betriebsart

Bei der asynchronen Auftragsabwicklung (Bild 2.2) kann ein Anwen-derprogramm nach einem erfolgreichen Auftrag jedes beliebige Ereig-nis entgegennehmen und geeignet darauf reagieren. Die Auftragsbe-stätigung erfolgt erst mit einem expliziten Empfangsaufruf.

Client Kommunikationssystem Server

Bild 2.2: asynchrone Betriebsart

Synchrone Auf-tragsabwicklung

Asynchrone Auf-tragsabwicklung

request

request

indication

indication

confirmation

confirmation

response

response


3. Empfangs-aufruf


1. Aufruf


17

2.2 Vorteile der asynchronen Betriebsart

Die SAPI-S7-Programmierschnittstelle ist asynchron ausgelegt,

➢ da mit asynchronen Aufrufen ein höherer Datendurchsatz er-reicht werden kann (mehrere Aufträge können gleichzeitig bear-beitet werden).

➢ damit die Applikation nicht blockiert wird und sich um andereDinge, wie z. B. den Empfang von Statusmeldungen, kümmernkann.

➢ da asynchrone Mechanismen sich ideal für die Erstellung ereig-nisgesteuerter Programme, z. B. unter Windows, eignen.

Aus Sicht der Anwendung ist zu entscheiden, ob die angesprochenenDienste voneinander abhängen. Ist dies der Fall, so muß die Durchfüh-rung eines Auftrags bestätigt werden, bevor der nächste Auftrag abge-setzt werden kann. Beispielsweise muß eine Verbindung aufgebautsein, bevor über diese Verbindung Daten transferiert werden können.

Asynchrone Auf-träge als Grund-prinzip der SAPI-S7-Programmier-schnittstelle


18

2.3 Empfangsaufruf und Bearbeitungsfunktionen

Eine von den unterlagerten Protokollschichten empfangene Nachrichtwird vom Anwenderprogramm in den beiden folgenden Schritten ab-gearbeitet (Bild 2.3):

➢ Die Funktion 's7_receive()' holt zunächst eine vorhandeneNachricht ab. Der Return-Wert gibt Auskunft über das empfan-gene Ereignis. In der Header-Datei 'SAPI_S7.H' ist je Ereigniseine Konstante definiert, z. B. zeigt der Wert 'S7_INITIATE_IND'an, daß die Partnerstation den Aufbau einer S7-Verbindungwünscht. Bei 'S7_NO_MSG' wurde keine Nachricht empfangen.

➢ Im nächsten Schritt rufen Sie die entsprechende Bearbeitungs-funktion für die empfangene Nachricht auf: das mit'S7_INITIATE_IND' gekennzeichnete Ereignis bedarf des Aufrufsder Bearbeitungsfunktion 's7_get_initiate_ind()'.

Mit Hilfe der Empfangsfunktion kann pollend auf ein Ereignis gewartetwerden. Zwischen Empfang und Aufruf der Bearbeitungsfunktion darfallerdings kein weiteres Ereignis beim Kommunikationssystem abge-holt werden.

SAPI-S7Anwenderprogramm

s7_receive()

remoter Partner

= S7_INITIATE_IND

s7_get_initiate_ind()

= S7_OK

Anstoß Verbindungsaufbau

Indication bearbeiten

Bild 2.3: Nachrichten empfangen und bearbeiten

Wie wird eine emp-fangene Nachrichtbearbeitet?


19

Eine Aufteilung der Ereignisbearbeitung in eine Empfangsfunktion undeine ereignisspezifische Bearbeitungsfunktion:

➢ erlaubt eine einfachere und übersichtlichere Programmier-schnittstelle. Nur die für das empfangene Ereignis relevantenDaten und Parameter werden den Funktionen übergeben,

➢ ermöglicht eine problemlose Erweiterung der SAPI-S7-Program-mierschnittstelle um zusätzliche Ereignisse durch Bereitstellenvon entsprechenden Bearbeitungsfunktionen,

➢ bewirkt eine Trennung von Indication (Empfangsaufruf) undResponse (Bearbeitungsfunktion). Dadurch ist es möglich, An-wenderdaten für die Response aufzubereiten.

Vorteile derAufteilung


20

2.4 Handhabung der S7-Verbindungsmanagementdienste

Die SAPI-S7-Library unterstützt Sie beim aktiven und passiven Verbin-dungsaufbau, der sich aus vielen Einzelschritten zusammensetzt. Beijedem Schritt wird auf Erfolg und Mißerfolg geprüft. Im Fehlerfall wirdsichergestellt, daß schon zuvor erfolgreich durchgeführte Einzelschrittekorrigiert werden. Sie müssen hierzu nach Absetzen des entsprechen-den Requests lediglich die Empfangsfunktion mehrfach bis zum Erhaltder Abschlußquittung aufrufen; Bild 2.4 zeigt diesen Ablauf.


s7_initiate_req()

remoter Partner

= S7_OK

s7_receive()

= S7_NO_MSG

s7_receive()

n-fach wiederholen

= S7_INITIATE_CNF

s7_get_initiate_cnf()

= S7_OK

Anstoß zumVerbindungsaufbau

Confirmation abholen

Nachricht(Confirmation) da!

n-fach wiederholen

n-fach wiederholen

Bild 2.4: aktiver Verbindungsaufbau

Unterstützungdurch dieS7-Library


21

2.5 Fehlermeldekonzept

Die SAPI-S7-Programmierschnittstelle unterstützt ein dreistufigesFehlermeldekonzept:

➢ Erfolg oder Mißerfolg werden zwecks einfacher Fehlerbehand-lung lediglich durch den Return-Wert des Aufrufes angezeigt.

➢ Die Fehlerursachen sind nach IEC 1131 (International Electro-technical Commission) genormt und reduzieren die Anzahl derFehlerkennungen auf ein handhabbares Maß.

➢ Für genauere Fehleranalysen stehen detailliertere Fehlercodesund -meldungen zur Verfügung.

Für die Return-Werte der einzelnen SAPI-S7-Aufrufe stehen in derHeader-Datei 'SAPI_S7.H' Defines bereit:

➢ Der Wert 'S7_OK' zeigt die fehlerfreie Durchführung eines Aufru-fes an.

➢ Mit dem Wert 'S7_ERR_RETRY' wird ein Fehler bei der Ausfüh-rung des angeforderten Dienstes angezeigt. Dabei handelt essich um ein temporär aufgetretenes Problem, wie z. B. um einenvorübergehenden Speicherengpaß. Der Aufruf kann ohne Ände-rung der Übergabeparameter wiederholt werden.

➢ Mit dem Wert 'S7_ERR' wird ebenfalls ein Fehler bei der Aus-führung des angeforderten Dienstes angezeigt. Allerdings han-delt es sich hierbei um einen Fehler, der ein wiederholtes Aus-führen des Dienstes nicht erlaubt. Hier müssen weitere Schrittezur Fehlerbehebung, wie das Versorgen des Aufrufs mit anderenParametern, eingeleitet werden.

Die S7-Library stellt die Funktionen 's7_last_iec_err_no()' und's7_last_iec_err_msg()' zum Auslesen einer Fehlernummer und einerFehlermeldung bereit. Diese Fehlerursachen sind nach IEC 1131(International Electrotechnical Commission) genormt und reduzierendie Anzahl der Fehlerkennungen auf ein handhabbares Maß.

Für detailliertere Fehleranalysen sind an der SAPI-S7-Programmier-schnittstelle die Funktionen 's7_last_detailed_err_no()' und's7_last_detailed_err_msg()' realisiert. Sie beschreiben die Fehlerquel-len genauer und liefern auch Hinweise zur Behebung der aufgetrete-nen Fehler.

Das dreistufigeFehlermelde-konzept der SAPI-S7-Programmier-schnittstelle

Die Return-Werteder SAPI-S7-Programmier-schnittstelle

Die IEC-Fehlerkennungen

Die detailliertenFehlercodes


22

2.6 Der Trace

Der Trace stellt eine einfache und trotzdem effektive Debug-Hilfe fürdie S7-Library dar. Dadurch werden Daten und Ereignisse in einenUmlaufpuffer und eine Trace-Datei abgelegt.

Der Trace kann den verschiedensten Anwendungsfällen angepaßtwerden:

➢ der Name der Trace-Datei kann beliebig vorgegeben werden,

➢ die Dienstklassen, für die der Trace aktiviert werden soll, könneneingestellt werden,

➢ die Trace-Tiefe (Trace ausgeschaltet, Trace nur für negativeEreignisse eingeschaltet etc.) kann bestimmt werden,

➢ das Target des Trace gibt an, ob eine Trace-Datei neu angelegt,eine alte Trace-Datei verwendet oder in den internen Umlaufpuf-fer geschrieben werden soll.

Während des laufenden Betriebs schreibt die S7-Library wichtige Da-ten in die Trace-Datei. Der Inhalt der Datei

➢ dient als Protokoll über sämtliche Aktionen, die von derS7-Library durchgeführt wurden,

➢ erlaubt eine Ablaufkontrolle sowohl der Applikation als auch derLibrary selbst,

➢ ermöglicht ein einfaches Debuggen und Überprüfen der Datenund Parameter an der SAPI-S7-Programmierschnittstelle.

Weiter können Sie die Trace-Datei selbst beschreiben. Durch solcheEintragungen ist es möglich, wichtige Daten zu Kontrollzwecken zusichern, den Programmablauf zu kontrollieren bzw. mit den Eintragun-gen durch die Library zu synchronisieren.

Der Trace mit der Ablage der Daten in die Trace-Datei verlangsamtdas Anwendungsprogramm. Deshalb gibt es zusätzlich die Möglichkeit,den Umlaufpuffer als Schnappschuß in eine Datei zu schreiben.

Was versteht manunter dem Trace?

Nutzen des Trace

Zeitverhalten


23

2.7 Die Mini-DB

Mit Hilfe der Mini-DB (Mini-Datenbasis) können Abweichungen vomStandard-Betriebsfall eingestellt und detaillierte Informationen ausge-lesen werden. Die Mini-DB stellt einen Datenbereich innerhalb derS7-Library dar,

➢ in dem immer wieder (in der Regel unverändert) benötigte Datenabgelegt sind,

➢ in dem protokollspezifische Daten abgelegt sind bzw. im laufen-den Betrieb abgelegt werden,

➢ in dem die Kennungen des zuletzt aufgetretenen Fehlers hinter-legt werden,

➢ der durch Funktionen wie 's7_mini_db_get()', 's7_mini_db_set()'etc. auslesbar und veränderbar ist.

Die S7-Library ermöglicht einen Betrieb mit Default-Einstellungen fürden Trace, den Aufbau von S7-Verbindungen (aktiv und passiv) etc.Diese Default-Einstellungen sind für einen Großteil der Anwendungsfäl-le ausreichend, können aber durch einen Mini-DB-Aufruf jederzeit ge-ändert und an die jeweiligen Anforderungen angepaßt werden.

Die Verwendung einer Mini-DB in der S7-Library bietet folgende Vortei-le:

➢ Die Programmierschnittstelle kann auf wenige Übergabeparame-ter vereinfacht werden. Die (eventuell immer unverändert) be-nötigten Werte werden aus der Mini-DB gelesen. Dies erhöht diePerformance und vereinfacht das Handling der SAPI-S7-Pro-grammierschnittstelle.

➢ Die hohe Flexibilität, die das Protokoll S7 bietet, bleibt erhalten.Eine Änderung der Einstellungen und deren Anpassung an dieeigenen Bedürfnisse ist jederzeit durch Mini-DB-Aufrufe möglich.

Zweck der Mini-DB

Vorteile derMini-DB


24

2.8 Multi-CP- und Multi-User-Betrieb

Unter einem Multi-CP-Betrieb versteht man die Fähigkeit, von einerApplikation auf einem Rechner

➢ mehrere CPs ansprechen zu können.

➢ die mit den verschiedenen CPs per Vernetzung verbundenenPartnerstationen ansprechen zu können.

Bei einem Multi-User-Betrieb können die angebotenen Dienste undRessourcen von mehreren Applikationen eines Rechners gleichzeitig,d. h. ohne gegenseitige Beeinflussung, in Anspruch genommen wer-den.

Voraussetzung für einen Multi-CP- und Multi-User-Betrieb ist, daß Re-quests und Confirmations einerseits sowie Indications und Responsesandererseits unmißverständlich einander und auch der zugehörigenApplikation zugeordnet werden können.

Diese Voraussetzung wird erreicht durch eine Anmeldefunktion derSAPI-S7-Programmierschnittstelle. Eine Anmeldung erfolgt

➢ für einen CP und

➢ für ein VFD dieses CP.

Mit dem VFD sind die VFD-eigenen S7-Verbindungen für die Applikati-on verfügbar (Bild 2.5). Eine weitere Anmeldung für das VFD ist wedervon dieser noch von einer anderen Applikation aus möglich, währendeine Anmeldung für den CP durchaus mehrfach möglich ist.

Multi-CP-Betrieb

Multi-User-Betrieb

Voraussetzungen


25

2.8.1 Zuordnung von VFD und S7-Verbindungsliste

Eine Applikation kann sich bei mehreren VFDs auf einem oder aufverschiedenen CPs anmelden. Multi-CP- und Multi-User-Betrieb setzenvoraus, daß ein VFD nach Anmeldung eindeutig einer Applikation zu-geordnet werden kann (1 : n - Zuordnung). Mit der Anmeldung beimCP und bei der ausgewählten VFD stehen aus der S7-Verbindungslistedes CPs diejenigen Verbindungen zur Verfügung, die durch Projektie-rung dem VFD zugeordnet sind. Beispielsweise ist im nachfolgendenBild eine Kommunikation über die Verbindungen 'V1', 'V2' und 'V3'nach Anmeldung bei 'CP 1' und 'VFD 1' möglich.

CP 1 CP 2

V6 V7 V8

S7-VerbindungslisteS7-Verbindungsliste

V1 V2 V3 V4 V5

Applikation 3Applikation 2

VFD 3 VFD 4

Applikation 1

VFD 1 VFD 2

Bild 2.5: Zuordnung der Liste der S7-Verbindungen bei einer Anmeldung an VFD 1 aufCP 1

ZusammenhangVFD und S7-Ver-bindungsliste


26

2.9 Installation und Betriebsvoraussetzungen

Die zur Installation notwendigen Arbeitsschritte sind den jeweiligenProduktbeschreibungen zu entnehmen und nicht Gegenstand dieserUnterlage.

Für den Betrieb der S7-Library muß sich das Kommunikationssystemin einem betriebsbereiten Zustand befinden, d. h. VFD und S7-Verbin-dungslisten müssen projektiert worden sein. Diese Aufgaben werdennicht von der SAPI-S7-Programmierschnittstelle übernommen.

Installation

Betriebsvoraus-setzungen

B89077/07 S7-Programmierschnittstelle

27

3 Die Programmierschnittstelle

Im folgenden Kapitel lernen Sie die praktische Anwendung der S7-Program-mierschnittstelle für die Programmiersprache 'C' kennen.

Den Umgang mit den Aufrufen der Programmierschnittstelle, die Ihnen den Zugang zuden Diensten und Objekten von S7 ermöglichen, lernen Sie in den folgenden Unter-kapiteln anhand von Beispielprogrammen kennen. Die Beispiele

➢ beschreiben eindeutig und übersichtlich die einzuhaltenden Reihenfolgen für ei-nen erfolgreichen Kommunikationsverlauf,

➢ stellen die Programmierschnittstelle Schritt für Schritt vor,

➢ bauen aufeinander auf, wobei neue Funktionen oder veränderteProgrammsegmente des vorhergehenden Beispiels fettgedruckt dargestelltwerden,

➢ realisieren eine Fehlerbehandlungsroutine, die von Ihnen auf Ihre jeweiligenAnforderungen angepaßt werden sollte.

Die S7-Funktionen werden in den Beispielprogrammen nicht direkt aufgerufen, sondernin eigene Funktionen (z. B. 'my_init()' für 's7_init()') gekapselt. Dies ist nicht zwingenderforderlich, macht das Programm aber besser geeignet für Debugging, Fehlerausga-ben und nachträgliche Erweiterungen.

Am Ende dieses Kapitels wissen Sie,

➢ welche Dienste im einzelnen auf einem Host-System zur Verfügung stehen,

➢ für welche Aufgaben die einzelnen Dienste zu verwenden sind,

➢ welche Kommunikationsabläufe durch eine Dienstanforderung und Dienstbestä-tigung entstehen,

➢ welche Aufruf- und Ablaufstruktur Sie allgemein an derS7-Programmierschnittstelle vorfinden.

Sie sind dann mit den Grundlagen der S7-Programmierschnittstelle soweit vertraut,daß Sie die Programmierung einer SAPI-S7-Anwendung angehen können.

S7-Programmierschnittstelle B89077/07

28

3.1 Übersicht über die Programmierschnittstelle

Die S7-Programmierschnittstelle bietet folgende Dienste:

➢ Administrative Dienste

➢ Empfangsaufrufdienst

➢ S7-Verbindungsmanagementdienste

➢ Variablendienste

➢ Blockorientierte Dienste

➢ Meldedienste

➢ VFD-Dienste

➢ Diagnosedienste für hochverfügbare Verbindungen

Einteilung derDienste


29

3.1.1 Administrative Dienste

Als administrative Dienste stehen Funktionen zum Auslesen von Pro-jektierinformationen und zum An- und Abmelden beim Kommunikati-onssystem zur Verfügung. Außerdem gibt es Funktionen, die Referen-zen für symbolische S7-Verbindungsnamen liefern.

Die folgende Tabelle gibt einen Überblick über die administrativenDienste. Eine genaue Beschreibung finden Sie in Kapitel 3.2 auf Sei-te 43.

s7_get_device() Mit dieser Funktion können alle in-stallierten CP-Namen abgefragtwerden.

s7_get_vfd() Mit dieser Funktion können alleprojektierten VFDs eines CP abge-fragt werden, denen Verbindungenzugeordnet wurden.

s7_init() Mit dieser Funktion meldet sich dasAnwenderprogramm beim Kommu-nikationssystem an.

s7_get_cref() Diese Funktion liefert eine Referenzzu einem symbolischen S7-Verbin-dungsnamen. Dieser Wert selektiertdie reale Verbindung im Netz und isthandlicher als der symbolische Na-me.

s7_get_conn() Diese Funktion liefert alle symboli-schen S7-Verbindungsnamen beimangemeldeten VFD sowie derenReferenz zurück.

s7_shut() Mit dieser Funktion meldet sich dasAnwenderprogramm beim Kommu-nikationssystem ab.

Beschreibung


30

3.1.2 Empfangsaufrufdienst

Dienst zum Abholen von Nachrichten.

Eine genaue Beschreibung finden Sie in Kapitel 3.3.1 auf Seite 55.

s7_receive() Mit dieser Funktion holt sich dasAnwenderprogramm empfangeneNachrichten beim Kommunikations-system ab.

3.1.3 S7-Verbindungsmanagementdienste

Die S7-Verbindungsmanagementdienste werden zum Auf- und Abbauvon S7-Verbindungen benötigt.

Die folgende Tabelle gibt einen Überblick über die Verbindungsmana-gementdienste beim aktiven Verbindungsaufbau. Eine genaue Be-schreibung finden Sie ab Kapitel 3.4.1 auf Seite 63.

s7_initiate_req() Diese Funktion leitet einen Auftragzum aktiven Aufbau einer S7-Ver-bindung an das Kommunikations-system weiter.

s7_get_initiate_cnf() Diese Funktion nimmt das Ergebnisdes obigen Aufrufs entgegen.

Beschreibung

Beschreibung

Aktiver Verbin-dungsaufbau


31

Die folgende Tabelle gibt einen Überblick über die Verbindungsmana-gementdienste beim passiven Verbindungsaufbau. Eine genaue Be-schreibung finden Sie ab Kapitel 3.4.3 auf Seite 65.

s7_await_initiate_req() Diese Funktion bereitet das Kom-munikationssystem zum Empfangeines passiven S7-Verbindungs-aufbauwunsches vor.

s7_get_await_initiate_cnf() Diese Funktion nimmt das Ergebnisdes obigen Aufrufs entgegen.

s7_get_initiate_ind() Diese Funktion schließt die Entge-gennahme einer Initiate Indicationab.

s7_initiate_rsp() Der Aufbauwunsch kann mit dieserFunktion akzeptiert oder auch abge-lehnt werden.

Die folgende Tabelle gibt einen Überblick über die Verbindungsmana-gementdienste bei Verbindungsabbruch. Eine genaue Beschreibungfinden Sie ab Kapitel 3.4.7 auf Seite 70.

s7_abort() Diese Funktion bricht eine aufge-baute S7-Verbindung ab.

s7_get_abort_ind() Diese Funktion schließt die Entge-gennahme einer Abort Indication ab.

Passiver Verbin-dungsaufbau

Verbindungs-abbruch


32

3.1.4 Variablendienste

Bei den Variablendiensten stehen Funktionen zum Lesen und Schrei-ben einer oder mehrerer Variablen zur Verfügung.

Die folgende Tabelle gibt einen Überblick über die Variablendienstebeim Lesen und Schreiben einer Variablen. Eine genaue Beschreibungfinden Sie ab Kapitel 3.5.1 auf Seite 79.

s7_read_req() Mit dieser Funktion wird ein Va-riablen-Leseauftrag eingeleitet.

s7_get_read_cnf() Diese Funktion nimmt den gele-senen Variablenwert entgegen.

s7_write_req() Diese Funktion leitet einen Vari-ablen-Schreibauftrag ein.

s7_get_write_cnf() Diese Funktion nimmt das Ergeb-nis des obigen Aufrufs entgegen.

Die folgende Tabelle gibt einen Überblick über die Variablendienstebeim Lesen und Schreiben mehrerer Variablen. Eine genaue Beschrei-bung finden Sie ab Kapitel 3.5.6 auf Seite 90.

s7_multiple_read_req() Mit dieser Funktion wird ein Auf-trag zum Lesen mehrerer Varia-blen eingeleitet.

s7_get_multiple_read_cnf() Diese Funktion nimmt die gele-senen Variablenwerte entgegen.

s7_multiple_write_req() Diese Funktion leitet einen Auf-trag zum Schreiben mehrerer Va-riablen ein.

s7_get_multiple_write_cnf() Diese Funktion nimmt die Er-gebnisse des obigen Aufrufs ent-gegen.

Beschreibung

Lesen undSchreiben einerVariablen

Lesen undSchreibenmehrerer Variablen


33

Die folgende Tabelle gibt einen Überblick über die Variablendienstebeim zyklischen Lesen mit mehreren Aufrufen. Eine genaue Beschrei-bung finden Sie ab Kapitel 3.5.10 auf Seite 101.

s7_cycl_read_init_req() Mit dieser Funktion wird der Ser-ver veranlaßt, ein zyklisches Le-sen von Variablen vorzubereiten.

s7_get_cycl_read_init_cnf() Diese Funktion nimmt das Ergeb-nis des obigen Aufrufs entgegen.

s7_cycl_read_start_req() Mit dieser Funktion wird der Ser-ver veranlaßt, ein zyklisches Le-sen von Variablen zu starten.

s7_get_cycl_read_start_cnf() Diese Funktion nimmt das Ergeb-nis des obigen Aufrufs entgegen.

Die folgende Tabelle gibt einen Überblick über die Variablendienstebeim zyklischem Daten entgegennehmen. Eine genaue Beschreibungfinden Sie ab Kapitel 3.5.14 auf Seite 107.

s7_get_cycl_read_ind() Mit dieser Funktion werden dievom Server gesendeten Datenentgegengenommen.

Die folgende Tabelle gibt einen Überblick über die Variablendienstebeim Anhalten und Beenden des zyklischen Lesens. Eine genaue Be-schreibung finden Sie ab Kapitel 3.5.15 auf Seite 109.

s7_get_cycl_read_abort_ind() Diese Funktion schließt die Ent-gegennahme einer Cyclic ReadAbort Indication ab.

s7_cycl_read_stop_req() Mit dieser Funktion wird derServer veranlaßt, ein zyklischesLesen von Variablen anzuhalten.

s7_get_cycl_read_stop_cnf() Diese Funktion nimmt das Er-gebnis des obigen Aufrufs entge-gen.

s7_cycl_read_delete_req() Mit dieser Funktion wird das zy-klische Lesen abgebrochen undbeim Server abgemeldet.

s7_get_cycl_read_delete_cnf() Diese Funktion nimmt das Er-gebnis des obigen Aufrufs entge-gen.

Zyklisches Lesenmit mehreren Auf-rufen anstoßen

Zyklische Datenentgegennehmen

Zyklisches Lesenanhalten undbeenden


34

Die folgende Tabelle gibt einen Überblick über den Variablendienst„Zyklisches Lesen mit einem Anruf anstoßen“. Eine genaue Beschrei-bung finden Sie ab Kapitel 3.5.20 auf Seite 114.

s7_cycl_read() Mit dieser Funktion wird derServer veranlaßt, ein zykli-sches Lesen von Variablenvorzubereiten und sofort zustarten.

Zyklisches Lesenmit einem Anrufanstoßen


35

3.1.5 Blockorientierte Dienste

Die blockorientierten Diensten bieten Funktionen zum Datenaustauschvon bis zu 65534 Byte. Sie setzen eine zweiseitige Verbindungsprojek-tierung voraus (STEP 7, COML S7).

Die folgende Tabelle gibt einen Überblick über die blockorientiertenDienste. Eine genaue Beschreibung finden Sie ab Kapitel 3.6.1 aufSeite 123.

s7_bsend_req() Mit dieser Funktion kann eineClient-Applikation bis zu64 kbyte Daten an eine remoteStation senden.

s7_get_bsend_cnf() Mit dieser Funktion wird dasErgebnis des BSEND-Auftragsentgegengenommen.

s7_brcv_init() Mit dieser Funktion wird dyna-misch Puffer bereitgestellt, umfür den Empfang von BSEND-Daten bereit zu sein, die vonder remoten Station gesendetwerden.

s7_get_brcv_ind() Mit dieser Funktion werden dievom Partner gesendeten Net-todaten in den angegebenenSpeicherbereich kopiert.

s7_brcv_stop() Mit dieser Funktion wird dervon s7_brcv_init belegte Pufferwieder freigegeben, d. h. dieKommunikation zum remotenBSEND ist nicht mehr möglich.

Beschreibung


36

3.1.6 Meldedienste

Mit diesen Diensten können Meldungen vom SIMATIC S7-Automati-sierungssystem empfangen und weiterverarbeitet werden.

Der SCAN–Dienst gehört zu den projektierten oder auch symbolbezo-genen, der ALARM–Dienst zu den programmierten oder auch bau-steinbezogenen Meldediensten. Eine genaue Beschreibung finden Sieab Kapitel 3.7 auf Seite 131.

Die eintreffenden Telegramme enthalten den Zeitstempel, die Mel-dungsnummer (Event-ID) sowie den Ereignis- und Quittierungszustanddes Ereignisses. Optional können Begleitwerte mitgesendet werden.

Die folgende Tabelle gibt einen Überblick über die Meldedienste.

s7_msg_initiate_req() Mit dieser Funktion informierteine Client-Applikation die re-mote Station, daß sie Meldun-gen empfangen möchte.

s7_get_msg_initiate_cnf() Mit dieser Funktion wird dasErgebnis dess7_msg_initiate_req-Auftragsentgegengenommen.

s7_msg_abort_req() Mit dieser Funktion informierteine Client-Applikation die re-mote Station, daß sie keineMeldungen mehr empfangenmöchte.

s7_get_msg_abort_cnf() Mit dieser Funktion wird dasErgebnis dess7_get_msg_abort_cnf-Auftrags entgegengenommen.

s7_get_scan_ind() Mit dieser Funktion werden dievon der remoten Station ge-sendeten Daten entgegenge-nommen, wenn beims7_receive-Aufruf die Anzeige„S7_SCAN_IND“ kam.

s7_get_alarm_ind() Mit dieser Funktion werden dievon der remoten Station ge-sendeten Daten entgegenge-nommen, wenn beims7_receive-Aufruf die Anzeige„S7_ALARM_IND“ kam

Beschreibung


37

3.1.7 VFD-Dienste

Die folgende Tabelle gibt einen Überblick über die VFD-Dienste. Einegenaue Beschreibung finden Sie ab Kapitel 3.8.1 auf Seite 156.

s7_vfd_state_req() Mit dieser Funktion wird dieAbfrage des Geräte-/Anwender-status initiiert.

s7_get_vfd_state_cnf() Diese Funktion nimmt den Ge-räte-/Anwenderstatus entgegen.

Beschreibung


38

3.1.8 Diagnosedienste für hochverfügbare Verbindungen

Eine hochverfügbare Verbindung ist die Kommunikationsverbindungzwischen einem hochverfügbaren System und einem anderen hochver-fügbaren oder Standardsystem.

Im Gegensatz zu einer Standardverbindung besteht eine hochverfüg-bare Verbindung aus mindestens zwei redundanten Verbindungen(konfigurationsabhängig maximal vier redundante Verbindungen).

Die gerade aktive redundante Verbindung wird auch als Produktivver-bindung, die andere(n) als Standby-Verbindungen bezeichnet.

Über die SAPI-S7-Funktionen lassen sich neben StandardS7-Verbindungen auch hochverfügbare Verbindungen zuSIMATIC S7-H-Systemen aufbauen, sofern S7-H-CPUs und entspre-chend freigegebene SIMATIC NET-Produkte eingesetzt werden. Diehochverfügbaren Verbindungen müssen mit STEP 7 projektiert werdenund sowohl in die SIMATIC S7 geladen als auch in Form einer XDB-Datei auf den PC kopiert werden.

Die folgende Tabelle gibt einen Überblick über die Diagnosedienste fürhochverfügbare Verbindungen. Eine genaue Beschreibung finden Sieab Kapitel 3.9 auf Seite 159.

s7_diag_init Anmelden der DiagnoseEs werden Diagnosemeldungenempfangen.

s7_get_diag_ind Diagnosedaten abholen

s7_diag_stop Abmelden von der DiagnoseEs werden keine Diagnosemel-dungen mehr empfangen.

Die Diagnosedienste funktionieren auch bei Standardverbindungen,sind aber dort weniger sinnvoll.

Definition

Beschreibung


39

3.2 Administrative Dienste

Das nachfolgende Beispiel beschreibt die administrativen Dienste zumAn- ('s7_init()') und Abmelden ('s7_shut()') einer S7-Applikation beimKommunikationssystem. Eine Kommunikation mit einem lokalen CPund damit auch mit einem remoten CP ist erst nach erfolgreichemAnmelden möglich. Da bei der Anmeldung beim lokalen VFD die VFD-eigenen Ressourcen für die anmeldende Applikation reserviert werden,muß vor dem Programmende für jede Anmeldung auch eine Abmel-dung erfolgen.

Die zum Anmelden benötigten Übergabeparameter, wie der CP-Nameund der VFD-Name, können mit Hilfe der Funktionen's7_get_device()' bzw. mit 's7_get_vfd()' vom Kommunikationssy-stem erfragt werden.

Beschreibung desBeispiels


40

Beispiel

#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);

}}


41

/* 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);

}


42


s7_get_device()

remoter Partner

= S7_OK,

s7_get_vfd()

number!=0

s7_init()

= S7_OK

s7_shut()

= S7_OK

number!=0

= S7_OK,

s7_get_cref()

= S7_OK

Bild 3.1: Ablaufdiagramm für das Beispiel

Ablaufdiagramm


43

3.2.1 s7_get_device

Mit diesem Aufruf können die konfigurierten Namen der installiertenKommunikationsprozessoren vom Kommunikationssystem abgefragtwerden. Die Namen sind für die Anmeldung mit 's7_init()' relevant.

int32 s7_get_device(

ord16 index, /* Vorgabe */ord16 *number_ptr, /* Rückgabe */char *dev_name /* Rückgabe */

)

index Der Parameter 'index' selektiert einen der vorhande-nen CPs, die mit 0 beginnend fortlaufend numeriertsind.

number_ptr Adresse einer vom Anwenderprogramm bereitgestell-ten Variablen vom Typ 'ord16'. Hier wird die Anzahlder installierten CPs zurückgeliefert.

dev_name Anfangsadresse eines vom Anwenderprogrammbereitgestellten Speicherbereichs, in dem ein konfi-gurierter CP-Name eingetragen wird. Der Speicher-bereich sollte mindestens(S7_MAX_DEVICELEN + 1) Byte groß sein für denmaximal S7_MAX_DEVICELEN Byte langenCP-Namen plus String-Endekennung.

Zum Abfragen aller CPs verwenden Sie am besten eine Programm-schleife. Der Parameter 'index' wird als Schleifenvariable verwendetund läuft von 0 bis '*number_ptr-1'. Der Parameter '*number_ptr' wirdmit 1 vorbesetzt.

Beschreibung

Deklaration

Parameter

Abfrage aller CPs


44

S7_OK Die Funktion konnte ohne Fehler abgearbeitetwerden.

S7_ERR_RETRY Dieser Wert zeigt einen Fehler bei der Ausführungdes angeforderten Dienstes an. Dabei handelt essich um ein temporär aufgetretenes Problem, wiez. B. um einen vorübergehenden Speicherengpaß.Der Aufruf kann ohne Änderung der Übergabepa-rameter wiederholt werden.

S7_ERR Dieser Wert zeigt ebenfalls einen Fehler bei derAusführung des angeforderten Dienstes an. Aller-dings handelt es sich hierbei um einen Fehler, derein wiederholtes Ausführen des Dienstes nicht er-laubt. Hier müssen weitere Schritte zur Fehlerbe-hebung, wie das Versorgen des Aufrufs mit ande-ren Parametern, eingeleitet werden.

Return-Werte


45

3.2.2 s7_get_vfd

Mit diesem Aufruf können die projektierten VFDs eines Kommunikati-onsprozessors abgefragt werden, denen Verbindungen zugeordnetwurden. Die VFD-Namen sind für die Anmeldung mit 's7_init()' rele-vant.

int32 s7_get_vfd(

char *dev_name, /* Vorgabe */ord16 index, /* Vorgabe */ord16 *number_ptr, /* Rückgabe */char *vfd_name /* Rückgabe */

)

dev_name Konfigurierter Name des Kommunikationsprozessors,über den kommuniziert werden soll. Für diesen Pa-rameter wird üblicherweise ein mit 's7_get_device()'ausgelesener CP-Name verwendet. Er muß mit ei-nem konfigurierten CP-Namen übereinstimmen (z. B.'CP_L2_1:').

index Der Parameter 'index' selektiert eines der vorhande-nen VFDs, die mit 0 beginnend fortlaufend numeriertsind.

number_ptr Adresse einer vom Anwenderprogramm bereitgestell-ten Variablen vom Typ 'ord16'. Hier wird die Anzahlder projektierten VFDs zurückgeliefert.

vfd_name Anfangsadresse eines vom Anwenderprogrammbereitgestellten Speicherbereichs, in dem ein projek-tierter VFD-Name eingetragen wird. Der Speicherbe-reich sollte mindestens (S7_MAX_NAMLEN + 1)Byte für den maximal S7_MAX_NAMLEN Byte lan-gen VFD-Namen plus String-Endekennung groß sein.

Zum Abfragen aller VFDs verwenden Sie am besten eine Programm-schleife. Der Parameter 'index' wird als Schleifenvariable verwendetund läuft von 0 bis '*number_ptr-1'. Der Parameter '*number_ptr' wirdmit 1 vorbesetzt.

Beschreibung

Deklaration

Parameter

Abfrage aller VFDs


46




Return-Werte


47

3.2.3 s7_init

Mit diesem Aufruf meldet sich ein Anwenderprogramm bei einem VFDeines unterlagerten Kommunikationssystems an.

Das Anwenderprogramm gibt als Eingabeparameter den konfiguriertenNamen des Kommunikationsprozessors, über den er kommunizierenmöchte, und den projektierten Namen des VFD vor, deren Ressourcenund Dienste genutzt werden sollen.

Zurück erhält es einen Descriptor 'cp_descr', der bis zur Abmeldungder Applikation bei allen folgenden Aufrufen als Adressierungsparame-ter für den selektierten CP und das VFD mitgegeben wird.

Bei der Anmeldung wird die Projektierinformation (z. B. die Liste allerS7-Verbindungen) aus einer Datei ausgelesen, deren Name sich ausdem CP-Namen wie folgt ableitet: Entfernen des Doppelpunkts, mitdem der CP-Name abschließt, und Anhängen der Namenserweiterung'.LDB'. Dabei wird vorausgesetzt, daß sich die Datei im aktuellen Ar-beitsverzeichnis befindet. Als Alternative hierzu kann über Environ-mentvariablen der Name der Projektierdatei frei vorgegeben werden.

Bei paralleler Benutzung von mehreren VFDs in einem oder mehrerenKommunikationsprozessoren durch eine Applikation sind entsprechendviele Aufrufe 's7_init()' notwendig.

int32 s7_init(

char *cp_name, /* Vorgabe */char *vfd_name, /* Vorgabe */ ord32 *cp_descr_ptr /* Rückgabe */

)

Beschreibung

Deklaration


48

cp_name Konfigurierter Name des Kommunikationsprozes-sors, über den kommuniziert werden soll. Um einebestimmte Baugruppe anzusprechen, verwendetdas Anwenderprogramm einen mit demSIMATIC NET Installations-Tool konfiguriertenCP-Namen (z. B. 'CP_L2_1:'). Hier wird üblicher-weise ein mit 's7_get_device()' ausgelesener CP-Name verwendet.

vfd_name Projektierter Name des lokalen VFD, auf die sichdie Applikation anmeldet. Um ein bestimmtesVFD anzusprechen, verwendet das Anwenderpro-gramm einen mit dem SIMATIC NET Projektier-Tool festgelegten VFD-Namen. Mit dem VFD wer-den auch die S7-Verbindungen selektiert. Hierwird üblicherweise ein mit 's7_get_vfd()' ausgele-sener VFD-Name verwendet.

cp_descr_ptr Adresse einer vom Anwenderprogramm bereitge-stellten Variablen vom Typ 'ord32'. Hier wird einDescriptor zur Adressierung des ausgewähltenKommunikationsprozessors und dem VFD abge-legt. Dieser Parameter muß für die weitere Kom-munikation über den gewählten Kommunikations-prozessor und das VFD benutzt werden.




Parameter

Return-Werte


49

3.2.4 s7_get_cref

Die S7-Applikation sieht vom Kommunikationssystem nur den symboli-schen Namen der S7-Verbindung, der zur Laufzeit unhandlich ist. Des-halb besorgt sich die Applikation über den Aufruf 's7_get_cref()' eineReferenz auf einen symbolischen Verbindungsnamen.

int32 s7_get_cref(

ord32 cp_descr, /* Vorgabe */char *conn_name, /* Vorgabe */ord16 *cref_ptr /* Rückgabe */

)

cp_descr Handle als Rückgabewert des 's7_init()'-Aufrufs.

conn_name Symbolischer Name der S7-Verbindung, über diekommuniziert werden soll.

cref_ptr Adresse einer vom Anwenderprogrammbereitgestellten Variablen vom Typ 'ord16'. Hierwird die ermittelte Verbindungsreferenzzurückgegeben.




Beschreibung

Deklaration

Parameter

Return-Werte


50

3.2.5 s7_get_conn

Mit diesem Aufruf können die S7-Verbindungen eines VFDs auf einemKommunikationsprozessor und deren Referenzen abgefragt werden.Dieser Wert selektiert die reale Verbindung im Netz und ist handlicherals der symbolische Name.

int32 s7_get_conn(

ord32 cp_descr, /* Vorgabe */ord16 index, /* Vorgabe */ord16 *number_ptr, /* Rückgabe */ord16 *cref_ptr, /* Rückgabe */char *conn_name /* Rückgabe */

)


index Der Parameter 'index' selektiert eine der vorhande-nen S7-Verbindungen, die mit 0 beginnend fortlau-fend numeriert sind.

number_ptr Adresse einer vom Anwenderprogramm bereitgestell-ten Variablen vom Typ 'ord16'. Hier wird die Anzahlder S7-Verbindungen zurückgeliefert.

cref_ptr Adresse einer vom Anwenderprogramm bereitgestell-ten Variablen vom Typ 'ord16'. Hier wird die ermittel-te Verbindungsreferenz zurückgegeben.

conn_name Anfangsadresse eines vom Anwenderprogrammbereitgestellten Speicherbereichs, in dem ein S7-Verbindungsname eingetragen wird. Der Speicherbe-reich sollte mindestens (S7_MAX_NAMLEN + 1)Byte für den maximal S7_MAX_NAMLEN Byte lan-gen Verbindungsnamen plus String-Endekennunggroß sein.

Zum Abfragen aller S7-Verbindungen verwenden Sie am besten eineProgrammschleife. Der Parameter 'index' wird als Schleifenvariableverwendet und läuft von 0 bis '*number_ptr-1'. Der Parameter'*number_ptr' wird mit 1 vorbesetzt.

Beschreibung

Deklaration

Parameter

Abfrage allerS7-Verbindungen


51




Return-Werte


52

3.2.6 s7_shut

Mit dem Aufruf 's7_shut()' macht die Applikation eine durch den CP-Descriptor gekennzeichnete Anmeldung ('s7_init()') beim Kommunika-tionsprozessor rückgängig. Dabei werden alle beim Anmelden belegtenRessourcen des Kommunikationssystems zurückgegeben und aufge-baute Verbindungen abgebrochen. Dieser Aufruf muß daher unbedingtvor dem Programmende für jede einzelne Anmeldung abgesetzt wer-den.

int32 s7_shut(

ord32 cp_descr /* Vorgabe */

)

cp_descr Handle als Rückgabewert des 's7_init()'-Aufrufs.Er kennzeichnet die Anmeldung, die rückgängiggemacht werden soll.




Beschreibung

Deklaration

Parameter

Return-Werte


53

3.3 Empfangsaufrufdienst

Als Erweiterung zum Beispiel aus Kapitel 3.2 wird mit Hilfe des Emp-fangsaufrufs 's7_receive()' auf eine eventuell vorhandene Nachrichtgeprüft. Eine Nachricht wird in diesem einfachen Fall nicht erwartet('S7_NO_MSG' als Return-Wert); das Beispiel dient lediglich als Vor-bereitung für nachfolgende Programme.

Beispiel

::/* 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);

}


ord16 cref;



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


}



54


s7_receive()

remoter Partner

= S7_NO_MSG


Ablaufdiagramm


55

3.3.1 s7_receive

Diese Empfangsfunktion der S7-Library hat die zentrale Aufgabe, vomunterlagerten Kommunikationssystem empfangene Ereignisse zu ana-lysieren und ohne weitere Bearbeitung direkt an die Applikation zumelden.

Der Aufruf 's7_receive()' ist zwingend notwendig, wenn der Client

➢ quittierte Aufrufe abgesetzt hat und auf die zugehörige Quittungdes Servers wartet,

➢ unquittierte Nachrichten vom Netz empfangen will,

➢ Sequenzaufträge abgesetzt hat (z. B. Aufbau einer S7-Verbin-dung), um so die Bearbeitung der Dienstsequenz bis zu derenEnde zu gewährleisten.

Der Rückgabewert der Funktion 's7_receive()' liefert bei Empfang einerNachricht eine Dienstkennung. Diese identifiziert die Dienstart derempfangenen Antwort (z. B. 'S7_READ_CNF', wenn eine Variablegelesen wurde). Nach Erhalt einer Nachricht mit 's7_receive()' ist derAufruf der zugehörigen Bearbeitungsfunktion zwingend notwendig(z. B. 's7_get_read_cnf()'). Weitere Empfangsaufrufe werden sonst miteiner Fehlermeldung abgelehnt.

int32 s7_receive(

ord32 cp_descr, /* Vorgabe */ord16 *cref_ptr, /* Rückgabe */ord16 *orderid_ptr /* Rückgabe */

)

Beschreibung

Deklaration


56

cp_descr Handle als Rückgabewert des 's7_init()'-Aufrufs.Er kennzeichnet den Kommunikationsprozessorund das VFD, über die ein Ereignis abgeholt wer-den soll.

cref_ptr Adresse einer vom Anwenderprogramm bereitge-stellten Variablen vom Typ 'ord16'. Hier wird dieReferenz der S7-Verbindung, auf der eine Indica-tion oder eine Confirmation empfangen wurde,abgelegt. Sie entspricht der S7-Verbindungs-referenz, auf der der Auftrag abgegeben wurde.

orderid_ptr Adresse einer vom Anwenderprogramm bereitge-stellten Variablen vom Typ 'ord16'. Hier wird dasAuftragskennzeichen der erhaltenen Quittung ab-gelegt. Dieses dient dem Anwenderprogramm zurIdentifizierung des zuvor abgegebenen Auftrags.Die Order-ID ist bei unquittierten Diensten oderDiensten zum Aufbau einer S7-Verbindung nichtrelevant und wird mit einem Default-Wert belegt.

Parameter


57

S7_NO_MSG Es wurde keine Nachricht empfangen.

S7_UNKOWN_MSG Es wurde eine ungültige Nachricht empfangen;Fehler beim Verbindungspartner oder in dieserVersion der Programmierschnittstelle nichtunterstützter Dienst.

S7_ERR_RETRY Dieser Wert zeigt einen Fehler bei der Ausfüh-rung des angeforderten Dienstes an. Dabeihandelt es sich um ein temporär aufgetretenesProblem, wie z. B. um einen vorübergehendenSpeicherengpaß. Der Aufruf kann ohne Ände-rung der Übergabeparameter wiederholt wer-den.

S7_ERR Dieser Wert zeigt ebenfalls einen Fehler beider Ausführung des angeforderten Dienstes an.Allerdings handelt es sich hierbei um einenFehler, der ein wiederholtes Ausführen desDienstes nicht erlaubt. Hier müssen weitereSchritte zur Fehlerbehebung, wie das Versor-gen des Aufrufs mit anderen Parametern, ein-geleitet werden.

Neben diesen Werten werden je nach empfan-gener Nachricht weitere Dienstkennungen, wiez. B. 'S7_READ_CNF', zurückgeliefert. Dieentsprechenden Definitionen finden Sie in derDatei 'SAPI_S7.H'.

Beim Auftreten von nicht erwarteten Werten muß (z. B. im Default-Zweig der entsprechenden switch-Anweisung) die Funktions7_discard_msg aufgerufen werden.

In Single-Tasking-Betriebssystemen wie MS-DOS wird die Empfangs-funktion pollend aufgerufen. Für Multi-Tasking-Betriebssysteme wieMS-Windows besteht die Möglichkeit, die Empfangsfunktion an einerzentralen Wartestelle einzuklinken, um so alle Ereignisse empfangenzu können.

Return-Werte

Aufrufart


58

3.4 S7-Verbindungsmanagementdienste

Als Erweiterung zum Beispiel aus Kapitel 3.3 wird eine S7-Verbindungmit dem symbolischen Namen 'TEST' aufgebaut ('s7_initiate_req()')und nach Erhalt der Quittung ('s7_get_initiate_cnf()') wieder abgebro-chen ('s7_abort()').

Beispiel ::/* 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,"Errors7_initiate_req",ret);

}}



59

/* receive any message from communication system */static void my_receive(ord32 cp_descr,int32last_event_expected){ ord16 cref,orderid;

int32 ret;


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)&&

}


ord16 cref;



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

/* receive initiate confirmation */my_receive(cp_descr,S7_INITIATE_CNF);


}


60


s7_initiate_req()

remoter Partner

= S7_OK

s7_receive()

= S7_NO_MSG

s7_receive()

mehrfach wiederholen

= S7_INITIATE_CNF

s7_get_initiate_cnf()

= S7_OK

Anstoß zumS7-Verbindungsaufbau




Bild 3.3: Ablaufdiagramm für den aktiven S7-Verbindungsaufbau

Ablaufdiagrammfür den aktivenVerbindungs-aufbau


61


s7_await_initiate_req()

remoter Partner

= S7_OK

s7_receive()

= S7_NO_MSG


Vorbereiten desS7-Verbindungsaufbau




s7_receive()

= S7_AWAIT_INITIATE_CNF

s7_get_await_initiate_cnf()

= S7_OK

Bild 3.4: Ablaufdiagramm für das Vorbereiten zum passiven S7-Verbindungsaufbau

Ablaufdiagrammfür das Vorbereitenzum passivenVerbindungs-aufbau (nichtBestandteil desBeispiels)


62

SAPI-S7Anwenderprogramm remoter Partner

s7_receive()

= S7_INITIATE_IND

s7_get_initiate_ind()

= S7_OK

Indication abholen

Nachricht(Indication) da!

mehrfach wiederholen mehrfach wiederholen

s7_receive()

= S7_NO_MSG

Anstoß zumS7-Verbindungsaufbau

s7_initiate_rsp()

= S7_OK

Bild 3.5: Ablaufdiagramm für den passiven S7-Verbindungsaufbau

Ablaufdiagrammzum passivenVerbindungs-aufbau (nichtBestandteil desBeispiels)


63

3.4.1 s7_initiate_req

Mit dem Aufruf 's7_initiate_req()' wird der Aufbau einer S7-Verbindungangestoßen. Die Initiative zum Aufbau geht dabei vom Anwenderpro-gramm aus, die notwendigen Parameter werden aus der Mini-DB gele-sen. Dort können sie vom Anwenderprogramm ausgelesen, verändertund den jeweiligen Anforderungen angepaßt werden.

Beim Partner (Passivseite) werden die entsprechenden, durch Projek-tierung festgelegten Leistungsparameter mit den empfangenen Wertendes Auftrags verglichen. Die realisierbare Leistungsfähigkeit derS7-Verbindung (Sende-Credit, Empfangs-Credit, PDU-Größe, ... ) istdurch den jeweils kleineren der beidseitig möglichen Leistungsparame-ter bestimmt.

int32 s7_initiate_req(

ord32 cp_descr, /* Vorgabe */ord16 cref /* Vorgabe */

)


cref Referenz der S7-Verbindung, die aufgebaut wer-den soll.




Beschreibung

Deklaration

Parameter

Return-Werte


64

3.4.2 s7_get_initiate_cnf

Mit dem Aufruf 's7_get_initiate_cnf()' wird das Ergebnis einesS7-Verbindungsaufbaus entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_INITIATE_CNF', falls der Aufbauwunsch abgearbeitet wurde. Da-nach muß die zugehörige Bearbeitungsfunktion 's7_get_initiate_cnf()'zur internen Bearbeitung in der Library aufgerufen werden.

Die ausgehandelten Leistungsparameter (Sende-Credit, Empfangs-Credit, PDU-Größe) werden in der Mini-DB eingetragen und könnenanschließend mit Mini-DB-Aufrufen ausgelesen werden.

int32 s7_get_initiate_cnf(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


65

3.4.3 s7_await_initiate_req

Mit dem Aufruf 's7_await_initiate_req()' wird das Kommunikationssy-stem für Verbindungsaufbauwünsche vom remoten Partner vorbereitet.Die Initiate zum Verbindungsaufbau geht dabei von der Partnerstationaus, die notwendigen Parameter werden aus der Mini-DB gelesen. Dortkönnen sie vom Anwenderprogramm ausgelesen, verändert und denjeweiligen Anforderungen angepaßt werden.

int32 s7_await_initiate_req(


)






Beschreibung

Deklaration

Parameter

Return-Werte


66

3.4.4 s7_get_await_initiate_cnf

Mit dem Aufruf 's7_get_await_initiate_cnf()' wird das Ergebnis des's7_await_initiate_req()'-Auftrags entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_AWAIT_INITIATE_CNF', falls das Kommunikationsystem für einenVerbindungsaufbau vorbereitet wurde. Danach muß die zugehörigeBearbeitungsfunktion 's7_get_initiate_cnf()' zur internen Bearbeitung inder Library aufgerufen werden.

int32 s7_get_await_initiate_cnf(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


67

3.4.5 s7_get_initiate_ind

Mit dem Aufruf 's7_get_initiate_ind()' wird ein Aufbauwunsch einerS7-Verbindung von der remoten Seite entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_INITIATE_IND', falls der remote Partner eine S7-Verbindung auf-bauen möchte. Danach muß die zugehörige Bearbeitungsfunktion's7_get_initiate_ind()' zur internen Bearbeitung in der Library aufgeru-fen werden.

Mit dem Aufruf 's7_get_initiate_ind()' werden die Leistungsparameterder S7-Verbindung in der Mini-DB abgelegt. Anschließend könnenweitere Ereignisse vom Kommunikationssystem (z. B. über andereS7-Verbindungen) empfangen werden. Eine Zustimmung oder Ableh-nung des Aufbauwunsches kann mit dem Aufruf 's7_initiate_rsp()' zeit-lich verzögert erfolgen .

Durch diese Zweiteilung des passiven Aufbaus ist es möglich,

➢ bei einer einfachen Aufrufstruktur die Leistungsparameter vordem Aufbau zu überprüfen und

➢ den Aufbauwunsch einer anderen Applikation weiterzureichen,die ihrerseits darüber entscheidet (Applikation hat Gateway-Funktionalität).

int32 s7_get_initiate_ind(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


68

3.4.6 s7_initiate_rsp

Mit dem Aufruf 's7_initiate_rsp()' entscheidet das Anwenderprogrammüber den passiven Aufbauwunsch.

Der passive Aufbau einer S7-Verbindung ist zweigeteilt:

➢ mit dem Aufruf 's7_get_initiate_ind()' werden die Leistungspa-rameter in die Mini-DB eingetragen und können dort ausgelesenwerden. Anschließend ist es möglich, weitere Ereignisse vomKommunikationssystem (z. B. über andere S7-Verbindungen) zuempfangen.

➢ mit dem Aufruf 's7_initiate_rsp()' wird der Aufbauwunsch zu-stimmend oder ablehnend beantwortet.

int32 s7_initiate_rsp(

ord32 cp_descr, /* Vorgabe */ord16 cref, /* Vorgabe */ord16 accept /* Vorgabe */

)

cp_descr Descriptor des CP, über den der Aufbauwunscheiner S7-Verbindung gemeldet wurde.


accept Mit diesem Parameter kann der Aufbauwunschangenommen ('accept=S7_ACCEPT') oder auchabgewiesen werden ('accept=S7_NON_ACCEPT').

Beschreibung

Deklaration

Parameter


69




Return-Werte


70

3.4.7 s7_abort

Mit dem Aufruf 's7_abort()' wird eine bestehende S7-Verbindung un-quittiert und nicht verhandelbar abgebrochen.

Das Abholen einer Anwort mittels 's7_receive()' ist nicht notwendig, daes sich hierbei um einen unquittierten Dienst handelt. Noch nicht quit-tierte Aufträge dieser S7-Verbindung können anschließend eintreffenoder ganz ausbleiben.

int32 s7_abort(


)


cref Referenz der S7-Verbindung, die abgebrochenwerden soll.




Beschreibung

Deklaration

Parameter

Return-Werte


71

3.4.8 s7_get_abort_ind

Mit dem Aufruf 's7_get_abort_ind()' wird ein Abbruch einerS7-Verbindung durch eine remote Station oder den unterlagerten CPentgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_ABORT_IND', falls durch die remote Partnerstation oder durch denunterlagerten Kommunikationsprozessor die S7-Verbindung abgebro-chen wurde. Danach muß die zugehörige Bearbeitungsfunktion's7_get_abort_ind()' zur internen Bearbeitung in der Library aufgerufenwerden.

Bei S7 ist der Abbruch einer S7-Verbindung ein unquittierter Dienst.Noch nicht quittierte Aufträge dieser S7-Verbindung werden nicht mehrbestätigt.

int32 s7_get_abort_ind(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


72

3.5 Variablendienste

Als Erweiterung zum Beispiel aus Kapitel 3.4 wird über die aufgebauteS7-Verbindung ein Auftrag zum zyklischen Lesen einer Variablen('s7_cycl_read()') abgesetzt. Die empfangenen Daten werden mit Hilfeder Funktion 's7_get_cycl_read_ind()' in den Anwenderspeicher ko-piert. Der Zyklus wird mit 's7_cycl_read_delete_req()' beendet.

Die Adressierung von S7-Variablen erfolgt symbolisch. Diese Art desZugriffs orientiert sich an der Notation bei S7-Werkzeugen. Sie müs-sen sich also nicht verschiedene Notationen für Variablenadressenaneignen.

Beispiele:

DB5,X12.1 Datenbaustein 5, Datenbyte 12, Datenbit 1

DB5,B12 Datenbaustein 5, Datenbyte 12

DB5,W10 Datenbaustein 5, Datenwort 10

MB9,3 3 Merkerbyte ab Merkerbyte 9

DB5,W10,9 9 Worte im Datenbaustein 5, ab Datenwort 10

Syntax:

Die Syntax ist wie folgt definiert (Klein-/Großschreibung irrelevant):

DB<nr>, <typ> <index> ,<anzahl>

DI<nr>, <index>.<bitnr>

<bereich>

vorgeschrieben optional vorgeschrieben optional

Parameterbeschreibung:

DB bzw. DI Datenbaustein oder Instanzdatenbaustein

<nr> Nummer des Datenbausteins oder Instanzdatenbau-steins


symbolischeVariablen-adressierung


73

<bereich> A Ausgang

C Zähler - Details zu diesem Parametersind weiter unten in einem besonderenAbsatz beschrieben.

E Eingang

M Merker

PA Peripherieausgang

PE Peripherieeingang

T Timer - Details zu diesem Parametersind weiter unten in einem besonderenAbsatz beschrieben.

Z Zähler - Details zu diesem Parametersind weiter unten in einem besonderenAbsatz beschrieben.

<typ> B Byte (unsigned), 1 Byte

BYTE Byte (unsigned), 1 Byte

CHAR Byte (signed), 1 Byte

D Doppelwort (unsigned), 4 Byte

DINT Doppelwort (signed), 4 Byte

DWORD Doppelwort (unsigned), 4 Byte

INT Word (signed), 2 Byte

REAL Floating Point, 4 Byte

W Wort (unsigned), 2 Byte

WORD Wort (unsigned), 2 Byte

X Byte für Bereich DB und DI

Alle Datenbausteine sind bei S7 Byte-orientiert(S5 ist wortorientiert).

Beispiel:DB7,W10,5 DB8,REAL10,2

... ... ... ...W10 10 11 REAL10 10 11W12 12 13 12 13W14 14 15 REAL14 14 15W16 16 17 16 17W18 18 19 ... ...

... ...

<index> Elementnummer bezogen auf den Bausteinanfang.

<bitnr> Bit innerhalb der Elementnummer.

<anzahl> Anzahl der Variablen eines Typs, deren Werte ab<adresse> im <bereich> adressiert werden.


74

Die folgende Tabelle beschreibt die Bedeutung der einzelnen Bits derErgebnisdaten des Typs 'T' vom Parameter 'Bereich'.

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

Bedeutungssymbol 0 0 x x z z z z z z z z z z z z

Symbol '0' nicht relevant

Symbol 'x' Angabe des Zeitrasters

In der folgenden Tabelle wird die Bedeutung dermöglichen Werte von Bit 13 und 12 erklärt.

Bit 13 und 12 Zeitraster in Sekunden

00 0,01

01 0,1

10 1

11 10

Symbol 'z' BCD kodierter Zeitwert (0 bis 999)

Die folgende Tabelle beschreibt die Bedeutung der einzelnen Bits derErgebnisdaten des Typs 'C' oder 'Z' vom Parameters 'Bereich'.

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

Bedeutungssymbol 0 0 0 0 z z z z z z z z z z z z

Symbol '0' nicht relevant

Symbol 'z' BCD kodierter Zählerstand (0 bis 999)

Erläuterungen zumTyp 'T' desParameters'Bereich'

Erläuterungen zumTyp 'C' oder 'Z' desParameters'Bereich'


75

Beispiel

::/* 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);

}}


76

/* 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);

}}


int32 ret;


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));

}


77


ord16 cref;




/* receive cyclic read delete confirmation */my_receive(cp_descr,S7_CYCL_READ_DELETE_CNF);


}


78


s7_cycl_read()

remoter Partner

= S7_OK

s7_receive()

= S7_NO_MSG

s7_receive()


= S7_CYCL_READ_IND

s7_get_cycl_read_ind

= S7_OK

Anstoß zum zyklischen Leseneiner S7-Variablen

Indication abholen

Nachricht(Indication) da!



Ablaufdiagramm


79

3.5.1 s7_read_req

Mit dem Aufruf 's7_read_req()' kann eine Client-Applikation auf eineVariable eines Servers lesend zugreifen. Der Zugriff auf die Variablenkann nur per symbolischer Adresse erfolgen. Die Daten werden in derQuittung vom Server zum Client übertragen und werden mit Hilfe derentsprechenden Bearbeitungsfunktion für die Abschlußquittung('s7_get_read_cnf()') in den Anwenderpuffer übertragen.

int32 s7_read_req(

ord32 cp_descr, /* Vorgabe */ord16 cref, /* Vorgabe */ord16 orderid, /* Vorgabe */struct S7_READ_PARA *read_para_ptr

/* Vorgabe */ )


cref Referenz der S7-Verbindung, über die der Auftraggesendet werden soll.

orderid Auftragskennzeichen zur Identifizierung des abzuge-benden Auftrags und der zugehörigen Quittung.

read_para_ptr Zeiger auf einen vom Anwenderprogramm bereitge-stellten Puffer der nachfolgenden Struktur:

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];}

Der Parameter 'access' gibt die Zugriffsart an. Mitdem Wert 'S7_ACCESS_SYMB_ADDRESS' wird diesymbolische Adresse im Feld 'var_name' erwartet.

Der Parameter 'var_name' gibt die symbolischeAdresse der zu lesenden Variablen an und wird aus-gewertet, falls der Zugriff auf eine Variable per sym-bolischer ('access=S7_ACCESS_SYMB_ADDRESS')Adresse erfolgt (Beachten Sie bitte die allgemeinenHinweise zur Variablenadressierung zu Beginn die-ses Kapitels).

Beschreibung

Deklaration

Parameter


80

Der Parameter 'index' ist nicht relevant und nuraus Kompatibilitätsgründen zu anderenSAPI-Schnittstellen realisiert.

Der Parameter 'subindex' ist nicht relevant undnur aus Kompatibilitätsgründen zu anderenSAPI-Schnittstellen realisiert.

Der Parameter 'address_len' ist nicht relevantund nur aus Kompatibilitätsgründen zu anderenSAPI-Schnittstellen realisiert.

Der Parameter 'address' ist nicht relevant und nuraus Kompatibilitätsgründen zu anderenSAPI-Schnittstellen realisiert.




Die maximale Länge der Ergebnisdaten hängt von der ausgehandeltenPDU-Größe ab. Einzelheiten zur PDU-Größe entnehmen Sie Kapitel3.4.2, 's7_get_initiate_cnf', Seite 64 (Formeln zur Ermittlung von Zwi-schenwerten im Kapitel 7.3, Seite 207).

Die folgende Tabelle zeigt Beispiele:

PDU-Größe (Byte) Maximale Länge der Ergebnisdaten (Byte)

240 222

256 238

480 462

960 942

Return-Werte

Mengengerüst


81

3.5.2 s7_get_read_cnf

Mit dem Aufruf 's7_get_read_cnf()' wird ein gelesener Variablenwertentgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_READ_CNF', falls der Leseauftrag durchgeführt wurde. Danachmuß die zugehörige Bearbeitungsfunktion 's7_get_read_cnf()' zur in-ternen Bearbeitung in der Library aufgerufen werden, um die gelese-nen Werte in einen Anwenderpuffer zu kopieren.

int32 s7_get_read_cnf(

void *od_ptr, /* Vorgabe */ord16 *var_length_ptr,/* Vor- und */

/* Rückgabe */void *value_ptr /* Rückgabe */

)

od_ptr Der Parameter 'od_ptr' ist aus Kompatibilitätsgründenzu anderen SAPI-Schnittstellen realisiert und mußmit dem NULL-Pointer belegt werden, d. h die Va-riablenwerte werden an der SAPI-S7-Programmier-schnittstelle in Netzdarstellung übergeben.

var_length_ptr Adresse einer vom Anwenderprogramm bereitgestell-ten Variablen vom Typ 'ord16'. Hier wird die Längedes Datenpuffers vorgegeben. Nach dem Aufruf ent-hält der Parameter die Länge der gelesenen Varia-blen.

value_ptr Zeiger auf einen vom Anwenderprogramm bereitge-stellten Puffer. Hier wird der gelesene Variableninhaltin der Netzdarstellung abgelegt. Beim Auswerten desPufferinhalts muß der Datentyp der Variablen beach-tet werden.

Es ist darüber hinaus zu berücksichtigen, daßdie Variablenwerte byte-aligned, d. h. ohneFüllbytes (Padding-Bytes) zwischen zwei Kom-ponenten, abgelegt werden.

Beschreibung

Deklaration

Parameter

☞


82




Return-Werte


83

3.5.3 s7_write_req

Mit dem Aufruf 's7_write_req()' kann eine Client-Applikation auf eineVariable eines Servers schreibend zugreifen. Der Zugriff auf die Va-riablen kann nur per symbolischer Adresse erfolgen. Die Daten werdenim Auftrag vom Client zum Server übertragen.

int32 s7_write_req(

ord32 cp_descr, /* Vorgabe */ord16 cref, /* Vorgabe */ord16 orderid, /* Vorgabe */struct S7_WRITE_PARA *write_para_ptr

/* Vorgabe */void *od_ptr /* Vorgabe */

)




write_para_ptr Zeiger auf einen vom Anwenderprogramm bereitge-stellten Puffer der nachfolgenden Struktur:

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];

}


Der Parameter 'var_name' gibt die symbolischeAdresse der zu schreibenden Variablen an und wirdausgewertet, falls der Zugriff auf eine Variable persymbolischer Adresse erfolgt ('access=S7_ACCESS_SYMB_ADDRESS') (Beachten Siebitte die allgemeinen Hinweise zur Variablenadres-sierung zu Beginn dieses Kapitels).

Beschreibung

Deklaration

Parameter


84

Der Parameter 'index' ist nicht relevant und nur ausKompatibilitätsgründen zu anderen SAPI-Schnitt-stellen realisiert.

Der Parameter 'subindex' ist nicht relevant und nuraus Kompatibilitätsgründen zu anderen SAPI-Schnitt-stellen realisiert.

Der Parameter 'address_len' ist nicht relevant undnur aus Kompatibilitätsgründen zu anderenSAPI-Schnittstellen realisiert.

Der Parameter 'address' ist nicht relevant und nuraus Kompatibilitätsgründen zu anderen SAPI-Schnitt-stellen realisiert.

Der Parameter 'var_length' gibt die Anzahl der rele-vanten und gültigen Bytes im Datenpuffer 'value' an.

Im Puffer 'value' ist der Wert der zu schreibendenVariable in der Netzdarstellung abgelegt. Beim Aus-werten des Pufferinhalts muß der Datentyp der Va-riablen beachtet werden.

Es ist darüber hinaus zu berücksichtigen, daßdie Variablenwerte byte-aligned, d. h. ohneFüllbytes (Padding-Bytes) zwischen zwei Kom-ponenten, übergeben werden müssen.

od_ptr Der Parameter 'od_ptr' ist aus Kompatibilitätsgründenzu anderen SAPI-Schnittstellen realisiert und mußmit dem NULL-Pointer belegt werden, d. h. die Va-riablenwerte werden an der SAPI-S7-Programmier-schnittstelle in Netzdarstellung übergeben.

☞


85




Die maximale Länge der Nutzdaten hängt von der ausgehandeltenPDU-Größe ab. Einzelheiten zur PDU-Größe entnehmen Sie Kapitel3.4.2, 's7_get_initiate_cnf', Seite 64 (Formeln zur Ermittlung von Zwi-schenwerten im Kapitel 7.3, Seite 207).


PDU-Größe (Bytes) Maximale Länge der Nutzdaten

240 212

256 228

480 256 *)

960 256 *)

*) HinweisMit dem Aufruf 's7_write_long_req' sind längere Nutzdaten möglich.

Return-Werte

Mengengerüst


86

3.5.4 s7_write_long_req

Mit dem Aufruf 's7_write_long_req()' kann eine Client-Applikation aufeine Variable eines Servers schreibend zugreifen. Der Zugriff auf dieVariablen kann nur per symbolischer Adresse erfolgen. Die Daten wer-den im Auftrag vom Client zum Server übertragen.

int32 s7_write_long_req

(ord32 cp_descr, /* Vorgabe */ord16 cref, /* Vorgabe */ord16 orderid, /* Vorgabe */struct S7_WRITE_PARA_LONG *write_para_ptr

/* Vorgabe */void *od_ptr /* Vorgabe */)




write_para_ptr Zeiger auf einen vom Anwenderprogramm bereitge-stellten Puffer der nachfolgenden Struktur:

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];

}


Der Parameter 'var_name' gibt die symbolischeAdresse der zu schreibenden Variablen an und wirdausgewertet, falls der Zugriff auf eine Variable persymbolischer Adresse erfolgt ('access=S7_ACCESS_SYMB_ADDRESS') (Beachten Siebitte die allgemeinen Hinweise zur Variablenadres-sierung zu Beginn dieses Kapitels).

Beschreibung

Deklaration

Parameter


87








od_ptr Der Parameter 'od_ptr' ist aus Kompatibilitätsgründenzu anderen SAPI-Schnittstellen realisiert und mußmit dem NULL-Pointer belegt werden, d. h. die Va-riablenwerte werden an der SAPI-S7-Programmier-schnittstelle in Netzdarstellung übergeben.

☞


88




Die maximale Länge der Nutzdaten hängt von der ausgehandeltenPDU-Größe ab. Einzelheiten zur PDU-Größe entnehmen Sie Kapitel3.4.2, 's7_get_initiate_cnf', Seite 64 (Formeln zur Ermittlung von Zwi-schenwerten im Kapitel 7.3, Seite 207).


PDU-Größe (Bytes) Maximale Länge der Nutzdaten

240 212

256 228

480 452

960 932

Return-Werte

Mengengerüst


89

3.5.5 s7_get_write_cnf

Mit dem Aufruf 's7_get_write_cnf()' wird das Ergebnis des Variablen-Schreibauftrags entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_WRITE_CNF', falls der Schreibauftrag durchgeführt wurde. Da-nach muß die zugehörige Bearbeitungsfunktion 's7_get_write_cnf()' zurinternen Bearbeitung in der Library aufgerufen werden.

int32 s7_get_write_cnf(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


90

3.5.6 s7_multiple_read_req

Mit dem Aufruf 's7_multiple_read_req()' kann eine Client-Applikationauf eine oder mehrere Variablen eines Servers gleichzeitig lesendzugreifen. Der Zugriff auf die Variablen kann nur per symbolischerAdresse erfolgen. Die Daten werden in der Quittung vom Server zumClient übertragen und werden mit Hilfe der entsprechenden Bearbei-tungsfunktion für die Abschlußquittung ('s7_get_multiple_read_cnf()') indie Anwenderpuffer übertragen.

int32 s7_multiple_read_req(

ord32 cp_descr, /* Vorgabe */ ord16 cref, /* Vorgabe */ ord16 orderid, /* Vorgabe */

ord16 number, /* Vorgabe */struct S7_READ_PARA *read_para_array

/* Vorgabe */

)

Beschreibung

Deklaration


91


cref Referenz der Verbindung, über die der Auftrag ge-sendet werden soll.


number Anzahl der Variablen, die gelesen werden sollen.

read_para_array Zeiger auf ein vom Anwenderprogramm bereitgestell-tes Array von insgesamt 'number' Elementen dernachfolgenden Struktur, wobei das i-te Element diei-te Variable beschreibt:

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];

}


Der Parameter 'var_name' gibt die symbolischeAdresse der zu lesenden Variablen an und wird aus-gewertet, falls der Zugriff auf eine Variable per sym-bolischer Adresse erfolgt ('access=S7_ACCESS_SYMB_ADDRESS') (Beachten Siebitte die allgemeinen Hinweise zur Variablenadres-sierung zu Beginn dieses Kapitels).





Parameter


92




Die maximale Länge der Variablenadressen und Ergebnisdaten hängtvon der ausgehandelten PDU-Größe ab. Einzelheiten zur PDU-Größeentnehmen Sie Kapitel 3.4.2, 's7_get_initiate_cnf', Seite 64 (Formelnzur Ermittlung von Zwischenwerten im Kapitel 7.3, Seite 207).


PDU-Größe(Bytes)

Maximale AnzahlVariablenadressen

Maximale Länge derErgebnisdaten bei

maximaler Anzahl derVariablenadressen

240 19 150

256 20 162

480 39 310

960 79 630

Return-Werte

Mengengerüst


93

3.5.7 s7_get_multiple_read_cnf

Mit dem Aufruf 's7_get_multiple_read_cnf()' werden die gelesenenVariablenwerte entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_MULTIPLE_READ_CNF', falls der Leseauftrag durchgeführt wur-de. Danach muß die zugehörige Bearbeitungsfunktion's7_get_multiple_read_cnf()' zur internen Bearbeitung in der Libraryaufgerufen werden. Sie kopiert die gelesenen Werte in die Anwender-puffer.

int32 s7_get_multiple_read_cnf(

void *od_ptr, /* Vorgabe */ord16 *result_array, /* Rückgabe */ord16 *var_length_array,

/* Vor- und *//* Rückgabe */

void *value_array /* Rückgabe */

)


result_array Adresse eines vom Anwenderprogramm bereitge-stelltes Arrays vom Typ 'ord16'. Das Array muß min-destens so viele Elemente enthalten, wie Variablengelesen wurden. Die Array-Elemente enthalten dieZugriffsergebnisse in der Reihenfolge, in der die Va-riablen beim Auftrag angegeben wurden. FolgendeZugriffsergebnisse sind möglich:

S7_RESULT_OK

Dieser Wert zeigt den fehlerfreien Zugriff auf dieVariable an.

S7_RESULT_HW_ERROR

Bei diesem Wert trat ein Hardwarefehler auf.

S7_RESULT_OBJ_ACCESS_DENIED

Der Zugriff auf eine Variable wurde abgelehnt.

S7_RESULT_OBJ_ADDRESS_INVALID

Die angegebene Adresse ist ungültig.

Beschreibung

Deklaration

Parameter


94

S7_RESULT_OBJ_TYPE_NOT_SUPPORTED

Der Server unterstützt den Datentyp nicht.

S7_RESULT_OBJ_TYPE_INCONSISTENT

Der Datentyp der Variablen ist nicht konsistent.

S7_RESULT_OBJ_NOT_EXISTS

Die anzusprechende Variable existiert nicht.

var_length_array Adresse eines vom Anwenderprogramm bereitge-stellten Arrays vom Typ 'ord16'. Das Array muß min-destens so viele Elemente umfassen, wie Variablengelesen wurden. In den einzelnen Array-Elementenwerden die Längen der Datenpuffer vorgegeben.Nach dem Aufruf enthalten die Elemente dieses Ar-rays die Längen der gelesenen Variablen. Der Wert'0' bedeutet, daß die entsprechende Variable nichtgelesen werden konnte.

value_array Zeigerfeld auf vom Anwenderprogramm bereitge-stellte Puffer. In den einzelnen Puffern werden diegelesenen Variablenwerte abgelegt. Auch hier gilt dieReihenfolge, in der die Variablen beim Auftrag ange-geben wurden. Beim Auswerten der Pufferinhaltemuß der Datentyp der Variablen beachtet werden.


☞


95




Return-Werte


96

3.5.8 s7_multiple_write_req

Mit dem Aufruf 's7_multiple_write_req()' kann eine Client-Applikationauf eine oder mehrere Variablen eines Servers gleichzeitig schreibendzugreifen. Der Zugriff auf die Variablen kann nur per symbolischerAdresse erfolgen. Die Daten werden im Auftrag vom Client zum Serverübertragen.

int32 s7_multiple_write_req(

ord32 cp_descr, /* Vorgabe */ ord16 cref, /* Vorgabe */ ord16 orderid, /* Vorgabe */

ord16 number, /* Vorgabe */struct S7_MULTIPLE_WRITE_PARA *write_para_array, /* Vorgabe */void *od_ptr /* Vorgabe */

)


cref Referenz der Verbindung, über die der Auftrag ge-sendet werden soll.


number Anzahl der Variablen, die geschrieben werden sollen.

write_para_array Zeiger auf ein vom Anwenderprogramm bereitgestell-tes Array von insgesamt 'number' Elementen dernachfolgenden Struktur, wobei das i-te Element diei-te Variable beschreibt:

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];}


Beschreibung

Deklaration

Parameter


97










☞


98




Die maximale Anzahl der Variablenadressen und die maximale Längeder Nutzdaten hängt von der ausgehandelten PDU-Größe ab. Einzel-heiten zur PDU-Größe entnehmen Sie Kapitel 3.4.2,'s7_get_initiate_cnf', Seite 64 (Formeln zur Ermittlung von Zwischen-werten im Kapitel 7.3, Seite 208).


PDU-Größe(Bytes)


Maximale Länge derNutzdaten bei maximaler

Anzahl der Variablenadressen

240 12 36

256 13 36

480 26 52

960 52 116

Return-Werte

Mengengerüst


99

3.5.9 s7_get_multiple_write_cnf

Mit dem Aufruf 's7_get_multiple_write_cnf()' werden die Ergebnisseeines Variablen-Schreibauftrags entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_MULTIPLE_WRITE_CNF', falls der Schreibauftrag durchgeführtwurde. Danach muß die zugehörige Bearbeitungsfunktion's7_get_multiple_write_cnf()' zur internen Bearbeitung in der Libraryaufgerufen werden.

int32 s7_get_multiple_write_cnf(

ord16 *result_array /* Rückgabe */

)

result_array Adresse eines vom Anwenderprogramm bereitge-stellten Arrays vom Typ 'ord16'. Das Array muß min-destens so viele Elemente enthalten, wie Variablengelesen wurden. Die Array-Elemente enthalten dieZugriffsergebnisse in der Reihenfolge, in der die Va-riablen beim Auftrag angegeben wurden. FolgendeZugriffsergebnisse sind möglich:

S7_RESULT_OK


S7_RESULT_HW_ERROR












Beschreibung

Deklaration

Parameter


100




Return-Werte


101

3.5.10 s7_cycl_read_init_req

Eine S7-Applikation veranlaßt mit diesem Auftrag den Server, ein zy-klisches Lesen von Variablen vorzubereiten. Im Auftrag werden dieZykluszeit, die Anzahl der Variablen sowie die Variablen, deren Wertegelesen werden sollen, übergeben

int32 s7_cycl_read_init_req(

ord32 cp_descr, /* Vorgabe */ord16 cref, /* Vorgabe */ord16 orderid, /* Vorgabe */ord16 cycl_time, /* Vorgabe */ord16 number, /* Vorgabe */struct S7_READ_PARA *read_para_array

/* Vorgabe */

)

cp_descr Handle als Rückgabewert des 's7_init()'-Aufrufs

cref Referenz der Verbindung, über die der Auftrag ge-sendet werden soll. Über diese Verbindung werdendie Variablenwerte übertragen.

orderid Auftragskennzeichen zur Identifizierung des abzuge-benden Auftrags und der zugehörigen Quittung. Die-ses Auftragskennzeichen muß bei weiteren Aufträ-gen wie das Starten ('s7_cycl_read_start_req()'), An-halten ('s7_cycl_read_stop_req()') und Löschen('s7_cycl_read_delete_req()') des zyklischen Lesenswiederverwendet werden.

cycl_time Zykluszeit als Vielfaches von 10tel Sekunden.SAPI-S7 rundet auf einen erlaubten Wert ab, dassind:1, 2 ... 9 sowie 10, 20 ... 90 und 100, 200 ... 900.

number Anzahl der Variablen, deren Werte zyklisch gelesenwerden sollen.

Beschreibung

Deklaration

Parameter


102




}








103




Die maximale Länge der Variablenadressen und Ergebnisdaten hängtvon der ausgehandelten PDU-Größe ab. Einzelheiten zur PDU-Größeentnehmen Sie Kapitel 3.4.2, 's7_get_initiate_cnf', Seite 64 (Formelnzur Ermittlung von Zwischenwerten im Kapitel 7.3, Seite 208).


PDU-Größe(Bytes)


Maximale Länge derErgebnisdaten bei maximalerAnzahl der Variablenadressen

240 17 144

256 19 152

480 37 304

960 77 624

Return-Werte

Mengengerüst


104

3.5.11 s7_get_cycl_read_init_cnf

Mit dem Aufruf 's7_get_cycl_read_init_cnf()' wird das Ergebnis eines's7_cycl_read_init_req()'-Auftrags entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_CYCL_READ_INIT_CNF', falls der remote Partner den Auftragzum Vorbereiten des zyklischen Variablen-Lesens abgearbeitet hat.Danach muß die zugehörige Bearbeitungsfunktion's7_get_cycl_read_init_cnf()' zur internen Bearbeitung in der Libraryaufgerufen werden.

int32 s7_get_cycl_read_init_cnf(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


105

3.5.12 s7_cycl_read_start_req

Eine S7-Applikation veranlaßt mit diesem Auftrag den Server, ein zy-klisches Lesen von Variablen zu starten. Voraussetzung hierfür ist, daßder Server mit Hilfe des Aufrufs 's7_cycl_read_init_req()' für diesenDienst vorbereitet wurde.

int32 s7_cycl_read_start_req(

ord32 cp_descr, /* Vorgabe */ ord16 cref, /* Vorgabe */ ord16 orderid /* Vorgabe */

)

cp_descr Handle als Rückgabewert des 's7_init()'-Aufrufs.Dieser Parameter muß mit dem entsprechendenParameter des 's7_cycl_read_init_req()'-Aufrufsübereinstimmen

cref Referenz der Verbindung, über die der Auftraggesendet werden soll. Dieser Parameter muß mitdem entsprechenden Parameter des's7_cycl_read_init_req()'-Aufrufs übereinstimmen.

orderid Auftragskennzeichen zur Identifizierung des abzu-gebenden Auftrags und der zugehörigen Quittung.Dieser Parameter muß mit dem entsprechendenParameter des 's7_cycl_read_init_req()'-Aufrufsübereinstimmen.




Beschreibung

Deklaration

Parameter

Return-Werte


106

3.5.13 s7_get_cycl_read_start_cnf

Mit dem Aufruf 's7_get_cycl_read_start_cnf()' wird das Ergebnis eines's7_cycl_read_start_req()'-Auftrags entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_CYCL_READ_START_CNF', falls der remote Partner den Auftragzum Starten des zyklischen Variablen-Lesens abgearbeitet hat. Da-nach muß die zugehörige Bearbeitungsfunktion's7_get_cycl_read_start_cnf()' zur internen Bearbeitung in der Libraryaufgerufen werden.

int32 s7_get_cycl_read_start_cnf(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


107

3.5.14 s7_get_cycl_read_ind

Mit dem Aufruf 's7_get_cycl_read_ind()' werden die vom Server ge-sendeten Daten entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_CYCL_READ_IND', falls vom remoten Partner eine Variable zy-klisch gelesen wurde. Danach muß die zugehörige Bearbeitungsfunkti-on 's7_get_cycl_read_ind()' aufgerufen werden, um die gelesenenWerte in die Anwenderpuffer zu kopieren.

int32 s7_get_cycl_read_ind(

void *od_ptr, /* Vorgabe */ ord16 *result_array, /* Rückgabe */

ord16 *var_length_array,/* Vor- und */ /* Rückgabe */

void *value_array /* Rückgabe */

)


result_array Adresse eines vom Anwenderprogramm bereitge-stellten Arrays vom Typ 'ord16'. Das Array muß min-destens so viele Elemente enthalten, wie Variablengelesen wurden. Die Array-Elemente enthalten dieZugriffsergebnisse in der Reihenfolge, in der die Va-riablen beim Auftrag angegeben wurden. FolgendeZugriffsergebnisse sind möglich:

S7_RESULT_OK


S7_RESULT_HW_ERROR






Beschreibung

Deklaration

Parameter


108







var_length_array Adresse eines vom Anwenderprogramm bereit-gestellten Arrays vom Typ 'ord16'. Das Array mußmindestens so viele Elemente umfassen, wie Va-riablen gelesen wurden. In den einzelnen Array-Elementen werden die Längen der Datenpuffervorgegeben. Nach dem Aufruf enthalten die Ele-mente dieses Arrays die Längen der gelesenenVariablen. Der Wert '0' bedeutet, daß die entspre-chende Variable nicht gelesen werden konnte.

value_array Zeigerfeld auf vom Anwenderprogramm bereitge-stellte Puffer. In den einzelnen Puffern werden diegelesenen Variablenwerte abgelegt. Auch hier giltdie Reihenfolge, in der die Variablen beim Auftragangegeben wurden. Beim Auswerten der Pufferin-halte muß der Datentyp der Variablen beachtetwerden.

Achten Sie darauf, daß die Variablenwertebyte-aligned, d. h. ohne Füllbytes (Padding-Bytes) zwischen zwei Komponenten, überge-ben werden müssen.




☞

Return-Werte


109

3.5.15 s7_get_cycl_read_abort_ind

Mit dem Aufruf 's7_get_cycl_read_abort_ind()' wird eine Cyclic ReadAbort Indication entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_CYCL_READ_ABORT_IND', falls das zyklische Variablen-Lesenabgebrochen wurde. Danach muß die zugehörige Bearbeitungsfunktion's7_get_cycl_read_delete_cnf()' zur internen Bearbeitung in der Libraryaufgerufen werden.

Mit Hilfe der in den vorigen Kapiteln beschriebenen Funktionen kannein zyklisches Variablen-Lesen wieder eingerichtet werden.

int32 s7_get_cycl_read_abort_ind(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


110

3.5.16 s7_cycl_read_stop_req

Eine S7-Applikation veranlaßt mit diesem Auftrag den Server, ein zy-klisches Lesen von Variablen anzuhalten. Voraussetzung hierfür ist,daß der Server zum zyklischen Variablen-Lesen bereits erfolgreichaufgefordert wurde.

int32 s7_cycl_read_stop_req(


)

cp_descr Handle als Rückgabewert des 's7_init()'-Aufrufs.Dieser Parameter muß mit dem entsprechendenParameter des 's7_cycl_read_init_req()'- oder's7_cycl_read()'-Aufrufs übereinstimmen.

cref Referenz der Verbindung, über die der Auftraggesendet werden soll. Dieser Parameter muß mitdem entsprechenden Parameter des's7_cycl_read_init_req()'- oder 's7_cycl_read()'-Aufrufs übereinstimmen.

orderid Auftragskennzeichen zur Identifizierung des abzu-gebenden Auftrags und der zugehörigen Quittung.Dieser Parameter muß mit dem entsprechendenParameter des 's7_cycl_read_init_req()'- oder's7_cycl_read()'-Aufrufs übereinstimmen.




Beschreibung

Deklaration

Parameter

Return-Werte


111

3.5.17 s7_get_cycl_read_stop_cnf

Mit dem Aufruf 's7_get_cycl_read_stop_cnf()' wird das Ergebnis eines's7_cycl_read_stop_req()'-Auftrags entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_CYCL_READ_STOP_CNF', falls der remote Partner den Auftragzum Beenden des zyklischen Variablen-Lesens abgearbeitet hat. Da-nach muß die zugehörige Bearbeitungsfunktion's7_get_cycl_read_stop_cnf()' zur internen Bearbeitung in der Libraryaufgerufen werden.

int32 s7_get_cycl_read_stop_cnf(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


112

3.5.18 s7_cycl_read_delete_req

Mit dieser Funktion wird das zyklische Lesen abgebrochen und beimServer abgemeldet.

int32 s7_cycl_read_delete_req(


)

cp_descr Handle als Rückgabewert des 's7_init()'-Aufrufs.Dieser Parameter muß mit dem entsprechendenParameter des 's7_cycl_read_init_req()'- oder's7_cycl_read()'-Aufrufs übereinstimmen.

cref Referenz der Verbindung, über die der Auftraggesendet werden soll. Dieser Parameter muß mitdem entsprechenden Parameter des's7_cycl_read_init_req()'- oder 's7_cycl_read()'-Aufrufs übereinstimmen.

orderid Auftragskennzeichen zur Identifizierung des abzu-gebenden Auftrags und der zugehörigen Quittung.Dieser Parameter muß mit dem entsprechendenParameter des 's7_cycl_read_init_req()'- oder's7_cycl_read()'-Aufrufs übereinstimmen.




Beschreibung

Deklaration

Parameter

Return-Werte


113

3.5.19 s7_get_cycl_read_delete_cnf

Mit dem Aufruf 's7_get_cycl_read_delete_cnf()' wird das Ergebnis ei-nes 's7_cycl_read_delete_req()'-Auftrags entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_CYCL_READ_DELETE_CNF', falls der remote Partner den Auf-trag zum Aufheben des zyklischen Variablen-Lesens abgearbeitet hat.Danach muß die zugehörige Bearbeitungsfunktion's7_get_cycl_read_delete_cnf()' zur internen Bearbeitung in der Libraryaufgerufen werden.

int32 s7_get_cycl_read_delete_cnf(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


114

3.5.20 s7_cycl_read

Eine S7-Applikation veranlaßt mit diesem Auftrag den Server, zyklischVariablen zu lesen. Der Auftrag faßt die Sequenz zusammen, die ausden Aufrufen 's7_cycl_read_init_req()' (Anmelden beim Server) und's7_cycl_read_start_req()' (Starten des Variablen-Lesens) besteht. DieZykluszeit, die Anzahl der Variablen und die Variablen, deren Wertegelesen werden sollen, werden vorgegeben.

Wichtig: Bei S7 ist dieser Auftrag ein unquittierter Dienst (im Gegen-satz zu den Einzelaufträgen, aus denen sich dieser Aufruf zusammen-setzt).

int32 s7_cycl_read(

ord32 cp_descr, /* Vorgabe */ord16 cref, /* Vorgabe */ord16 orderid, /* Vorgabe */ord16 cycl_time, /* Vorgabe */ord16 number, /* Vorgabe */struct S7_READ_PARA *read_para_array

/* Vorgabe */

)

cp_descr Handle als Rückgabewert des 's7_init()'-Aufrufs

cref Referenz der Verbindung, über die der Auftrag ge-sendet werden soll. Über diese Verbindung werdendie Variablenwerte übertragen.

orderid Auftragskennzeichen zur Identifizierung des abzuge-benden Auftrags und der zugehörigen Quittung. Die-ses Auftragskennzeichen muß bei weiteren Aufträ-gen wie das Anhalten ('s7_cycl_read_stop_req()'),Fortsetzen ('s7_cycl_read_start_req()') und Löschen('s7_cycl_read_delete_req()') des zyklischen Lesenswiederverwendet werden.

cycl_time Zykluszeit als Vielfaches von 10tel Sekunden.SAPI-S7 rundet auf einen erlaubten Wert ab, dassind: 1, 2 bis 9 sowie 10, 20 bis 90 und 100, 200 bis900.

number Anzahl der Variablen, deren Werte zyklisch gelesenwerden sollen.

Beschreibung

Deklaration

Parameter


115




}


Der Parameter 'var_name' gibt die symbolischeAdresse der zu lesenden Variablen an und wird aus-gewertet, falls der Zugriff auf eine Variable per sym-bolischer Adresse erfolgt ('access=S7_ACCESS_SYMB_ADDRESS') (Beachten Siebitte die allgemeinen Hinweise zur Variablenadres-sierung zu Beginn dieses Kapitels).






116




Return-Werte


117

3.6 Blockorientierte Dienste

Dem Anwendungsprogrammierer werden sowohl auf PG/PC- als auchauf Seite von SIMATIC S7-Automatisierungssystemen blockorientierteDienste angeboten.

Diese Dienste bieten folgende Vorteile:

➢ Übertragung größerer Datenmengen

➢ Anstoß zur Übertragung kann von SIMATIC S7-Automatisie-rungssystemen ausgehen

Die blockorientierten Dienste stehen unter MSDOS und Windows 3.xnicht zur Verfügung

Auf der Seite von SIMATIC S7-Automatisierungssystemen stehen diebeiden Bausteine BSEND und BRCV zur Verfügung. Diese Funktionali-tät wird auf PG/PC-Seite mit den Funktionen der 'BlockorientiertenDienste' umgesetzt.

Für den Datenaustausch zwischen zwei Kommunikationspartnern isteine Verbindungsprojektierung notwendig. Bei den blockorientiertenDiensten gehört immer das Bausteinpaar BSEND und BRCV zusam-men. Hierfür ist eine zweiseitige Verbindungsprojektierung (COML S7und STEP 7 NETPRO) notwendig.

Ab SIMATIC NET-CD, November 99 kann auf die Projektierung mitCOML S7 verzichtet werden. Die Konfigurationsdatei für den PC wirdvon STEP 7 erzeugt; siehe Installationsanleitung Ihres Produkts.

Im Gegensatz zu den nicht blockorientierten Diensten muß die mitSTEP 7 NETPRO erstellte Verbindungsprojektierung in das Automati-sierungssystem geladen werden. Über eine Verbindung können mehre-re Bausteinpaare Daten austauschen.

Beachten Sie bitte bei der Projektierung der Verbindungen die Hinwei-se in der betreffenden Produktinformation.

Die Datenmenge beträgt bei diesem Datentransfer bis zu 65534 Byte,unabhängig von der Größe der CPU. Die Segmentierung der Datenwird von den Funktionen selbst übernommen.

Der Adressierungsparameter R_ID ist für ein Bausteinpaar (BSEND/BRCV) festgelegt und innerhalb einer Verbindung eindeutig definiert.Das heißt, es können mehrere BSEND-Bausteine über eine Verbin-dung senden, aber immer mit einer unterschiedlichen R_ID. GleicheR_IDs können für weitere Verbindungen verwendet werden.

Beschreibung

Einschränkungen

Standard-funktionen

Datenaustausch

Datenmenge

Adressierungs-parameter


118

In der folgende Tabelle sind die blockorientierten Dienste in zweiGruppen eingeteilt:

➢ Gruppe 'bsend'

➢ Gruppe 'brcv'

Blockorientierte Dienste Funktionen

bsend s7_bsend_req()

s7_get_bsend_cnf()

brcv s7_brcv_init()

s7_get_brcv_ind()

s7_brcv_stop()

In den folgenden Kapiteln werden die oben aufgeführten Funktionenbeschrieben.

Einteilung derFunktionen


119

Beispiel '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;

...Verbindung aufgebaut

...

/* 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;

}}

}


}


120

s7_bsend_req()

= S7_OK

s7_receive()

= S7_NO_MSG


s7_receive()

= S7_BSEND_CNF

s7_get_bsend_cnf

= S7_OK

Anwenderprogramm SAPI-S7 remoter Partner


Bild 3.7: Ablaufdiagramm 'bsend'

Ablaufdiagramm'bsend'


121

Beispiel '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;

...Verbindung aufgebaut

...

/* 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);


}


122

s7_brcv_init()

= S7_OK

s7_receive()

= S7_NO_MSG


s7_receive()

= S7_BRCV_IND

s7_get_brcv_ind

= S7_OK

s7_brcv_stop

= S7_OK



alle Nettodaten vomPartner (BSEND)

empfangen!

brcv explizit beenden

Bild 3.8: Ablaufdiagramm 'brcv'

Ablaufdiagramm'brcv'


123

3.6.1 s7_bsend_req

Mit dem Aufruf s7_bsend_req kann eine Client-Applikation bis zu65534 Byte Daten an eine remote Station senden.

int32 s7_bsend_req (

ord32 cp_descr, /* Vorgabe */ord16 cref, /* Vorgabe */ord16 orderid, /* Vorgabe */ord32 r_id, /* Vorgabe */void *buffer_ptr, /* Vorgabe */ord32 buffer_len /* Vorgabe */

)


cref Referenz der S7-Verbindung, über die der Auf-trag gesendet werden soll.

orderid Auftragskennzeichen zur Identifizierung desabzugebenden Auftrags und der zugehörigenQuittung.

r_id Es werden nur Daten zum Partner über dieseVerbindung erfolgreich gesendet, wenn derAdressierungsparameter r_id für die Verbindungeindeutig ist und mit dem remoten R_ID desBRCV übereinstimmt.Wertebereich (hexadezimal): 0 bis FFFF FFFF

*buffer_ptr Zeiger auf den zu sendenden Adreßbereich

buffer_len explizite Längenangabe der Nettodaten in Bytes;Wertebereich (hexadezimal): 1 bis FFFE

Beschreibung

Deklaration

Parameter


124


S7_ERR_RETRY Dieser Wert zeigt einen Fehler bei derAusführung des angeforderten Dienstes an.Dabei handelt es sich um ein temporäraufgetretenes Problem, wie z. B. um einenvorübergehenden Speicherengpaß. Der Aufrufkann ohne Änderung der Übergabeparameterwiederholt werden.

S7_ERR Dieser Wert zeigt ebenfalls einen Fehler bei derAusführung des angeforderten Dienstes an.Allerdings handelt es sich hierbei um einenFehler, der ein wiederholtes Ausführen desDienstes nicht erlaubt. Hier müssen weitereSchritte zur Fehlerbehebung, wie das Versorgendes Aufrufs mit anderen Parametern, eingeleitetwerden.

Return-Werte


125

3.6.2 s7_get_bsend_cnf

Mit dem Aufruf s7_get_bsend_cnf wird das Ergebnis des BSEND-Auftrags entgegengenommen.

Das Anwenderprogramm erhält beim s7_receive–Aufruf die AnzeigeS7_BSEND_CNF, wenn der Sendeauftrag abgearbeitet wurde. Danachmuß die zugehörige Bearbeitungsfunktion s7_get_bsend_cnf zur inter-nen Bearbeitung in der Library aufgerufen werden.

int32 s7_get_bsend_cnf (void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


126

3.6.3 s7_brcv_init

Mit diesem Aufruf meldet sich die Applikation zum Empfang vonBSEND-Aufträgen vom Verbindungspartner an. Jedem BSEND-Auftrag mit einer bestimmten R_ID des Verbindungspartners muß ge-nau ein s7_brcv_init mit der gleichen R_ID entsprechen.

int32 s7_brcv_init

(ord32 cp_descr, /* Vorgabe */ord16 cref, /* Vorgabe */ord32 r_id /* Vorgabe */)



r_id Es werden nur Daten vom Partner über dieseVerbindung empfangen, wenn der Adressie-rungsparameter r_id für die Verbindung eindeu-tig ist und mit dem remoten R_ID am BSENDübereinstimmt.

Der Inhalt des Parameters r_id ihrer Applika-tion und der Inhalt des Parameters r_id desProgramms ihres Verbindungspartners mußgleich sein!

Sie können BSEND-Daten nur dann empfan-gen, wenn die r_id-Parameter bei beidenPartnern gleich sind.

Beschreibung

Deklaration

Parameter

☞


127


S7_ERR_RETRY Dieser Wert zeigt einen Fehler bei der Ausfüh-rung des angeforderten Dienstes an. Dabei han-delt es sich um ein temporär aufgetretenes Pro-blem, wie z. B. um einen vorübergehendenSpeicherengpaß. Der Aufruf kann ohne Ände-rung der Übergabeparameter wiederholt werden.

S7_ERR Dieser Wert zeigt ebenfalls einen Fehler bei derAusführung des angeforderten Dienstes an. Al-lerdings handelt es sich hierbei um einen Fehler,der ein wiederholtes Ausführen des Dienstesnicht erlaubt. Hier müssen weitere Schritte zurFehlerbehebung, wie das Versorgen des Aufrufsmit anderen Parametern, eingeleitet werden.

Return-Werte


128

3.6.4 s7_get_brcv_ind

Mit dem Aufruf s7_get_brcv_ind werden die vom Partner gesendetenNettodaten in den angegebenen Speicherbereich kopiert.

int32 s7_get_brcv_ind

(void *buffer_ptr, /* Vorgabe */ord32 buffer_len, /* Vorgabe */ord32 *r_id_ptr, /* Rückgabe */ord32 *rec_buffer_len_ptr /* Rückgabe */)

*buffer_ptr Der Pointer zeigt auf die Zieladresse, an der dieempfangenen Daten abgelegt werden sollen.

buffer_len Maximale Länge des Empfangspuffers(buffer_ptr); wenn die empfangene Datenlängegrößer als die hier angegebene Pufferlänge ist,wird S7_ERR zurückgegeben. In diesem Fallwird im Parameter rec_buffer_len die benötigtePuffergröße angegeben und der „detailed error“aufS7_ERR_INVALID_DATARANGE_OR_TYPEgesetzt.

*r_id_ptr *r_id_ptr zeigt auf eine Variable vom Typ ord32,die nach Aufruf der Funktion die R_ID desempfangenen BSEND-Auftrags enthält.

rec_buffer_len_ptr Gesamte empfangene Datenlänge bei Return-Wert = S7_OK bzw. benötigte Puffergröße,wenn der Empfangspuffer zu klein ist und derReturn-Wert = S7_ERR ist.

Beschreibung

Deklaration

Parameter


129




Return-Werte


130

3.6.5 s7_brcv_stop

Mit diesem Aufruf meldet sich die Applikation beim Verbindungspartnerab.

int32 s7_brcv_stop (

ord32 cp_descr, /* Vorgabe */ord16 cref, /* Vorgabe */ord32 r_id /* Vorgabe */

)



r_id Die beim entsprechenden brcv_init angegebeneR_ID.




Beschreibung

Deklaration

Parameter

Return-Werte


131

3.7 Meldedienste

Mit den Meldediensten kann der Anwendungsprogrammierer Meldun-gen von einem SIMATIC S7-Automatisierungssystem empfangen.

Diese Dienste bieten folgende Vorteile:

➢ Übertragung von überwachten Daten nur bei deren Änderung!

➢ Den übertragenen Daten können beliebige 'Begleitwerte' ange-fügt werden.

Die Meldedienste stehen unter MS-DOS und Windows 3... nicht zurVerfügung.

Bei SAPI S7 werden die folgenden 2 Meldearten verarbeitet:

➢ projektierte Meldungen (SCAN)

➢ programmierte Meldungen (ALARM, ALARM_8, ALARM_8P,NOTIFY)

Bei projektierten Meldungen werden in einem festen Zeitraster(100 ms, 500 ms, oder 1000 ms) Daten im SIMATICS7-Automatisierungssystem von dessen Betriebssystem überprüft,ob sie sich im Vergleich zum letzten Durchlauf geändert haben.

Bei Änderung werden sie vom SIMATIC-S7-Automatisierungssystemzum angemeldeten PC/PG gesendet. Dort speichert sie ein vom An-wender bereitgestellter Puffer.

Eine Meldung wird im 'Symbol Editor' von STEP 7 projektiert, indemeiner Variablen ('Adresse') die 'Spezielle Objekteigenschaft' 'Meldung'zugeordnet wird.

Die Zuordnung vom symbolischen Namen der überwachten Variablenzur Meldungsnummer wird im Dialogfeld 'Meldungsprojektierung' an-gezeigt. (Die Meldungsprojektierung wird natürlich erst dann aktiv,wenn sie ins Zielsystem geladen wurde.)

Für die programmierten Meldungen ist vom Anwender einS7-Baustein (ALARM, ALARM_8, ALARM_8P, NOTIFY) in seinS7-Anwendungsprogramm einzubinden. Dieser Baustein prüft bei je-dem Bearbeitungszyklus Signale auf Änderung und setzt unmittelbardanach ein Telegramm mit dem Ereigniszustand der Signale, Uhrzeitund Begleitwerten ab. Es können ebenso Meldungen von meldefähigenPCS 7-Bausteinen, z. B. Technologische Funktionen, empfangen wer-den.

Beschreibung

Einschränkungen

Standard-funktionen

ProjektierteMeldungen (SCAN)

ProgrammierteMeldungen(ALARM)


132

Bevor Meldungen von des SIMATIC S7-Automatisierungssystemsabgesetzt werden können, muß sich ein PC/PG bei dem gewünschtenSIMATIC S7-Automatisierungssystem anmelden. Die Funktion's7_msg_initiate_req' kann für beide Meldearten verwendet werden.

Man kann sich dabei entweder für alle SCAN- oder alle ALARM-,ALARM_8-, ALARM_8P oder NOTIFY–Meldungen verbindungsspezi-fisch anmelden.

Anmeldung


133

s7_msg_initiate_req()

=S7_OK


s7_receive()

=S7_NO_MSG


s7_receive()

=S7_SCAN_IND

Meldungen vom Partnerempfangen!

s7_msg_abort_req()

=S7_OK

SCAN_an_alleTelegramme azyklisch

s7_get_scan_ind()

=S7_OK

s7_receive()

=S7_MSG_INITIATE_CNF

Anmelden für SCAN

+ Quittung

s7_get_msg_initiate_cnf()

s7_receive()

=S7_MSG_ABORT_CNF

s7_get_msg_abort_cnf()

Abmelden für SCAN

+ Quittung

nmelden

Abmelden

Meldungen empfangen

Bild 3.9: Ablaufdiagramm SCAN

Ablaufdiagramm'scan'


134

s7_msg_initiate_req()

=S7_OK


s7_receive()

=S7_NO_MSG


s7_receive()

=S7_ALARM_IND

Meldungen vom Partnerempfangen!

s7_msg_abort_req()

=S7_OK

ALARM_8P-Telegramme azyklisch

s7_get_alarm_ind()

=S7_OK

s7_receive()

=S7_MSG_INITIATE_CNF

Anmelden fürALARM_8P

+ Quittung

s7_get_msg_initiate_cnf()

s7_receive()

=S7_MSG_ABORT_CNF

s7_get_msg_abort_cnf()

Abmelden fürALARM_8

+ Quittung

Anmelden

Meldungen empfangen

Abmelden

Bild 3.10: Ablaufdiagramm 'alarm'

Ablaufdiagramm'alarm'


135

3.7.1 s7_msg_initiate_req

Mit diesem Aufruf meldet sich eine Client-Applikation bei einemSIMATIC S7-Automatisierungssystem für einen der Dienste SCANoder ALARM an. Das Ergebnis der Anmeldung wird mit der Funktions7_get_msg_initiate_cnf entgegengenommen.

int32 s7_msg_initiate_req(

ord32 cp_descr, /* Vorgabe */

ord16 cref, /* Vorgabe */

ord16 orderid, /* Vorgabe */

ord16 fct_code /* Vorgabe */

)




fct_code Funktionskennung Anmelden fürS7_SCAN_ALL_INITIATE oderS7_ALARM_ALL_INITIATE; andere Kennungenwerden ignoriert.


S7_ERR Dieser Wert zeigt einen Fehler bei derAusführung des angeforderten Dienstes an. Hiermüssen weitere Schritte zur Fehlerbehebung wiedas Versorgen des Aufrufs mit anderen Parame-tern eingeleitet werden.

S7_ERR_RETRY Dieser Wert zeigt einen Fehler bei derAusführung des angeforderten Dienstes an.Dabei handelt es sich um ein temporäraufgetretenes Problem, wie z. B. um einenvorübergehenden Speicherengpaß. Der Aufrufkann ohne Änderung der Übergabeparameterwiederholt werden.

Beschreibung

Deklaration

Parameter

Return-Werte


136

3.7.2 s7_get_msg_initiate_cnf

Das Anwenderprogramm erhält beim 's7_receive'-Aufruf die AnzeigeS7_MSG_INITIATE_CNF, wenn der Anmeldevorgang abgearbeitetwurde. Danach muß diese hier beschriebene Funktion's7_get_msg_initiate_cnf' aufgerufen werden, um das Ergebnis einerALARM- oder SCAN-Anmeldung entgegenzunehmen.

int32 s7_get_msg_initiate_cnf(void)

keine


S7_ERR Dieser Wert zeigt einen Fehler bei der Ausführungdes angeforderten Dienstes an. Hier müssen wei-tere Schritte zur Fehlerbehebung wie das Versor-gen des Aufrufs mit anderen Parametern eingelei-tet werden.


Beschreibung

Deklaration

Parameter

Return-Werte


137

3.7.3 s7_msg_abort_req

Mit diesem Aufruf meldet sich die Applikation vom Empfang von Mel-dediensten ab.

int32 s7_msg_abort_req

(

ord32 cp_descr, /* Vorgabe */

ord16 cref, /* Vorgabe */

ord16 orderid, /* Vorgabe */

ord16 fct_code /* Vorgabe */

)




fct_code Funktionskennung Abmelden fürS7_SCAN_ALL_ABORT oderS7_ALARM_ALL_ABORT.


S7_ERR Dieser Wert zeigt einen Fehler bei der Ausfüh-rung des angeforderten Dienstes an. Hier müs-sen weitere Schritte zur Fehlerbehebung wie dasVersorgen des Aufrufs mit anderen Parameterneingeleitet werden.


Beschreibung

Deklaration

Parameter

Return-Werte


138

3.7.4 s7_get_msg_abort_cnf

Das Anwenderprogramm erhält beim 's7_receiv'-Aufruf die AnzeigeS7_MSG_ABORT_CNF, wenn der Abmeldevorgang abgearbeitet wur-de. Danach muß die hier beschriebene Funktion's7_get_msg_abort_cnf' aufgerufen werden, um das Ergebnis einerALARM- oder SCAN-Abmeldung entgegenzunehmen.

int32 s7_get_msg_abort_cnf(void)

keine




Beschreibung

Deklaration

Parameter

Return-Werte


139

3.7.5 s7_get_scan_ind

Mit dem Aufruf 's7_get_scan_ind' werden die vom SIMATIC S7-Auto-matisierungssystem gesendeten Nettodaten in die angegebenen Spei-cherbereiche kopiert. Wenn vom remoten Partner eine Meldung ge-sendet wurde, dann erhält das Anwenderprogramm beim's7_receive()'-Aufruf die Anzeige 'S7_SCAN_IND'.

Eine Quittierung von SCAN-Meldungen über SAPI-S7 ist momentannicht möglich.

int32 s7_get_scan_ind

(

void *od_ptr, /* Vorgabe */

ord16 *no_scan_objects_ptr, /* Rückgabe */

struct S7_TIME_STAMP *time_stamp_ptr,/* Rückgabe */

struct S7_SCAN_OBJECT *scan_objects_array/* Rückgabe */

)

od_ptr Dieser Parameter ist für zukünftige Erweiterun-gen vorgesehen und muß momentan mit NULLbelegt werden.

no_scan_objects_ptr Adresse des Datenwertes mit der Anzahl derempfangenen SCAN-Objekte.

time_stamp_ptr Adresse eines vom Anwenderprogramm bereit-gestellten Puffers einer Struktur für den Zeit-stempel des Ereignisses. Details zu diesem Pa-rameter sind weiter unten in einem besonderenAbsatz beschrieben.

scan_objects_array Adresse eines vom Anwenderprogramm bereit-gestellten Feldes von SCAN-Objektstrukturen.Details zu diesem Parameter sind weiter untenin einem besonderen Absatz beschrieben.

Beschreibung

Deklaration

Parameter


140

Adresse eines vom Anwenderprogramm bereitgestellten Puffers einerStruktur für den Zeitstempel des Ereignisses; es wird die Zeitangabedes SIMATIC S7-Automatisierungssystems verwendet.

struct S7_TIME_STAMP

{

ord16 year;

ord16 month;

ord16 day;

ord16 week_day;

ord16 hour;

ord16 minute;

ord16 second;

ord16 millisecond;

}

year Der Parameter gibt das Jahr an (1950 bis 2049);Beispiel: 1999 wird dargestellt als 1999.

month Der Parameter gibt den Monat an; Beispiel: März wird dargestellt als 3.

day Der Parameter gibt den Tag an;Beispiel: Der 30. Tag des Monats wird darge-stellt als 30.

week_day Der Parameter gibt den Wochentag an.

Die folgende Tabelle ordnet dem Parameterwertden Wochentag zu.

Parameterwert Wochentag1 Sonntag

2 Montag

usw. bis usw. bis

7 Samstag

hour Der Parameter gibt die Stunde an; der darstell-bare Bereich geht von 0 bis 23.

minute Der Parameter gibt die Minuten an; der darstell-bare Bereich geht von 0 bis 59.

second Der Parameter gibt die Sekunden an; der dar-stellbare Bereich geht von 0 bis 59.

millisecond Der Parameter gibt die Millisekunden an; derdarstellbare Bereich geht von 0 bis 999.

Erläuterungen desParameters'time_stamp_ptr'


141

Adresse eines vom Anwenderprogramm bereitgestellten Puffers einesFeldes mit der Anzahl von S7_MAX_SCAN_OBJECT Elementen. DieAnzahl der relevanten Elemente wird im Parameter'no_scan_objects_ptr' zurückgeben.

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 Angabe des allgemeinen Zustands, ob die Mel-dung vorhanden ist oder nicht:

Parameterwert BeschreibungS7_SCAN_MSG_EXIST OK

S7_SCAN_NO_MSG Meldung nichtvorhanden )*

)* Das mit Scan überwachte Objekt ist in derS7-CPU nicht vorhanden, z. B. Datenbau-stein mit zu überwachenden Daten ist ge-löscht.

ack_state Quittierungszustand des Scan-Objekts:

Bit Beschreibung0 Quittierung für gekommene Mel-

dung

1 bis 7 irrelevant

8 Quittierung für gegange Meldung

Beispiele für Meldungen:Temperatur zu hoch: gekommene MeldungTemperatur normal: gegangene Meldung

Beide Zustandsübergänge könnenunabhängigvon einander quittiert werden. Daher sind zweiunabhängige Bits sinnvoll.

SAPI-S7 quittiert bisher Meldungen nicht.Meldungen können möglicherweise von an-deren Bediensystemen quittiert werden.

Erläuterungen desParameters'scan_objects_array'

☞


142

event_state Ereigniszustand:

Bit Beschreibung0 aktueller Zustand des Ereignisses

1 bis 15 irrelevant

event_id Normierte Meldungsnummer

no_add_value Anzahl der Begleitwerte.

add_value Feld von Begleitwerten - Der Begleitwert wird imArray 'value' der Länge'S7_MAX_SCAN_ADD_VALUE_LEN+2' abge-legt.

Die Anzahl der relevanten Bytes dieses Arrayshängt vom Datentyp des im SIMATICS7-Automatisierungssystems projektierten Be-gleitwertes ab. Sie wird im Parameter'add_value_len' angegeben.

data_type Datentyp des Begleitwerts:

Parameterwert BeschreibungS7_DATATYPE_ERROR ERROR

S7_DATATYPE_BOOLEAN BOOLEAN

S7_DATATYPE_BITSTRING BITSTRING -Hinweis: Län-genangabe inByte statt inBit!

S7_DATATYPE_INTEGER INTEGER

S7_DATATYPE_OCTET_STRING STRING

add_value_len Anzahl der relevanten Bytes des Begleitwertes.

value Übertragener Begleitwert


S7_ERR Dieser Wert zeigt ebenfalls einen Fehler bei derAusführung des angeforderten Dienstes an. Al-lerdings handelt es sich hierbei um einen Fehler,der ein wiederholtes Ausführen des Dienstesnicht erlaubt. Hier müssen weitere Schritte zurFehlerbehebung wie das Versorgen des Aufrufsmit anderen Parametern eingeleitet werden.

Return-Werte


143



144

Beispiel zumAufruf derFunktion's7_get_scan_ind'

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; /* Timestamp */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: Timestamp */(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 additional values = %d", scan_objects[i].no_add_value);

/* loop over all additional values */for ( j= 0; j < scan_objects[i].no_add_value;j++ )

{/* prepare string buffer for additional value */TempBufferPtr = TempBuffer;TempBufferPtr += sprintf(TempBuffer,

" %d. additional value = ",j );


145

/* Length of addtional value */len = scan_objects[i].add_value[j].add_value_len;

for (l = 0; l < len ; l++ ){/* displaying additional 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 */


146

3.7.6 s7_get_alarm_ind

Mit dem Aufruf 's7_get_alarm_ind' werden die vom SIMATIC S7-Auto-matisierungssystem gesendeten Nettodaten in die angegebenen Spei-cherbereiche kopiert. Das Anwenderprogramm erhält beim's7_receive()'-Aufruf die Anzeige 'S7_ALARM_IND', falls vom remotenPartner ein Alarm gesendet wurde.

Eine Quittierung von Alarmen über SAPI-S7 ist momentan nicht mög-lich.

int32 s7_get_alarm_ind

(

void *od_ptr, /* Vorgabe */

ord16 *state_ptr, /* Rückgabe */

ord16 *ack_state_ptr, /* Rückgabe */

ord16 *event_state_ptr, /* Rückgabe */

ord32 *event_id_ptr, /* Rückgabe */

struct S7_TIME_STAMP *time_stamp_ptr,/* Rückgabe */

ord16 *no_add_value_ptr, /* Rückgabe */

struct S7_ADD_VALUE *add_value_ptr,/* Rückgabe */

)

od_ptr Dieser Parameter ist für zukünftige Erweiterun-gen vorgesehen und muß momentan mit NULLbelegt werden.

state_ptr Zeiger auf den Status - Der Status gibt den all-gemeinen Zustand an:

Bit Beschreibung0 Init-Anlauf1 Overflow-Signal

2 Overflow-Instanz3 bis 5 reserviert

6 Begleitwerte nicht eintragbar(Größe)

7 Begleitwerte nicht erreichbar

Beschreibung

Deklaration

Parameter


147

ack_state_ptr Zeiger auf den Quittungszustand des Alarmob-jekts:

Bit Beschreibung0 bis 7 Quittierung für gekommene

Meldung8 bis 15 Quittierung für gegange Mel-

dung

Beispiele für Meldungen:Temperatur zu hoch: gekommene MeldungTemperatur normal: gegangene Meldung

Beide Zustandsübergänge könnenunabhängigvon einander quittiert werden. Daher sind zweiunabhängige Bits sinnvoll.

SAPI-S7 quittiert bisher Meldungen nicht.Meldungen können möglicherweise von an-deren Bediensystemen quittiert werden.

event_state_ptr Zeiger auf den Ereigniszustand der 8 Signale:

Signal Bit Beschreibung

1 0 aktueller Zustand des Er-eignisses


usw. bis usw. bis usw. bis


event_id_ptr Zeiger auf die normierte Meldungsnummer.

time_stamp_ptr Zeiger auf die Adresse der Struktur für die Zeit-stempelalarmmeldung. Details zu diesem Para-meter sind weiter unten in einem besonderenAbsatz beschrieben.

no_add_value_ptr Zeiger auf ein Element, das die Anzahl derempfangenen Begleitwerte beschreibt.

add_value_ptr Zeiger auf ein Feld von Begleitwerten; Details zudiesem Parameter sind weiter unten in einembesonderen Absatz beschrieben.

☞


148




Return-Werte


149

Adresse eines vom Anwenderprogramm bereitgestellten Puffers einerStruktur für den Zeitstempel des Ereignisses.

struct S7_TIME_STAMP

{

ord16 year;

ord16 month;

ord16 day;

ord16 week_day;

ord16 hour;

ord16 minute;

ord16 second;

ord16 millisecond;

}

year Der Parameter gibt das Jahr an (1950 bis 2049);Beispiel: 1999 wird dargestellt als 1999.

month Der Parameter gibt den Monat an; Beispiel: März wird dargestellt als 3.

day Der Parameter gibt den Tag an;Beispiel: Der 30. Tag des Monats wird darge-stellt als 30.

week_day Der Parameter gibt den Wochentag an.

Die folgende Tabelle ordnet dem Parameterwertden Wochentag zu.

Parameterwert Wochentag1 Sonntag

2 Montag

usw. bis usw. bis

7 Samstag

hour Der Parameter gibt die Stunde an; der darstell-bare Bereich geht von 0 bis 23.

minute Der Parameter gibt die Minuten an; der darstell-bare Bereich geht von 0 bis 59.

second Der Parameter gibt die Sekunden an; der dar-stellbare Bereich geht von 0 bis 59.

millisecond Der Parameter gibt die Millisekunden an; derdarstellbare Bereich geht von 0 bis 999.

Erläuterungen desParameters'time_stamp_ptr'


150

Zeiger für ein Feld von Begleitwerten mit folgender Struktur.

Allokieren Sie Speicher für die Anzahl von Elementen, die in der Kon-stanten 'S7_MAX_ADD_VALUE' angegeben ist.

Der Begleitwert wird im Array 'value' der Länge'S7_MAX_ALARM_ADD_VALUE_LEN+2' abgelegt. Die Anzahl derrelevanten Bytes dieses Arrays hängt vom Datentyp des im SIMATICS7-Automatisierungssystem projektierten Begleitwerts ab. Sie wird imParameter 'add_value_len' angegeben.

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 Der Parameter gibt den Datentyp des Begleit-werts an:

Parameterwert BeschreibungS7_DATATYPE_ERROR ERROR

S7_DATATYPE_BOOLEAN BOOLEAN

S7_DATATYPE_BITSTRING BITSTRING -Hinweis: Län-genangabe inByte statt inBit!

S7_DATATYPE_INTEGER INTEGER

S7_DATATYPE_OCTET_STRING STRING

S7_DATATYPE_FLOAT Gleitpunktzahl

S7_DATATYPE_DATE Anzahl derTage seit1.1.1990

S7_DATATYPE_TIME_OF_DAY Millisekundenseit Tagesbe-ginn

S7_DATATYPE_TIME Zeitdauer inMillisekunden

S7_DATATYPE_S5_TIME S5-Zeitformat

add_value_len Anzahl der relevanten Bytes des Begleitwerts.

value Übertragener Begleitwert

Erläuterungen desParameters'add_value_ptr'


151

Beispiel zumAufruf derFunktion's7_get_alarm_ind'

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; /* Timestamp */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: achnowledge state */&event_state,&event_id, /* OUT: event id */&time_stamp, /* OUT: time stamp */&no_add_value, /* OUT: number of additional values */add_value /* OUT: startaddress of additional 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 additional values = %d",no_add_value);

/* loop over all additional values */for ( j= 0; j < no_add_value;j++ )

{/* prepare string buffer for additional value */TempBufferPtr = TempBuffer;TempBufferPtr += sprintf(TempBuffer,

" %d. additional value = ",j );

/* Length of addtional value */len = add_value[j].add_value_len;


152

for (l = 0; l < len ; l++ ){/* displaying additional value as byte array */TempBufferPtr += sprintf

(TempBufferPtr," %02x",add_value[j].value[l]);

}/* Output the whole string */MYPRINTF("%s",TempBuffer );

}}

}


153

3.8 VFD-Dienste

Als Erweiterung zum Beispiel aus Kapitel 3.5 wird nach dem Beendendes zyklischen Variable-Lesens noch der Status des remoten VFDabgefragt. Der Status gibt Auskunft über die Betriebsbereitschaft desremoten Kommunikationspartners.

Beispiel

::/* 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);

}}



154


int32 ret;


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));

}


ord16 cref;




/* receive vfd state confirmation */my_receive(cp_descr,S7_VFD_STATE_CNF);


}


155


s7_vfd_state_req()

remoter Partner

= S7_OK

s7_receive()

= S7_NO_MSG

s7_receive()


= S7_VFD_STATE_CNF

s7_get_vfd_state_cnf

= S7_OK

Anstoß zum Lesen desStatus eines remoten VFD





Ablaufdiagramm


156

3.8.1 s7_vfd_state_req

Mit dem Aufruf 's7_vfd_state_req()' kann eine Client-Applikation denlogischen und physikalischen Status eines anderen (remoten) virtuellenGerätes (VFD) lesen.

int32 s7_vfd_state_req

(ord32 cp_descr, /* Vorgabe */ord16 cref, /* Vorgabe */ord16 orderid /* Vorgabe */)



orderid Auftragskennzeichen zur Identifizierung des abzu-gebenden Auftrags und der zugehörigen Quittung.




Beschreibung

Deklaration

Parameter

Return-Werte


157

3.8.2 s7_get_vfd_state_cnf

Mit dem Aufruf 's7_get_vfd_state_cnf()' wird das Ergebnis eines VFD-Status-Auftrags entgegengenommen.

Das Anwenderprogramm erhält beim 's7_receive()'-Aufruf die Anzeige'S7_VFD_STATE_CNF', falls der Statusauftrag durchgeführt wurde.Danach muß die zugehörige Bearbeitungsfunktion's7_get_vfd_state_cnf()' zur internen Bearbeitung in der Library aufge-rufen werden.

Mit dem Aufruf 's7_get_vfd_state_cnf()' werden die gelesenen Werte(der physikalische, der logische Status des VFD und der lokale Statusder Anwendung) in Anwenderpuffer kopiert.

int32 s7_get_vfd_state_cnf

(ord16 *log_state_ptr, /* Rückgabe */ord16 *phy_state_ptr, /* Rückgabe */ord8 *local_detail_ptr /* Rückgabe */)

log_state_ptr Adresse einer vom Anwenderprogramm bereitge-stellten Variablen vom Typ 'ord16'. Hier wird derlogische Status des VFD vermerkt. Dieser Para-meter gibt an, welche Dienste momentan nutzbarsind. Hier ist 'S7_STATE_CHANGES_ALLOWED'als einziger Zustand möglich, d. h. es sind alleDienste erlaubt.

phy_state_ptr Adresse einer vom Anwenderprogramm bereitge-stellten Variablen vom Typ 'ord16'. Hier wird derphysikalische Status des VFD vermerkt. Der Wertdieses Parameters leitet sich aus den Zuständender Betriebsmittel ab. Im Fall'S7_OPERATIONAL' ist das VFD voll funktions-fähig, bei 'S7_NEEDS_COMMISSIONING' müs-sen noch lokale Eingriffe erfolgen, um in einenbetriebsbereiten Zustand zu gelangen.

local_detail_ptr Zeiger auf einen vom Anwenderprogramm bereit-gestellten Puffer, der eine Mindestgröße von 3Byte haben muß. Hier wird der lokale Status derAnwendung und des Gerätes abgelegt. Die Be-deutung der 3 Bytes ist VFD-spezifisch und in derzugehörigen VFD-Beschreibung des Serversnachzulesen.

Beschreibung

Deklaration

Parameter


158




Return-Werte


159

3.9 Diagnosedienste für hochverfügbare Verbindungen

Im Zusammenhang mit hochverfügbaren SIMATIC S7-Systemen, istes möglich hochverfügbare SAPI-S7-Verbindungen aufzubauen. Diesebestehen aus mehreren redundanten Verbindungen, die über unter-schiedliche Wege zu einem hochverfügbaren SIMATIC S7-Systemführen. Diese hochverfügbaren Verbindungen bleiben auch dann auf-gebaut, wenn eine der redundanten Verbindungen nicht mehr funktio-niert. Die Umschaltung erfolgt automatisch.

Fällt eine weitere redundante Verbindung aus, so kann dies zum Ab-bruch der hochverfügbaren Verbindung führen.

Mit den Diagnosediensten kann der Zustand einer hochverfügbarenVerbindung angezeigt und eine Störung (Teil- oder Totalausfall) er-kannt werden. Die Diagnosedienste melden jede Zustandsänderungeiner hochverfügbaren Verbindung und informieren, ob alle redundan-ten Verbindungen (Wege) funktionieren

Die Diagnosedienste liefern auch für Standardverbindungen Zustands-informationen.

Die Diagnosefunktionen stehen nur bei dem ProduktS7-REDCONNECT zur Verfügung.

Die Diagnosedienste können nur für Verbindungen, die mit STEP 7 zueiner Station vom Typ SIMATIC-PC-Station projektiert wurden, ver-wendet werden.

Beschreibung

Einschränkungen


160

Die Anmeldefunktion 's7_diag_init()' startet die Diagnosedienste. Lie-gen Diagnoseinformationen vor, erhält die Anwendung eine Windows-Message.Diese stößt die Funktion 's7_receive()' an, welche 'S7_DIAG_IND' zu-rückliefert.Der Rückgabeparameter muß vom Anwenderprogramm ausgewertetwerden, um dann die Diagnoseinformationen mit der Lesefunktion's7_get_diag_ind()' zu übernehmen. Diese liefert alle benötigten Infor-mationen (z.B. Status der projektierten Verbindungen, welche Verbin-dungswege benutzt werden, welche ausgefallen sind usw.) in einenvom Anwender bereitzustellenden Datenbereich.Die Funktion 's7_diag_stop()' beendet die Diagnosedienste und gibt diebelegten Ressourcen wieder frei.

5#2+�5�#PYGPFGTRTQITCOO

U�AFKCIAKPKV�

TGOQVGT 2CTVPGT

� 5�A1-

U�ATGEGKXG�

� 5�A&+#)A+0&

U�AIGVAFKCIAKPF�

� 5�A1-

&KCIPQUG CPOGNFGP

&KCIPQUG CDOGNFGP

&KCIPQUG�+PHQ KUV FC

9KPFQYU/GUUCIG

� 5�A1-

&KCIPQUG�+PHQ CDJQNGP

U�AFKCIAUVQR�

Bild 3.12: Ablaufdiagramm

Ablaufdiagramm


161

3.9.1 s7_diag_init

Anmelden für Diagnose-Meldungen. Alle Verbindungen mit dem gleichen cp_descr werden auf Änderungenüberwacht. Ändert sich der Zustand einer oder mehrerer dieser Verbin-dungen, wird eine durch s7_set_window_handle_msg definierte Win-dows-Message erzeugt. Die Applikation muß darauf s7_receive aufru-fen, um festzustellen, welches Ereignis eingetreten ist .

int s7_diag_init

(ord32 cp_descr, /* Vorgabe */)

cp_descr Der bei 's7_init()' zurückgelieferte cp_descr. Die Dia-gnosedaten beziehen sich auf alle Verbindungen, diemit dem bei 's7_init()' erhaltenen cp_descr aufgebautwerden.

S7_OK Die Funktion konnte ohne Fehler abgearbeitet wer-den.

S7_ERR Zeigt einen Fehler an, zu dessen Behebung weitereSchritte eingeleitet werden müssen.

Beschreibung

Deklaration

Parameter

Return-Werte


162

3.9.2 s7_get_diag_ind

Lesen der Diagnoseinformation, wenn eine Message mit s7_receiveempfangen wurde. Die Funktion gibt nur die für das gewünschte VFD(bei STEP 7 „Applikation“ genannt) relevanten Diagnoseinformationenaus und übergibt sie in einen bereitzustellenden Datenbereich.

int s7_get_diag_ind

(ord16 number, /* Vorgabe */CONN_INFO *info_ptr /* Rückgabe */)

number Anzahl der projektierten Verbindungen, wie sie bei-spielsweise mit 's7_get_conn()' ermittelt wer-den kann.

*info_ptr Zeiger auf ein Array von Strukturen des TypsCONN_INFO. Der Anwender muß im Array die imParameter 'number' übergebene Anzahl Elementezur Verfügung stellen.



S7_ERR_INVALID_DATA_SIZEDatenpuffer für Diagnoseinformation zu klein.

Beschreibung

Deklaration

Parameter

Return-Werte

Detailed ErrMsg


163

typedef struct

{

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 derStruktur

CONN_INFO

Mögliche Werte Erklärung

cref Referenz (Handle) der Verbindung,wie sie auch von 's7_get_cref()' zu-rückgeliefert wird.

conn_type Verbindungstyp

S7D_STD_TYPES7D_H_TYPE

StandardverbindungHochverfügbare Verbindung

conn_state Verbindungszustand (Standardverbindung)S7_DIAG_STD_DOWNS7_DIAG_STD_ABORT

S7_DIAG_STD_NOT_USEDS7_DIAG_STD_OK

Verbindung gewollt abgebautVerbindung ungewollt abgebaut(Fehler)Verbindung noch nie aufgebautVerbindung aufgebaut

Verbindungszustand (Hochverfügbare Verbindung)Im Idealfall besteht eine hochverfügbare Verbindung aus einer Produktivver-bindung, über die der Datenverkehr abgewickelt wird, und einer Standby-Verbindung, die als Reserve dient, falls die Produktivverbindung ausfällt.Dieser Zustand wird als redundant bezeichnet.

S7_DIAG_H_OK_REDS7_DIAG_H_OK_RED_PATH_CHG

S7_DIAG_H_OK_NOT_RED

S7_DIAG_H_ABORTS7_DIAG_H_NOT_USEDS7_DIAG_H_DOWN

Verbindung aufgebaut (redundant)Verbindung aufgebaut (redundant,es wurde umgeschaltet)Verbindung nicht redundant aufge-bautVerbindung ungewollt abgebautVerbindung noch nie aufgebautVerbindung gewollt abgebaut

way_state Zustand der VerbindungswegeS7_DIAG_HW_PRODS7_DIAG_HW_STBYS7_DIAG_HW_ABORTS7_DIAG_HW_NOT_USEDS7_DIAG_HW_DOWNS7_DIAG_HW_CN_BREAK

Weg ist ProduktivverbindungWeg ist Standby-VerbindungWeg wurde ungewollt abgebautWeg wurde noch nie aufgebautWeg wurde gewollt abgebautWeg konnte nicht aufgebaut werden

Aufbau derStrukturCONN_INFO


164

3.9.3 s7_diag_stop

Abmelden für Diagnose-Meldungen.

int s7_diag_stop

(Ord32 cp_descr /* Vorgabe */)

cp_descr Der bei 's7_diag_init ' angegebene cp_descr.



Beschreibung

Deklaration

Parameter

Return-Werte


165

4 Trace und Mini-DB

Im folgenden Kapitel lernen Sie den Umgang mit den Trace- und den Mini-DB-Aufrufenkennen. Sie erfahren,

➢ wie Sie Einträge in den Library-eigenen Trace ermöglichen können.

➢ wie Sie Einstellungen in der Mini-DB abfragen oder ändern können.

➢ wie Sie Informationen zum zuletzt aufgetretenen Fehler erhalten.

Am Ende des Kapitels können Sie

➢ die komplette Funktionalität, die Ihnen S7 bietet, für Ihre Applikation nutzen un-ter Beibehaltung einer einfachen SAPI-S7-Programmierschnittstelle.

➢ Fehlersituationen durch Ihre Applikation erkennen und beseitigen.


166

4.1 s7_trace

Mit diesem Aufruf können Eintragungen in den Trace der S7-Libraryvorgenommen werden. Dadurch ist es möglich, wichtige Daten zuKontrollzwecken zu sichern, den Programmablauf zu kontrollieren bzw.mit den Trace-Eintragungen zu synchronisieren.

void s7_trace

(char *msg /* Vorgabe */)

msg String mit der Anwendermeldung, die in den Traceeingetragen werden soll. Eine Trace-Zeile kann biszu 78 Zeichen enthalten, wobei aber 14 Zeichen fürdie seit der Initialisierung des Trace verstrichene Zeitund die Zeilennummer reserviert sind. Somit ist eineNetto-Datenlänge von 64 Zeichen je Trace-Aufruf er-reichbar. Längere Strings werden abgeschnitten.

keine

Beschreibung

Deklaration

Parameter

Return-Werte


167

4.2 s7_write_trace_buffer

Bei hochperformanten Anwendungen ist das Schreiben des Trace ineine Datei störend. Trotzdem sollen die Eintragungen in den Trace,z. B. im Fehlerfall, verfügbar sein. Deswegen wurde die Möglichkeitgeschaffen, mit Hilfe der Mini-DB den Trace dahingehend zu konfigu-rieren, daß sämtliche Trace-Einträge in einen internen Umlaufpuffererfolgen. Die gesamte Information kann dann mit der Funktion's7_write_trace_buffer()' in eine Datei geschrieben werden und stehtsomit für Fehleranalysen und Auswertung zur Verfügung.

void s7_write_trace_buffer

(char *filename /* Vorgabe */)

filename Name der Datei, in die der interne Umlaufpuffer ge-schrieben werden soll.

keine

Beschreibung

Deklaration

Parameter

Return-Werte


168

4.3 s7_mini_db_set

Mit diesem Aufruf werden Einstellungen in der Mini-DB überschrieben,um den verschiedensten Anforderungen bezüglich Aufbau einerS7-Verbindung, Trace und Fehlerabfragen gerecht zu werden. Für diegewünschten Daten und deren Werte sind nur eine gewisse Anzahl vonKombinationen möglich, die im folgenden noch beschrieben werden.

int32 s7_mini_db_set

(ord16 type, /* Vorgabe */char *value /* Vorgabe */)

type Kennzeichen für die zu ändernde Einstellung. Diemöglichen Übergabewerte sind im folgenden be-schrieben.

value Neuer Wert für die zu ändernde Einstellung. DerWert wird immer als String übergeben. Dafür ste-hen in der Header-Datei 'SAPI_S7.H' Defines zurVerfügung, die als ASCII-Zeichenkette dargestell-ten Zahlen entsprechen. Sind Kombinationen vonEinzelwerten erlaubt, so müssen zunächst die ein-zelnen Defines in Ganzzahlen gewandelt, oder-verknüpft und das Ergebnis wieder in einen Stringzurückgewandelt werden.




Beschreibung

Deklaration

Parameter

Return-Werte


169

Der Trace stellt eine einfache und trotzdem effektive Debug-Hilfe fürdie S7-Library dar. Er kann den verschiedensten Anwendungsfällenangepaßt werden. Die erlaubten Wertekombinationen werden im fol-genden ausgehend vom Parameter 'type' beschrieben.

Ab den SAPI-S7 Bibliotheken der Version V 1.371.2002 besteht dieMöglichkeit, die Trace-Ausgabe auf mehrere Dateien aufzuteilen. Hier-durch wird ein zu großes Anwachsen der Trace-Datei verhindert. DieAnzahl und Größe der Dateien läßt sich mit den Parametern S7_MINI_DB_TRACE_MAXFILES und S7_MINI_DB_TRACE_MAXLINESeinstellen.

S7_MINI_DB_TRACE_FILENAME

Mit diesem Parameterwert wird der Name der Trace-Datei bestimmt.Als 'value' wird der Dateiname übergeben (Default: 'S7TRACE.TXT' imaktuellen Arbeitsverzeichnis).

S7_MINI_DB_TRACE_TARGET

Dieser Wert legt das Target für den Trace fest.

Parameter 'value' Beschreibung

S7_TRACE_TARGET_BUFFER Die Trace-Einträge werden ineinen internen Umlaufpuffergeschrieben (Default-Einstel-lung).

S7_TRACE_TARGET_OLD_FILE Die Trace-Einträge werden ineine Datei geschrieben. Eineeventuell schon bestehendeDatei bleibt unverändert, an-schließende Trace-Einträgewerden an die Datei angehängt.

S7_TRACE_TARGET_NEW_FILE Die Trace-Einträge werden ineine Datei geschrieben. DieDatei wird neu erstellt, an-schließende Trace-Einträgewerden an die Datei angehängt.Eine überdimensional anwach-sende Trace-Datei kann hiermitvermieden werden.

S7_TRACE_TARGET_CONSOLE Die Trace-Einträge werden aneine andere Applikation weiter-geleitet. Das weitere Verhaltenist betriebssystemabhängig.

Wertekom-binationen für denTrace


170

S7_ MINI_DB_TRACE_MAXFILES

Der Trace ist ein Umlaufpuffer mit einer Anzahl von Dateien, die imParameter S7_MINI_DB_TRACE_MAXFILES angegeben wird. Hateine Datei ihre maximale Länge erreicht, wird eine neue Datei ange-legt. Haben alle Dateien ihre maximale Länge erreicht, wird immer dieälteste überschrieben.

Es sind Werte zwischen 1 und 999 einstellbar. Der Default-Werte ist 2.

S7_MINI_DB_TRACE_MAXLINES

Hiermit wird die Größe der S7_Trace-Dateien festgelegt

Es sind Werte zwischen 1 und 22-1 einstellbar. Die Größe sollte demverfügbaren Speicherplatz angepaßt werden.

Der Default-Wert ist 10.000.

S7_MINI_DB_TRACE_DEPTH

Hiermit wird die Trace-Tiefe eingestellt.


S7_TRACE_DEPTH_OFF Der Trace wird ausgeschaltet.

S7_TRACE_DEPTH_USER Mit diesem Wert (Default) wer-den nur die vom Anwenderpro-gramm durch die Funktion's7_trace()' vorgegebenenStrings in den Trace eingetra-gen.

S7_TRACE_DEPTH_EXCEPT Diese Einstellung läßt nurTrace-Einträge nach fehlerhaf-ten Ereignissen oder Ergebnis-sen zu.

S7_TRACE_DEPTH_INTERFACE Mit diesem Wert werden dar-über hinaus Übergabeparameteran der SAPI-S7-Programmier-schnittstelle in den Trace einge-tragen. Damit können fehlerhaf-te Parameter schnell und ohneDebugger erkannt werden.

S7_TRACE_DEPTH_OTHER Diese Einstellung liefert weitereInformationen.


171

S7_MINI_DB_TRACE_SELECT

Um den Trace dienstklassenspezifisch ein- oder auszuschalten, stehtje Dienstklasse ein Define in der Header-Datei 'SAPI_S7.H' zur Verfü-gung. Die Defines können wie oben beschrieben kombiniert werden.


S7_TRACE_SELECT_ADMIN_SERVICES Der Trace wird aktiviert für die ad-ministrativen Dienste.

S7_TRACE_SELECT_CONN_SERVICES Der Trace wird aktiviert für die S7-Verbindungsmanagementdienste.

S7_TRACE_SELECT_VAR_SERVICES Der Trace wird aktiviert für die Va-riablendienste.

S7_TRACE_SELECT_CYCL_VAR_SERVICES Der Trace wird aktiviert für die zykli-schen Variablendienste.

S7_TRACE_SELECT_RECEIVE_SERVICES Der Trace wird aktiviert für denEmpfangsaufruf.

S7_TRACE_SELECT_VFD_SERVICES Der Trace wird aktiviert für die VFD-Dienste.

S7_TRACE_SELECT_OTHER_SERVICES Der Trace wird aktiviert für die Zu-griffsfunktionen auf die Mini-DB.

S7_TRACE_SELECT_PBK_SERVICES Der Trace wird aktiviert für dieblockorientierten Dienste.

S7_TRACE_SELECT_ALL Der Trace wird aktiviert für sämtli-che Dienstklassen.

S7_MINI_DB_TRACE_NO_LINES

Mit diesem Parameter kann die Anzahl der Zeilen des internen Um-laufpuffers verändert werden. Für speicherplatzintensive Applikationenkann der Umlaufpuffer verkleinert, für das Auftreten von Fehlernzwecks Aufzeichnung der Vorgeschichte vergrößert werden. Die Funk-tion 's7_write_trace_buffer()' erlaubt das Schreiben des Umlaufpuffersin eine Datei.

Die Änderung dieses Parameters ist nur wirksam, wenn sie vordem ersten S7-Library-Aufruf geschieht.☞


172

Für den S7-Verbindungsaufbau können sowohl auf der aktiven alsauch auf der passiven Seite verschiedene Verbindungsparameter vor-besetzt werden, die zwischen den beiden Stationen ausgehandelt wer-den. Die erlaubten Wertekombinationen sind im folgenden ausgehendvom Parameter 'type' beschrieben.

S7_MINI_DB_INIT_REQ_AMQ_CALLING

Mit diesem Wert wird für den aktiven Partner vor dem Verbindungs-aufbau festgelegt, wieviele Aufträge mit Quittungen auf dieser Verbin-dung gleichzeitig empfangen werden können (Default: '3'). Hierbeihandelt es sich um einen Vorschlagswert, der von der Partnerstationakzeptiert oder heruntergehandelt werden kann. Der ausgehandelteWert kann mit Hilfe der Funktion 's7_mini_db_get()' ausgelesen wer-den.

S7_MINI_DB_INIT_REQ_AMQ_CALLED

Mit diesem Wert wird für den aktiven Partner vor dem Verbindungs-aufbau festgelegt, wieviele Aufträge mit Quittungen auf dieser Verbin-dung gleichzeitig gesendet werden können (Default: '3'). Hierbei han-delt es sich um einen Vorschlagswert, der von der Partnerstation ak-zeptiert oder heruntergehandelt werden kann. Der ausgehandelte Wertkann mit Hilfe der Funktion 's7_mini_db_get()' ausgelesen werden.

S7_MINI_DB_INIT_REQ_PDU_SIZE

Mit diesem Wert wird für den aktiven Partner vor dem Verbindungs-aufbau die maximale Größe einer PDU auf dieser Verbindung vorge-geben (Default: '0x100'). Hierbei handelt es sich um einen Vorschlags-wert, der von der Partnerstation akzeptiert oder heruntergehandeltwerden kann. Der ausgehandelte Wert kann mit Hilfe der Funktion's7_mini_db_get()' ausgelesen werden.

S7_MINI_DB_INIT_RSP_AMQ_CALLING

Mit diesem Wert wird für den passiven Partner vor dem Verbindungs-aufbau festgelegt, wieviele Aufträge mit Quittungen auf dieser Verbin-dung gleichzeitig gesendet werden können (Default: '3'). Ausgehandeltwird das Minimum der entsprechenden Größen auf der aktiven und aufder passiven Seite.

S7_MINI_DB_INIT_RSP_AMQ_CALLED

Mit diesem Wert wird für den passiven Partner beim Verbindungsauf-bau festgelegt, wieviele Aufträge mit Quittungen auf dieser Verbindunggleichzeitig empfangen werden können (Default: '3'). Ausgehandeltwird das Minimum der entsprechenden Größen auf der aktiven und aufder passiven Seite.

Wertekom-binationen für denAufbau vonS7-Verbindungen


173

S7_MINI_DB_INIT_RSP_PDU_SIZE

Mit diesem Wert wird für den passiven Verbindungsaufbau die maxi-male Größe einer PDU auf dieser Verbindung vorgegeben (Default:'0x100'). Ausgehandelt wird das Minimum der PDU-Größen auf deraktiven und auf der passiven Seite.

S7_MINI_DB_PERSISTANCE_COUNT

Mit diesem Wert wird die Anzahl der Wiederholungsversuche für einenaktiven Verbindungsaufbau gesetzt (Default: '5'). Erst wenn die Part-nerstation entsprechend oft den Aufbauwunsch abgelehnt hat, wird derVerbindungsaufbau beendet und dem Anwenderprogramm negativquittiert.

Dieser Wert kann bei bestimmten SIMATIC NET-Produkten eine ande-re Bedeutung haben. In diesem Fall wird die Bedeutung im jeweiligenProduktinfo erläutert.

S7_MINI_DB_ABORT_TIMEOUT

Mit diesem Wert wird die maximale Zeitdauer für Sendewiederholun-gen festgelegt, falls die remote Station nicht antwortet. Die Festlegungerfolgt in Vielfachen von 51 ms (Default: '3000'). Der Parameter giltsowohl für die Verbindungsaufbauphase als auch für die Datentrans-ferphase.

Dieser Wert kann bei bestimmten SIMATIC NET-Produkten eine ande-re Bedeutung haben. In diesem Fall wird die Bedeutung im jeweiligenProduktinfo erläutert.

Für TCP/IP-Protokolle ist dieser Wert ohne Bedeutung.


174

4.4 s7_mini_db_get

Mit diesem Aufruf werden Einstellungen aus der Mini-DB gelesen. DasAnwenderprogramm gibt ein Kennzeichen für die zu lesende Einstel-lung vor und erhält einen String zurück, der abhängig vom Kennzei-chen interpretiert werden muß.

const char *s7_mini_db_get

(ord16 type /* Vorgabe */)

type Kennzeichen für die zu lesende Einstellung. Diemöglichen Werte sind im folgenden beschrieben.

Die Mini-DB erlaubt bezüglich des Trace jederzeit das Lesen aller än-derbaren Einstellungen. Dies sind:

S7_MINI_DB_TRACE_FILENAME

Mit diesem Parameter wird der Name der Trace-Datei zurückgegeben.

S7_MINI_DB_TRACE_TARGET

Mit diesem Parameter wird das Target des Traces ausgegeben.

S7_MINI_DB_TRACE_DEPTH

Mit diesem Parameter kann die Trace-Tiefe abgefragt werden.

S7_MINI_DB_TRACE_SELECT

Mit diesem Parameter werden die Dienstklassen, für die der Traceaktiviert wurde, angezeigt.

Die Rückgabewerte entsprechen den Vorgabewerten beim Aufruf's7_mini_db_set()' und können dort nachgelesen werden.

Beschreibung

Deklaration

Parameter

Return-Werte fürTrace-Einstellungen


175

Nach Empfang einer Initiate-Confirmation werden von der entspre-chenden Bearbeitungsfunktion 's7_get_initiate_cnf()' zwischen Clientund Server ausgehandelte Leistungsparameter in die Mini-DB einge-tragen.

S7_MINI_DB_INIT_IND_AMQ_CALLING

Mit diesem Wert wird dem passiven Partner nach Erhalt der Initiate-Indication angezeigt, wieviele Aufträge der aktive Partner auf dieserVerbindung gleichzeitig empfangen kann.

S7_MINI_DB_INIT_IND_AMQ_CALLED

Mit diesem Wert wird dem passiven Partner nach Erhalt der Initiate-Indication angezeigt, wieviele Aufträge der aktive Partner auf dieserVerbindung gleichzeitig senden kann.

S7_MINI_DB_INIT_IND_PDU_SIZE

Mit diesem Wert wird dem passiven Partner nach Erhalt der Initiate-Indication angezeigt, wieviele Daten der aktive Partner auf dieser Ver-bindung empfangen kann.

S7_MINI_DB_INIT_CNF_AMQ_CALLING

Mit diesem Wert wird nach dem aktiven Verbindungsaufbau die Anzahlder Aufträge mit Quittungen ausgelesen, die auf dieser Verbindunggleichzeitig empfangen werden können. Der Wert wurde zwischen denbeiden Kommunikationspartnern beim Verbindungsaufbau ausgehan-delt.

S7_MINI_DB_INIT_CNF_AMQ_CALLED

Mit diesem Wert wird nach dem aktiven Verbindungsaufbau die Anzahlder Aufträge mit Quittungen ausgelesen, die auf dieser Verbindunggleichzeitig gesendet werden können. Der Wert wurde zwischen denbeiden Kommunikationspartnern beim Verbindungsaufbau ausgehan-delt.

S7_MINI_DB_INIT_CNF_PDU_SIZE

Mit diesem Wert wird nach dem aktiven Verbindungsaufbau die maxi-male Größe einer PDU auf dieser Verbindung ausgelesen. Der Wertwurde zwischen den beiden Kommunikationspartnern beim Verbin-dungsaufbau ausgehandelt.

Return-Werte fürAufbau einerS7-Verbindung


176

4.5 s7_last_iec_err_no

Sämtliche Fehlerkennungen werden von der S7-Library auf ein hand-habbares Maß abgebildet, um die Fehlerbehandlung in Applikationeneinfacher gestalten zu können. Nach IEC 1131 (International Electro-technical Commission) bestehen Norm-Fehlercodes, die mit diesemAufruf ausgelesen werden können.

ord16 s7_last_iec_err_no(void)

keine

Mögliche Rückgabewerte und deren Bedeutungen im einzelnen:

S7_ERR_IEC_NO

Es ist kein Fehler aufgetreten.

S7_ERR_IEC_DATA_TYPE_MISMATCH

Die Datentypen stimmen nicht überein.

S7_ERR_IEC_INVALID_REF

Die angegebene S7-Verbindungsreferenz existiert nicht.

S7_ERR_IEC_LOWER_LAYER

Es ist ein Fehler in den tieferen Schichten aufgetreten.

S7_ERR_IEC_NEG_RESPONSE

Der Client hat eine negative Quittung vom Kommunikationspartnererhalten.

S7_ERR_IEC_NO_ACCESS_TO_REM_OBJECT

Der Zugriff auf ein Objekt wurde abgelehnt.

S7_ERR_IEC_PARTNER_IN_WRONG_STATE

Die Partnerstation befindet sich in einem Zustand, in dem der abgege-bene Auftrag nicht bearbeitet werden kann.

Beschreibung

Deklaration

Parameter

Return-Werte


177

S7_ERR_IEC_RECEIVER_DISABLED

Der Server antwortet nicht.

S7_ERR_IEC_RECEIVER_OVERRUN

Die Ressourcen im Server sind erschöpft.

S7_ERR_IEC_RESET_RECEIVED

Es ist eine Anforderung zum Reset eingetroffen.


178

4.6 s7_last_iec_err_msg

Dieser Aufruf liefert zum vorhandenen IEC-Fehlercode einen Stringzurück, der den aufgetretenen Fehler beschreibt. Es handelt sich dabeium einen englischsprachigen Fehlerstring, der z. B. für Ausgaben aufeiner Operator-Console, in eine Protokolldatei etc. verwendet werdenkann.

const char *s7_last_iec_err_msg(void)

keine

Beschreibung

Deklaration

Parameter


179

4.7 s7_last_detailed_err_no

Mit diesem Aufruf erhält der Aufrufer eine Fehlernummer, die detaillier-tere Angaben zur Fehlerursache macht, als die genormten IEC-Fehlercodes.

ord16 s7_last_detailed_err_no(void)

keine

Mögliche Rückgabewerte und deren Bedeutungen im einzelnen:

S7_ERR_NO_ERROR

Es ist kein Fehler aufgetreten.

S7_ERR_CONN_ABORTED

Die S7-Verbindung wurde abgebrochen.

S7_ERR_CONN_CNF

Die S7-Verbindung konnte nicht aufgebaut werden.

S7_ERR_CONN_NAME_NOT_FOUND

Der angegebene S7-Verbindungsname konnte nicht gefunden werden.

S7_ERR_FW_ERROR

Auf der Anschaltung ist ein Firmware-Fehler aufgetreten.

S7_ERR_INSTALL

Beim Installieren des SIMATIC NET-Treibers bzw. beim Initialisierender Anschaltung ist ein Fehler aufgetreten, der eine Kommunikationunmöglich macht.

S7_ERR_INTERNAL_ERROR

Bei der Kommunikation wurden library-interne Daten überschrieben,die einen weiteren Betrieb der Applikation nicht zulassen.

Beschreibung

Deklaration

Parameter

Return-Werte


180

S7_ERR_INVALID_CONN_STATE

Der abgegebene Auftrag ist im aktuellen Zustand der S7-Verbindungnicht zulässig.

S7_ERR_INVALID_CREF

Die angegebene S7-Verbindungssreferenz ist ungültig.

S7_ERR_INVALID_CYCL_READ_STATE

Der Auftrag ist im aktuellen Status des zyklischen Leseauftrag nichterlaubt.

S7_ERR_INVALID_DATARANGE_OR_TYPE

Eingangsparameter der aufgerufenen Funktion außerhalb des gültigenWertebereichs.

S7_ERR_INVALID_DATA_SIZE

Der vom Anwenderprogramm bereitgestellte Datenpuffer ist zu klein.

S7_ERR_INVALID_ORDERID

Es besteht kein Auftrag mit dem angegebenen Auftragskennzeichen(Parameter 'orderid').

S7_ERR_INVALID_PARAMETER

Ein Übergabeparameter oder ein Vorgabewert in einer übergebenenStruktur ist nicht gültig.

S7_ERR_MAX_REQ

Die maximale Anzahl an Aufträgen mit Quittung, wie beim Verbin-dungsaufbau ausgehandelt, wurde schon abgesetzt.

S7_ERR_MINI_DB_TYPE

Der Parameter 'type' bei einem Mini-DB-Aufruf ist nicht erlaubt.

S7_ERR_MINI_DB_VALUE

Der Parameter 'value' bei einem Mini-DB-Aufruf ist nicht erlaubt.


181

S7_ERR_NO_LICENCE

Die für das Produkt notwendige Lizenz konnte nicht gefunden werden.

S7_ERR_NO_RESOURCE

Die zur Verfügung stehenden Ressourcen sind momentan erschöpft.

S7_ERR_NO_SIN_SERV

Der für S7-Applikationen unter Windows notwendige SIMATIC NET-Server, der Nachrichten an die zuständige Applikation schickt, konntenicht gestartet werden.

S7_ERR_OBJ_ACCESS_DENIED

Der Zugriff auf das gewünschte Objekt wurde abgelehnt.

S7_ERR_OBJ_ATTR_INCONSISTENT

Das OD oder die Attribute des angesprochenen Objekts sind inkonsi-stent.

S7_ERR_OBJ_UNDEFINED

Das Objekt, auf das zugegriffen werden soll, existiert nicht.

S7_ERR_ORDERID_USED

Das beim Aufruf übergebene Auftragskennzeichen (Parameter 'orde-rid') wird bereits benutzt.

S7_ERR_RECEIVE_BUFFER_FULL

Es wurde zwar eine Nachricht empfangen, die entsprechende Bearbei-tungsfunktion aber noch nicht aufgerufen.

S7_ERR_SERVICE_NOT_SUPPORTED

Der angeforderte Dienst wird nicht unterstützt.

S7_ERR_SERVICE_VFD_ALREADY_USED

Die Applikation oder ein anderer Prozeß hat sich schon auf das VFDangemeldet.


182

S7_ERR_SYMB_ADDRESS

Die im Auftrag übergebene symbolische Adresse ist fehlerhaft.

S7_ERR_SYMB_ADDRESS_INCONSISTENT

Die in der symbolischen Adresse enthaltene Größe der Anwenderdatenund die Größe des Anwenderpuffers sind widersprüchlich.

S7_ERR_TOO_LONG_DATA

Es sollten mehr Daten geschrieben werden als nach Norm zulässig.

S7_ERR_UNKNOWN_ERROR

Es ist ein unbekannter Fehler aufgetreten.

S7_ERR_WRONG_CP_DESCR

Der beim Aufruf angegebene CP-Descriptor ist nicht korrekt.

S7_ERR_WRONG_IND_CNF

Es wurde zu einer empfangenen Nachricht die falsche Bearbeitungs-funktion aufgerufen.


183

4.8 s7_last_detailed_err_msg

Dieser Aufruf liefert zur vorhandenen, detaillierten Fehlernummer eineFehlermeldung zurück, die den aufgetretenen Fehler beschreibt undHinweise zur Fehlerbehebung gibt. Es handelt sich dabei um einenenglischsprachigen Fehlerstring, der z. B. für Ausgaben auf einer Ope-rator-Console, in eine Protokolldatei etc. verwendet werden kann.

const char *s7_last_detailed_err_msg(void)

keine

Beschreibung

Deklaration

Parameter


184

4.9 s7_discard_msg

Mit diesem Aufruf kann eine empfangene Nachricht verworfen werden,ohne die entsprechende Bearbeitungsfunktion aufgerufen zu haben.

Für jede S7-Verbindung können nur eine maximal festgelegte undbeim Aufbau ausgehandelte Anzahl von quittierten Aufträgen gleich-zeitig bearbeitet werden. Das Ignorieren von (z. B. unerwarteten) Er-eignissen und damit das Fehlen von Quittungen vermindert dauerhaftdie Anzahl der gleichzeitig nutzbaren Aufträge mit Quittungen.

void s7_discard_msg(void)

keine

Beschreibung

Deklaration

Parameter


185

5 Projektierung

In diesem Kapitel

➢ lernen Sie die Bedeutung der Projektierung kennen,

➢ erhalten Sie einen Überblick über die zum Betrieb notwendigenProjektierungsparameter,

➢ finden Sie eine Zusammenfassung der Dienste, die Projektierungsparameterverwenden.

Am Ende des Kapitels sind Sie in der Lage, Ihre SAPI-S7-Applikation auf die Projektie-rung abzustimmen.


186

5.1 Bedeutung der Projektierung

Um Applikationen von Anpassungen bei Änderungen im Kommunikati-onssystem (Netz) freizuhalten, erfolgt die Bereitstellung und Zuord-nung von S7-Verbindungen mittels Projektierung. Die Projektierung isteine standardisierte Methode, Adreßparameter usw. für alle Applikatio-nen einstellbar zu machen. In der Regel wird die Inbetriebnahme vonSoftware und deren Integration ins Netz nicht vom Softwareentwicklerdurchgeführt.

Bei einer Umprojektierung ist darauf zu achten, daß die für die Appli-kation sichtbaren Projektierungsparameter weiterhin Bestand haben.So muß z. B. der Name einer S7-Verbindung immer noch existieren,auch wenn über diese Verbindung eine andere Partnerstation, u. U.sogar mit einer anderen S7-Verbindungsreferenz, angesprochen wer-den soll. Anpassungen können unter dieser Randbedingung mit denentsprechenden Projektierungswerkzeugen jederzeit ohne Eingriff indie Anwenderprogramme vorgenommen werden.

In Kapitel 6.5 ist der Zugriff auf die Projektierung beschrieben.

Projektierung er-höht die FlexibilitätIhrer Applikation


187

5.2 Dienste mit Projektierdaten

Von den administrativen Diensten benötigt die Anmeldefunktion's7_init()' zwei Vorgaben:

➢ zum einen muß der CP-Name, der einen CP identifiziert, vorge-geben werden und mit einem bei der Installation festgelegtenNamen übereinstimmen; die Installation wird von denSIMATIC NET-Produkten übernommen. Die notwendigen Be-schreibungen liegen dem jeweiligen Produkt bei;

➢ zum anderen wird der Name des lokalen VFD benötigt, auf dassich das Anwenderprogramm anmelden will. Für die Applikationwerden durch die Anmeldung die VFD-eigenen S7-Verbindungenzugänglich. Der VFD-Name wird per Projektierung festgelegt.

Die Namen der installierten CPs bzw. die Namen der auf einem CPprojektierten VFDs, denen Verbindungen zugeordnet wurden, könnenmit den Aufrufen 's7_get_device()' bzw. 's7_get_vfd()' abgefragt wer-den.

Von den Managementdiensten für S7-Verbindungslisten benötigt ledig-lich der Aufruf 's7_get_cref()' einen Projektierungsparameter in Formdes S7-Verbindungsnamens. Diese Funktion liefert die Referenz füreine S7-Verbindung zurück. Eine Applikation sollte im weiteren Verlaufdie so ermittelte Referenz verwenden.

Die Namen aller projektierten S7-Verbindungen können mit dem Aufruf's7_get_conn()' ausgelesen werden.

AdministrativeDienste

Management-dienste für S7-Ver-bindungslisten


188

5.3 Projektierung mit STEP 7 V5

Die Projektierung der SAPI-S7-Verbindungen vom PC zum SIMATICS7-Automatisierungssystem ist ab STEP 7 V5 auch mit STEP 7 mög-lich.

Wählen Sie dazu in STEP 7 den Stationstyp SIMATIC-PC-Station.

Die von STEP 7 erzeugte Konfigurationsdatei (XDB-Datei) muß aufden PC kopiert werden. Der Ort der XDB-Datei ist über das Programm‚'PG-PC-Schnittstelle einstellen' (Lasche STEP 7 Projektierung) wähl-bar.

Hochverfügbare Verbindungen müssen mit STEP 7 V5 projektiert wer-den. Weitere Hinweise zur Projektierung finden Sie in der STEP 7 V5Dokumentation.

Bitte überprüfen Sie anhand der Produktinfos Ihres SIMATIC NET-Pro-dukts, ob eine Projektierung mit STEP 7 V5 unterstützt wird.

Wird die Verbindungsprojektierung über STEP 7 gewählt, so müssenalle S7-Verbindungen auf einem PC mit STEP 7 projektiert werden.

Hochverfügbare Verbindungen stehen nur bei dem ProduktS7-REDCONNECT zur Verfügung.

Vorgehen

Einschränkungen


189

6 SAPI-S7 unter MS-DOS/Windows

Im folgenden Kapitel lernen Sie die betriebssystemspezifischen Eigenschaften derSAPI-S7-Programmierschnittstelle für MS-DOS und Windows kennen. Dabei werdenmit der Bezeichnung „Windows“ die Windows-Betriebssysteme Windows 3.x (3.1 und3.11) im sogenannten „enhanced mode 386“, Windows 95 sowie Windows NT zusam-mengefaßt, falls nicht eines dieser Systeme explizit benannt wird.

Sie erfahren,

➢ für welche Compiler und Speichermodelle die S7-Library unter MS-DOS undWindows zur Verfügung steht,

➢ welche Compileroptionen bei der Übersetzung eigener Applikationen sinnvollsind,

➢ welche Linker-Optionen beim Linken Ihrer Programmodule mit der S7-Librarynotwendig sind,

➢ wie Sie den Trace durch Environmentvariablen steuern können, ohne Ihre Appli-kation ändern zu müssen.

Am Ende des Kapitels können Sie

➢ eigene Programmodule übersetzen und zusammen mit der S7-Library zu einemausführbaren Programm binden,

➢ die Trace-Ausgaben Ihrer Applikation steuern.


190

6.1 Allgemeines

Die SAPI-S7-Programmierschnittstelle wird in Form von Libraries zurVerfügung gestellt. Die für die Benutzung der Programmierschnittstellenotwendigen Definitionen sind in der Datei 'SAPI_S7.H' hinterlegt. Eswerden Libraries für MS-DOS, Windows 3.x sowie für Windows 95 undWindows NT für verschiedene Compiler angeboten.

Für MS-DOS und Windows 3.x setzen sich die Namen dieser Librarieswie folgt zusammen:

<Speichermodell><Betriebssystem>s7<Compiler>.lib

Die nachfolgende Tabelle erklärt die Komponenten, aus denen sich derLibrary-Namen zusammen setzt:

Formatbezeichnung Formateintrag Bedeutung

<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

Beispielsweise handelt es sich bei der Datei 'LDS7TC.LIB' um die mitdem Turbo-C-Compiler im Speichermodell 'Large' übersetzte Libraryfür das Betriebssystem MS-DOS.

Für das Betriebssystem Windows 3.x steht mit der Datei 'S7.DLL' eineDLL-Version (Dynamic Link Library) zur Verfügung mit den Import-Libraries 'S7MSC.LIB' und 'S7BC.LIB' für den Microsoft-C- bzw. Bor-land-C-Compiler.

Für Windows 95 und Windows NT wird eine 32-Bit-DLL 'S732.DLL' unddie zugehörige Importlibrary 'S7MSC.LIB' zur Verfügung gestellt.

Speichermodelle


191

Normalerweise werden Variablen vom Compiler in einer Form imSpeicher abgelegt, wie es für den Compiler am sinnvollsten erscheint.Hierbei können zwischen Komponenten einer Variablen Lücken entste-hen (padding bytes).

Die Strukturen, die an der SAPI-S7-Programmierschnittstelle angebo-ten werden, sind so ausgelegt, daß mit Byte- oder Word-Alignmentübersetzte Anwenderprogramme problemlos auf die einzelnen Kompo-nenten zugreifen können. Double-Word-Alignment wird von derS7-Library nicht unterstützt.

Anwenderprogramme müssen sich zwecks Kommunikation beimKommunikationssystem anmelden, das zur Verwaltung Ressourcenbelegt. Wird eine Applikation durch die Tastenkombination 'CTRL+C'abgebrochen, bleiben die Ressourcen für den Prozeß reserviert, unddie Anmeldung hat weiterhin Bestand. Um dies zu vermeiden, sollte imAnwenderprogramm ein 'CTRL+C'-Handler implementiert sein, der beiProgrammabbruch sämtliche Abmeldungen beim Kommunikationssy-stem übernimmt.

Alignment

Programmabbruch


192

6.2 Übersetzen und Binden für MS-DOS

In den folgenden Kapiteln werden Generierbeispiele aufgelistet, dieIhnen die notwendigen Compiler- und Linker-Optionen für Ihre Applika-tionen vermitteln.

Die absoluten und auf Ihrem Zielrechner gültigen Laufwerks- undPfadangaben müssen von Ihnen in die Generieranweisung eingebrachtbzw. im Suchpfad aufgenommen werden.

Die S7-Library für den MSC-Compiler 7.0 hat unter MS-DOS den Na-men 'LDS7MSC.LIB'. Das folgende Beispiel zeigt, wie ein Beispielpro-gramm 'BSP.C' mit dem Speichermodell 'Large' für MS-DOS übersetztund gebunden wird:

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

link @bsp.lnk

In der Datei 'BSP.LNK' stehen die Anweisungen für den Linker:

bsp.obj,

bsp.exe,

bsp.map,

lds7msc.lib+

\msc70\lib\oldnames.lib+

\msc70\lib\llibce.lib

;

Voraussetzungen

Arbeiten mit demMSC-Compiler 7.0


193

Wenn Sie den MS Visual C++-Compiler 1.0 für Ihre MS-DOS-Applikationen einsetzen wollen, so können Sie dieselbe S7-Library wiefür den MSC-Compiler 7.0 verwenden. Die Generieranweisungen fürdas Speichermodell 'Large' haben dann unter MS-DOS folgendes Aus-sehen:


link @bsp.lnk


bsp.obj,

bsp.exe,

bsp.map,

lds7msc.lib+

\msvc\lib\oldnames.lib+

\msvc\lib\llibce.lib

;

Für den Turbo-C-Compiler 1.0 liegen für MS-DOS zwei Ausprägungender S7-Library vor: 'LDS7TC.LIB' für das Speichermodell 'Large' und'HDS7TC.LIB' für das Speichermodell 'Huge'. Das folgende Beispielzeigt, wie ein Beispielprogramm 'BSP.C' mit dem Speichermodell 'Lar-ge' für MS-DOS übersetzt und gebunden wird:

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

tlink @bsp.lnk.


\tc10\lib\c0l.obj bsp.obj

bsp.exe

bsp.map

\tc10\lib\emu.lib \tc10\lib\mathl.lib \tc10\lib\cl.lib LDS7TC.LIB

Arbeiten mit demMS Visual C++-Compiler 1.0

Arbeiten mit demTurbo-C-Compiler 1.0


194

6.3 Übersetzen und Binden für Windows 3.x

In den folgenden Kapiteln werden Generierbeispiele aufgelistet, dieIhnen die notwendigen Compiler- und Linker-Optionen für Ihre Applika-tionen vermitteln sollen.


Die S7-Library für den MSC-Compiler 7.0 hat unter Windows 3.x denNamen 'LWS7MSC.LIB'. Das folgende Beispiel zeigt, wie ein Beispiel-programm 'BSP.C' mit dem Speichermodell 'Large' für Windows 3.xübersetzt und gebunden wird:


link @bsp.lnk


bsp.obj,

bsp.exe,

bsp.map,

lws7msc.lib+

\msc70\lib\oldnames.lib +

\msc70\lib\llibcew.lib +

\msc70\lib\libw.lib

bsp.def;

Die Moduldefinitionsdatei 'bsp.def' hat folgendes Aussehen:

NAME BSP

EXETYPE WINDOWS

CODE PRELOAD MOVEABLE DISCARDABLE

DATA PRELOAD MOVEABLE MULTIPLE

HEAPSIZE 1024

STACKSIZE 10240

EXPORTS

Voraussetzungen

Arbeiten mit demMSC-Compiler 7.0


195

Wenn Sie den MS Visual C++-Compiler 1.0 für Ihre Windows-Applikationen einsetzen wollen, so können Sie dieselbe S7-Library wiefür den MSC-Compiler 7.0 verwenden. Die Generieranweisungen fürdas Speichermodell 'Large' haben dann unter Windows 3.x folgendesAussehen:


link @bsp.lnk


bsp.obj,

bsp.exe,

bsp.map,

lws7msc.lib+

\msvc\lib\oldnames.lib +

\msvc\lib\llibcew.lib +

\msvc\lib\libw.lib

bsp.def;


NAME BSP

EXETYPE WINDOWS



HEAPSIZE 1024

STACKSIZE 10240

EXPORTS

Arbeiten mit demMS Visual C++-Compiler 1.0


196

Die S7-Library für den Borland-C-Compiler 3.1 hat unter Windows 3.xden Namen 'LWS7BC.LIB'. Das folgende Beispiel zeigt, wie ein Bei-spielprogramm 'BSP.C' mit dem Speichermodell 'Large' für Windows3.x übersetzt und gebunden wird:

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

tlink /Twe @bsp.lnk


\bc31\lib\c0wl.obj bsp.obj

bsp.exe

bsp.map

lws7bc.lib \bc31\lib\mathwl.lib \bc31\lib\import.lib\bc31\lib\cwl.lib

bsp.def


NAME BSP

EXETYPE WINDOWS



HEAPSIZE 1024

STACKSIZE 10240

EXPORTS

Unter dem Betriebssystem Windows 3.x steht neben den oben aufge-führten Libraries auch eine DLL-Version (Dynamic Link Library) zurVerfügung (Datei 'S7.DLL') und die notwendigen Import-Libraries fürden MSC-Compiler 7.0 und MS Visual C++-Compiler 1.0 (Datei'S7MSC.LIB') bzw. den Borland-C-Compiler 3.1 (Datei 'S7BC.LIB').

Die Generiervorschriften von SAPI-S7-Applikationen, die auf dieDLL-Version von SAPI-S7 aufsetzen, ähneln den Vorschriften für Ap-plikationen, die die SAPI-S7-Libraries verwenden. Die obigenSAPI-S7-Libraries 'LWS7MSC.LIB' und 'LWS7BC.LIB' sind durch dieImport-Libraries 'S7MSC.LIB' und 'S7BC.LIB' zu ersetzen. Darüberhinaus muß beim Compilieren von Quelldateien, dieSAPI-S7-Funktionen benutzen, das Define 'S7_DLL' gesetzt sein.

Wie Sie diese DLL in anderen Programmiersprachen (z. B. BASIC,Pascal) einsetzen, entnehmen Sie bitte den entsprechenden Handbü-chern.

Arbeiten mit demBorland-C-Compiler 3.1

SAPI-S7 alsDLL-Version


197

6.4 Übersetzen und Binden für Windows 95 und Windows NT

In den folgenden Kapiteln werden Generierbeispiele aufgelistet, dieIhnen die notwendigen Compiler- und Linker-Optionen für Ihre Applika-tionen vermitteln sollen.


Die S7-Importlibrary für den Microsoft Visual C++-Compiler 2.2 hatunter Windows 95 und Windows NT den Namen 'S7MSC.LIB'. Diezugehörige DLL hat den Namen 'S732.DLL'. Das folgende Beispielzeigt, wie ein Beispielprogramm 'BSP.C' für Windows 95 übersetzt undgebunden wird. Für Windows NT ist lediglich das Verzeichnis'SAPI_S7.W95' durch 'SAPI_S7.NT' zu ersetzen:

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:"bsp.exe" @bsp.dat

In der Datei 'BSP.DAT' stehen die Anweisungen für den Linker:

bsp.obj,

\sinec\sapi_s7.w95\lib\s7msc.lib

\msvc20\lib\kernel32.lib

\msvc20\lib\user32.lib

\msvc20\lib\gdi32.lib

\msvc20\lib\libc.lib

/SUBSYSTEM:windows /MACHINE:I386

Voraussetzungen

Arbeiten mit demMSVC-Compiler 2.2


198

6.5 Environmentvariablen

Beim Environment handelt es sich um einen Speicherbereich, in demdie Parameter abgespeichert sind, die über die MS-DOS-Befehle'path', 'prompt' und 'set' gesetzt werden. Er besteht aus einer Aneinan-derreihung von ASCII-Strings, die durch ein NULL-Zeichen abge-schlossen werden. Er wird verwendet, um Informationen über das ge-samte Computersystem festzuhalten.

Die Werte der für die SAPI-S7-Library notwendigen Umgebungsvaria-blen sind mit dem Konfigurationsprogramm „PG/PC-Schnittstelleeinstellen“ einzustellen. Dieses Programm setzt die Werte unter demSchlüssel„HKEY_LOCAL_MACHINE\SOFTWARE\SIEMENS\SINEC\SAPI_S7“in der Registrierdatenbank von Windows 95/NT. Erst wenn dort keinEintrag mit dem gesuchten Namen vorhanden ist, wird die Variable inder Programmumgebung gesucht.

Der Trace der S7-Library kann durch insgesamt drei Environmentva-riablen gesteuert werden. Mit den Variablen 'S7_TRACE_SELECT','S7_TRACE_DEPTH' und 'S7_TRACE_TARGET' können die Dienst-klassen, für die Eintragungen im Trace erfolgen sollen, die Trace-Tiefeund das Target des Trace eingestellt werden (siehe Datei'SAPI_S7.H').

Beispiel: set S7_TRACE_DEPTH=104

Das Vorhandensein und die Auswertung der Umgebungsvariablenerfolgt beim Initialisieren des Trace. Trace-Einstellungen, die schonzuvor getätigt wurden, werden hier überschrieben.

Es wird empfohlen, den Trace mit Hilfe der genannten Environment-variablen und nicht durch die Mini-DB-Aufrufe einzustellen. Damit kön-nen die Defaultwerte zu Debug-Zwecken überschrieben werden, ohnedaß die Applikation geändert und neu übersetzt werden muß.

Unter Windows 95 und Windows NT kann der Wert der Variablen auchdadurch festgelegt werden, daß Einträge mit den Namen der Umge-bungsvariablen in der Registrierdatenbank unter dem Schlüssel"HKEY_LOCAL_MACHINE\SOFTWARE\SIEMENS\SINEC\SAPI_S7"abgelegt werden.

Environment, wasist das?

Umgebungs-variablen derSAPI-S7-Libraryunter Windows 95und Windows NT

Steuerung desTrace


199

In dem Konfigurationsprogramm „PG/PC-Schnittstelle einstellen“ läßtsich die Laufwerksbezeichnung, der Pfad und der Name der Projek-tierdatei einstellen.

Schritt Vorgehen

1 Wählen Sie in dem Listenfeld 'Benutzte Baugruppenpa-rametrierung' eine Baugruppenparametrierung aus.

2 Klicken Sie auf die Schaltfläche 'Eigenschaften'.

3 Wählen Sie das Register 'S7-Protokoll'

4 Aktivieren Sie das Kontrollkästchen 'S7 aktivieren'

5 Geben Sie in dem Eingabefeld 'SAPI S7-Datenbasis' dieLaufwerksbezeichnung, den Pfad und den Namen derProjektierdatei an.

Unter MS-DOS und Windows 3.x versucht die SAPI-S7-Library denPfad der Projektierdatei einer Umgebungsvariablen zu entnehmen. DerNamen der Umgebungsvariablen entspricht dem Eintrag in der Regi-strierdatenbank unter Windows 95 und Windows NT, beim CP'CP_L2_1:' also 'CP_L2_1:_S7LDB'.

Wird beim Aufruf der Funktion 's7_init()' auch keine entsprechendeUmgebungsvariable gefunden, so versucht die SAPI-S7-Library dieProjektierdaten aus einer Datei im aktuellen Verzeichnis auszulesen.Der Dateiname wird aus dem Übergabeparameter 'cp_name' ermittelt,wobei der Doppelpunkt, mit dem der CP-Name abschließt, entfernt unddie Namenserweiterung '.LDB' angehängt wird. So wird, z. B. beimAnmelden des CP 'CP_L2_1:', die Datei 'CP_L2_1.LDB' ausgelesen.

Wie erfolgt derZugriff auf dieProjektierung?


200

6.6 Der Trace für MS-DOS oder Windows

Für den Trace der SAPI-S7-Programmierschnittstelle ist eine betriebs-systemabhängige Einstellung möglich: per Mini-DB-Aufruf kann dasTarget des Trace auf den Wert 'S7_TRACE_TARGET_CONSOLE'geändert werden. Das weitere Verhalten ist wie bereits beschriebenbetriebssystemabhängig und wird im folgenden näher erläutert.

Unter Windows wird bei der obigen Trace-Einstellung der gesamteTrace auf dem Bildschirm in einem eigenen Fenster ausgegeben. DasFenster kann an eigene Bedürfnisse angepaßt werden. Die Konfigura-tionsmöglichkeiten, wie Anzahl der auszugebenden Trace-Zeilen, sindder Online-Hilfe zu entnehmen.

Bei der oben genannten Trace-Einstellung werden unter dem Betriebs-system MS-DOS keinerlei Trace-Einträge getätigt. Als Single-User-Betriebssystem ist MS-DOS nicht in der Lage, eine zweite Applikationparallel zum S7-Anwenderprogramm zu starten, die den Trace aufbe-reitet und auf dem Bildschirm darstellt.

Allgemein

Die Trace-Einstellung fürWindows

Die Trace-Einstellung für MS-DOS


201

6.7 Besonderheiten für Windows

Windows-Applikationen unterscheiden sich von MS-DOS-Programmenu. a. dadurch, daß sie im Hauptprogramm an einer zentralen Stelle alleEreignisse empfangen und zur Bearbeitung an eine zuständige Win-dows-Procedure ('WndProc') weitergeben. Diese Windows-Proceduremuß bei Programmstart der Windows-Verwaltung zugänglich gemachtwerden.

::#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 einer Windows-Applikation muß nach 's7_init()' die Routine's7_set_window_handle_msg()' mit einem Window-Handle und einerMessage-ID aufgerufen werden, damit das unterlagerte Kommunikati-onssystem eine Meldung an die Applikation schicken kann. Mit Emp-fang einer Nachricht wird die Applikation durch eine Message infor-miert. Die aufgerufene Windows-Procedure ruft dann 's7_receive()'und die entsprechende Bearbeitungsfunktion auf.

Unterschied MS-DOS-/Windows-Programme

Beispiel einertypischenWindows-Applikation


202

6.7.1 s7_set_window_handle_msg

In einem Windows-Programm muß das Anwenderprogramm nach ei-nem erfolgreichen 's7_init()' die Routine's7_set_window_handle_msg()' aufrufen. Damit wird dem unterlagertenKommunikationssystem mitgeteilt, an welches Window und mit wel-cher ID es seine Nachrichten verschicken soll.

int32 s7_set_window_handle_msg

(ord32 cp_descr, /* Vorgabe */ord32 hWnd, /* Vorgabe */ord32 msgID /* Vorgabe */)


hWnd Handle des Windows, an das die SIMATIC NET-Message geschickt werden soll.

msgID ID der SIMATIC NET-Message, die an obigesWindow geschickt wird.




Beschreibung

Deklaration

Parameter

Return-Werte


203

7 Anhang

Im folgenden Kapitel erfahren Sie,

➢ welcher S7-Subset von der SAPI-S7-Library abgedeckt wird,

➢ welche Randbedingungen beim Betrieb der SAPI-S7-Library zu beachten sind,

➢ wie S7-Variablen im allgemeinen und die Standard-Datentypen von S7 darge-stellt werden (sowohl im Host als auch auf dem Netz).

Am Ende des Kapitels erhalten Sie einen Überblick über die gängigsten und in diesemDokument benutzten Abkürzungen sowie ein Literaturverzeichnis.


204

7.1 Funktionsumfang von SAPI-S7

Die SAPI-S7-Programmierschnittstelle bietet den Zugang zu dennachfolgend aufgeführten Diensten (Abkürzung: 'req' für Request, 'ind'für Indication, 'con' für Confirmation und 'rsp' für 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 RevisionIdentifier

- (can be set by COML)

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(enter 'YES' or 'NO')

YES

Called S7 User(enter 'YES' or 'NO')

YES

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

SAPI-S7 als Subsetvon S7


205

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 ExtensionArguments

0

PICS Part 4

Local Implementation Values Detail

Maximum length of S7-PDU 1024

Maximum number of ServicesOutstanding Calling

-

Maximum number of ServicesOutstanding Called

-

Syntax and semantics of the Exe-cution Argument

-

Syntax and semantics of Exten-sion

-

Beim Betrieb der SAPI-S7-Programmierschnittstelle sind folgendeRandbedingungen zu beachten:

Die Anzahl der möglichen Aufträge und Verbindungen entnehmenSie bitte der Produktinformation der eingesetzten Produkte(SIMATIC NET und SIMATIC S7 CPU).

Randbedingungen

☞


206

7.2 Besondere Hinweise

Information zu Datenkonsistenz, Nutzdatengröße und zyklisches Lesenkönnen im Handbuch Kommunikation mit SIMATIC (MLFB 6ES7398-8EA00-8AA0) nachgelesen werden.

Datenkonsistenz,Nutzdatengröße,zyklisches Lesen


207

7.3 Formeln zur Berechnung des Mengengerüstes beiVariablendiensten

In nachfolgender Tabelle wird die Maximallänge der Ergebnis-/Nutz-daten in Abhängigkeit der PDU-Größe als Formel angegeben.

Bei Diensten mit mehreren Variablen wird auch die maximale Anzahlvon Variablen in Abhängigkeit der PDU-Größe als Formel angegeben.

Dienst Formel Anmerkung

S7_read_req Len = PDU-Größe – 18

Len = Maximale Länge der Er-gebnisdaten in Abhängig-keit von der PDU-Größe

s7_write_req Len = PDU-Größe – 28

Len = Maximale Länge derNutzdaten in Abhängig-keit von der PDU-Größe

Die Länge der Nutzdaten kann256 Byte nicht überschreiten.

s7_write_long_req Len = PDU-Größe - 28

Len = Maximale Länge derNutzdaten in Abhängig-keit von der PDU-Größe

s7_multiple_read_req Nvar = (PDU-Größe – 12) / 12

Nvar = Maximale Anzahl vonVariablen in einem Auf-trag

SumErgDaten =PDU-Größe – 14 – Nvar * 4

SumErgDaten = Maximale Län-ge der Ergeb-

nisdaten in Abhängigkeit von derPDU-Größe und der Anzahl derVariablen

AchtungVariablen mit ungerader Daten-länge belegen im Auftrag dienächsthöhere geradzahlige Län-ge.

BeispielPDU-Größe = 112Nvar = 8,3 wird zu 8

SumErgDaten =(112 – 14 – 8 * 4) = 66d. h. in einem Auftrag könnenz. B. Merkerbyte (MB) 1 bis 33gelesen werden, denn 1 Merker-byte belegt 2 Byte (33 * 2 = 66).

Fortsetzung der Tabelle auf der nächsten Seite


208

Fortsetzung der Tabelle von der letzten Seite

Dienst Formel Anmerkung

s7_multiple_write_req Nvar = (PDU-Größe – 12 ) / 18


SumErgDaten =(PDU-Größe – 12 – Nvar * 16)

SumErgDaten = Maximale Län-ge der Nutz-

daten in Abhängigkeit von derPDU-Größe und der Anzahl vonVariablen


BeispielPDU-Größe = 480Nvar = 26

SumErgDaten =(480 – 12 – 26 * 16 ) = 52d. h. in einem Auftrag könnenz. B. Merkerbyte (MB) 1 bis 26geschrieben werden, denn1 Merkerbyte belegt 2 Byte(26 * 2 = 52).

s7_cycl_read_init_req Nvar = ( PDU-Größe – 26 ) / 12


SumErgDaten =PDU-Größe – 28 – Nvar * 4

SumErgDaten = Maximale Län-ge der Nutz-

daten in Abhängigkeit von derPDU-Größe und der Anzahl vonVariablen


BeispielPDU-Größe = 480Nvar = 37,83 d. h. 37

SumErgDaten =(480 – 28 – 37 * 4 ) = 304d. h. in einem Auftrag könnenz. B. Merkerwort (MW) 1 bis 152geschrieben werden, denn1 Merkerwort belegt 2 Byte(152 * 2 = 304).


209

7.4 Darstellung von S7-Variablen

Die SAPI-S7-Programmierschnittstelle setzt voraus, daß die Variablenbyte-aligned im Hauptspeicher abgelegt werden. Das bedeutet, daßkeine Füllbytes (Padding-Bytes), z. B. zwischen den einzelnen Kompo-nenten einer Struktur, eingefügt sein dürfen. Dies wird durch entspre-chende Compiler-Optionen bzw. durch Pragmas erreicht.

Die SAPI-S7-Library liefert die gelesenen bzw. erwartet die zu schrei-benden Variablenwerte in Netzdarstellung. Für zukünftige Versionender Library ist eine Wandlung zwischen Host- und Netzdarstellungvorgesehen. Deshalb sind alle betroffenen Funktionen um einen Über-gabeparameter 'od_ptr' erweitert, der in der aktuellen Version derLibrary mit dem NULL-Pointer belegt werden muß.

Dieser Übergabeparameter 'od_ptr' wird in einer späteren Ausgabe derLibrary die Darstellung der Variablen steuern. Sie ist abhängig davon,

➢ ob eine Wandlung von Host- in Netzdarstellung oder umgekehrterfolgen soll (momentan noch nicht Bestandteil derSAPI-S7-Library), oder ob auf dem Host die Netzdarstellung ge-wünscht wird,

➢ welche Host-CPU (z. B. Intel) vorhanden ist.

Byte-Alignment

Netzdarstellungder Variablenwerte


210

7.5 Darstellung der Standard-Datentypen

7.5.1 Darstellung des Datentyps 'Boolean''

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 0 0 0 0 0 0 0 x

Für 'FALSE' hat 'x' den Wert '0', für 'TRUE' den Wert '1'.

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 x8 x7 x6 x5 x4 x3 x2 x1

Ist mindestens 1 Bit der Bits 'x8' bis 'x1' gesetzt, so wird der Wert'TRUE' angenommen. Für 'FALSE' müssen alle Bits '0' sein.

Netzdarstellungund Wertebereich

Host-Darstellungund Wertebereich(Intel-CPU)


211

7.5.2 Darstellung des Datentyps 'Integer'

Beim Datentyp 'Integer' muß nach der Länge des Datentyps unter-schieden werden.

Datentyp Wertebereich Länge

8-Bit-Integer -128 ... 127 1 Octet

16-Bit-Integer - 32768 ... 32767 2 Octets

32-Bit-Integer -231 ... 231-1 4 Octets

Netzdarstellung (2er-Komplementdarstellung) für 8-Bit-Integer ('VZ'stellt das Vorzeichenbit dar und hat für negative Zahlen den Wert '1',sonst den Wert '0'):

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 VZ 26 25 24 23 22 21 20


Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 VZ 214 213 212 211 210 29 28

2 27 26 25 24 23 22 21 20

Wertebereich

Netzdarstellung


212


Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 VZ 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-Darstellung (2er-Komplementdarstellung) für 8-Bit-Integer ('VZ'stellt das Vorzeichenbit dar und hat für negative Zahlen den Wert '1',sonst den Wert '0'):

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 VZ 26 25 24 23 22 21 20


Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 27 26 25 24 23 22 21 20

2 VZ 214 213 212 211 210 29 28

Host-Darstellung(Intel-CPU)


213


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 VZ 230 229 228 227 226 225 224


214

7.5.3 Darstellung des Datentyps 'Unsigned'

Beim Datentyp 'Unsigned' muß nach der Länge des Datentyps unter-schieden werden.

Datentyp Wertebereich Länge

8-Bit-Unsigned 0 ... 255 1 Octet

16-Bit- Unsigned 0 ... 65535 2 Octets

32-Bit- Unsigned 0 ... 232-1 4 Octets

Netzdarstellung für 8-Bit-Unsigned:

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 27 26 25 24 23 22 21 20


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


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

Wertebereich

Netzdarstellung


215

Host-Darstellung für 8-Bit-Unsigned:

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 27 26 25 24 23 22 21 20


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


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



216

7.5.4 Darstellung des Datentyps 'Floating Point'

Wertebereich Länge

-3.37*1038 ... -8.43*10-37 4 Octets

0

8.43*10-37 ... 3.37*1038

Netzdarstellung ('VZ' ist das Vorzeichen der Mantisse, die schattiertenFelder gehören zum Exponenten, die restlichen zur Mantisse):

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 VZ 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-

10 2-

11 2-

12 2-

13 2-

14 2-

15

4 2-

16 2-

17 2-

18 2-

19 2-

20 2-

21 2-

22 2-

23

Host-Darstellung ('VZ' ist das Vorzeichen der Mantisse, die schattiertenFelder gehören zum Exponenten, die restlichen zur Mantisse):

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 2-

16 2-

17 2-

18 2-

19 2-

20 2-

21 2-

22 2-

23

2 2-8 2-9 2-

10 2-

11 2-

12 2-

13 2-

14 2-

15

3 20 2-1 2-2 2-3 2-4 2-5 2-6 2-7

4 VZ 27 26 25 24 23 22 21

Wertebereich

Netzdarstellung



217

Der Variablenwert wird wie folgt berechnet:

Exponent Variablenwert

0 (-1)VZ*((0.Mantisse)*2-126)

ungleich 0 (-1)VZ*((1.Mantisse)*2(Exponent-127))

Beispiel für die Darstellung des Variablenwertes '0,5' im Host als'C'-Datentyp '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

Werteberechnung


218

7.5.5 Darstellung des Datentyps 'Visible-String'

Als Zeichen für Variablen vom Typ 'Visible-String' sind alle Buchstaben(Klein- und Großschreibung), Ziffern, der Underscore ('_') und dasDollarzeichen ('$') zugelassen.

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 erstes Zeichen

2 zweites Zeichen

..

n n-tes Zeichen

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 erstes Zeichen

2 zweites Zeichen

..

n n-tes Zeichen

n+1 NULL-Terminierung

Eine Variable vom Typ 'Visible-String' entspricht im Host einem Stringder Programmiersprache 'C', d. h. er ist NULL-terminiert.

Wertebereich

Netzdarstellung



219

7.5.6 Darstellung des Datentyps 'Octet-String'

Eine Variable vom Typ 'Octet-String' wird auf dem Netz wie ein 'Vi-sible-String' dargestellt. Allerdings sind hier sämtliche Bytewerte zu-lässig.

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 erstes Zeichen

2 zweites Zeichen

..

n n-tes Zeichen

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 Längeninformation

2 erstes Zeichen

..

n (n-1)tes Zeichen

n+1 n-tes Zeichen

Die Host-Darstellung unterscheidet sich von der Netzdarstellung inso-fern, daß im ersten Byte die Längeninformation abgelegt ist.

Netzdarstellung



220

7.5.7 Darstellung des Datentyps 'Bit-String'

Eine Variable vom Typ 'Bit-String' wird auf dem Netz wie folgt darge-stellt.

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

..

Bit MSB LSB

Octet 8 7 6 5 4 3 2 1

1 Längeninformation

2 7 6 5 4 3 2 1 0

3 15 14 13 12 11 10 9 8

..

Die Host-Darstellung unterscheidet sich von der Netzdarstellung inso-fern, daß im ersten Byte die Längeninformation abgelegt ist.

Netzdarstellung



221

Glossar

ASCII American Standard Code of Information Interchange - Kodierungs-vorschrift für ein Byte große Zeichen.

CP Communication Processor - Kommunikationsbaugruppe für den Einbauin Rechner oder Automatisierungsgeräte.

CREF Connection Reference - Verbindungskennung.

DB Datenbaustein

default Standardeinstellung des Auslieferungszustandes von Siemens.

IEC International Electronical Commission - Internationales Normungs-komitee.

Kommunikations-system

Unterlagerte Software und Hardware zur Anbindung an das Kommu-nikationsnetz.

Multi-CP-Betrieb Mehrere CPs können gleichzeitig in einem PG/PC betrieben werden.

Multi-User-Betrieb Mehrere Applikationen auf einem PG/PC.

PBK Programmierte Baustein Kommunikation; zu den S7 PBK-Dienstengehören u. a. BSEND, BRCV, SEND, RCV, PUT, GET

PCS 7 Process Control System - Prozeßleitsystem auf Basis vonSIMATIC S7.

PDU Protocol Data Unit (Protokolldateneinheit) - Nachricht einerISO/OSI-Schicht.

PG Programmiergerät

PMC zu den PMC-Diensten gehören: SCAN, ALARM, NOTIFY, ALARM_S


222

PROFIBUS Process Field Bus - Netz für den Zell- und Feldbereich des mittlerenLeistungsbereichs mit dem Einsatzschwerpunkt in industrieller Umge-bung nach EN 50 170, Volume 2. PROFIBUS.

SAPI Simple Application Programmers Interface - einfache Programmier-schnittstelle für Kommunikationsprotokolle auf dem PG/PC.

SIMATIC NET Produktlinie für industrielle Kommunikation von Siemens.

SINEC L2 Alte Bezeichnung für -> PROFIBUS.

S7 SIMATIC S7 ist ein Automatisierungssystem der Siemens AG.

VFD Virtual Field Device - Abbildung eines realen Automatisierungsgerätesmit der Zielsetzung, eine einheitliche Sicht auf ein beliebiges Gerät zuerhalten.


223

Index

s7_abort() .........................................31, 70s7_await_initiate_req() ......................31, 65s7_brcv_init() ..................................35, 126s7_brcv_stop() ................................35, 130s7_bsend_req() ...............................35, 123s7_cycl_read() ................................34, 114s7_cycl_read_delete_req() ..............33, 112s7_cycl_read_init_req() ...................33, 101s7_cycl_read_start_req().................33, 105s7_cycl_read_stop_req() .................33, 110s7_diag_init() ..................................38, 161s7_diag_stop() ................................38, 164s7_discard_msg()..................................184s7_get_abort_ind() ............................31, 71s7_get_alarm_ind() .........................36, 146s7_get_await_initiate_cnf()................31, 66s7_get_brcv_ind() ...........................35, 128s7_get_bsend_cnf().........................35, 125s7_get_conn() ...................................29, 50s7_get_cref().....................................29, 49s7_get_cycl_read_abort_ind() .........33, 109s7_get_cycl_read_delete_cnf()........33, 113s7_get_cycl_read_ind() ...................33, 107s7_get_cycl_read_init_cnf().............33, 104s7_get_cycl_read_start_cnf() ..........33, 106s7_get_cycl_read_stop_cnf()...........33, 111s7_get_device() ................................29, 43s7_get_diag_ind() ...........................38, 162s7_get_initiate_cnf()..........................30, 64s7_get_initiate_ind()..........................31, 67s7_get_msg_abort_cnf()..................36, 138

s7_get_msg_initiate_cnf() ...............36, 136s7_get_multiple_read_cnf()...............32, 93s7_get_multiple_write_cnf() ..............32, 99s7_get_read_cnf() .............................32, 81s7_get_scan_ind()........................... 36, 139s7_get_vfd()......................................29, 45s7_get_vfd_state_cnf()....................37, 157s7_get_write_cnf().............................32, 89s7_init().............................................29, 47s7_initiate_req() ................................30, 63s7_initiate_rsp() ................................31, 68s7_last_detailed_err_msg() ...................183s7_last_detailed_err_no()......................179s7_last_iec_err_msg()...........................178s7_last_iec_err_no()..............................176s7_mini_db_get() ..................................174s7_mini_db_set() ..................................168s7_msg_abort_req() ........................ 36, 137s7_msg_initiate_req()...................... 36, 135s7_multiple_read_req() .....................32, 90s7_multiple_write_req().....................32, 96s7_read_req() ...................................32, 79s7_receive()......................................30, 55s7_set_window_handle_msg()...............202s7_shut()...........................................29, 52s7_trace()..............................................166s7_vfd_state_req() .......................... 37, 156s7_write_long_req().................................86s7_write_req() ...................................32, 83s7_write_trace_buffer() .........................167


224

❑

SIMATIC NET - support.industry.siemens.com · SIMATIC NET S7-Programmierschnittstelle Band 1 von 1...

Documents

Transcript of SIMATIC NET - support.industry.siemens.com · SIMATIC NET S7-Programmierschnittstelle Band 1 von 1...