EDIABAS — API-BENUTZERHANDBUCH

EDIABAS
Elektronik Diagnose Basissystem

API-BENUTZERHANDBUCH

VERSION 6d

Copyright BMW AG, created by Softing AG

APIUSER.DOC
EDIABAS — API-BENUTZERHANDBUCH

INHALT

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

1. Änderungshistorie ..............................................................................................3

2. Einführung ...........................................................................................................4
2.1. Über diese Dokumentation...................................................................4
2.2. Konventionen .......................................................................................4
2.3. Besonderheiten, Begriffe, Akronyme....................................................5
2.4. Warenzeichen ......................................................................................5

3. Allgemeines .........................................................................................................6
3.1. API-Include-Datei .................................................................................6
3.2. API-Bibliothek.......................................................................................7

4. Benutzung von Include-Datei und Bibliothek ...................................................8

4.1. WIN32/16/CE-Anwendungsprogramme ...............................................8
4.1.1. Microsoft Visual C++ 6.0 ..................................................................8
4.1.2. Microsoft Visual C++ 1.52 ................................................................8
4.1.3. Microsoft Visual Basic 6.0, 4.0, 3.0 ..................................................9
4.1.4. Microsoft eMbedded Visual C++ 4.0 SP2, 3.0 .................................9
4.1.5. Microsoft .NET Compact Framework 1.1 .........................................10
4.1.6. DLL-Schnittstelle ..............................................................................11
4.2. SCO-UNIX-Anwendungsprogramme....................................................12
4.3. QNX-Anwendungsprogramme .............................................................12

A. LITERATURVERZEICHNIS..................................................................................14

B. INDEX ...................................................................................................................15

2
EDIABAS — API-BENUTZERHANDBUCH

1. Änderungshistorie

Version 3.0 Erstellung

Version 4.1 Überarbeitung für EDIABAS V4.1.0

Version 5 Überarbeitung für EDIABAS V5.1.0

Version 5a Beschreibung von Borland C 4.5 Anbindung

Version 5b Beschreibung von Visual Basic 4.0 Anbindung

Version 5c Überarbeitung für WIN32 Anbindung

Version 5d Erweitert für QNX

Version 6 EDIABAS V6.0.0

Version 6a Keine Unterstützung mehr für DOS

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

Version 6c Erweitert für Windows CE / eMbedded Visual C++

Version 6d Erweitert für .NET Compact Framework

3
EDIABAS — API-BENUTZERHANDBUCH

2. Einführung

2.1. Über diese Dokumentation

Diese Dokumentation beschreibt die Erstellung und Wartung von

Anwendungsprogrammen mit Zugriff auf das Elektronik Diagnose Basissystem
(EDIABAS). Es werden die Benutzung und die Optionen der Tools erklärt. Eine
allgemeine Beschreibung der Schnittstelle befindet sich in [3]. Eine detaillierte
Beschreibung aller API-Funktionen finden Sie in [4]. 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.

4
EDIABAS — API-BENUTZERHANDBUCH

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".

2.4. Warenzeichen

Microsoft, MS, MS-DOS, Windows, WIN32, Pocket PC, Visual C++ und Visual Basic
sind registrierte Warenzeichen der Microsoft Corporation.

SCO, SCO UNIX und OpenServer sind registrierte Warenzeichen der Santa Cruz
Operation, Inc.

QNX ist registriertes Warenzeichen der QNX Software Systems Ltd.

ARM ist registriertes Warenzeichen der ARM Ltd.

5
EDIABAS — API-BENUTZERHANDBUCH

3. Allgemeines

Die Programmierschnittstelle API des EDIABAS zeigt sich dem

Anwendungsprogramm als eine Sammlung von Funktionen, den API-Funktionen. Als
Programmiersprache ist ANSI C vorgesehen.

Für die EDIABAS-Zielsysteme gibt es von SOFTING vorgefertigte API-Bibliotheken,

welche zu den Anwendungsprogrammen hinzugebunden werden müssen.

Alle notwendigen Dateien zur Erstellung von Anwendungsprogrammen mit Zugriff auf
EDIABAS befinden sich auf der Diskette APPLICATION DEVELOPMENT KIT.

3.1. API-Include-Datei

Um eine API-Funktion in einem Anwendungsprogramm aufrufen zu können, benötigt

der C/C++ Compiler den Prototypen der entsprechenden API-Funktion. Die
Prototypen aller API-Funktionen befinden sich in der Include-Datei API.H. Neben den
Prototypen sind in der Include-Datei auch alle für das Anwendungsprogramm
notwendigen Konstanten und Typdefinitionen, die EDIABAS benutzt, enthalten.

Anweisung zum Einbinden der Include-Datei API.H in einer C Quelldatei:

#include "api.h"

Anweisungen zum Einbinden der Include-Datei API.H in einer C++ Quelldatei:

extern "C" {
#include "api.h"
}

Diese Anweisungen sind in jeder C/C++ Quelldatei des Anwendungsprogramms

anzugeben, in welcher API-Funktionen aufgerufen oder Konstanten bzw.
Typdefinitionen von API.H benötigt werden.

Damit der C/C++ Compiler die Include-Datei findet, ist der Suchpfad von API.H
anzugeben. Die entsprechende Compiler-Option ist Compiler-abhängig und der
Beschreibung des verwendeten Compilers zu entnehmen.

6
EDIABAS — API-BENUTZERHANDBUCH

3.2. API-Bibliothek

Alle API-Funktionen eines Zielsystems befinden sich in einer Bibliothek. Während

des Link-Vorgangs ist dann diese Bibliothek dem Linker zum Einbinden anzugeben.
Dies ist Linker-abhängig und wird überlicherweise in einer Make-Datei
vorgenommen.

7
EDIABAS — API-BENUTZERHANDBUCH

4. Benutzung von Include-Datei und Bibliothek

4.1. WIN32/16/CE-Anwendungsprogramme

SOFTING unterstützt folgende Entwicklungsumgebungen zur Erstellung von

Anwendungsprogrammen mit EDIABAS-Zugriff:

„ Microsoft Visual C++ 6.0 (WIN32)

„ Microsoft Visual C++ 1.52 (WIN16)
„ Microsoft Visual Basic 6.0 (WIN32)
„ Microsoft Visual Basic 4.0 (WIN32 und WIN16)
„ Microsoft Visual Basic 3.0 (WIN16)
„ Microsoft eMbedded Visual C++ 4.0 SP2 (WINCE 4.2)
„ Microsoft eMbedded Visual C++ 3.0 (WINCE 3.0)
„ Microsoft Visual C#.NET + .NET Compact Framework 1.1 (WINCE 4.2)
„ Microsoft Visual Basic.NET + .NET Compact Framework 1.1 (WINCE 4.2)

Die Include-Datei API.H befindet sich im EDIABAS-Verzeichnis API.

4.1.1.Microsoft Visual C++ 6.0

Für jede Quelldatei mit Zugriff auf API-Funktionen ist der Compiler neben den
projektspezifischen Compiler-Optionen mit folgender Compiler-Option aufzurufen:

/I<Pfad von api.h>

Die Compiler-Option /I legt den Suchpfad für API.H fest.

Microsoft Visual C++ 6.0 wird für Single- und Multi-Thread-Betrieb unterstützt, die
API-Bibliotheken APIW32.LIB (Single-Thread) und APIW32MT.LIB (Multi-Thread)
befinden sich im EDIABAS-Verzeichnis API\WIN32.

Beispiel zur Erstellung eines Anwendungsprogramms BEISPIEL.EXE:

cl /Ic:\ediabas\api beispiel.c /link

c:\ediabas\api\win32\apiw32.lib

4.1.2.Microsoft Visual C++ 1.52

Für jede Quelldatei mit Zugriff auf API-Funktionen ist der Compiler neben den
projektspezifischen Compiler-Optionen mit folgenden Compiler-Optionen aufzurufen:

8
EDIABAS — API-BENUTZERHANDBUCH

/AL /G2 /GA /I<Pfad von api.h>

Die Compiler-Option /I legt den Suchpfad für API.H, die Compiler-Option /AL das
Speichermodell LARGE und die Compiler-Optionen /G2 /GA die Generierung fest.

Microsoft Visual C++ 1.52 wird im Speichermodell LARGE unterstützt, die API-
Bibliothek APIW.LIB befindet sich im EDIABAS-Verzeichnis API\WIN.

Beispiel zur Erstellung eines Anwendungsprogramms BEISPIEL.EXE:

cl /AL /G2 /GA /Ic:\ediabas\api beispiel.c /link

c:\ediabas\api\win\apiw.lib

4.1.3.Microsoft Visual Basic 6.0, 4.0, 3.0

Durch Aufnahme des Moduls API.BAS in ein Visual Basic Projekt kann das
entsprechende Anwendungsprogramm auf EDIABAS zugreifen.

Das Modul API.BAS bietet eine im Funktionsumfang eingeschränkte API-Schnittstelle

und befindet sich in folgenden EDIABAS-Verzeichnissen:
„ API\WIN32\VB60 (für Visual Basic 6.0)
„ API\WIN32\VB40 (für Visual Basic 4.0)
„ API\WIN16\VB40 (für Visual Basic 4.0)
„ API\WIN16\VB30 (für Visual Basic 3.0)

Zur Laufzeit wird für den Zugriff auf EDIABAS die im RUNTIME SYSTEM enthaltene
APIVB.DLL (WIN16) bzw. APIVB32.DLL (WIN32) benötigt.

4.1.4.Microsoft eMbedded Visual C++ 4.0 SP2, 3.0

Für jede Quelldatei mit Zugriff auf API-Funktionen ist der Compiler neben den
projektspezifischen Compiler-Optionen mit folgender Compiler-Option aufzurufen:

/I<Pfad von api.h>

Die Compiler-Option /I legt den Suchpfad für API.H fest.

Microsoft eMbedded Visual C++ wird nur für die Plattformen Pocket PC 2002 und
2003 unterstützt (API-Bibliothek APICE.LIB):
„ APICE.LIB / Windows CE 4.2 (für eMbedded Visual C++ 4.0 SP2)
„ APICE.LIB / Windows CE 3.0 (für eMbedded Visual C++ 3.0)

9
EDIABAS — API-BENUTZERHANDBUCH

4.1.5.Microsoft .NET Compact Framework 1.1

Der API-Zugriff für das .NET Compact Framework wird nur für die Plattform Pocket
PC 2003 unterstützt.

Das Assembly apiNET.dll stellt die API-Schnittstelle für .NET Smart Device
Applications. Hier werden alle Zugriffe von .NET Smart Device Applications
("Managed Code") in die entsprechenden EDIABAS-Aufrufe ("Unmanaged Code")
umgesetzt und die Abbildung der DLL-Schnittstelle von apiCE.dll vorgenommen.

Das Assembly apiNET.dll enthält neben dem Programmcode bereits alle notwendige
API-Deklaration/Definitionen.

Das Assembly apivbNET.dll dient zur Behandlung von Microsoft Visual Basic.NET
spezifischen Besonderheiten und setzt diese in entsprechende Aufrufe der Assembly
apiNET.dll um.

API-Zugriff mit Microsoft Visual C#.NET

(Microsoft Visual Studio 2003 mit .NET Compact Framework 1.1)

Bei .NET Smart Device Projekten mit API-Zugriff sind folgende Schritte auf dem
Entwicklungs-PC mit Microsoft Visual C#.NET erforderlich:

„ Kopieren der Assembly apiNET.dll des Lieferpakets auf Entwicklungs-PC

„ Öffnen des Referenzdialogs:
Project | Add Reference...
„ .NET Komponente apiNET.dll auswählen, selektieren und übernehmen

Alle API-Zugriffe müssen über die Klasse Ediabas.API erfolgen. Bei Angabe des
Namespaces Ediabas via using-Anweisung ist nur noch der Klassenname API
anzugeben.

Beispiel für C# Quelldatei mit using-Anweisung (Auszug):

using System;
using Ediabas;

if ( Api.apiInit() ) // API initialisieren

{
//…
Api.apiEnd(); // API beenden
}

10
EDIABAS — API-BENUTZERHANDBUCH

API-Zugriff mit Microsoft Visual Basic.NET

(Microsoft Visual Studio 2003 mit .NET Compact Framework 1.1)

Bei .NET Smart Device Projekten mit API-Zugriff sind folgende Schritte auf dem
Entwicklungs-PC mit Microsoft Visual Basic.NET erforderlich:

„ Kopieren der Assembly apiNET.dll des Lieferpakets auf Entwicklungs-PC

„ Kopieren der Assembly apivbNET.dll des Lieferpakets auf Entwicklungs-PC
„ Kopieren des API-Moduls VB70\API.vb des Lieferpakets auf Entwicklungs-PC
„ Öffnen des Referenzdialogs:
Project | Add Reference...
„ .NET Komponenten apiNET.dll und apivbNET.dll auswählen, selektieren und
übernehmen
„ Aufnahme des Basic-Moduls API.VB in das Projekt:
Project | Add Existing Item

Das Basic-Modul API.VB importiert das Assembly apiNET.dll und verbirgt die via
apivbNET.dll notwendigen Sonderbehandlungen für Visual Basic.NET.

Alle API-Zugriffe müssen über die in API.VB definierte Klasse API erfolgen. Der
Import der Assembly apiNET.dll/apivbNET.dll erfolgt bereits in API.VB und ist in den
Quelldateien der Anwendung nicht mehr vorzunehmen.

Beispiel für Visual Basic.NET Quelldatei (mit Verwendung der API.VB-Klasse):

If API.apiInit() Then ' API initialisieren

'…
call API.apiEnd() ' API beenden
End If

4.1.6.DLL-Schnittstelle
Der Zugriff auf EDIABAS kann auch direkt über die DLL-Schnittstelle von API.DLL
bzw. API32.DLL/APICE.DLL mit jedem hierzu geeigneten Entwicklungswerkzeug
erfolgen. Die DLL-Schnittstelle bietet aber nicht den vollen Funktionsumfang der API-
Schnittstelle.

Die C-Funktionsdeklarationen der DLL-Schnittstelle befinden sich in der Include-

Datei APIDLL.H.

11
EDIABAS — API-BENUTZERHANDBUCH

Die Datei APICALLS.C enthält den Quellcode der Bibliotheken

APIW32.LIB/APICE.LIB und APIW.LIB, womit die komplette API-Funktionalität auch
unter anderen C/C++ Entwicklungswerkzeugen zur Verfügung steht.

Die Dateien APIDLL.H und APICALLS.C befinden sich in den EDIABAS-

Verzeichnissen API\WIN32 bzw. API\WIN.

4.2. SCO-UNIX-Anwendungsprogramme

SOFTING unterstützt den Compiler cc zur Erstellung von Anwendungsprogrammen

mit EDIABAS-Zugriff.

Die Include-Datei API.H befindet sich im Katalog /USR/EDIABAS/API/INCLUDE.

Für jede Quelldatei mit Zugriff auf API-Funktionen ist der Compiler neben den
projektspezifischen Compiler-Optionen mit folgender Compiler-Option zu übersetzen:

-I /usr/ediabas/api/include

Die Compiler-Option -I legt den Suchpfad für API.H fest.

Die API-Bibliothek LIBAPI.A befindet sich im Katalog /USR/EDIABAS/API/LIB.

Beispiel zur Erstellung eines Anwendungsprogramms:

cc -I /usr/ediabas/api/include beispiel.c
/usr/ediabas/api/lib/libapi.a

4.3. QNX-Anwendungsprogramme

SOFTING unterstützt den Compiler cc zur Erstellung von Anwendungsprogrammen

mit EDIABAS-Zugriff.

Die Include-Datei API.H befindet sich im Katalog /USR/EDIABAS/API/INCLUDE.

Für jede Quelldatei mit Zugriff auf API-Funktionen ist der Compiler neben den
projektspezifischen Compiler-Optionen mit folgenden Compiler-Optionen zu
übersetzen:

-j -I /usr/ediabas/api/include

Die Compiler-Option -I legt den Suchpfad für API.H fest.

12
EDIABAS — API-BENUTZERHANDBUCH

Für den Linker ist die API-Bibliothek LIBAPI.A sowie die Bibliothek MQUEUE für den
Message-Queue-Server anzugeben. Die API-Bibliothek LIBAPI.A befindet sich im
Katalog /USR/EDIABAS/API/LIB.

Beispiel zur Erstellung eines Anwendungsprogramms:

cc -j -I /usr/ediabas/api/include beispiel.c
/usr/ediabas/api/lib/libapi.a -l mqueue

13
EDIABAS — API-BENUTZERHANDBUCH

A. LITERATURVERZEICHNIS

[1] EDIABAS: BEST Benutzerhandbuch

[2] EDIABAS: Benutzerhandbuch

[3] EDIABAS: API Schnittstellenbeschreibung

[4] EDIABAS: API Funktionsreferenz

14
EDIABAS — API-BENUTZERHANDBUCH

B. INDEX

—S—
—A— SCO-UNIX 12
api.bas 9
api.dll 12 —T—
API.H 6
api32.dll 12 Typdefinitionen 6
apicalls.c 12
apiCE.dll 12
apidll.h 12
—W—
API-Funktionen 4 Win32/16/CE- 8
apivb.dll 9

—B—
Bibliotheken 6

—D—
DLL-Schnittstelle 12

—E—
EDIABAS 4

—K—
Konstanten 6

—L—
Linker 7

—M—
Make 7
Microsoft .NET Compact Framework 1.1 10
Microsoft eMbedded Visual C++ Version 3.0 9
Microsoft eMbedded Visual C++ Version 4.0 SP2 9
Microsoft Visual Basic 3.0 9
Microsoft Visual Basic 4.0 9
Microsoft Visual Basic 6.0 9
Microsoft Visual C++ Version 1.52 9
Microsoft Visual C++ Version 6.0 8

—P—
Programmiersprache 6

—Q—
QNX 13

15