ApiRef PDF

EDIABAS — API-FUNKTIONSREFERENZ
EDIABAS
Elektronik Diagnose Basissystem
API-FUNKTIONSREFERENZ
VERSION 6d
Copyright BMW AG, created by Softing AG
APIREF.DOC
INHALT
INHALT ............................................................................................................2
1. Änderungshistorie .................................................................................4
2. Einführung ..............................................................................................5
2.1. Über diese Dokumentation......................................................5
2.2. Konventionen ..........................................................................5
2.3. Besonderheiten, Begriffe, Akronyme.......................................6
3. Datentypen, Konstanten und Fehlermeldungen..................................7

3.1. Datentypen..............................................................................7
3.2. Konstanten ..............................................................................9
3.3. Fehlermeldungen ....................................................................10
4. API-Funktionsreferenz ...........................................................................12
apiBreak ...................................................................................................13
apiCallBack ..............................................................................................14
apiEnd......................................................................................................15
apiErrorCode............................................................................................16
apiErrorHandler........................................................................................17
apiErrorText .............................................................................................18
apiGetConfig ............................................................................................19
apiInit .......................................................................................................20
apiInitExt ..................................................................................................21
apiJob ......................................................................................................23
apiJobData ...............................................................................................24
apiJobExt .................................................................................................25
apiJobInfo ................................................................................................26
apiResultBinary ........................................................................................27
apiResultByte ...........................................................................................28
apiResultChar ..........................................................................................29
apiResultDWord .......................................................................................30
2
apiResultFormat.......................................................................................31
apiResultInt ..............................................................................................32
apiResultLong ..........................................................................................33
apiResultName.........................................................................................34
apiResultNumber .....................................................................................35
apiResultReal...........................................................................................36
apiResultsDelete ......................................................................................37
apiResultSets ...........................................................................................38
apiResultsNew .........................................................................................39
apiResultsScope ......................................................................................40
apiResultText ...........................................................................................41
apiResultVar.............................................................................................42
apiResultWord..........................................................................................43
apiSetConfig.............................................................................................44
apiState....................................................................................................45
apiSwitchDevice.......................................................................................46
5. Sonstige Funktionen..............................................................................47
enableServer............................................................................................47
closeServer ..............................................................................................48
enableMultiThreading...............................................................................49
A. LITERATURVERZEICHNIS.....................................................................50
B. INDEX ......................................................................................................51
3
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 API-Funktionen apiResultByte/apiResultChar unter VB 4.0 verfügbar
Version 6 Neue API-Funktion apiInitExt unter Ergänzung zu apiJobInfo
Version 6a Überarbeitung für EDIABAS V6.4.0
Version 6b Überarbeitung für EDIABAS V6.4.1
Version 6c Ergänzungen für Windows CE
Version 6d Ergänzungen für .NET Compact Framework und MultiThreading/Win32
4
2. Einführung
2.1. Über diese Dokumentation
Diese Dokumentation beschreibt die Konstanten und Funktionen, die in der

EDIABAS-API Schnittstelle zur Verfügung stehen. Eine genaue Beschreibung ihrer
Verwendung befindet sich in [5]. Die Einbindung in eine Entwicklungsumgebung wird
in [6] beschrieben. Allgemeines über EDIABAS und über Steuergeräte-
beschreibungsdateien wird in [4] 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 Sprachen C/C++/Visual Basic 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.
5
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".
6
3. Datentypen, Konstanten und Fehlermeldungen
3.1. Datentypen
Folgende Datentypen werden von API verwendet:
API-Datentyp C/C++ Visual Basic- C# Verwendung

Definition Definition Definition
APIBOOL enum, Werte: VB 3.0/4.0/6.0: bool Rückgabewert

APIFALSE, Integer
APITRUE VB.NET:
Boolean
APICHAR char Î Byte *) char Ergebnistyp
APIBYTE unsigned char VB 4.0/6.0/.NET: byte Ergebnistyp
Byte
APIINTEGER short VB 3.0/4.0/6.0: short Ergebnistyp
Integer
VB.NET:
Short
APIWORD unsigned Î Integer *) ushort Ergebnistyp
short
APILONG long VB 3.0/4.0/6.0: int Ergebnistyp
Long
VB.NET:
Integer
APIDWORD unsigned long Long uint Ergebnistyp
APIREAL double Double double Ergebnistyp
APITEXT[] char[] String string Ergebnistyp
APIBINARY[] unsigned VB 3.0: byte[] Ergebnistyp
char[] String
VB 4.0/6.0/.NET:
Array of Byte
Î Ersatzdatentyp *)
7
Neben den einfachen Datentypen ist noch der komplexe Datentyp

APIRESULTFIELD definiert, welcher eine Referenz auf ein Ergebnisfeld darstellt.
Variable des Datentyps APIRESULTFIELD können wie Variable einfachen

Datentyps (z.B. APIBYTE) benutzt werden.
Unter Visual Basic und C# sind die API-Datentypen nicht verfügbar.
8
3.2. Konstanten
Folgende Konstanten werden von API zur Verfügung gestellt:
Konstante Zweck
APIMAXCONFIG Maximale und empfohlene Größe von Puffer für

Konfigurationseinstellung (incl. Abschlußzeichen)
APIMAXDEVICE Maximale Länge der Device-Argumente Anschluß und

Applikation (incl. Abschlußzeichen)
APIMAXNAME Maximale Länge der Job-Argumente Steuergerät und

Name, der Ergebnisnamen sowie der Format-Strings
(incl. Abschlußzeichen)
APIMAXSTDPARA Maximale Länge des Job-Arguments Parameter für

Standardjobs
APIMAXPARA Maximale Länge des Job-Arguments Parameter
APIMAXRESULT Maximale Länge von Job-Ergebnis Ergebnis (incl.

Abschlußzeichen)
APIMAXTEXT Maximale und empfohlene Größe von APITEXT-

Ergebnispuffer (incl. Abschlußzeichen)
APIMAXBINARY Maximale und empfohlene Größe von APIBINARY-

Ergebnispuffer
APIMAXFILENAME Maximale und empfohlene Größe von Dateinamen (incl.

Abschlußzeichen)
APIBUSY BUSY-Status von EDIABAS

Visual Basic: APIBUSY_
APIREADY READY-Status von EDIABAS

Visual Basic: APIREADY_
APIBREAK BREAK-Status von EDIABAS

Visual Basic: APIBREAK_
APIERROR ERROR-Status von EDIABAS

Visual Basic: APIERROR_
9
EDIABAS_XXX_#### Fehlermeldungen (siehe Kap. "Fehlermeldungen")
3.3. Fehlermeldungen
Eine EDIABAS Fehlermeldung besteht aus folgenden Komponenten:
Fehlersymbol (Fehlerursprung, Fehlernummer)
Fehlercode
Default-Fehlertext
Bei Auftritt eines Fehlers kann sich das Anwendungsprogramm den Fehlercode mit
der Funktion apiErrorCode() und/oder den Default-Fehlertext mit der Funktion
apiErrorText() von EDIABAS abholen.
Jedem Fehlercode ist ein Fehlersymbol zugeordnet, auf das im Rahmen einer
Fehlerbehandlung im Anwendungsprogramm referenziert werden kann.
Die Fehlersymbole sind in API.H definiert.
Das Fehlersymbol eines jeden Fehlers hat folgenden Aufbau:
EDIABAS_XXX_####
Die Zeichengruppe XXX benennt den EDIABAS-internen Ursprungsbereich des

aufgetretenen Fehlers, die Zahl #### bezeichnet die entsprechende Fehlernummer.
Fehler- bzw. Programmbereiche:
EDIABAS_API_#### API
EDIABAS_BIP_#### BEST-Interpreter, Laufzeitsystem
EDIABAS_SYS_#### Ablaufsteuerung, Laufzeitsystem
EDIABAS_IFH_#### Interface-Handler
EDIABAS_NET_#### Netzwerk, Laufzeitsystem
EDIABAS_RUN_#### Steuergerätebeschreibungsdatei
10
Eine Ausnahme bildet hierbei der Pseudo-Fehler EDIABAS_ERR_NONE

(Fehlercode 0), welcher einen fehlerfreien Zustand anzeigt.
Im Dokument [1] befindet sich eine Auflistung aller Fehler mit zugehörigem
Fehlersymbol, Fehlercode, Default-Fehlertext und Beschreibung der Fehlermeldung.
11
4. API-Funktionsreferenz
Die folgenden Seiten beschreiben die API-Funktionen in alphabetischer Reihenfolge.
Die Beschreibung einer Funktion ist in folgende Abschnitte gegliedert:
Kurzbeschreibung. Faßt die Wirkung der Funktion kurz zusammen, illustriert

die C/C++ Syntax und beschreibt kurz die Argumente.
Die Syntax der Funktion für Visual Basic und die DLL-
Schnittstelle ist in den Dateien API.BAS bzw. APIDLL.H
festgelegt. Die Syntax der Funktion für C# und Visual
Basic.NET ist in den Dateien APINET.DLL bzw.
APIVBNET.DLL festgelegt. Die Dateien sind in [6]
beschrieben.
Bemerkung. Gibt eine detaillierte Beschreibung der Funktion und deren

Benutzung.
Rückgabewert. Beschreibt den Wert, der von der Funktion zurückgegeben

wird.
Anbindung. Listet die Anbindungen auf, welche die Funktion

unterstützen (C/C++, Visual Basic, C# und DLL-
Schnittstelle). Eine genaue Beschreibung dieser
Anbindungen erfolgt in [6].
Siehe auch. Zeigt verwandte Funktionen auf.
12
apiBreak
Kurzbeschreibung Abbruch der gerade laufenden Auftragsbearbeitung
void apiBreak ( )
Bemerkung Die laufende Auftragsbearbeitung kann mit der Funktion

apiBreak() abgebrochen werden (automatischer Aufruf bei
apiEnd()). Eventuell vorhandene Ergebnisse werden dann
gelöscht.
Rückgabewert -
Anbindung C/C++ Visual Basic C# DLL
Siehe auch apiEnd apiInit apiInitExt apiState apiCallBack
13
apiCallBack
Kurzbeschreibung Installation einer Call-Back-Routine im Anwendungsprogramm

(optional).
void apiCallBack ( APIBOOL (*action)() )
action Funktionsreferenz (Adresse) der Call-Back-Routine
Bemerkung Die laufende Auftragsbearbeitung kann durch den APIBOOL-

Rückgabewert der Call-Back-Routine gesteuert werden:
Rückgabewert = APITRUE Auftragsbearbeitung wird

abgebrochen
Rückgabewert = APIFALSE Auftragsbearbeitung wird
fortgesetzt
Der Aufruf der Call-Back-Routine durch EDIABAS erfolgt nur

bei den Funktionen apiState oder apiResultxxx!
Rückgabewert -
Siehe auch apiBreak apiEnd apiInit apiInitExt apiState apiSwitchDevice
14
apiEnd
Kurzbeschreibung Auflösung der Applikationsbindung an EDIABAS
void apiEnd ( )
Bemerkung Das EDIABAS-Laufzeitsystem wird für andere Applikationen

wieder freigegeben.
Rückgabe des belegten Speicherplatzes.
Rückgabewert -
Siehe auch apiBreak apiInit apiInitExt apiState apiCallBack

apiSwitchDevice
15
apiErrorCode
Kurzbeschreibung Ermittlung des aktuellen Fehlercodes
int apiErrorCode ( )
Bemerkung Diese Funktion darf auch außerhalb von apiInit() bzw.

apiInitExt(...) aufgerufen werden. Liefert apiInit() bzw.
apiInitExt(...) den Wert APIFALSE zurück, dann kann der
Fehlercode mit apiErrorCode() abgefragt werden.
Rückgabewert Fehlercode oder EDIABAS_ERR_NONE falls kein Fehler

vorliegt
Siehe auch apiErrorHandler apiErrorText
16
apiErrorHandler
Kurzbeschreibung Installation einer Error-Handlers-Funktion im

Anwendungsprogramm (optional).
void apiErrorHandler ( void (*action)() )
action Referenz des Error-Handlers (Funktionsadresse)
Bemerkung Die Error-Handler-Funktion im Anwendungsprogramm wird von

EDIABAS immer dann aufgerufen, wenn ein EDIABAS-Fehler
auftritt.
Rückgabewert -
Siehe auch apiErrorCode apiErrorText
17
apiErrorText
Kurzbeschreibung Ermittlung des aktuellen Fehlertextes.
const char *apiErrorText ( )
Bemerkung Diese Funktion darf auch außerhalb von apiInit() bzw.

apiInitExt(...) aufgerufen werden. Liefert apiInit() bzw.
apiInitExt(...) den Wert APIFALSE zurück, dann kann der
Fehlertext mit apiErrorText() abgefragt werden.
Rückgabewert Zeiger auf Fehlertext oder NULL falls kein Fehler vorliegt
Siehe auch apiErrorCode apiErrorHandler apiErrorText
18
apiGetConfig
Kurzbeschreibung Abfrage der EDIABAS-Konfiguration
APIBOOL apiGetConfig ( const char *config, char *buf )
config Abzufragendes Konfigurationelement

buf Puffer für Konfigurationseinstellung
Bemerkung Ermittlung der Einstellung des Konfigurationselements config.

APIMAXCONFIG ist die maximale Anzahl der kopierten
Zeichen und die somit empfohlene Puffergröße für buf.
Der Fehlerstatus wird nicht beeinflußt.
Alle Konfigurationselemente und deren Einstellungen sind in [4]
beschrieben.
Rückgabewert Erfolg von Konfigurationsermittlung
APITRUE Konfiguration ermittelt

APIFALSE Konfigurationsabfrage fehlerhaft
Siehe auch apiSetConfig
19
apiInit
Kurzbeschreibung Initialisierung der EDIABAS-Komponenten: API, Laufzeitsystem

und Interface-Handler.
APIBOOL apiInit ( )
Bemerkung Die Funktion apiInit (oder apiInitExt) muß vor Aufruf weiterer
API-Funktionen erfolgreich durchlaufen werden!
Eine Ausnahme bilden die Funktionen apiErrorCode() und
apiErrorText(). Diese Funktionen liefern den Fehler, wenn
apiInit() bzw. apiInitExt(...) fehlschlägt.
Das Laufzeitsystem wird initialisiert und für andere
Anwendungsprogramme gesperrt (Applikations-Locking).
Voreinstellung von Device-Anschluß und Device-Applikation.
Fehlerstatus wird beeinflußt.
Rückgabewert APITRUE Initialisierung fehlerfrei, Aufruf weiterer API-

Funktionen ist möglich
APIFALSE Initialisierung fehlerhaft oder Zugriff verweigert,
Aufruf weiterer API-Funktionen nicht möglich
-> Fehlerbehandlung im Anwendungsprogramm
Siehe auch apiBreak apiEnd apiState apiCallBack apiSwitchDevice
20
apiInitExt
Kurzbeschreibung Initialisierung der EDIABAS-Komponenten: API, Laufzeitsystem

und Interface-Handler.
APIBOOL apiInitExt (const char *ifh,

const char *deviceUnit,
const char *deviceApplication,
const char *reserved )
ifh Interfacehandler (max. APIMAXFILENAME),
voreingestellter Interfacehandler bei Übergabe
eines Leer-Strings
deviceUnit Device-Name (genau ein Zeichen), voreingestellter
Name bei Übergabe eines Leer-Strings
deviceApplication Device-Applikation (max. APIMAXDEVICE),
voreingestellte Applikation bei Übergabe eines
Leer-Strings
reserved Leer-String, reserviert für Erweiterungen
Bemerkung Die Funktion apiInitExt (oder apiInit) muß vor Aufruf weiterer
API-Funktionen erfolgreich durchlaufen werden!
Eine Ausnahme bilden die Funktionen apiErrorCode() und
apiErrorText(). Diese Funktionen liefern den Fehler, wenn
apiInit() bzw. apiInitExt(...) fehlschlägt.
Das Laufzeitsystem wird initialisiert und für andere
Anwendungsprogramme gesperrt (Applikations-Locking).
Die Einstellung eines - von der Voreinstellung abweichenden -
Interfacehandlers wird nur unter WIN32/WINCE/WIN16
unterstützt. Die Einstellungen von Interfacehandler, Device-
Name und Device-Applikation gelten nur bis zum API-Ende
(apiEnd).
Für die Bildung des Diagnose-Interface-Dateinames gelten die
Regeln entsprechend der EDIABAS-Konfiguration.
Rückgabewert APITRUE Initialisierung fehlerfrei, Aufruf weiterer API-

Funktionen ist möglich
APIFALSE Initialisierung fehlerhaft oder Zugriff verweigert,
Aufruf weiterer API-Funktionen nicht möglich
21
-> Fehlerbehandlung im Anwendungs-

programm
Siehe auch apiBreak apiEnd apiState apiCallBack apiSwitchDevice
22
apiJob
Kurzbeschreibung Absetzen eines Auftrags an EDIABAS
void apiJob ( const char *ecu, const char *job, const char *para, const
char *result )
ecu Name der zu ladenden Gruppen- oder Varianten-
Beschreibungsdatei (max. APIMAXNAME)
job Abzusetzender Auftrag, der Auftragsname ist in den
angesprochenen SGBD festgelegt (max. APIMAXNAME)
para Auftragsparameter (max. APIMAXPARA) als String, mehrere
Auftragsparameter sind mit Semikolon zu trennen.
Die Auftragsparameter sind abhängig vom jeweiligen Auftrag
(job).
result Zu ermittelnde Ergebnisse (max. APIMAXRESULT), mehrere
Ergebnisse sind mit Semikolon zu trennen.
Zur Bearbeitung aller Ergebnisse ist ein Leer-String ("")
anzugeben.
Die Ergebnisse sind abhängig vom jeweiligen Auftrag (job).
Bemerkung Absetzen eines Auftrags an EDIABAS, ohne Warten auf

Beendigung der Auftragsbearbeitung.
Das Argument ecu wird zuerst wie der Name einer
Variantenbeschreibungsdatei behandelt. Bei
Nichtvorhandensein dieser Datei (ecu.prg) erfolgt die
Behandlung als Gruppenbeschreibungsdatei (ecu.grp).
Rückgabewert -
Siehe auch apiJobData, apiJobExt
23
apiJobData
void apiJobData ( const char *ecu, const char *job, const unsigned
char *parabuf,int paralen, const char *result )
Beschreibunsdatei (max. APIMAXNAME)
job Abzusetzender Auftrag, der Auftragsname ist in der
parabuf Auftragsparameter (max. APIMAXPARA) als binäre Daten. Die
Parameterdaten sind abhängig vom jeweiligen Auftrag (job).
paralen Anzahl der Datenbytes des Auftragsparameters.
anzugeben.
Bemerkung siehe apiJob
Rückgabewert -
Siehe auch apiJob, apiJobExt
24
apiJobExt
void apiJobExt ( const char *ecu, const char *job, const unsigned
char *stdpara,int stdparalen, const unsigned char
*para, int paralen, const char *result, long
reserved ))
Beschreibunsdatei (max. APIMAXNAME)
job Abzusetzender Auftrag, der Auftragsname ist in der
stdpara Auftragsparameter (max. APIMAXSTDPARA) an die
Standardjobs Initialisierung, Identifikation,
Ende. Die Parameterdaten sind abhängig vom jeweiligen
Auftrag (job).
stdparalen Anzahl der Datenbytes des Auftragsparameters.für die
Standardjobs
para Auftragsparameter (max. APIMAXPARA) als binäre Daten. Die
Parameterdaten sind abhängig vom jeweiligen Auftrag (job).
paralen Anzahl der Datenbytes des Auftragsparameters.
anzugeben.
reserved 0, reserviert für Erweiterungen.
Bemerkung siehe apiJob, apiJobData
Rückgabewert -
Siehe auch apiJob, apiJobData
25
apiJobInfo
Kurzbeschreibung Abfragen des Abarbeitungsgrads eines Jobs
int apiJobInfo (char *infoText)

infoText NULL oder Adresse der Puffervariable im
Anwendungsprogramm
Bemerkung Diese Funktion liefert den Abarbeitungsgrad eines Jobs in

Prozent. Diese Funktion muß in der Beschreibungsdatei
unterstützt werden. Ist dies nicht der Fall, dann liefert diese
Funktion -1 als Ergebnis (d.h. der Abarbeitungsgrad ist
undefiniert).
Wertebereich: 0 ... 100 [%]
Die Funktion apiJobInfo ermöglicht zudem die optionale

Abfrage eines abarbeitungsspezifischen Infotextes. Diese
Funktion muß in der Beschreibungsdatei unterstützt werden.
APIMAXTEXT ist die maximal mögliche Länge des Infotextes

und die somit empfohlene Puffergröße der Zielvariable.
Bei Übergabe des Funktionsparameterwerts NULL wird keine

zusätzliche Infotext-Abfrage durchgeführt.
Rückgabewert Abarbeitungsgrad in Prozent
Siehe auch -
26
apiResultBinary
Kurzbeschreibung Ermittlung eines APIBINARY-Ergebnisses
APIBOOL apiResultBinary ( APIBINARY *buf, APIWORD *buflen, const

char *result, APIWORD set)
buf Adresse der Puffer-Zielvariable im Anwendungsprogramm

buflen Adresse der Längen-Zielvariable im Anwendungsprogramm
result Abzufragendes Ergebnis
set Ergebnissatznummer
Bemerkung Ermittlung eines APIBINARY-Ergebnisses. Bei noch nicht

abgeschlossener Auftragsbearbeitung wird auf dessen
Beendigung gewartet.
Das gesuchte Ergebnis result wird aus dem Ergebnissatz set
des Ergebnisfeldes ausgelesen und in die Zielvariable buf im
Anwendungsprogramm kopiert.Die Anzahl der kopierten Bytes
wird in die Zielvariable buflen kopiert. APIMAXBINARY ist die
maximale Anzahl der kopierten Zeichen vom Typ APIBINARY
und somit die empfohlene Puffergröße der Puffer-Zielvariablen.
Liegt das Ergebnis nicht im APIBINARY-Format vor, so erfolgt
keine Konvertierung in das APIBINARY-Format.
Der Fehlerstatus wird beeinflußt.
Rückgabewert APITRUE Ergebnis vorhanden

APIFALSE Auftrag fehlerhaft oder Ergebnis nicht
vorhanden
Siehe auch apiResultChar apiResultByte apiResultInt apiResultWord

apiResultLong apiResultDWord apiResultReal
apiResultText
27
apiResultByte
Kurzbeschreibung Ermittlung eines APIBYTE-Ergebnisses
APIBOOL apiResultByte ( APIBYTE *buf, const char *result, APIWORD

set )
buf Adresse der Zielvariable im Anwendungsprogramm

Bemerkung Ermittlung eines APIBYTE-Ergebnisses. Bei noch nicht

Beendigung gewartet. Das gesuchte Ergebnis result wird aus
dem Ergebnissatz set des Ergebnisfeldes ausgelesen und in
die Zielvariable buf des Anwendungsprogramms kopiert. Liegt
das Ergebnis nicht im APIBYTE-Format vor, besteht aber die
Möglichkeit einer Typumwandlung, so erfolgt die Konvertierung
in das APIBYTE-Format. Der Fehlerstatus wird beeinflußt.

vorhanden
Siehe auch apiResultChar apiResultInt apiResultWord apiResultLong

apiResultDWord apiResultReal apiResultText
apiResultBinary
28
apiResultChar
Kurzbeschreibung Ermittlung eines APICHAR-Ergebnisses
APIBOOL apiResultChar ( APICHAR *buf, const char *result,

APIWORD set )

Bemerkung Ermittlung eines APICHAR-Ergebnisses. Bei noch nicht

die Zielvariable buf des Anwendungsprogramm kopiert. Liegt
das Ergebnis nicht im APICHAR-Format vor, besteht aber die
in das APICHAR-Format. Der Fehlerstatus wird beeinflußt.
Rückgabewert Erfolg von Ergebnisabfrage
APITRUE Ergebnis vorhanden

APIFALSE Auftrag fehlerhaft oder Ergebnis nicht vorhanden
Siehe auch apiResultByte apiResultInt apiResultWord apiResultLong

apiResultBinary
29
apiResultDWord
Kurzbeschreibung Ermittlung eines APIDWORD-Ergebnisses
APIBOOL apiResultDWord ( APIDWORD *buf, const char *result,

APIWORD set )

Bemerkung Ermittlung eines APIDWORD-Ergebnisses. Bei noch nicht

das Ergebnis nicht im APIDWORD-Format vor, besteht aber die
in das APIDWORD-Format. Der Fehlerstatus wird beeinflußt.
Visual Basic: Ist das Ergebnis >= 2^31 (2147483648), so wird
ein negativer Wert abgelegt.

vorhanden

apiResultLong apiResultReal apiResultText
apiResultBinary
30
apiResultFormat
Kurzbeschreibung Ermittlung des Formats eines Ergebnisses
APIBOOL apiResultFormat ( APIRESULTFORMAT *buf, const char

*result, APIWORD set )

Bemerkung Ermittlung des Formats eines Ergebnisses. Bei noch nicht

abgeschlossener Auftragbearbeitung wird auf dessen
Beendigung gewartet. Das Format des gesuchten Ergebnisses
result wird aus dem Ergebnissatz set des Ergebnisfeldes
ausgelesen und in die Zielvariable buf des Anwendungs-
programms kopiert.
Folgende Ergebnisformate sind möglich:
APIFORMAT_CHAR
APIFORMAT_BYTE
APIFORMAT_INTEGER
APIFORMAT_WORD
APIFORMAT_LONG
APIFORMAT_DWORD
APIFORMAT_TEXT
APIFORMAT_BINARY
APIFORMAT_REAL
Der Fehlerstatus wird beeinflußt.

vorhanden
Siehe auch apiResultName apiResultNumber apiResultSets

apiResultVar
31
apiResultInt
Kurzbeschreibung Ermittlung eines APIINTEGER-Ergebnisses
APIBOOL apiResultInt ( APIINTEGER *buf, const char *result,

APIWORD set )

Bemerkung Ermittlung eines APIINTEGER-Ergebnisses. Bei noch nicht

das Ergebnis nicht im APIINTEGER-Format vor, besteht aber
die Möglichkeit einer Typumwandlung, so erfolgt die
Konvertierung in das APIINTEGER-Format. Der Fehlerstatus
wird beeinflußt.

vorhanden
Siehe auch apiResultChar apiResultByte apiResultWord apiResultLong

apiResultBinary
32
apiResultLong
Kurzbeschreibung Ermittlung eines APILONG-Ergebnisses
APIBOOL apiResultLong ( APILONG *buf, const char *result,

APIWORD set )

Bemerkung Ermittlung eines APILONG-Ergebnisses. Bei noch nicht

das Ergebnis nicht im APILONG-Format vor, besteht aber die
in das APILONG-Format. Der Fehlerstatus wird beeinflußt.

vorhanden

apiResultBinary
33
apiResultName
Kurzbeschreibung Ermittlung des Ergebnisnamens
APIBOOL apiResultName ( char *buf, APIWORD index, APIWORD set )

index Ergebnisindex
Bemerkung Ermittlung des Ergebnisnamens unter Angabe des

Ergebnisindex und Ergebnissatzes. Bei noch nicht
Beendigung gewartet. Der Ergebnisname wird entsprechend
des vorgegebenen Ergebnisindex index (beginnend mit 1)
sowie des Ergebnissatzes set des Ergebnisfeldes ermittelt und
in die Zielvariable buf des Anwendungsprogrammes kopiert.
APIMAXNAME ist die maximale Anzahl der kopierten Zeichen
und die somit empfohlene Puffergröße der Zielvariablen. Der

APIFALSE Auftrag fehlerhaft oder keine Ergebnisse
vorhanden
Siehe auch apiResultFormat apiResultNumber apiResultSets

apiResultVar
34
apiResultNumber
Kurzbeschreibung Ermittlung der Anzahl von Ergebnissen
APIBOOL apiResultNumber ( APIWORD *buf, APIWORD set )

Bemerkung Ermittlung der Anzahl der vorliegenden Ergebnisse eines

Ergebnissatzes. Bei noch nicht abgeschlossener
Auftragsbearbeitung wird auf dessen Beendigung gewartet. Die
Anzahl der Ergebnisse wird entsprechend des vorgegebenen
Ergebnissatzes set des Ergebnisfeldes ermittelt und in die
Zielvariable buf des Anwendungsprogrammes kopiert. Der

APIFALSE Auftrag fehlerhaft oder keine Ergebnisse
vorhanden
Siehe auch apiResultFormat apiResultName apiResultSets

apiResultVar
35
apiResultReal
Kurzbeschreibung Ermittlung eines APIREAL-Ergebnisses
APIBOOL apiResultReal ( APIREAL *buf, const char *result, APIWORD

set )

set Ergebnissatz
Bemerkung Ermittlung eines APIREAL-Ergebnisses. Bei noch nicht

das Ergebnis nicht im APIREAL-Format vor, besteht aber die
in das APIREAL-Format. Der Fehlerstatus wird beeinflußt.

vorhanden

apiResultLong apiResultDWord apiResultText
apiResultBinary
36
apiResultsDelete
Kurzbeschreibung Löschen eines applikationseigenen Ergebnisfeldes.
void apiResultsDelete ( APIRESULTFIELD field )
field Referenz auf das zu löschende Ergebnisfeld
Bemerkung -
Rückgabewert -
Siehe auch apiResultsNew apiResultsScope
37
apiResultSets
Kurzbeschreibung Vereinfachte Ermittlung der Anzahl von Ergebnissätzen
APIBOOL apiResultSets ( APIWORD *sets )
sets Adresse der Zielvariable im Anwendungsprogramm
Bemerkung Vereinfachte Ermittlung der Anzahl von Ergebnissätzen (des

letzten Auftrags). Bei noch nicht abgeschlossener
Auftragsbearbeitung wird auf dessen Beendigung gewartet. Die
Anzahl der Ergebnissätze wird ermittelt, und in die Zielvariable
sets im Anwendungsprogramm kopiert. Das Ergebnis ist auch
mit mit apiResultWord(sets,"SAETZE",0) ermittelbar. Der

vorhanden
Siehe auch apiResultFormat apiResultName apiResultNumber

apiResultVar
38
apiResultsNew
Kurzbeschreibung Dynamisches Anlegen einer Kopie des aktuellen

Ergebnisfeldes.
APIRESULTFIELD apiResultsNew ( )
Bemerkung Dynamisches Anlegen einer Kopie des aktuellen

Ergebnisfeldes. Vom aktuellen Ergebnisfeld kann immer nur
eine Kopie erzeugt werden. Bei noch nicht abgeschlossener
Auftragsbearbeitung wird auf dessen Beendigung gewartet. Der
Rückgabewert Referenz auf angelegte Ergebnisfeldkopie oder NULL im

Fehlerfall
Siehe auch apiResultsDelete apiResultsScope
39
apiResultsScope
Kurzbeschreibung Umschalten auf ein applikationseigenes Ergebnisfeld.
void apiResultsScope ( APIRESULTFIELD field )
field Referenz auf das umzuschaltendde Ergebnisfeld
Bemerkung Umschalten auf ein applikationseigenes Ergebnisfeld. Die

Bindung an dieses Ergebnisfeld besteht bis zum nächsten
Auftrag oder apiResultsScope -Funktionsaufruf.
Rückgabewert -
Siehe auch apiResultsDelete apiResultsNew
40
apiResultText
Kurzbeschreibung Ermittlung eines APITEXT-Ergebnisses
APIBOOL apiResultText ( APITEXT *buf, const char *result, APIWORD

set, const char *format )

format Wunschformat des Ergebnisses (max. APIMAXNAME), zur
Durchführung der Default-Konvertierung ist ein Leer-String
anzugeben.
Bemerkung Ermittlung eines APITEXT-Ergebnisses. Bei noch nicht

die Zielvariable buf des Anwendungsprogrammes kopiert.
APIMAXTEXT ist die maximale Anzahl der kopierten Zeichen
vom Typ APITEXT und die somit empfohlene Puffergröße der
Zielvariable. Bei Überschreitung der Puffergröße wird das
Ergebnis auf APIMAXTEXT begrenzt. Durch die
Konvertierungsanweisung format besteht die Möglichkeit der
Ergebnisumwandlung in das APITEXT-Format. Stellt das
Argument format hingegen einen Leer-String dar, so erfolgt eine
Default-Konvertierung. Der Fehlerstatus wird beeinflußt.

vorhanden

apiResultLong apiResultDWord apiResultReal
apiResultBinary
41
apiResultVar
Kurzbeschreibung Ermittlung des Namens der geladenen SGBD
APIBOOL apiResultVar ( APITEXT *ecu )
ecu Adresse von Steuergeräte-Varianten-Puffer
Bemerkung Ermittlung des Namens der geladenen SGBD des letzten

Auftrags. Bei noch nicht abgeschlossener Auftragsbearbeitung
wird auf dessen Beendigung gewartet. Der Name wird ermittelt
und in die Zielvariable ecu im Anwendungsprogramm kopiert.
Der Name ist im Systemergebnissatz (Ergebnissatz 0) als
Ergebnis VARIANTE abgelegt. Das Ergebnis ist auch mit mit
apiResultText(ecu,"VARIANTE",0,"") ermittelbar. Die Größe
des von API kopierten APITEXT-Ergebnisses kann die
maximale Länge eines Dateinamens betragen. Der Fehlerstatus
wird beeinflußt.

vorhanden
Siehe auch apiResultFormat apiResultName apiResultNumber

apiResultSets
42
apiResultWord
Kurzbeschreibung Ermittlung eines APIWORD-Ergebnisses
APIBOOL apiResultWord ( APIWORD *buf, const char *result,

APIWORD set )

set Ergebnissatz
Bemerkung Ermittlung eines APIWORD-Ergebnisses. Bei noch nicht

das Ergebnis nicht im APIWORD-Format vor, besteht aber die
in das APIWORD-Format. Der Fehlerstatus wird beeinflußt.
Visual Basic: Ist das Ergebnis >= 2^15 (32768), so wird ein
negativer Wert abgelegt.

vorhanden
Siehe auch apiResultChar apiResultByte apiResultInt apiResultLong

apiResultBinary
43
apiSetConfig
Kurzbeschreibung Änderung der EDIABAS-Konfiguration
APIBOOL apiSetConfig ( const char *config, const char *value )
config Zu änderndes Konfigurationselement

value Neue Konfigurationseinstellung
Bemerkung: Änderung des Konfigurationselements config durch Angabe der

neuen Konfigurationseinstellung value. Die
Konfigurationsänderung ist bis zum Abbruch von API gültig.
Der Fehlerstatus wird nicht beeinflußt.
Alle Konfigurationselemente und deren Einstellungen sind in [4]
beschrieben.
Rückgabewert APITRUE Konfiguration geändert

APIFALSE Konfigurationsänderung fehlerhaft
Siehe auch apiGetConfig
44
apiState
Kurzbeschreibung Ermittlung des aktuellen Zustands der Auftragsbearbeitung
int apiState ( )
Bemerkung: Der Fehlerstatus wird beeinflußt.
Rückgabewert Bearbeitungszustand
APIBUSY Auftrag wird noch bearbeitet
APIREADY Auftrag ist abgearbeitet
APIBREAK Auftrag wurde abgebrochen
APIERROR Auftrag war fehlerhaft
Siehe auch apiBreak apiEnd apiInit apiInitExt apiCallBack

apiSwitchDevice
45
apiSwitchDevice
Kurzbeschreibung Device-Wechsel
APIBOOL apiSwitchDevice ( const char *deviceConnection,

const char *deviceApplication )
deviceConnection Device-Anschluß (max. APIMAXDEVICE),
voreingestellter Anschluß bei Übergabe eines Leer-
Strings
deviceApplication Device-Applikation (max. APIMAXDEVICE),
voreingestellte Applikation bei Übergabe eines
Leer-Strings
Bemerkung: Device-Wechsel durch Angabe des neuen Device-Anschlusses

und der Device-Applikation. Das neue Device ist bis gültig bis
zum Aufruf von apiEnd(), apiInit oder apiInitExt(). Der
Rückgabewert APITRUE Device gewechselt

APIFALSE Device-Wechsel fehlerhaft
Siehe auch apiBreak apiEnd apiInit apiState apiCallBack
46
5. Sonstige Funktionen
Hinweis: Die in diesem Kapitel beschriebenen Funktionen sind nur im BMW-

Lieferumfang für MS-WINDOWS enthalten!
enableServer
Kurzbeschreibung Umschaltung zwischen Serverbetrieb und Parallelbetrieb
BOOL enableServer ( BOOL onOff )
onOff Neue Betriebsart:

TRUE Serverbetrieb
FALSE Parallelbetrieb
Bemerkung Mit der Funktion kann zwischen Serverbetrieb und

Parallelverarbeitung umgeschalten werden. Zum Zeitpunkt der
Umschaltung darf KEINE Anwendung bei EDIABAS
angemeldet sein, d.h. die Umschaltung darf nicht zwischen
apiInit()/apiInitExt() und apiEnd() einer Anwendung erfolgend.
Die Funktion ist unter MS-WINDOWS verfügbar, eine
Umschaltung zwischen Serverbetrieb und Parallelbetrieb jedoch
nur unter WIN32 mit installiertem EDIABAS-Server möglich.
Rückgabewert TRUE Umschaltung ist erfolgt

FALSE Umschaltung ist nicht erfolgt, da die
gewünschte Betriebsart nicht unterstützt wird
Siehe auch closeServer
47
closeServer
Kurzbeschreibung Beendigung des EDIABAS-Servers
void closeServer ( )
Bemerkung Die Funktion beendet den laufenden EDIABAS-Server.
Rückgabewert -
Siehe auch enableServer
48
enableMultiThreading
Kurzbeschreibung Umschaltung in Multi-Threading-Betrieb
BOOL enableMultiThreading (onOff )
onOff Neue Betriebsart:

TRUE Multi-Threading-Betrieb
Bemerkung Mit der Funktion kann vom Single-Threading-Betrieb (Standard)

in den Multi-Threading-Betrieb umgeschalten werden. Zum
Zeitpunkt der Umschaltung darf noch KEINE Anwendung bei
EDIABAS angemeldet sein, d.h. die Umschaltung muss VOR
dem ersten Aufruf von apiInit()/apiInitExt() einer Anwendung
erfolgen. Die Funktion ist unter MS-WINDOWS verfügbar, eine
Umschaltung jedoch nur unter WIN32 mit installiertem
EDIABAS-Server möglich.
Rückgabewert TRUE Umschaltung ist erfolgt

FALSE Umschaltung ist nicht erfolgt, da die
gewünschte Betriebsart nicht unterstützt wird
Siehe auch closeServer
49
A. LITERATURVERZEICHNIS
[1] EDIABAS: Fehlerreferenz
[2] EDIABAS: BEST/1 - Sprache und Interpreter
[3] EDIABAS: Transparentmode
[4] EDIABAS: Benutzerhandbuch
[5] EDIABAS: API-Schnittstellenbeschreibung
[6] EDIABAS: API-Benutzerhandbuch
50
B. INDEX
apiResultName 34
apiResultNumber 35
APIBINARY 8 apiResultReal 36
APIBOOL 7 apiResultsDelete 37
apiBreak 13 apiResultSets 38
APIBREAK 45 apiResultsNew 39
APIBUSY 9, 45 apiResultsScope 40
APIBYTE 7 apiResultText 41
apiCallBack 14 apiResultVar 42
APIDWORD 7 apiResultWord 43
apiEnd 15 apiSetConfig 44
APIERROR 45 apiState 45
apiErrorCode 16 apiSwitchDevice 46
apiErrorHandler 17 APITEXT 7
apiErrorText 18 APIWORD 7
apiGetConfig 19
apiInit 20 closeServer 48
apiInitExt 21
APIINTEGER 7 Datentypen 7
apiJob 23 Device-Anschluß 20
apiJobData 24 Device-Applikation 20, 21
apiJobExt 25 Device-Name 21
apiJobInfo 26
APIMAXBINARY 9 EDIABAS_ERR_NONE 11
APIMAXCONFIG 9 enableMultiThreading 49
APIMAXDEVICE 9 enableServer 47
APIMAXFILENAME 9
APIMAXNAME 9 Fehlercode 10
APIMAXPARA 9 Fehlersymbol 10
APIMAXRESULT 9 Fehlertext 10
APIMAXSTDPARA 9
APIMAXTEXT 9 Interfacehandler 21
APIREADY 45
APIREAL 7 Konstante 9
apiResultBinary 27
apiResultByte 28 Multi-Threading-Betrieb 49
apiResultChar 29
apiResultDWord 30 Parallelverarbeitung 47
APIRESULTFIELD 8
apiResultFormat 31 Serverbetrieb 47
apiResultInt 32 Single-Threading-Betrieb 49
apiResultLong 33
51

ApiRef PDF

Cargado por

Información del documento

Título original

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

ApiRef PDF

Cargado por

Copyright:

Formatos disponibles

EDIABAS — API-FUNKTIONSREFERENZ

Copyright BMW AG, created by Softing AG

3. Datentypen, Konstanten und Fehlermeldungen..................................7

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 API-Funktionen apiResultByte/apiResultChar unter VB 4.0 verfügbar

Version 6 Neue API-Funktion apiInitExt unter Ergänzung zu apiJobInfo

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

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

Version 6c Ergänzungen für Windows CE

Version 6d Ergänzungen für .NET Compact Framework und MultiThreading/Win32

2.1. Über diese Dokumentation

Diese Dokumentation beschreibt die Konstanten und Funktionen, die in der

Diese Dokumentation verwendet die folgenden typographischen Konventionen:

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

2.3. Besonderheiten, Begriffe, Akronyme

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

3. Datentypen, Konstanten und Fehlermeldungen

Folgende Datentypen werden von API verwendet:

API-Datentyp C/C++ Visual Basic- C# Verwendung

APIBOOL enum, Werte: VB 3.0/4.0/6.0: bool Rückgabewert

Neben den einfachen Datentypen ist noch der komplexe Datentyp

Variable des Datentyps APIRESULTFIELD können wie Variable einfachen

Unter Visual Basic und C# sind die API-Datentypen nicht verfügbar.

Folgende Konstanten werden von API zur Verfügung gestellt:

APIMAXCONFIG Maximale und empfohlene Größe von Puffer für

APIMAXDEVICE Maximale Länge der Device-Argumente Anschluß und

APIMAXNAME Maximale Länge der Job-Argumente Steuergerät und

APIMAXSTDPARA Maximale Länge des Job-Arguments Parameter für

APIMAXPARA Maximale Länge des Job-Arguments Parameter

APIMAXRESULT Maximale Länge von Job-Ergebnis Ergebnis (incl.

APIMAXTEXT Maximale und empfohlene Größe von APITEXT-

APIMAXBINARY Maximale und empfohlene Größe von APIBINARY-

APIMAXFILENAME Maximale und empfohlene Größe von Dateinamen (incl.

APIBUSY BUSY-Status von EDIABAS

APIREADY READY-Status von EDIABAS

APIBREAK BREAK-Status von EDIABAS

APIERROR ERROR-Status von EDIABAS

EDIABAS_XXX_#### Fehlermeldungen (siehe Kap. "Fehlermeldungen")

Eine EDIABAS Fehlermeldung besteht aus folgenden Komponenten:

Fehlersymbol (Fehlerursprung, Fehlernummer)

Die Fehlersymbole sind in API.H definiert.

Das Fehlersymbol eines jeden Fehlers hat folgenden Aufbau:

Die Zeichengruppe XXX benennt den EDIABAS-internen Ursprungsbereich des

Fehler- bzw. Programmbereiche:

EDIABAS_BIP_#### BEST-Interpreter, Laufzeitsystem

EDIABAS_SYS_#### Ablaufsteuerung, Laufzeitsystem

EDIABAS_NET_#### Netzwerk, Laufzeitsystem

Eine Ausnahme bildet hierbei der Pseudo-Fehler EDIABAS_ERR_NONE

Die folgenden Seiten beschreiben die API-Funktionen in alphabetischer Reihenfolge.

Die Beschreibung einer Funktion ist in folgende Abschnitte gegliedert:

 Kurzbeschreibung. Faßt die Wirkung der Funktion kurz zusammen, illustriert

 Bemerkung. Gibt eine detaillierte Beschreibung der Funktion und deren

 Rückgabewert. Beschreibt den Wert, der von der Funktion zurückgegeben

 Anbindung. Listet die Anbindungen auf, welche die Funktion

 Siehe auch. Zeigt verwandte Funktionen auf.

Kurzbeschreibung Abbruch der gerade laufenden Auftragsbearbeitung

Bemerkung Die laufende Auftragsbearbeitung kann mit der Funktion

Anbindung C/C++ Visual Basic C# DLL

Siehe auch apiEnd apiInit apiInitExt apiState apiCallBack

Kurzbeschreibung Installation einer Call-Back-Routine im Anwendungsprogramm

void apiCallBack ( APIBOOL (*action)() )

Kurzbeschreibung. Faßt die Wirkung der Funktion kurz zusammen, illustriert

Bemerkung. Gibt eine detaillierte Beschreibung der Funktion und deren

Rückgabewert. Beschreibt den Wert, der von der Funktion zurückgegeben

Anbindung. Listet die Anbindungen auf, welche die Funktion

Siehe auch. Zeigt verwandte Funktionen auf.

APIBOOL apiGetConfig ( const char config, char buf )

APIBOOL apiResultBinary ( APIBINARY buf, APIWORD buflen, const