Sie sind auf Seite 1von 44

EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

EDIABAS
Elektronik Diagnose Basissystem

API-SCHNITTSTELLENBESCHREIBUNG

VERSION 6d

Copyright BMW AG, created by Softing AG

API.DOC
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

INHALT

INHALT ............................................................................................................2

1. Änderungshistorie .................................................................................5

2. Einführung ..............................................................................................6
2.1. Über diese Dokumentation......................................................6
2.2. Konventionen ..........................................................................6
2.3. Besonderheiten, Begriffe, Akronyme.......................................7

3. Allgemeines ............................................................................................8

4. Bedienung der API-Schnittstelle...........................................................9


4.1. Initialisierung und Abbruch von EDIABAS...............................9
4.2. API-Aufträge............................................................................11
4.2.1. Aufträge mit unbekannter Variante .....................................12
4.2.2. Aufträge mit vorgegebener Variante ...................................12
4.2.3. Standardaufträge ................................................................13
4.2.3.1. Standardauftrag INITIALISIERUNG .........................13
4.2.3.2. Standardauftrag IDENTIFIKATION...........................14
4.2.3.3. Standardauftrag ENDE.............................................14
4.2.4. Virtuelle Aufträge ................................................................14
4.2.4.1. Virtueller Auftrag _JOBS ..........................................15
4.2.4.2. Virtueller Auftrag _JOBCOMMENTS ........................15
4.2.4.3. Virtueller Auftrag _VERSIONINFO ...........................15
4.2.4.4. Virtueller Auftrag _ARGUMENTS .............................16
4.2.4.5. Virtueller Auftrag _RESULTS ...................................16
4.2.4.6. Virtueller Auftrag _TABLES ......................................17
4.2.4.7. Virtueller Auftrag _TABLE ........................................17
4.3. API-Ergebnisse .......................................................................17
4.3.1. Datenverwaltung .................................................................17
4.3.2. Ergebnisermittlung ..............................................................19
4.3.2.1. Ermittlung des Namens der Steuergeräte-Variante ..21

2
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

4.3.2.2. Ermittlung der Anzahl von Ergebnissätzen...............21


4.3.2.3. Ermittlung der Anzahl von Ergebnissen eines
Ergebnissatzes 22
4.3.2.4. Ermittlung eines Ergebnisnamens mittels Ergebnisindex
22
4.3.2.5. Ermittlung des Ergebnisformats eines Ergebnisses .22
4.3.3. Ergebnistypen und Formate................................................23
4.3.3.1. Ergebnistypen...........................................................23
4.3.3.2. Ergebnisformate .......................................................23
4.3.4. Applikationseigene Ergebnisfelder ......................................25
4.3.4.1. Anlegen eines applikationseigenen Ergebnisfeldes..25
4.3.4.2. Bezug zum applikationseigenen Ergebnisfeld herstellen
25
4.3.4.3. Freigabe eines applikationseigenen Ergebnisfeldes.26
4.4. Device-Wechsel ......................................................................26
4.5. API-Ablaufsteuerung ...............................................................27
4.5.1. Auftragssteuerung..............................................................28
4.5.1.1. Automatische Auftragsabarbeitung...........................28
4.5.1.2. Zyklische Abfrage (Polling) .......................................28
4.5.1.3. Call-Back-Mechanismus ...........................................29
4.5.1.4. Auftragsabbruch .......................................................30
4.5.2. Auftragsbearbeitungsstand ................................................30
4.5.3. Parallelverarbeitung (nur WIN32/CE und SCO-UNIX) .......30
4.5.4. Applikations-Locking (nicht WIN32/CE und SCO-UNIX) ....31
4.5.4.1. Binden eines Anwendungsprogramms an das EDIABAS
31
4.5.4.2. Aufheben der Bindung an das EDIABAS..................32
4.5.4.3. Zugriff mehrerer Anwendungsprogramme auf das EDIABAS
(nicht WIN32/CE und SCO-UNIX) ...........................................32
4.6. Konfiguration ...........................................................................32
4.6.1. Ermittlung der Konfiguration................................................33
4.6.2. Änderung der Konfiguration ................................................33

3
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

4.7. Fehlerbehandlung ...................................................................34


4.7.1. Ermittlung der Fehlerursache..............................................34
4.7.2. Verwendung eines Error-Handlers ......................................34
4.7.3. Vorgehensweise zur Fehleranalyse bei Initialisierung und
Ergebnisermittlung...........................................................................34
4.7.4. Löschen eines Fehlers ........................................................35

5. Beispiel Applikation...............................................................................36

A. LITERATURVERZEICHNIS.....................................................................42

B. INDEX ......................................................................................................43

4
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

1. Änderungshistorie

Version 3.0 Ersterstellung

Version 4.1 Überarbeitung für EDIABAS V4.1.0

Version 5 Aufnahme der neuen API-Funktionen apiJobExt und apiJobInfo

Version 5a Beschreibung des neuen virtuellen Jobs _JOBCOMMENTS

Version 6 Neue API-Funktion apiInitExt, zusätzliche Ergebnisse des virtuellen


Jobs _VERSIONINFO und Parallelverarbeitung unter Win32

Version 6a Beschreibung des neuen virtuellen Jobs _TABLES und _TABLE

Version 6b Überarbeitung für EDIABAS V6.4.0

Version 6b Überarbeitung für EDIABAS V6.4.3

Version 6c Ergänzungen für Windows CE

5
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

2. Einführung

2.1. Über diese Dokumentation

Diese Dokumentation beschreibt die Verwendung der Konstanten und Funktionen,


die in der EDIABAS-API Schnittstelle zur Verfügung stehen. Eine detailierte
Beschreibung dieser Funktionen befindet sich in [3]. Die Einbindung in eine
Entwicklungsumgebung wird in [4] beschrieben. Allgemeines über EDIABAS und
über Steuergerätebeschreibungsdateien wird in [2] beschrieben.

2.2. Konventionen

Diese Dokumentation verwendet die folgenden typographischen Konventionen:

Beispiel Beschreibung
SAMPLE.C Großschrift kennzeichnet Dateinamen und
Betriebssystemkommandos.
apiJob, Fettschrift kennzeichnet Schlüsselwörter und
APIREADY Operatoren der Sprache C/C++ sowie Funktionen
und Definitionen von API.
In Beschreibungen der Syntax müssen diese Wörter
wie angegeben geschrieben werden.
ausdruck Kursivschrift kennzeichnet Platzhalter für vom
Programmierer einzutragende Werte, wie z.B.
Dateinamen.
[option] Wörter in eckigen Klammern bedeuten optionale
Angaben.
{ result | Geschweifte Klammern und senkrechte Striche
argument } kennzeichnen Eingaben, von denen jeweils eine
gewählt werden muß, außer wenn sie in eckigen
Klammern steht.
[constant...] job... Drei Punkte, die direkt einem Ausdruck folgen,
kennzeichnen, daß mehrere Ausdrücke der selben
Form folgen können.
hallo="Test"; Diese Schriftart kennzeichnet Beispiele,
Benutzereingaben, Programmausgaben und
Fehlermeldungen.

6
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

while() { Eine Spalte oder eine Zeile aus drei Punkten


. kennzeichnet, daß ein Teil eines Beispiels
.} absichtlich weggelassen wurde.
[1] Verweis auf ein Dokument aus dem
Literaturverzeichnis.

2.3. Besonderheiten, Begriffe, Akronyme

Eine Erklärung der in dieser und allen anderen EDIABAS-Dokumentationen


verwendeten Abkürzungen finden Sie in der Dokumentation "EDIABAS
Benuterhandbuch" im Kapitel "GLOSSAR". Der Begriff API wird im Kapitel
"Allgemeines" näher erläutert.

7
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

3. Allgemeines

Das Applikations-Interface API ist die standardisierte Programmschnittstelle des


EDIABAS, über die ein Anwendungsprogramm Aufträge zur Bedienung von
Steuergerätefunktionen an das EDIABAS absetzen muß und über die das
Anwendungsprogramm vom EDIABAS Ergebnisse der Auftragsbearbeitung
zurückerhält.

Eine Beschreibung der Gesamtsystems befindet sich in [2].

8
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

4. Bedienung der API-Schnittstelle

4.1. Initialisierung und Abbruch von EDIABAS

Bevor vom Anwendungsprogramm API-Funktionen aufgerufen werden können, muß


zuerst eine allgemeine Initialisierung des EDIABAS erfolgen. Dies geschieht über
eine der folgenden Initialisierungsfunktionen:

apiInit ( )

apiInitExt ( Device, Device-Anschluß, Device-Applikation, reserviert )

Bei Initialisierung von API mit apiInit() wird vom EDIABAS eine systemabhängige
Voreinstellung für Diagnose-Interface (Device), Device-Anschluß und Device-
Applikation vorgenommen.

Mit Aufruf von apiInitExt() kann bereits zum Zeitpunkt der Initialisierung von API das
zu verwendende Diagnose-Interface (Device) sowie der Device-Anschluß und die
Device-Applikation festgelegt werden. Die Voreinstellung für Diagnose-Interface
(Device), Device-Anschluß und Device-Applikation kann durch die entsprechende
Angabe eines Leer-Strings bestimmt werden. Die mit apiInitExt() vorgenommenen
Einstellungen sind nur bis zum Abbruch von API (apiEnd()) wirksam.

Solange ein Anwendungsprogramm auf EDIABAS zugreift spricht man von einer API-
Sitzung.

Mit Aufruf von apiInit() oder apiInitExt() erfolgt unter anderem das sogenannte
Applikations-Locking, das im entsprechenden Kapitel beschrieben wird.

Als Rückgabewert liefern die Funktionen apiInit() und apiInitExt() eine Information
hinsichtlich des Erfolgs der Initialisierung des EDIABAS:

APITRUE Initialisierung korrekt (API-Zugriffe möglich)


APIFALSE Initialisierung fehlerhaft (keine API-Zugriffe möglich)

Vorgehensweisen zur Fehlerbehandlung sind im Kapitel "Fehlerbehandlung"


beschrieben.

Eine API-Sitzung kann mit der Funktion apiEnd() beendet werden, wobei die
Freigabe von Arbeitsspeicher und Betriebsmittel erfolgt.

Nach Abbruch einer API-Sitzung ist vor dem erneuten Zugriff auf API-Funktionen
dessen Initialisierung mit apiInit() oder apiInitExt() durchzuführen.

9
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Ein erneuter Aufruf von apiInit() oder apiInitExt() ohne vorhergehendem apiEnd()
bewirkt (sofern eine Sitzung noch nicht beendet ist) innerhalb des
Anwendungsprogramms die selbständige Durchführung von apiEnd().

10
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

4.2. API-Aufträge

Nach erfolgreicher Initialisierung ist der Zugriff auf Steuergeräte mittels Absetzen von
API-Aufträgen an das EDIABAS möglich, diese weisen dabei immer folgende
Struktur auf:

apiJob ( SG-Gruppe/Variante, Auftrag, Parameter, Ergebnisse )


apiJobData (SG-Gruppe/Variante, Auftrag, Parameterdaten, Parameterlänge,
Ergebnisse)
apiJobExt (SG-Gruppe/Variante, Auftrag, Parameterdaten für Standard Jobs,
Parameterlänge für Standard Jobs, Parameterdaten, Parameterlänge,
Ergebnisse, reserviert)

Das Argument SG-Gruppe/Variante stellt den Bezug zum anzusprechenden


Steuergerät, das heißt zur zugehörigen Steuergerätebeschreibungsdatei (SGBD),
her. Hier wird immer der Name der SGBD ohne ihre Extension angegeben, zum
Beispiel:

DMETEST.PRG -> DMETEST


ALLEDME.GRP -> ALLEDME

Das Argument Auftrag entspricht dem in der SGBD definierten Jobnamen. Es


erfolgt keine Unterscheidung zwischen Groß-/Kleinschreibung.

Die Argumente Parameter bzw. Parameterdaten/-Länge sind Auftragsparameter. An


die Funktion apiJob kann nur ein Textstring im "C"-Format als Argument übergeben
werden (z.B. "Par1;Par2;Par3" oder ""). Die einzelnen Parameter werden im
Argument mit Semikolon getrennt und zwischen Groß-/Kleinschreibung wird
unterschieden. An apiJobData und apiJobExt können sowohl ein Textstring als
auch binäre Daten übergeben werden. An die Funktion apiJobExt können zusätzlich
noch Parameter für Standardaufträge übergeben werden. Diese Parameter werden
an alle Standardaufträge übergeben, die nach dem Aufruf von apiJobExt
automatisch vor bzw. nach dem angegebenen Auftrag ausgeführt werden. Wird in
apiJobData oder apiJobExt ein Textstring als Parameter übergeben muß als Länge
die Länge des Textstrings ohne den abschließenden '\0'-Charakter übergeben
werden, sonst muß die Anzahl der Datenbytes übergeben werden. Ein typischer
Anwendungsfall für binäre Parameterdaten ist der TRANSPARENT-MODE des
EDIABAS, weitere Informationen sind dem Dokument [5] zu entnehmen.

11
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Das Argument Ergebnisse legt fest, welche Ergebnisse von einem Auftrag erzeugt
werden sollen. Die einzelnen Ergebnisse werden im Argument mit Semikolon
getrennt und es erfolgt keine Unterscheidung zwischen Groß-/Kleinschreibung.
Sollen alle Ergebnisse bearbeitet werden, so ist ein Leer-String für das Argument
Ergebnisse anzugeben. Das selektive Erzeugen von bestimmten Ergebnisse muß bei
der Erstellung der SGBD vom Ersteller implementiert worden sein, sonst werden trotz
Angabe spezieller Ergebisse im Aufruf alle Ergebnisse erzeugt.

4.2.1.Aufträge mit unbekannter Variante


Die Kommunikation mit einer unbekannten Steuergeräte-Variante erfolgt durch
Angabe des Gruppennamens als 1. Argument des Auftrags:

apiJobxxx ( SG-Gruppe, ... )

Zur Ermittlung der verbauten Variante wird die Steuergeräte-


Gruppenbeschreibungsdatei geladen.

Nach erfolgreicher Identifikation wird automatisch die entsprechende Steuergeräte-


Beschreibungsdatei geladen und der eigentlich gewünschte Auftrag ausgeführt.

Der Name der Steuergeräte-Gruppe wird bei der Variantenbestimmung als Referenz
zur Steuergeräte-Gruppenbeschreibungsdatei benutzt, der Variantenname der
Steuergeräte dient als Zuordnung für entsprechende Steuergeräte-
Beschreibungsdateien.

4.2.2.Aufträge mit vorgegebener Variante


Die Kommunikation mit einer vorgegebenen Steuergeräte-Variante erfolgt durch
Angabe des Variantennamens als 1. Argument des Auftrags:

apiJobxxx ( SG-Variante, ...)

Der Name der Steuergeräte-Variante wird abschließend in das Standardergebnis


VARIANTE kopiert.

12
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

4.2.3.Standardaufträge
Standardaufträge sind vom EDIABAS vordefinierte Aufträge, deren Verwendung
exakt festgelegt ist und in Steuergeräte-Beschreibungsdateien vorzusehen sind.

Standardaufträge werden automatisch vom EDIABAS aufgerufen.

Mit der Funktion apiJobExt können Parameter an Standardaufträge übergeben


werden.

Das Ergebnis von Standardaufträgen ist in festgelegten Standardergebnissen


abgelegt, welche vom EDIABAS automatisch abgefragt werden.

4.2.3.1. Standardauftrag INITIALISIERUNG


Der Standardauftrag INITIALISIERUNG einer Beschreibungsdatei wird automatisch
aufgerufen:

„ nach vorhergehender Initialisierung von API (apiInit() oder apiInitExt())


„ nach vorhergehendem Diagnose-Interface-Wechsel via apiSetConfig()
„ nach vorhergehendem Device-Wechsel (apiSwitchDevice())
„ nach vorhergehendem Ein- bzw Ausschalten des Simulationsmodes via
apiSetConfig()
„ nach vorhergehendem Auftreten eines Fehlers
„ bei einem Auftrag mit vorgegebener Variante (nur nach Wechsel der
Steuergeräte-Variante)
„ bei einem Auftrag mit unbekannter Variante
„ nach vorangegangenem Aufruf der BEST/2 Funktion doNewInit in einer SGBD

Der Standardauftrag INITIALISIERUNG muß in jeder Gruppen- und Varianten-


Beschreibungsdatei vorhanden sein.

Die erfolgreiche Initialisierung ist mit dem Standardergebnis DONE (Ergebnistyp


APIINTEGER oder APIWORD) in einem Ergebnissatz anzuzeigen:

„ Ergebnis DONE <> 0 Erfolgreiche Initialisierung


„ Ergebnis DONE = 0 Fehlerhafte Initialisierung
„ Ergebnis DONE nicht vorhanden Fehlerhafte Initialisierung

Der Standardauftrag INITIALISIERUNG darf außer DONE keine weiteren Ergebnisse


zurückliefern.

13
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

4.2.3.2. Standardauftrag IDENTIFIKATION


Der Standardauftrag IDENTIFIKATION wird zur Ermittlung der verbauten
Steuergeräte-Variante aufgerufen:

„ bei einem Auftrag mit unbekannter Variante

Der Standardauftrag IDENTIFIKATION muß in jeder Gruppen-Beschreibungsdatei


vorliegen.

Eine identifizierte Steuergeräte-Variante ist mit dem Standardergebnis VARIANTE


(String vom Ergebnistyp APITEXT) in einem Ergebnissatz anzuzeigen:

„ Ergebnis VARIANTE = String (mind. 1 Zeichen) Erfolgreiche Identifikation, das


Ergebnis stellt den Namen der
Steuergeräte-Variante dar
„ Ergebnis VARIANTE = Leer-String Fehlerhafte Identifikation
„ Ergebnis VARIANTE nicht vorhanden Fehlerhafte Identifikation

Der Standardauftrag IDENTIFIKATION darf außer VARIANTE keine weiteren


Ergebnisse zurückliefern.

4.2.3.3. Standardauftrag ENDE


Der optionale Standardauftrag ENDE wird beim Wechsel der Beschreibungsdatei
aufgerufen:

„ Vor dem Wechsel der Beschreibungsdatei


„ Vor einem Auftrag mit unbekannter Variante

Der Standardauftrag ENDE kann in jeder Gruppen- und Varianten-


Beschreibungsdatei vorliegen.

Der Standardauftrag ENDE darf keine Ergebnisse zurückliefern.

4.2.4.Virtuelle Aufträge
Virtuelle Aufträge sind vom EDIABAS vordefinierte Aufträge, mit deren Aufruf man
Informationen hinsichtlich einer Steuergeräte-Beschreibungsdatei erhält.

Virtuelle Aufträge können durch den EDIABAS-Anwender nicht geändert werden.

14
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Virtuelle Aufträge liegen im Gegensatz zu Standardaufträgen nicht in den


Steuergeräte-Beschreibungsdateien vor, sondern werden durch das EDIABAS
simuliert. Durch selbstdefinierte Aufträge innerhalb der Steuergeräte-
Beschreibungsdateien können jedoch virtuelle Aufträge überschrieben werden.

Die Ergebnisse virtueller Aufträge sind in Standardergebnissen mit festem Namen


abgelegt, die auf die gleiche Art und Weise wie die Ergebnisse normaler Aufträge
abzufragen sind (siehe Kap. Ergebnisermittlung).

4.2.4.1. Virtueller Auftrag _JOBS


Der virtuelle Auftrag _JOBS ermittelt die Namen aller in der Steuergeräte-
Beschreibungsdatei vorliegenden Aufträge (nicht jedoch die Namen der virtuellen
Aufträge).

Jeder Auftragsname wird als Ergebnis JOBNAME in einem eigenen Ergebnissatz


abgelegt, die Anzahl der Ergebnissätze ergibt somit die Anzahl der in der
Steuergeräte-Beschreibungsdatei vorhandenen Aufträge.

4.2.4.2. Virtueller Auftrag _JOBCOMMENTS


Der virtuelle Auftrag _JOBCOMMENTS ermittelt den Kommentar zu einem Job. Der
Name des zu untersuchenden Jobs ist beim Aufruf des virtuellen Jobs als Job-
Parameter anzugeben. Die Ergebnisermittlung ist nur bei BEST2 SGBDs möglich,
welche nicht mit dem Tool STRIP nachbearbeitet wurden.

Folgende Informationen werden für jedes Ergebnis im ersten Ergebnissatz abgelegt:

JOBCOMMENTx Kommentarzeilen (x ist eine fortlaufende Nummer


in dezimaler Schreibweise beginnend mit 0)

4.2.4.3. Virtueller Auftrag _VERSIONINFO


Der virtuelle Auftrag _VERSIONINFO ermittelt allgemeine Informationen über die
Steuergeräte-Beschreibungsdatei und legt diese im 1. Ergebnissatz ab:

REVISION Versionskennung
AUTHOR Autor der letzten Änderung
FROM Datum der letzten Änderung

Folgende zusätzliche Informationen werden bei BEST2 SGBDs ermittelt, welche


nicht mit dem Tool STRIP nachbearbeitet wurden:

ECU SGBD-Beschreibung
ORIGIN Autor der Ersterstellung

15
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

LANGUAGE Sprachkennzeichnung
USESx Basisdateien (x ist eine fortlaufende Nummer
in dezimaler Schreibweise beginnend mit 0)
ECUCOMMENTx SGBD-Kommentarzeilen (x ist eine fortlaufende Nummer
in dezimaler Schreibweise beginnend mit 0)

4.2.4.4. Virtueller Auftrag _ARGUMENTS


Der virtuelle Auftrag _ARGUMENTS ermittelt alle definierten Argumente eines Jobs,
der Name des zu untersuchenden Jobs ist beim Aufruf des virtuellen Jobs als Job-
Parameter anzugeben. Die Argumentermittlung ist nur bei BEST2 SGBDs möglich,
welche nicht mit dem Tool STRIP nachbearbeitet wurden.

Der virtuelle Auftrag _ARGUMENTS kann nicht die tatsächlich zur Laufzeit
übergebenen Argumente ermitteln, sondern nur die im Job-Header der SGBD
definierten Argumente.

Folgende Informationen werden für jedes Argument in einem eigenen Ergebnissatz


abgelegt:

ARG Argumentname
ARGTYPE BEST-Datentyp des Arguments
ARGCOMMENTx Kommentarzeilen (x ist eine fortlaufende Nummer
in dezimaler Schreibweise beginnend mit 0)

4.2.4.5. Virtueller Auftrag _RESULTS


Der virtuelle Auftrag _RESULTS ermittelt Ergebnisse eines Jobs, der Name des zu
untersuchenden Jobs ist beim Aufruf des virtuellen Jobs als Job-Parameter
anzugeben. Die Ergebnisermittlung ist nur bei BEST2 SGBDs möglich, welche nicht
mit dem Tool STRIP nachbearbeitet wurden.

Der virtuelle Auftrag _RESULTS kann nicht die tatsächlich zur Laufzeit angelegten
Ergebnisse ermitteln, sondern nur die im Job-Header der SGBD definierten
Ergebnisse.

Folgende Informationen werden für jedes Ergebnis in einem eigenen Ergebnissatz


abgelegt:

RESULT Ergebnisname
RESULTTYPE BEST-Datentyp des Ergebnisses
RESULTCOMMENTx Kommentarzeilen (x ist eine fortlaufende Nummer
in dezimaler Schreibweise beginnend mit 0)

16
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

4.2.4.6. Virtueller Auftrag _TABLES


Der virtuelle Auftrag _TABLES gibt die Namen aller Tabellen der geladenen SGBD
zurück.

Hinweis:
Es werden nur lokale, in der SGBD definierte Tabellennamen zurückgegeben

Für jede Tabelle wird ein eigener Ergebnissatz mit dem Textergebnis ‚TABLE‘
gebildet:

TABLE Name der Tabelle

Das Systemergebnis SETS beinhaltet die Anzahl gefundener Tabellen (0 ... n).

4.2.4.7. Virtueller Auftrag _TABLE


Der virtuelle Auftrag _TABLE gibt den Inhalt einer Tabelle zurück. Der Name der
aufzulistenden Tabelle ist beim Aufruf des virtuellen Jobs als Jobparameter
anzugeben.

Hinweis:
Es kann nur eine lokale, in der SGBD definierte Tabelle zurückgegeben
werden

In jedem Ergebnissatz wird eine Zeile der Tabelle dargestellt. Ein Ergebnissatz
besteht aus den Textergebnissen ‚COLUMN0‘ bis ‚COLUMNn‘.
Es wird mit der ersten Zeile der Tabelle (welche die Index-Texte enthält) begonnen.

COLUMN0 Text der ersten Spalte


COLUMN1 Text der zweiten Spalte
... ...
COLUMNn Inhalt der n-ten Spalte

Das Systemergebnis SETS beinhaltet die gesamte Zeilenanzahl der Tabelle.

4.3. API-Ergebnisse

4.3.1.Datenverwaltung
Nach Absetzen eines Auftrags mit apiJob() lädt EDIABAS die entsprechende
Steuergeräte-Beschreibungsdatei und bearbeitet den übergebenen Auftrag. Während

17
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

der Abarbeitung des Auftrags fallen Ergebnisse des Auftrags an, die dem
Anwendungsprogramm zu übergeben sind.

Die Ergebnisse werden von EDIABAS in einer Datenstruktur abgelegt, diese


Datenstruktur wird als ERGEBNISFELD bezeichnet.

Ein Ergebnisfeld besteht aus einer Anzahl von ERGEBNISSÄTZEN, welche


ihrerseits wiederum eine Anzahl von ERGEBNISSEN beinhalten. Die Anzahl der
Ergebnissätze und der Ergebnisse ist abhängig vom Job in der SGBD.

System- System- ... System- Ergebnissatz 0


Ergebnis 1 Ergebnis 2 Ergebnis m0

Ergebnis 1 Ergebnis 2 ... Ergebnis m1 Ergebnissatz


1

Ergebnis 1 Ergebnis 2 ... Ergebnis m2 Ergebnissatz


2

...

Ergebnis 1 Ergebnis 2 ... Ergebnis mn Ergebnissatz


n

Der Ergebnissatz 0 eines Jobs wird automatisch von EDIABAS angelegt. Dieser als
SYSTEMERGEBNISSATZ bezeichnete Ergebnissatz enthält allgemeine
Informationen über den abgearbeiteten Job.

Die Ergebnisse des Systemergebnissatzes werden SYSTEMERGEBNISSE genannt.

Die Generierung der Systemergebnisse durch EDIABAS ist über die EDIABAS-
Konfiguration abschaltbar. Ausgenommen sind hiervon die Systemergebnisse
VARIANTE, OBJECT, JOBNAME und SETS, welche immer angelegt werden.

In der folgenden Übersicht sind alle Systemergebnisse sowie die möglichen


Ergebniswerte beschrieben:

Systemergebnis Bemerkung Wert

VARIANTE Name der Steuergeräte-Variante APITEXT[]

OBJECT Name der SGBD in der sich der Job APITEXT[]


befindet

18
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

JOBNAME Name des gerade augeführten Jobs APITEXT[]

SETS Anzahl der zurückgelieferten Ergebnis- APIWORD


sätze

UBATTCURRENT Zustand der Versorgungsspannung -1 = undefiniert


0 = aus
1 = ein

UBATTHISTORY Zustandshistorie der Versorgungs- -1 = undefiniert


spannung 0 = war aus
1 = war ein

IGNITIONCURRENT Zustand der Zündung -1 = undefiniert


0 = aus
1 = ein

IGNITIONHISTORY Zustandshistorie der Zündung -1 = undefiniert


0 = war aus
1 = war ein

JOBSTATUS Zusammenfassende Statusmeldung des APITEXT[]


Jobs (= Job-Rückgabewert)

4.3.2.Ergebnisermittlung
Die Ergebnisse eines Auftrags sind mit den Funktionen

apiResultxxx(Zieladresse,Ergebnis,Ergebnissatz )
apiResultText(Zieladresse,Ergebnis,Ergebnissatz,Format )
apiResultBinary(Zieladresse,Längenadresse,Ergebnis,Ergebnissatz )

zu ermitteln bzw. aus dem Ergebnisfeld auszulesen.

Im Ergebnisfeld wird ein Ergebnis in dem Format abgelegt, wie vom Job in der SGBD
definiert und zurückgeliefert.

Ein Anwendungsprogramm kann sich unabhängig davon ein Ergebnis in jedem


gewünschten Format abholen, vorausgesetzt eine Konvertierung ist möglich.

Für jeden vom Anwendungsprogramm gewünschten Ergebnistyp ist die


entsprechende Funktion auszuwählen:

19
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Ergebnisfunktion Ergebnisformat
apiResultChar() APICHAR
apiResultByte() APIBYTE
apiResultInt() APIINTEGER
apiResultWord() APIWORD
apiResultLong() APILONG
apiResultDWord() APIDWORD
apiResultReal() APIREAL
apiResultText() APITEXT
apiResultBinary() APIBINARY

Die Zieladresse stellt die Adresse der gewünschten Ergebnisvariable im


Anwendungsprogramm dar, in welche API das Ergebnis ablegen soll. Als Argument
Ergebnis ist der Namen des auszulesenden Ergebnisses anzugeben, wobei keine
Unterscheidung von Groß-/Kleinschreibung erfolgt.

Die Ergebnisfunktion apiResultBinary() stellt eine Ausnahme dar, da noch


zusätzlich die Längenadresse einer APIWORD-Ergebnisvariable benötigt wird, in
welche API die Anzahl der kopierten Bytes ablegt.

Einen weiteren Sonderfall stellt das Argument Format dar, welcher nur für das Ziel-
Ergebnisformat APITEXT zur Verfügung steht. Mit dem Argument Format ist die
Konvertierung vom ursprünglichen Ergebnisformat in das Ziel-Ergebnisformat
APITEXT mit definierbarer Konvertierspezifikation (siehe auch Kap. Ergebnistypen
und Formate) möglich. Stellt das Argument Format hingegen einen Leer-String dar,
so wird das Ergebnis im Ergebnisformat APITEXT mit der Default-Konvertierung
umgesetzt.

Aufträge können mehrere Ergebnissätze liefern (Bündelung der Mehrfachergebnisse,


z.B. Fehlerspeicher), weshalb immer der Ergebnissatz (Argument Ergebnissatz) zu
spezifizieren ist.

Der Rückgabewert der apiResultxxx()-Funktionen kennzeichnet das Vorhandensein


des gewünschten Ergebnisses:

APITRUE Ergebnis vorhanden


APIFALSE Ergebnis nicht vorhanden

Bei mehreren Ergebnissen mit gleichem Ergebnisnamen innerhalb eines


Ergebnissatzes kann nur das letzte Ergebnis ermittelt werden.

20
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Ein Ergebnis kann aus folgenden Gründen nicht vorhanden sein:

„ Es ist ein Fehler ist während der Auftragsabarbeitung aufgetreten, keine


Ergebnisse vorhanden
„ Das Ergebnis ist zwar vorhanden, eine Konvertierung in das gewünschte Format
ist jedoch nicht möglich
„ Das Ergebnis ist nicht vorhanden

Durch Aufruf der API-Funktion apiResultFormat() kann ermittelt werden, in welchem


Formate ein Ergebnis im Ergebnisfeld abgelegt ist:

Der Rückgabewert APIFALSE zeigt an, daß das Ergebnis NICHT vorhanden ist.

Vorgehensweisen zur Fehlerbehandlung sind im Kapitel "Fehlerbehandlung"


beschrieben.

4.3.2.1. Ermittlung des Namens der Steuergeräte-Variante


Ist bei Absetzen eines Auftrags die Steuergeräte-Identifikation erfolgreich, so wird der
Name der Steuergeräte-Beschreibung vom EDIABAS als Systemergebnis
VARIANTE im System-Ergebnissatz (Ergebnissatz 0) abgelegt.

Neben der Abfrage mit apiResultxxx() ist eine vereinfachte Abfrage mit

apiResultVar ( Zieladresse )

möglich. Die Zieladresse ist die Adresse einer Variable im Anwendungsprogramm, in


welche API den Inhalt des Systemergebnisses VARIANTE ablegt.

Die Beschreibung des Rückgabewerts von apiResultxxx() ist ebenso für


apiResultVar() gültig.

4.3.2.2. Ermittlung der Anzahl von Ergebnissätzen


Die Anzahl der Ergebnissätze wird von API automatisch im System-Ergebnissatz
(Ergebnissatz 0) als Systemergebnis SETS abgelegt.

Neben der Abfrage mit apiResultxxx() ist eine vereinfachte Abfrage mit der Funktion

apiResultSets ( Zieladresse )

möglich. Die Zieladresse ist die Adresse einer APIWORD-Variable im


Anwendungsprogramm, in welche API den Inhalt des Systemergebnisses SETS
ablegt.

21
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Die Beschreibung des Rückgabewerts von apiResultxxx() ist ebenso für


apiResultSets() gültig.

4.3.2.3. Ermittlung der Anzahl von Ergebnissen eines


Ergebnissatzes
Die Anzahl der Ergebnisse eines Ergebnissatzes kann mit der Funktion

apiResultNumber ( Zieladresse, Ergebnissatz )

ermittelt werden. Die Zieladresse ist die Adresse einer APIWORD-Variable im


Anwendungsprogramm, in welche API die Anzahl der Ergebnisse des
Ergebnissatzes Ergebnissatz ablegt.

Die Beschreibung des Rückgabewerts von apiResultxxx() ist ebenso für


apiResultNumber() gültig.

4.3.2.4. Ermittlung eines Ergebnisnamens mittels Ergebnisindex


Den Namen eines Ergebnisses kann mit der Funktion

apiResultName ( Zieladresse, Ergebnisindex, Ergebnissatz )

ermittelt werden. Die Zieladresse ist die Adresse einer String-Variable im


Anwendungsprogramm, in welche API den Ergebnisnamen ablegt.

Der Ergebnisindex ist die fortlaufende Nummer eines Ergebnisses in einem


Ergebnissatz. Gültige Wert sind 1..nr, wobei nr die mit apiResultNumber() ermittelte
Anzahl von Ergebnissen im Satz Ergebnissatz ist.

Die Beschreibung des Rückgabewerts von apiResultxxx() ist ebenso für


apiResultName() gültig.

4.3.2.5. Ermittlung des Ergebnisformats eines Ergebnisses


Das Format des von der Steuergeräte-Beschreibungsdatei zurückgelieferten
Ergebnisses mit der Funktion

apiResultFormat ( Zieladresse, Ergebnis, Ergebnissatz )

ermittelt werden. Die Zieladresse ist die Adresse einer APIRESULTFORMAT-


Variable im Anwendungsprogramm, in welche API das Ergebnisformat ablegt. Der
Argument Ergebnis bezeichnet das gesuchte Ergebnis, im Argument Ergebnissatz ist
der Ergebnissatz anzugeben.

22
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Die Beschreibung des Rückgabewerts von apiResultxxx() ist ebenso für


apiResultFormat() gültig.

4.3.3.Ergebnistypen und Formate

4.3.3.1. Ergebnistypen
Die Ergebnisse eines Auftrags können in folgenden Formaten vorliegen bzw.
konvertiert werden:

APICHAR
APIBYTE
APIINTEGER
APIWORD
APILONG
APIDWORD
APIREAL
APITEXT
APIBINARY

4.3.3.2. Ergebnisformate
Die Formatierungsanweisung ist mit apiResultText(...,Format) möglich und
folgendermaßen aufzubauen :

[ Spezifikationen ] Konvertierungszeichen

23
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Konvertierungszeichen Konvertierung
C[HAR] APICHAR Æ APITEXT
B[YTE] APIBYTE Æ APITEXT
I[NTEGER] APIINTEGER Æ APITEXT
W[ORD] APIWORD Æ APITEXT
L[ONG] APILONG Æ APITEXT
D[WORD] APIDWORD Æ APITEXT
R[EAL] APIREAL Æ APITEXT
T[EXT] APITEXT Æ APITEXT

Spezifikationen:

[ - ] [ ziff1 ] [ .ziff2 ] [ e,E ]


APIREAL: Exponentialdarstellung

APITEXT: maximal auszugebende Zeichenzahl


APIREAL: Anzahl der Nachkommastellen
2
minimale Feldgröße

linksbündige Formatierung, sonst


rechtsbündige Formatierung

2
Ergänzung mit Leerzeichen bei kürzeren Argumenten
Erweiterung auf benötigte Stellenzahl bei längeren Argumenten

Beispiele:

Formatierungsanweisung "B": Konvertierung eines Ergebnisses (sofern


konvertierbar) in das Format APIBYTE, daraufhin
weitere Konvertierung und Rückgabe eines
rechtsbündigen APITEXT-Strings.

Formatierungsanweisung "20T": Konvertierung eines Ergebnisses (sofern


konvertierbar) in das Format APITEXT, daraufhin
weitere Konvertierung und Rückgabe eines
rechtsbündigen APITEXT-Strings mit insgesamt
20 Stellen.

24
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Formatierungsanweisung "-8.2ER": Konvertierung eines Ergebnisses (sofern


konvertierbar) in das Format APIREAL, daraufhin
weitere Konvertierung und Rückgabe eines
linksbündigen APITEXT-Strings mit insgesamt 8
Stellen, wobei das Ergebnis in
Exponentialdarstellung mit 2 Nachkommastellen
abgelegt wird.

Formatierungsanweisung "": Konvertierung eines Ergebnisses (sofern


konvertierbar) in das Format APITEXT und
Rückgabe des linksbündigen APITEXT-Strings.

4.3.4.Applikationseigene Ergebnisfelder
Eine (Zwischen-) Speicherung und zeitversetzte Auswertung von Ergebnisfeldern
durch das Anwendungsprogramm ist mit dem im nachfolgenden beschriebenen
Mechanismus möglich.

ACHTUNG: Diese Umschaltung betrifft nur das Ergebnisfeld, es wird nicht der
Status des EDIABAS gespeichert.

4.3.4.1. Anlegen eines applikationseigenen Ergebnisfeldes


Ein Duplikat des aktuellen Ergebnisfeldes kann mit der Funktion

apiResultsNew( )

innerhalb API angelegt werden. Der Rückgabewert stellt eine Referenz auf das im
Arbeitsspeicher dynamisch angelegte Ergebnisfeld (Applikations-Ergebnisfeld) dar,
im Fehlerfall erfolgt die Rückgabe von NULL.

4.3.4.2. Bezug zum applikationseigenen Ergebnisfeld herstellen


Durch Aufruf der Funktion

apiResultsScope ( Referenz )

ist das Umschalten auf das applikationseigene Ergebnisfeld möglich, wobei eine
Referenz auf das applikationseigene Ergebnisfeld als Funktionsargument notwendig
ist (bekannt durch apiResultsNew()).

Nachfolgend kann mit den bekannten Auswertungsverfahren auf Ergebnisse des


applikationseigenen Ergebnisfeldes zugegriffen werden (apiResultxxx()).

25
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Die Bindung an das applikationseigene Ergebnisfeld besteht solange bis neue


Ergebnisse wieder im API-eigenen Ergebnisfeld angelegt werden (ausgelöst durch
einen Aufruf von apiJobxxx()).

4.3.4.3. Freigabe eines applikationseigenen Ergebnisfeldes


Eine Freigabe des mit apiResultsNew() einmal angelegten Speicherplatzes ist mit
der Funktion

apiResultsDelete ( Referenz )

für jedes applikationseigene Ergebnisfeld (Referenz als Funktionsargument)


durchführbar.

4.4. Device-Wechsel

Die Kommunikation mit dem Diagnose-Interface erfolgt durch Zugriff auf den
Schnittstellentreiber.

Für den Zugriff auf das Diagnose-Interface (Device) ist die Angabe von Device-
Anschluß und Device-Applikation notwendig:

Notwendige Zugriffsinformationen für Diagnose-Interface = Device-Anschluß +


Device-Applikation

Der Device-Anschluß kennzeichnet die anzusteuernde Schnittstelle, die auf dem


Interface anzusprechende Applikation wird als Device-Applikation bezeichnet.

Bei Initialisierung von API mit apiInit() wird vom EDIABAS eine systemabhängige
Voreinstellung für Device-Anschluß und Device-Applikation vorgenommen.

Die Voreinstellung verwendet den von Softing gelieferten Gerätetreiber zum


Diagnosebus-Interface.

Ein Wechsel auf einen anderen Device-Anschluß bzw. andere Device-Applikation


kann durch den Aufruf der Funktion

apiSwitchDevice ( deviceConnection, deviceApplication )

durchgeführt werden.

Sowohl der Device-Anschluß deviceConnection als auch die Device-Applikation


deviceApplication ist als String anzugeben.

26
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Der Wechsel auf einen anderen Device-Anschluß bzw. andere Device-Applikation ist
nur bis zu einem weiteren Wechsel mit apiSwitchDevice() oder dem Abbruch von
API (apiEnd()) wirksam.

Die Voreinstellung für Device-Anschluß bzw. Device-Applikation kann durch die


Angabe eines Leer-Strings bestimmt werden.

Als Rückgabewert liefert die Funktion apiSwitchDevice() eine Information


hinsichtlich der erfolgreichen Umschaltung des Device-Anschlusses und der Device-
Applikation:

APITRUE Umschaltung korrekt


APIFALSE Umschaltung fehlerhaft

Vorgehensweisen zur Fehlerbehandlung sind im Kapitel FEHLERBEHANDLUNG


beschrieben.

4.5. API-Ablaufsteuerung

Generell muß folgender Ablauf eingehalten werden, wobei sich dieser beliebig oft
wiederholen kann:

...
apiInitxxx()
...
Sonstige API-Funktionen
...
apiEnd()
...

Nach korrekter API-Initialisierung (apiInitxxx() mit Rückgabewert APITRUE) können


alle weiteren API-Funktionsaufrufe bis zum Abbruch von API (apiEnd()) durchgeführt
werden.

Eine Ausnahme stellen hierbei die API-Funktionen zu Fehlerbehandlung dar, welche


auch bei fehlerhafter API-Initialisierung aufgerufen werden dürfen (siehe Kap.
Fehlerbehandlung).

27
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

4.5.1. Auftragssteuerung

4.5.1.1. Automatische Auftragsabarbeitung


Folgende Funkionen bewirken die Abarbeitung eines bereits abgesetzten, jedoch
noch nicht abgeschlossenen Auftrags:

„ Absetzen eines neuen Auftrags (apiJobxxx)

„ Device-Wechsel (apiSwitchDevice)

„ Ergebnisermittlung (apiResultxxx)

Der noch nicht abschlossene Auftrag wird vor der neuen Aktion abgehandelt.

Die neue Aktion wird auch dann ausgeführt, wenn im automatisch abgehandelten
Auftrag ein Fehler auftritt.
Vor dem Ausführen der neuen Aktion wird ein im automatisch ausgeführten Auftrag
aufgetretener Fehler gelöscht.

4.5.1.2. Zyklische Abfrage (Polling)


Um während der Abarbeitung eines API-Auftrags zeitkritische Aktionen des
Anwendungsprogramms auszuführen (z.B. Tastaturabfragen, Bildschirmaufbau, ...),
ist vor der Ergebnisabfrage mit apiResultxxx() der Bearbeitungszustand des
Auftrags abzufragen:

apiState ( )

Der Rückgabewert von apiState() stellt den Auftragszustand des (letzten)


abgesetzten Auftrags dar:

APIBUSY : Auftrag wird noch bearbeitet


APIREADY : Auftrag ist abgearbeitet
APIBREAK : Auftrag wurde abgebrochen
APIERROR : Auftrag war fehlerbehaftet

Der ordnungsgemäße Abbruch des laufenden Auftrags kann mit der Funktion

apiBreak ( )

durchgeführt werden. Zusätzlich erfolgt hierbei das Löschen eventuell vorhandener


Ergebnisse sowie die anschließende Rückkehr zum Anwendungsprogramm.

28
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Der Auftragszustand APIBREAK ist im Gegensatz zu den anderen


Auftragszuständen ausschließlich durch das Anwendungsprogramm zu veranlassen.
Zu diesen Zweck ist entweder die Funktion apiBreak() aufzurufen oder mit dem
Rückgabewert APITRUE die Call-Back-Funktion zu beenden.

Im Falle des Auftragszustands APIERROR sind keine Ergebnisse vorhanden.

Die Auftragszustände APIBREAK und APIERROR bleiben bis zum Absetzen eines
Auftrags mit apiJobxxx() oder Neu-Initialisierung von API mit apiInitxxx() erhalten.

4.5.1.3. Call-Back-Mechanismus
Alternativ zu der EDIABAS-Ablaufsteuerung mit apiState() ist die Benutzung einer
Call-Back-Routine des Anwendungsprogramms möglich.

Hierbei wird während eines API-Auftrags vom EDIABAS kontinuierlich eine frei
wählbare Funktion des Anwendungsprogramms aufgerufen.

Aktivierung einer Call-Back-Routine


Eine Call-Back-Routine kann dem EDIABAS mit

apiCallBack ( Funktionsreferenz )

mitgeteilt werden.
Syntax einer Call-Back-Routine

Der Rückgabewert der Call-Back-Routine wird als Abbruchforderung an das


EDIABAS interpretiert:

Rückgabewert = APITRUE : Auftrag sofort abbrechen


Rückgabewert = APIFALSE : Auftrag fortsetzen

Stellt das EDIABAS nach Ausführung der Call-Back-Routine die Forderung nach
sofortigem Abbruch fest, so bewirkt dies den Abbruch des aktuellen API-Auftrags
(Zustand APIBREAK), das Löschen eventuell vorhandener Ergebnisse sowie die
Rückkehr zum Anwendungsprogramm.

Laufzeitanforderung
Da eine Call-Back-Routine während einer API-Auftragsbearbeitung kontinuierlich
aktiviert wird und somit jedesmal das EDIABAS unterbricht, ist bei Call-Back-
Routinen eine relativ kurze Laufzeit einzuhalten.

Beschränkungen

29
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Innerhalb einer Call-Back-Routine dürfen mit Ausnahme der Fehlerfunktionen


apiErrorCode() und apiErrorText() keine weiteren API-Funktionen aufgerufen
werden.

4.5.1.4. Auftragsabbruch
Die im folgenden aufgeführten Ereignisse führen zum Abbruch eines noch nicht
beendeten Auftrags:

„ Fehler während der Bearbeitung (indirekter Abbruch)


„ Abbruch von API mit apiEnd() (indirekter Abbruch)
„ Direkter Auftragsabbruch mit apiBreak()
„ Direkter Auftragsabbruch durch Rückgabewert APIFALSE in der Call-Back-
Routine

Der direkte Auftragsabbruch löst einen Fehler aus, weshalb alle Ergebnisdaten
gelöscht werden und nicht mehr zugänglich sind.

Während des API-Abbruchs mit apiEnd() wird ein apiBreak() ausgelöst und somit
ein noch nicht beendeter Auftrag abgebrochen.

4.5.2. Auftragsbearbeitungsstand
Während der Bearbeitung eines Auftrags kann der Bearbeitungsstand mit der
Funktion apiJobInfo abgefragt werden. Diese Funktion liefert den Abarbeitungsgrad
eines Auftrags in Prozent. Der Abfragemechanismus muß in der Beschreibungsdatei
durch spezielle BEST Sprachkonstrukte unterstützt werden. Ist dies nicht der Fall,
dann liefert die Funktion apiJobInfo -1 als Ergebnis (d.h. der Abarbeitungsgrad ist
undefiniert)

4.5.3. Parallelverarbeitung (nur WIN32/CE und SCO-UNIX)


EDIABAS für WIN32/CE und SCO-UNIX ermöglichen den gleichzeitigen Zugriff
mehrerer Anwendungsprogramme auf EDIABAS.

Im Unterschied zu den anderen Plattformen stellt EDIABAS für WIN32/CE keine 1x


auf dem System laufende Software dar, welche alle Anwendungsprogramme
nacheinander bedient. Statt dessen läuft für jedes Anwendungsprogramm ein
eigenes EDIABAS, welches ggf. automatisch gestartet (und unter WIN32/CE wieder
beendet) wird. Unter SCO-UNIX können bis zu 64 Anwendungsprogramme
gleichzeitig auf EDIABAS zugreifen.

30
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Die über EDIABAS verfügbaren Schnittstellen dürfen immer nur von 1


Anwendungsprogramm angesprochen werden. EDIABAS für WIN32/CE und SCO-
UNIX benötigen daher einen Schnittstellen-Locking-Mechanismus, welcher den
exklusiven Zugriff eines Anwendungsprogramms auf eine Schnittstelle garantiert
(Device-Locking).

Das Device-Locking greift beim Aufruf der Funktionen apiInit(), apiInitExt() und
apiSwitchDevice():

apiInit() Î Default-Device "_"

apiInitExt() Î Device entsprechend Funktionsaufruf, z.B. "A"

apiSwitchDevice() Î Device entsprechend Funktionsaufruf, z.B. "A"

Versuchen mehrere Anwendungsprogramme auf das gleiche Device zuzugreifen, so


bekommen alle Anwendungsprogramme (mit Ausnahme des ersten auf die
Schnittstelle zugreifenden Anwendungsprogramms) den Fehler IFH-0029: ACCESS
DENIED.

Hierbei ist zu beachten, daß beim Aufruf von apiInit() der exklusive Zugriff auf das
Default-Device "_" erfolgt. Sollte bereits eine andere Anwendung auf das Default-
Device "_" zugreifen, so wird der Aufruf von apiInit() fehlschlagen (IFH-0029:
ACCESS DENIED).

Ein Anwendungsprogramm kann somit nur dann mit apiInit() auf EDIABAS zugreifen,
wenn alle bereits laufenden Anwendungsprogramme vorher über apiInitExt() oder
apiSwitchDevice() eine andere Schnittstelle als "_" gewählt haben!

4.5.4. Applikations-Locking (nicht WIN32/CE und SCO-UNIX)


Das EDIABAS kann immer nur mit einem Anwendungsprogramm gleichzeitig
kommunizieren, weshalb bei Multitasking-Betriebssystemen ein Verfahren zur
Bindung des EDIABAS an ein Anwendungsprogramm notwendig ist (Applikations-
Locking).

4.5.4.1. Binden eines Anwendungsprogramms an das EDIABAS


Erfolgt innerhalb eines Anwendungsprogramms die Initialisierung von API (mit
apiInit() oder apiInitExt()), so wird zuerst auf eine bereits bestehende Bindung des
EDIABAS hin geprüft.

Eine bereits bestehende Bindung des EDIABAS mit einem noch aktiven
Anwendungsprogramm wird durch einen APIFALSE-Rückgabewerts der API-

31
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Funktionen apiInit() bzw. apiInitExt() angezeigt, das Anwendungsprogramm wird


somit abgewiesen (fehlerhafte Initialisierung).

Ist hingegen keine Bindung vorhanden oder existiert bei vorhandener Bindung das
entsprechende Anwendungsprogramm nicht mehr, so wird dies durch einen
APITRUE-Rückgabewert der API-Funktionen apiInit() bzw. apiInitExt() angezeigt,
das Anwendungsprogramm wird somit an das EDIABAS gebunden (erfolgreiche
Initialisierung). Das EDIABAS ist nun für andere Anwendungsprogramme gesperrt.

4.5.4.2. Aufheben der Bindung an das EDIABAS


Die Bindung eines Anwendungsprogramms an das EDIABAS kann durch Aufruf von
apiEnd() aufgehoben und das EDIABAS wieder für andere Prozesse zugänglich
gemacht werden.

4.5.4.3. Zugriff mehrerer Anwendungsprogramme auf das


EDIABAS (nicht WIN32/CE und SCO-UNIX)
Ein quasi-paralleler Zugriff mehrerer Anwendungsprogramme auf das EDIABAS ist
durch das nur kurzzeitige Sperren des EDIABAS möglich. Ideal ist die Durchführung
nur eines Auftrags je Bindung mit apiInitxxx()/apiEnd(). Jede Anwendung kann dann
bei gesperrtem EDIABAS auf die Aufhebung der Bindung warten.

4.6. Konfiguration

Die EDIABAS-Konfiguration besteht aus mehreren Informationspaaren, wobei jedes


Informationspaar aus

Konfigurationselement und Konfigurationeinstellung

besteht.

Konfigurationselement und Konfigurationseinstellung stellen jeweils Strings mit


vorgegebenen Inhalt dar.

Alle EDIABAS-Konfigurationselemente können abgefragt werden, eine Änderung der


Konfigurationseinstellung ist jedoch nicht bei allen Konfigurationselementen möglich.
Eine Konfigurationsänderung ist nur bis zum nächsten API-Abbruch (apiEnd())
wirksam.

Eine genaue Beschreibung aller Konfigurationselemente und deren


Konfigurationseinstellungen ist in [2] beschrieben.

32
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

4.6.1.Ermittlung der Konfiguration


Durch Aufruf der Funktion

apiGetConfig ( Konfigurationselement, Zieladresse )

kann die Einstellung eines Konfigurationselements ermittelt werden.

Als Argument Konfigurationselement ist das abzufragende Konfigurationselement als


String anzugeben. Als Zieladresse ist die Adresse der String-Variable anzugeben,
wohin API die entsprechende Konfigurationseinstellung kopiert.

Der Rückgabewert zeigt den Erfolg der Konfigurationsermittlung:

Rückgabewert = APITRUE : Konfiguration ermittelt


Rückgabewert = APIFALSE : Konfigurationsermittlung fehlerhaft

Eine fehlerhafte Konfigurationsermittlung löst keinen EDIABAS-Fehler aus.

4.6.2.Änderung der Konfiguration


Die Einstellung eines Konfigurationselements kann mit dem Aufruf der Funktion

apiSetConfig ( Konfigurationselement, Konfigurationseinstellung )

geändert werden, sofern dies vom EDIABAS zugelassen wird.

Als Argument Konfigurationsname ist das zu änderende Konfigurationselement als


String anzugeben, für das Argument Konfigurationseinstellung ist die neue
Einstellung als String anzugeben.

Der Rückgabewert zeigt den Erfolg der Konfigurationsänderung:

Rückgabewert = APITRUE : Konfiguration geändert


Rückgabewert = APIFALSE : Unzulässige Konfigurationsänderung

Eine fehlerhafte Konfigurationsänderung löst keinen EDIABAS-Fehler aus.

33
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

4.7. Fehlerbehandlung

4.7.1.Ermittlung der Fehlerursache


Der einem Fehler zugrundeliegende Fehlerstatus ist durch Abfrage der Funktion

apiErrorCode ( )

möglich.

Zusätzlich kann der Default-Fehlertext des aufgetretenen Fehlers mit der Funktion

apiErrorText ( )

ermittelt werden.

Eine Beschreibung aller möglichen Fehler befindet sich in [1].

4.7.2.Verwendung eines Error-Handlers


Zur Fehlerbehandlung kann vom Anwendungsprogramm eine Funktion ohne
Argumente bestimmt werden, welche vom Laufzeitsystem immer bei Auftritt eines
Fehlers zu aktivieren ist (Error-Handler):

apiErrorHandler ( Aktion )

Die Fehleranalyse innerhalb des Error-Handlers wird typischerweise durch Abfrage


von apiErrorCode() bzw. apiErrorText() erfolgen.

4.7.3.Vorgehensweise zur Fehleranalyse bei Initialisierung und


Ergebnisermittlung
Neben dem Rückgabewert APIFALSE bei Funktionen mit APIBOOL-Rückgabewert
ist eine Untersuchung auf einen API-Fehler durch folgende 2 Möglichkeiten gegeben
(siehe auch Kap. Fehlerbehandlung):

a) Abfrage des Fehlercodes mit der API-Funktion apiErrorCode()

Rückgabewert EDIABAS_ERR_NONE : Kein API-Fehler vorhanden


Sonstiger Rückgabewert : API-Fehler(code) vorhanden

b) Abfrage des Fehlertextes mit der API-Funktion apiErrorText()

34
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Rückgabewert NULL : Kein API-Fehler vorhanden


Sonstiger Rückgabewert : API-Fehler(text) vorhanden

Ob das gewünschte Ergebnisformat eines vorhandenen Ergebnisses überhaupt


vorliegt, kann durch Aufruf der API-Funktion apiResultFormat() überprüft werden:

Der Rückgabewert APIFALSE zeigt an, daß das Ergebnis nicht vorliegt.

4.7.4.Löschen eines Fehlers


Fehler bleiben bis zum Absetzen eines Auftrags mit apiJobxxx(), einem Device-
Wechsel mit apiSwitchDevice() oder der Neu-Initialisierung von API mit apiInitxxx()
gesetzt.

Eine Besonderheit stellen die Fehler API-0005 und API-0014 dar, welche zudem
auch bei der nächsten Ergebnisabfrage mit apiResultXxx() zurückgesetzt werden.

35
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

5. Beispiel Applikation

/********************************************************************
***
*** apidemo.c V1.1
***
*********************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <string.h>
#include <ctype.h>

#include "api.h"

#define TRUE 1
#define FALSE 0

#define LINESIZE 33

static char ecu[APIMAXNAME];


static char job[APIMAXNAME];
static char para[APIMAXPARA];
static char result[APIMAXRESULT];

static char buffer[81];

APIBOOL printResultField(FILE *);


void main (void);
void error (void);
void quit (int);

/*
* Beenden !!
*/
void quit (int exitCode)
{
apiEnd();
exit(exitCode);
}

/*
* EDIABAS Fehlermeldung anzeigen und Beenden !!
*/
void error (void)
{
printf("\nEDIABAS Fehler %d: %s\n",apiErrorCode(),apiErrorText());
quit(1);
}

/*

36
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

* Ausgabe eines binaeren Ergebnisses


*
*
* Parameter:
* - fp
* File-Pointer der Ausgabedatei
* - yb
* Adresse von APIBINARY-Puffer
* - yn
* Anzahl von auszugebenden Bytes
*/
void printBinary (FILE *fp,APIBINARY *yb,APIWORD yn)
{
/* Zeilenformat: */
/* line 0 25 */
/* XXX: XX XX XX XX XX XX XX XX XXXXXXXX */

static char line[LINESIZE+1];


static char addr[5];
unsigned n=0,z,hexz;

while (n<yn) {

for (z=0;z<LINESIZE;z++) line[z]=' ';


line[LINESIZE]=addr[0]='\0';
z=hexz=0;

while (n<yn && z<8) {


if (z==0)
sprintf(addr,"%03X:",n);
else
hexz++;
sprintf(&line[hexz],"%02X",yb[n]);
hexz+=2;
line[hexz]=' ';
line[LINESIZE-8+z]=(isprint((int)yb[n])? yb[n]:'.');
n++;
z++;
}
fprintf(fp,"\n %s
%s",addr,line);

}
}

/*
* Ausgabe des Ergebnisfeldes
*
* Falls der uebergebene File-Pointer den Wert NULL darstellt
* werden zwar alle Ergebnisse abgefragt, jedoch nicht
* ausgegeben
*
* Parameter:

37
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

* - fp
* File-Pointer der Ausgabedatei
*
* Rueckgabe von APITRUE falls ordnungsgemaess ausgegeben,
* sonst APIFALSE
*/
APIBOOL printResultField(FILE *fp)
{
static APITEXT t[APIMAXTEXT];
static APITEXT text[APIMAXNAME];
static APIBINARY yb[APIMAXBINARY];
APICHAR c;
APIBYTE b;
APIINTEGER n;
APIWORD yn,w,set,s,index,i;
APILONG l;
APIDWORD d;
APIREAL r;
APIRESULTFORMAT format;
APIBOOL ret=APITRUE;

if (fp!=NULL)
fprintf(fp,"ERGEBNISFELD:\n\n");

/* Anzahl der Ergebnissaetze bestimmen */


if (apiResultSets(&s)) {

/* Fuer alle Ergebnissaetze */


for (set=0;(set<=s) && (apiErrorCode()==EDIABAS_ERR_NONE);set++) {

if (fp!=NULL)
fprintf(fp,"SET %3u:",set);

/* Anzahl der Ergebnisse im aktuellen Ergebnissatz */


if (apiResultNumber(&i,set)) {

/* Fuer alle Ergebnisse */


for(index=1;
(index<=i)&&(apiErrorCode()==EDIABAS_ERR_NONE);
index++)
{
/* Ergebnisnamen bestimmen */
if (apiResultName(text,index,set)) {
if (fp!=NULL)
fprintf(fp," %sRESULT %3u: ",
(index==1)?"":" ",index);
/* Ergebnisformat bestimmen */
if (apiResultFormat(&format,text,set)) {
/* Ergebnisse nach Format auslesen und ausgeben */
switch (format) {
case APIFORMAT_CHAR:
if (apiResultChar(&c,text,set))
if (fp!=NULL)
fprintf(fp,"[ CHAR ] %s = %+d",text,c);

38
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

break;
case APIFORMAT_BYTE:
if (apiResultByte(&b,text,set))
if (fp!=NULL)
fprintf(fp,"[ BYTE ] %s = %u",text,b);
break;
case APIFORMAT_INTEGER:
if (apiResultInt(&n,text,set))
if (fp!=NULL)
fprintf(fp,"[ INTEGER ] %s = %+d",text,n);
break;
case APIFORMAT_WORD:
if (apiResultWord(&w,text,set))
if (fp!=NULL)
fprintf(fp,"[ WORD ] %s = %u",text,w);
break;
case APIFORMAT_LONG:
if (apiResultLong(&l,text,set))
if (fp!=NULL)
fprintf(fp,"[ LONG ] %s = %+ld",text,l);
break;
case APIFORMAT_DWORD:
if (apiResultDWord(&d,text,set))
if (fp!=NULL)
fprintf(fp,"[ DWORD ] %s = %lu",text,d);
break;
case APIFORMAT_REAL:
if (apiResultReal(&r,text,set))
if (fp!=NULL)
fprintf(fp,"[ REAL ] %s = %E",text,r);
break;
case APIFORMAT_TEXT:
if (apiResultText(t,text,set,""))
if (fp!=NULL)
fprintf(fp,"[ TEXT ] %s = %c%s%c",
text,'"',t,'"');
break;
case APIFORMAT_BINARY:
if (apiResultBinary(yb,&yn,text,set)) {
if (fp!=NULL) {
fprintf(fp,"[ BINARY ] %s = %u Bytes,",
text,yn);
printBinary(fp,yb,yn);
}
}
break;
}
if (fp!=NULL)
fprintf(fp,"\n");
}
}
}
}
}
}
return ret;

39
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

/*
Programmbeginn
*/
void main (void)
{
FILE *fp;
time_t start,stop;
unsigned loop=0i=0;
char c;
int showStatus=FALSE;
unsigned char *data;

printf("\n%s\n\n","APIDEMO V1.1");

/* APIJob Parameter einlesen */


printf("Steuergeraet: "); gets(ecu);
printf("Job: "); gets(job);
printf("Job-Parameter: "); gets(para);
printf("Job-Ergebnisse: "); gets(result);

printf("Anzahl von Durchgaengen (1-65535): "); gets(buffer);


sscanf(buffer,"%u",&loop);

printf("Status und Ergebnisse anzeigen (j/N) ?");


gets(buffer);
sscanf(buffer,"%c",&c);
if (c=='j' || c=='J')
showStatus=TRUE;

printf("\nDruecken von ENTER um Verarbeitung zu starten");


getchar();
printf("\n");

time(&start);

for (i=1;i<=loop;i++) {

if (showStatus)
printf("\nDurchgang #%03d...",i);

if (!apiInit()) {
printf("\nFehler bei apiInit(): %s\n",apiErrorText());
quit(1);
}

if (showStatus)
printf("Ok.\n\n");

apiJob(ecu,job,data,result);

while (apiState()==APIBUSY) /* tue nichts */;

if (apiState()==APIERROR) {

40
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

printf("\nEDIABAS Fehler %d:


%s\n",apiErrorCode(),apiErrorText());
continue;
}

if (showStatus){
printf("Ok.\n");
if(!printResultField(stdout))
error();
}

apiEnd();

time(&stop);

printf("\n\nAPIDEMO fertig (%u), benoetigte Zeit = %.1f Sekunden\n",


i-1,difftime(stop,start));

quit(0);
}

41
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

A. LITERATURVERZEICHNIS

[1] EDIABAS: Fehlerreferenz

[2] EDIABAS: Benutzerhandbuch

[3] EDIABAS: API-Funktionsreferenz

[4] EDIABAS: API Benutzerhandbuch

[5] EDIABAS: Transparentmodus

42
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

B. INDEX
apiResultText 20
apiResultVar 21
_ARGUMENTS 16 apiResultWord 19, 20
_JOBCOMMENTS 15 apiSetConfig 33
_JOBS 15 apiState 28, 29
_RESULTS 16 apiSwitchDevice 26
_TABLE 17 APITRUE 9, 20, 27, 28, 29, 31, 33
_TABLES 16 Applikations-Locking 31
_VERSIONINFO 15 Auftragsbearbeitungsstand 30
Auftragszustand 28
API 8 Automatische Auftragsabarbeitung 27
apiBreak 28, 30
APIBREAK 28, 29 Call-Back-Funktion 28
APIBUSY 28
apiCallBack 29 Device-Applikation 26
apiEnd 9, 27, 30, 32 Device-Name 26
APIERROR 28 DONE 13
apiErrorCode 29, 33, 34
apiErrorHandler 34 ENDE 14
apiErrorText 29, 33, 34 Ergebnis 17
APIFALSE 9, 20, 27, 29, 30, 31, 33, Ergebnisfeld 17
34 Ergebnisformate 23
apiGetConfig 32 ERGEBNISSATZ 18
apiInit 9, 27, 31, 32 Ergebnistypen 22
apiInitExt 9, 27, 31, 32
apiJob 11 IDENTIFIKATION 14
apiJobData 11 IGNITIONCURRENT 19
apiJobExt 11, 13 IGNITIONHISTORY 19
apiJobInfo 30 INITIALISIERUNG 13
APIREADY 28
apiResultByte 19 JOBSTATUS 19
apiResultDWord 20
apiResultFormat 22, 34 Konfiguration 18, 32
apiResultInt 19 Konfigurationsänderung 33
apiResultName 22 Konfigurationseinstellung 32
apiResultNumber 21 Konfigurationselement 32
apiResultReal 20 Konfigurationsermittlung 32
apiResultsDelete 26
apiResultSets 21 Multitasking-Betriebssysteme 31
apiResultsNew 25
apiResultsScope 25 OBJECT 18

43
EDIABAS — API-SCHNITTSTELLENBESCHREIBUNG

Parallelverarbeitung 30
Polling 28

Schnittstellentreiber 26
SETS 18
Standardaufträge 13
Standardergebnisse 13, 15
Steuergeräte-Variante 12
Systemergebnis 18
Systemergebnissatz 18

Transparent-Mode 11

UBATTCURRENT 19
UBATTHISTORY 19

VARIANTE 14, 18, 21


Versorgungsspannung 19
Virtuelle Aufträge 14

Zündung 19

44