0% found this document useful (0 votes)

1K views106 pages

Ediabas API Guide

This document is the EDIABAS API developer's guide. It provides information about using the EDIABAS API, including revising history, general information, and guidelines for including API files in different development environments like Visual C++ and .NET frameworks. It describes the API include file, API library, and considerations for WIN32, WIN64, and other application programs.

Uploaded by

edward carroll

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

1K views106 pages

Ediabas API Guide

Uploaded by

edward carroll

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 106

EDIABAS API Developer's Guide Page 1 of 106

EDIABAS API Developer's Guide

· API User Manual

· API Interface Description

· API Function Primer

· Transparent Mode Interface Description

EDIABAS API Developer's Guide

API User Manual

1. Revision history

2. Introduction

3. General Information

4. Using the INCLUDE File and Library

A. LIMITS AND CONSTRAINS

B. REFERENCES

EDIABAS API Developer's Guide > API User Manual

1. Revision history
Version 3.0 First release

Version 4.1 Revised for EDIABAS V4.1.0

Version 5 Revised for EDIABAS V5.1.0

Version 5a Description of Borland C 4.5 interface

Version 5b Description of Visual Basic 4.0 interface

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 2 of 106

Version 5c Revised for WIN32 interface

Version 5d Extended for QNX

Version 6 EDIABAS V6.0.0

Version 6c Revised for EDIABAS V6.4.4

Version 7a Revised for .NET Compact Framework

No more Win16 and QNX support

Revised for EDIABAS V7.1.0
Support for Windows CE / Visual C++ 2005

Version 7b Revised for .NET Framework

Version 7c Revised for Windows CE / eMbedded Visual C++

No more SCO UNIX support

Version 7d Revised for V7.2.0

Support for Visual C++ 2008 (Win32)

Support for .NET Framework 3.5 (Win32)
No more PocketPC 2005/Windows Mobile 2005 support (WinCE)

Version 7e Revised for V7.2.0

Version 7f Revised for V7.2.0

Support for Visual C++ 2010 (Win32)

Support for .NET Framework 4.0 (Win32)

Version 7g Revised for V7.3.0

Support for Visual C++ 2008 (Win64)

Support for Visual C++ 2010 (Win64)

EDIABAS API Developer's Guide > API User Manual

2. Introduction
More:

2.1. About this manual

2.2. Notational conventions

2.3. Special features, terms, acronyms

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 3 of 106

2.4. Trademarks

EDIABAS API Developer's Guide > API User Manual > 2. Introduction

2.1. About this manual

This manual describes how application, programs can be created and maintained with access to the
Electronic Diagnostic Basic System (EDIABAS). It describes the use of the tools and the various
options available. A general description of the interface is contained in [3]. A detailed description
of all API functions can be found in [4]. General information about EDIABAS and about the ECU
(Electronic Control Unit) description files (SGBDs) is described in [2].

EDIABAS API Developer's Guide > API User Manual > 2. Introduction

2.2. Notational conventions

The following typographical conventions are used throughout this manual:

Example Description
SAMPLE.C Uppercase denotes file names and operating system
commands.
apiJob, Bold-faced type identifies keywords and operators of the
APIREADY language C/C++ as well as API functions and definitions

These words must be written exactly as specified in syntax

descriptions.
expression Italics designate placeholders for values to be entered by
the programmer; e.g., file names.
[option] Words enclosed in square brackets may be optionally
specified.
{ result | Curvy braces and vertical strokes characterize entries from
argument } which only one must be selected, except when in square
brackets.
[constant...] job... An ellipsis (three dots) which directly follows an
expression indicates that several expressions of the same
type can follow.
hallo="Test"; This syntax designates examples, user entries, program
outputs and error messages.
while() { A column or a row comprising three dots indicates that a
section of an example was intentionally omitted.
.

.}
[1] Reference to a document in References.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 4 of 106

EDIABAS API Developer's Guide > API User Manual > 2. Introduction

2.3. Special features, terms, acronyms

An explanation of all the abbreviations used in this and all other EDIABAS documentation can be
found in the publication "EDIABAS User Manual", chapter "GLOSSARY".

EDIABAS API Developer's Guide > API User Manual > 2. Introduction

2.4. Trademarks

Microsoft, MS, MS-DOS, Windows, Windows Vista, WIN32, WIN64, Pocket PC, Visual C++ and
Visual Basic are registered trademarks of Microsoft Corporation.

SCO, SCO UNIX and OpenServer are registered trademarks of Santa Cruz Operation, Inc.

ARM is a registered trademark ARM Ltd.

EDIABAS API Developer's Guide > API User Manual

3. General Information
The API (Application Programming Interface) programming interface of EDIABAS can be seen by
the application program as a collection of functions, the API functions. ANSI C is used as the
programming language .

Ready-to-use API libraries are available from Softing for the EDIABAS target system. These
libraries must be included in the application programs.

All files necessary for creating application programs with access to EDIABAS are supplied on the
diskette APPLICATION DEVELOPMENT KIT.

3.2. API Library

EDIABAS API Developer's Guide > API User Manual > 3. General Information

3.1. API INCLUDE file

In order to call an API function in an application program, the C/C++ compiler requires the
prototypes of the corresponding API function. The prototypes of all API functions are contained in

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 5 of 106

INCLUDE file API.H. In addition to the prototypes, the INCLUDE file contains all constants and
type definitions which EDIABAS uses and which are required by the application program.

Instruction for inclusion of INCLUDE file API.H in a C source file:

#include "api.h"

Instructions for inclusion of INCLUDE file API.H in a C++ source file:

extern "C" {

#include "api.h"

These instructions are to be specified in every C/C++ source file of the application program in
which API functions are called or constants (or type definitions) are required from API.H are
required.

The API.H search path is to be specified so that the C/C++ compiler can find the INCLUDE file.
The corresponding compiler option is compiler dependent and can be found in the description of
the compiler being used.

EDIABAS API Developer's Guide > API User Manual > 3. General Information

3.2. API Library

All API functions of a target system are contained in a library. This library is to be specified to the
linker during linking for inclusion of the files. This is linker-dependent and usually accomplished in
a MAKE file.

EDIABAS API Developer's Guide > API User Manual

4. Using the INCLUDE File and Library

4.2. WIN64 Application Programs

EDIABAS API Developer's Guide > API User Manual > 4. Using the INCLUDE File and Library

4.1. WIN32 Application Programs

SOFTING supports the following development environments for creating application programs

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 6 of 106

with EDIABAS access:

• Visual C++ 2010 (Win32)

• Visual C++ 2008 (Win32)

• Visual C++ 6.0 (Win32)
• Visual Basic 6.0 (Win32)
• Visual Basic 4.0 (Win32)
• Visual C# 2003/2005/2008/2010 + .NET Framework 1.1/2.0/3.5/4.0 (Win32)
• Visual Basic 2003/2005/2008/2010 + .NET Framework 1.1/2.0/3.5/4.0 (Win32)

4.1.2. Visual C++ 6.0

4.1.3. Visual Basic 6.0, 4.0

4.1.4. .NET Framework 1.x / 2.0 / 3.5 / 4.0

4.1.5. DLL (Dynamic Link Library) Interface

EDIABAS API Developer's Guide > API User Manual > 4. Using the INCLUDE File and Library
> 4.1. WIN32 Application Programs

4.1.1. Visual C++ 2010/2008

In addition to the project-specific compiler options, the compiler is to be called with the following
options for every source file having access to API functions:

/I<path of api.h>

Compiler option /I determines the search path for API.H.

The API library API32.LIB for Visual C++ 2010/2008 resides in EDIABAS directory API\WIN32
\VC2010 / API\WIN32\VC2008.

EDIABAS API Developer's Guide > API User Manual > 4. Using the INCLUDE File and Library
> 4.1. WIN32 Application Programs

4.1.2. Visual C++ 6.0

In addition to the project-specific compiler options, the compiler is to be called with the following
options for every source file having access to API functions:

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 7 of 106

/I<path of api.h>

Compiler option /I determines the search path for API.H.

INCLUDE file API.H resides in EDIABAS directory API.

Visual C++ 6.0 is supported for single- und multi-thread-mode. The API libraries APIW32.LIB
(single-thread) and APIW32MT.LIB (multi-thread) resides in EDIABAS directory API\WIN32
\VC6.

Example for creating an application program EXAMPLE.EXE:

cl /Ic:\ediabas\api example.c /link c:\ediabas\api\win32\vc6\apiw32.lib

EDIABAS API Developer's Guide > API User Manual > 4. Using the INCLUDE File and Library
> 4.1. WIN32 Application Programs

4.1.3. Visual Basic 6.0, 4.0

The corresponding application program can access EDIABAS by adding the module API.BAS in a
Visual Basic project.

The module API.BAS resides in the EDIABAS directories:

• API\WIN32\VB60 (für Visual Basic 6.0)

• API\WIN32\VB40 (für Visual Basic 4.0)

and offers an API interface limited in functional scope. The APIVB32.DLL (WIN32) contained in
the RUNTIME SYSTEM is required at runtime for accessing EDIABAS.

EDIABAS API Developer's Guide > API User Manual > 4. Using the INCLUDE File and Library
> 4.1. WIN32 Application Programs

4.1.4. .NET Framework 1.x / 2.0 / 3.5 / 4.0

For the .NET Frameworks 1.x/2.0/3.5/4.0 access to EDIABAS is possible under Win32. To permit
this the framework-spezific .NET files apiNET32.DLL/apivbNET32.DLL must exist in the
application program directory. The EDIABAS program directory must be available over the system
search path.

The Assembly apiNET32.dll is the API interface for .NET applications under Win32. It handles the
access to the DLL interface of api32.dll. Since api32.dll doesn’t support the functions

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 8 of 106

apiCallback/apiErrorHandler, those functions aren’t supported under .NET either.

Additionally to the program code the Assembly apiNET32.dll all necessary API-
deklarations/definitions.

The Assembly apivbNET32.dll handles Visual Basic.NET specific features and translates them into
equivalent calls of the Assembly apiNET32.dll. The associated Basic-Modul API.VB imports the
Assembly apiNET32.dll and hides the via apivbNET32.dll necessary special handling for Visual
Basic.NET. All API access must be done using the class API defined in API.VB. The import of the
Assembly apiNET32.dll/apivbNET32.dll is already done in API.VB and needn’t be done in the
source files of the application.

API access using Microsoft Visual C#.NET

(Visual Studio 2003/2005/2008/2010 with .NET Framework 1.x/2.0/3.5/4.0)

The following steps are necessary on the developer’s PC with Visual C#.NET in .NET projects
with API access:

• Copy the correct Assembly apiNET32.dll to the developer’s PC

(apiNET32.dll for.NET1.x / VS2003,

apiNET32.dll for.NET2.0 / VS2005,
apiNET32.dll for.NET3.5 / VS2008,
apiNET32.dll for.NET4.0 / VS2010)
• Open the reference dialog:

Project | Add Reference...

• Select the .NET component apiNET32.dll

All API access must be done using the class Ediabas.API. If the name space Ediabas is defined by
the using command, only the class name API has to be given.

Example for C# source file with using command (extract):

using System;

using Ediabas;

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

//…

Api.apiEnd(); // end API

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 9 of 106

API access with Visual Basic.NET

(Visual Studio 2003/2005/2008/2010 with .NET Framework 1.x/2.0/3.5/4.0)

The following steps are necessary on the developer’s PC with Visual Basic.NET in .NET projects
with API access:

• Copy the correct Assembly apiNET32.dll to the developer’s PC

(apiNET32.dll for.NET1.x / VS2003,

apiNET32.dll for.NET2.0 / VS2005,
apiNET32.dll for.NET3.5 / VS2008,
apiNET32.dll for.NET4.0 / VS2010)
• Copy the correct Assembly apivbNET32.dll to the developer’s PC
(apivbNET32.dll for.NET1.x / VS2003,
apivbNET32.dll for.NET2.0 / VS2005.
apivbNET32.dll for.NET3.5 / VS2008,
apivbNET32.dll for.NET4.0 / VS2010)
• Copy the correct API-Moduls API.vb to the developer’s PC

(VB2003\API.vb for.NET1.x / VS2003,

VB2005\API.vb for.NET2.0 / VS2005,
VB2008\API.vb for.NET3.5 / VS2008,
VB2008\API.vb for.NET4.0 / VS2010)
• Open the reference dialog:

Project | Add Reference...

• Select the .NET components apiNET32.dll and apivbNET32.dll

• Insert the Basic module API.VB into the project:

Project | Add Existing Item

The Basic module API.VB imports the Assembly apiNET32.dll and hides the via apivbNET32.dll
necessary special handling for Visual Basic.NET.

All API access must be done using the class API defined in API.VB. The import of the Assembly
apiNET32.dll/apivbNET32.dll is already done in API.VB and needn’t be done in the source files of
the application.

Example for a Visual Basic.NET source file (using the API.VB class):

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 10 of 106

If API.apiInit() Then ' init API

'…

call API.apiEnd() ' end API

End If

Under Visual Basic 2005/2008/2010 the CLS compliance has to be deactivated/commented out in
the application (AssemblyInfo.vb):

'<Assembly: CLSCompliant(True)>

EDIABAS API Developer's Guide > API User Manual > 4. Using the INCLUDE File and Library
> 4.1. WIN32 Application Programs

4.1.5. DLL (Dynamic Link Library) Interface

EDIABAS can also be accessed directly via the DLL interface from API32.DLL with every
development tool suitable for this purpose. The DLL interface, however, does not offer the
complete scope of functions for the API interface.

The C functional declarations of the DLL interface are contained in INCLUDE file APIDLL.H.

File APICALLS.C contains the source code of the libraries APIW32.LIB/API32.LIB, in which the
complete API functionality is also available under other C/C++ development tools.

Files APIDLL.H and APICALLS.C are contained in the EDIABAS directory API\WIN32.

EDIABAS API Developer's Guide > API User Manual > 4. Using the INCLUDE File and Library
> 4.2 WIN64 Application Programs

4.2.1. Visual C++ 2010/2008

In addition to the project-specific compiler options, the compiler is to be called with the following
options for every source file having access to API functions:

/I<path of api.h>

Compiler option /I determines the search path for API.H.

The API library API64.LIB for Visual C++ 2010/2008 resides in EDIABAS directory API\WIN64

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 11 of 106

\VC2010 / API\WIN64\VC2008.

EDIABAS API Developer's Guide > API User Manual > 4. Using the INCLUDE File and Library
> 4.2 WIN64 Application Programs

4.2.2. DLL (Dynamic Link Library) Interface

EDIABAS can also be accessed directly via the DLL interface from API64.DLL with every
development tool suitable for this purpose. The DLL interface, however, does not offer the
complete scope of functions for the API interface.

The C functional declarations of the DLL interface are contained in INCLUDE file APIDLL.H.

File APICALLS.C contains the source code of the libraries API64.LIB, in which the complete API
functionality is also available under other C/C++ development tools.

Files APIDLL.H and APICALLS.C are contained in the EDIABAS directory API\WIN64.

EDIABAS API Developer's Guide > API User Manual

A. LIMITS AND CONSTRAINS

When using the API interface the following technical Limits and Constrains have to be heeded:

• Common

Max. length of a configuration name = 32 (incl. string ending)

Max. length of a configuration value:

APIMAXCONFIG = 256 (incl. string ending)

Max. length of path/file name:

APIMAXFILENAME = 256 (incl. string ending)

Max. length of device names (Connection, Application):

APIMAXDEVICE = 64 (incl. string ending)

• Job call

Max. name length (Job/ECU/Result):

APIMAXNAME = 64 (incl. string ending)

Max. job parameter length (apiJob):

APIMAXPARA = 1024 (incl. string ending where applicable)

Max. job parameter length (apiJobData/apiJobExt):

APIMAXPARAEXT = 65536 (incl. string ending where applicable)

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 12 of 106

Max. job standard parameter length:

APIMAXSTDPARA = 256 (incl. string ending where applicable)

• Identifying results

Max. result name length:

APIMAXRESULT = 256 (incl. string ending)

Max. APITEXT result length:

APIMAXTEXT = 1024 (incl. string ending)

Max. APIBINARY result length (apiResultBinary):

APIMAXBINARY = 1024

Max. APIBINARY result length (apiResultBinaryExt):

APIMAXBINARYEXT = 65536

EDIABAS API Developer's Guide > API User Manual

B. REFERENCES
[1] EDIABAS: BEST User Manual

[2] EDIABAS: User Manual

[3] EDIABAS: API Interface Description

[4] EDIABAS: API Function Primer

EDIABAS API Developer's Guide

API Interface Description

1. Update history

2. Introduction

3. General

4. Operating the API interface

5. Application example

A. List of references

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 13 of 106

EDIABAS API Developer's Guide > API Interface Description

1. Update history
Version 3.0 First release

Version 4.1 Revised for EDIABAS V4.1.0

Version 5 Inclusion of new API function apiJobExt and apiJobInfo

Version 5a Description of the new virtual job _JOBCOMMENTS

Version 6 New API function apiInitExt, additional results of the virtual job _VERSIONINFO
and parallel processing with Win32

Version 6d Revised for EDIABAS V6.4.4

Version 7 New API functions apiCheckVersion, apiStateExt, apiTrace and apiResultBinaryExt

Version 7a Revised for EDIABAS V7.1.0

Version 7b No more support for SCO UNIX

Version 7c Revised for EDIABAS V7.2.0

No more support for PocketPC 2005/Windows Mobile 2005 (WinCE)

Version 7d Revised for EDIABAS V7.2.0

Version 7e Revised for EDIABAS V7.3.0

EDIABAS API Developer's Guide > API Interface Description

2. Introduction
More:

2.1. About this manual

2.2. Conventions

2.3. Special features, definitions, acronyms

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 14 of 106

EDIABAS API Developer's Guide > API Interface Description > 2. Introduction

2.1. About this manual

This manual describes the use of constants and functions that are available in the EDIABAS-API
interface. Reference [3] gives a detailed description of these functions. Linking into a development
environment is described in Reference [4]. You will find general information about EDIABAS and
control unit description files in Reference [2].

EDIABAS API Developer's Guide > API Interface Description > 2. Introduction

2.2. Conventions

The following typographical conventions are used in this manual:

Example Description
SAMPLE.C Upper case characters are used for filenames, registers and
operating system commands.
apiJob, Bold type is used for key words and operators of the
APIREADY BEST/2 and BEST/1 languages and for API functions. In
syntax descriptions these words must be written as shown.
expression Italics designate placeholders for values to be entered by
the programmer; e.g., file names.
[option] Words enclosed in square brackets may be optionally
specified.
{ result | Curvy braces and vertical strokes characterize entries from
argument } which only one must be selected, except when in square
brackets.
[constant...] job... An ellipsis (three dots) which directly follows an
expression indicates that several expressions of the same
type can follow.
hallo="Test"; This syntax designates examples, user entries, program
outputs and error messages.
while() { A column or a row comprising three dots indicates that a
section of an example was intentionally omitted.
.

.}
[1] Reference to a document in References.

EDIABAS API Developer's Guide > API Interface Description > 2. Introduction

2.3. Special features, definitions, acronyms

The abbreviations used in this and all other EDIABAS documents are explained in the
"GLOSSARY" section of the "EDIABAS User Manual". The term API is explained in greater

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 15 of 106

detail in the "General" section.

EDIABAS API Developer's Guide > API Interface Description

3. General
The API application interface is the EDIABAS standard program interface across which an
application program sends jobs to EDIABAS to operate control unit functions and across which the
application program receives the results of the job execution back from EDIABAS.

The complete system is described in [2].

EDIABAS API Developer's Guide > API Interface Description

4. Operating the API interface

4.2. Initializing and abort of EDIABAS

4.3. API jobs

4.4. API Results

4.5. Device switching

4.6. API Sequence control

4.7. Configuration

4.8. Trouble shooting

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface

4.1. Compatibility and version check

The compatibility and version of the API can be checked by the function apiCheckVersion before
EDIABAS is accessed for the first time:

apiCheckVersion (version request, version information address )

As parameter version request the minimum API version required by the application should be
passed (e.g. 0x0700 for API 7.0.x):

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 16 of 106

0xMMmm (MM = API-Major-Version, mm = API-Minor-Version)

If compatibility shall be requested according to the current ADK, the pre-defined constant
APICOMPATIBILITYVERSION can be passed.

The function apiCheckVersion copies the current API version into the variable referenced by
version information address (max. APIMAXCONFIG characters). If version information address
has the value NULL, the reading of the version is suppressed.

The return value describes the compatibility of the API:

APITRUE API is compatible

APIFALSE API is not compatible or API not found

The function call apiCheckVersion doesn’t influence the API error state. In case of an
incompatible or no found API no EDIABAS error will be caused.

In case of a current API-Version < 7.0.0 an incompatible API will be assumed. In that case the
function apiCheckVersion will return APIFALSE and the version information will be an empty
string.

The function apiCheckVersion can be called before the EDIABAS initialization or between
initialization and abort of EDIABAS.

The function call apiCheckVersion is optional and will not be recorded in the API trace.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface

4.2. Initializing and abort of EDIABAS

A general initialization of EDIABAS must take place before the application program can call API
functions. This is done with one of the following initialization functions:

apiInit ( )

apiInitExt (device, device connection, device application, configuration )

When API is initialized with apiInit(), EDIABAS performs a system-dependent default setting for
the diagnostic interface (device), device connection and device application.

By calling apiInitExt(), it is possible to determine already during API initialization the diagnostic
interface (device) to be used, the device connection and device application. The default setting for
the diagnostic interface (device), device connection and device application can be accepted by
entering a null string.

In an initialization by apiInitExt() configurations can be given at the moment of initialization,

which differ from the standard configuration(configuration).

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 17 of 106

The settings performed with apiInitExt() are only effective until API is aborted (apiEnd()).

If an application program accesses EDIABAS, this is called an API session.

Calling apiInit() or apiInitExt() also runs the application locking procedure that is described below
in a separate section.

As a return value, the functions apiInit() and apiInitExt() provide information about the success of
the EDIABAS initializing procedure:

APITRUE Initializing successful (API accesses are possible)

APIFALSE Initializing failed (API accesses are not possible)

See section "Trouble shooting" for guidance on error correction.

An API session can be terminated with the apiEnd() function, in which case the main memory and
equipment are released.

After an API session has been terminated you must initialize with apiInit() or apiInitExt() before
you can access API functions again.

Calling apiInit() or apiInitExt() without an apiEnd() will automatically initiate an apiEnd() in the
application program (if a session is not yet terminated).

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface

4.3. API jobs

After initializing, control units can be accessed by sending API jobs to the EDIABAS. These jobs
always have the following structure:

apiJob (ECU group/variant, job, parameters, results)

apiJobData (ECU group/variant, job, parameter data, parameter length, results)

apiJobExt (ECU group/variant, job, parameter data for standard jobs, length of parameter
for standard jobs, parameter data, parameter length, results, reserved)

The argument CU group/variant establishes the link with the addressed control unit, i.e. the relevant
control unit description file (SGBD). The name of the SGBD is always given without its extension,
e.g.:

DMETEST.PRG -> DMETEST

ALLEDME.GRP -> ALLEDME

The argument job corresponds to the job name defined in the ECU description file SGBD, whereby
no differentiation is made between upper- and lowercase.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 18 of 106

Arguments parameter and Parameterdata/-length are job parameters. Only a text string in "C"
format can be passed as argument to function apiJob (e.g., "Par1;Par2;Par3" or ""). The individual
parameters are separated in the argument with a semicolon, whereby upper- and lowercase are
differentiated. apiJobData and apiJobExt can be passed as both a text string and binary data.
Additional parameters for standard jobs can be passed to function apiJobExt. These parameters are
passed to all standard jobs which are automatically executed after calling apiJobExt either before
or after the specified job. If a text string is passed as a parameter in either apiJobData or
apiJobExt, the length of the text string must be passed without the final '\0 character, otherwise the
number of data bytes must be passed. A typical application for binary parameter data is the
TRANSPARENT-MODE of EDIABAS. Further information can be found in reference [5].

The argument results determines which job events are to be produced. The individual results are
separated with a semicolon in the argument, whereby no difference is made between upper- and
lowercase. If all results are to be processed, specify a blank string for argument results. The
selective creation of certain results must have been implemented when creating the ECU
description file; otherwise all results are produces despite specification of special results.

For the function apiJob the maximum parameter length is APIMAXPARA, for the functions
apiJobData and apiJobExt it’s APIMAXPARAEXT.

4.3.2. Jobs with a defined variant

4.3.3. Standard jobs

4.3.4. Virtual jobs

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs

4.3.1. Jobs with an unknown variant

You communicate with an unknown control unit variant by defining the group name as the first
argument of the job:

apiJobxxx ( SG group , ... )

The control unit group description file is loaded to identify the fitted variant.

After successful identification the appropriate control unit description file is loaded and the job is run.

When identifying the variant the name of the control unit group is used as a reference for the control
unit group description file, the variant name of the control units being used to allocate corresponding
control unit description files.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 19 of 106

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs

4.3.2. Jobs with a defined variant

Communication with a defined control unit variant is achieved by defining the variant name as the
first argument in the job:

apiJobxxx ( SG variant, ...)

The name of the control unit variant is then copied to the standard result VARIANTE.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs

4.3.3. Standard jobs

Standard jobs are jobs predefined by EDIABAS, their use is precisely specified and must be stored in
control unit description files.

Standard jobs are called automatically by EDIABAS.

Function apiJobExt can be used to transfer parameters to standard jobs.

The result of standard jobs is stored in specified standard results that are polled automatically by
EDIABAS.

4.3.3.2. Standard job IDENTIFIKATION

4.3.3.3. Standard job ENDE

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs > 4.3.3. Standard jobs

4.3.3.1. Standard job INITIALISIERUNG

The standard job INITIALISIERUNG of a description file is called automatically:

• following an initialization of API (apiInit()) or apiInitExt())

• after a change of the diagnostic interface with apiSetConfig()

• after a device change (apiSwitchDevice())
• after the simulation mode has been switched on or off with apiSetConfig()
• following a previous error

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 20 of 106

• for a job with a defined variant (only after changing the control unit variant)
• for a job with an unknown variant
• after a call of the BEST/2 function doNewInit in an SGBD.

The standard job INITIALISIERUNG must exist in every group and variant description file.

Successful initializing must be displayed with the standard result DONE (result type APIINTEGER
or APIWORD) in a result set:

• Result DONE <> 0 Initializing successful

• Result DONE = 0 Initializing failed

• Result DONE not present Initializing failed

The standard job INITIALISIERUNG must not return any results except DONE.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs > 4.3.3. Standard jobs

4.3.3.2. Standard job IDENTIFIKATION

The standard job IDENTIFIKATION is called to identify the fitted control unit variant:

• for a job with an unknown variant

The standard job IDENTIFIKATION must exist in every group description file.

An identified control unit variant must be displayed with the standard result VARIANTE (string of
result type APITEXT) in a result set:

• Result VARIANTE = string (1 character min.) Identification successful, the result is the
name of the control unit variant

• Result VARIANTE = blank string Identification failed

• Result VARIANTE not present Identification failed

The standard job IDENTIFIKATION must not return any results except VARIANTE.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs > 4.3.3. Standard jobs

4.3.3.3. Standard job ENDE

The optional standard job ENDE is called when the description file is changed:

• before the description file is changed

• before a job with an unknown variant

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 21 of 106

The standard job ENDE can exist in any group and variant description file.

The standard job ENDE must not return any results.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs

4.3.4. Virtual jobs

Virtual jobs are jobs predefined by EDIABAS; when called they provide information about a control
unit description file.

Virtual jobs cannot be edited by the EDIABAS user.

Unlike standard jobs, virtual jobs are not in the control unit description files but are simulated by
EDIABAS. However virtual jobs can be overwritten by self-defined jobs within the control unit
description files.

The results of virtual jobs are stored in standard results with fixed names which are polled in the same
way as the results of normal jobs (see section "Identifying results").

4.3.4.2. Virtual job _JOBCOMMENTS

4.3.4.3. Virtual job _VERSIONINFO

4.3.4.4. Virtual job _ARGUMENTS

4.3.4.5. Virtual job _RESULTS

4.3.4.6. Virtual job _TABLES

4.3.4.7. Virtual job _TABLE

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs > 4.3.4. Virtual jobs

4.3.4.1. Virtual job _JOBS

The virtual job _JOBS identifies the names of all the jobs in the control unit description file (but not
the names of virtual jobs).

Each job name is stored in a separate result set as a standard result JOBNAME, so the number of
result sets is the number of jobs in the control unit description file.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 22 of 106

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs > 4.3.4. Virtual jobs

4.3.4.2. Virtual job _JOBCOMMENTS

The virtual job _JOBCOMMENTS determines the comment to a particular job. The name of the
job to be investigated is to be specified as job parameter when calling the virtual job. Determining
the results is only possible with BEST2 ECU description files, which was not subsequently
processed using the tool STRIP.

The following information are stored in the first result set for each result.

JOBCOMMENTx Comment lines (x is a consecutive number

in decimal notation beginning with 0)

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs > 4.3.4. Virtual jobs

4.3.4.3. Virtual job _VERSIONINFO

The virtual job _VERSIONINFO determines general information about the ECU description file
and stores this in the first result set:

REVISION Versions identification

AUTHOR Author of last revision

FROM Date of last revision

The following additional information is determined for BEST2 SGBDs which were not post-
processed by the STRIP tool :

ECU SGBD description

ORIGIN author of the first version
LANGUAGE language definition
USESx basic files (x is a serial number
in decimal format, beginning with 0)
ECUCOMMENTx SGBD comment lines (x is a serial number
in decimal format, beginning with 0)

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs > 4.3.4. Virtual jobs

4.3.4.4. Virtual job _ARGUMENTS

The virtual job _ARGUMENTS determines all defined arguments of a job; the name of the job to

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 23 of 106

be investigated is to be specified as job parameter when calling the virtual job. Determining the
arguments is only possible with BEST2 ECU description files, which as not subsequently processed
using the tool STRIP.

The virtual job _ARGUMENTS cannot determined the arguments actually passed at runtime, but
only the arguments defined in the job header.

The following information are stored in a separate result set for each argument:

ARG Argument name

ARGTYPE BEST data type of the argument

ARGCOMMENTx Comment lines (x is a consecutive number

in decimal notation beginning with 0)

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs > 4.3.4. Virtual jobs

4.3.4.5. Virtual job _RESULTS

The virtual job_RESULTS determines job results; the name of the job to be investigated is to be
specified as job parameter when calling the virtual job. Determining the results is only possible
with BEST2 ECU description files, which was not subsequently processed using the tool STRIP.

The virtual job _RESULTS cannot determine the results actually stored at runtime, but the results
defined in the job header of the ECU description file.

The following information are stored in a separate result set for each result:

RESULT Result name

RESULTTYPE BEST data type of the result

RESULTCOMMENTx Comment lines (x is a consecutive number
in decimal notation beginning with 0)

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs > 4.3.4. Virtual jobs

4.3.4.6. Virtual job _TABLES

The virtual job _TABLES determines all table names of the ECU description files.

Note:

Only the names of local defined tables are determined

For each table a separate result set is stored with text result TABLE:

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 24 of 106

TABLE name of the table

The system result SAETZE determines the numer of founded tables (0 ... n).

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.3. API jobs > 4.3.4. Virtual jobs

4.3.4.7. Virtual job _TABLE

The virtual job _TABLE determines the contents of a table. The name of the table to be
investigated is to be specified as job parameter when calling the virtual job.

Note:

Only the contents of a local defined table are determined

In each result set the contents of one line of the table is stored. The result set consists of the text
results ‚COLUMN0‘ to ‚COLUMNn‘.

It is started with the first line of the table:

COLUMN0 content of first column

COLUMN1 content of second column

... ...

COLUMNn content of n+1st column

The system result SAETZE determines the numer of all lines of a tables.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface

4.4. API Results

4.4.2. Identifying results

4.4.3. Result types and formats

4.4.4. Application result fields

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 25 of 106

4.4. API Results

4.4.1. Data management

After executing a job with apiJob(), EDIABAS loads the corresponding ECU description file and
processed the job passed. As a job is being processed, results occur which are to be passed to the
application program.

The results are stored in a data structure by EDIABAS; this structure is designated
APIRESULTFIELD.

A result field consists of a number of APIRESULTFIELDS which, on the other hand, contain a
number of RESULTS. The number of result sets and the results depends on the job in the ECU
description file.

System result 1 System result 2 ... System result m0 Result set 0

Result 1 Result 2 ... Result m1 Result set 1

Result 1 Result 2 ... Result m2 Result set 2

...
Result 1 Result 2 ... Result mn Result set n

Result set 0 of a job is automatically stored by EDIABAS. This, as SYSTEMRESULTS, designates

result set contains general information about the processed job.

The results of the system result set are called SYSTEMRESULTS .

Generation of the system results via EDIABAS can be disabled via the EDIABAS configuration.
System results VARIANTE, OBJECT, JOBNAME and SAETZE, are excluded from this and
must always be stored.

All system results as well as the possible results values are described in the following summary:

System result Comment Value

VARIANTE Name of the ECU APITEXT[]
OBJECT Name of the ECU description file which APITEXT[]
contains the job
JOBNAME Name of the job being executed APITEXT[]
SAETZE Number of returned result sets APIWORD
UBATTCURRENT State of the supply voltage -1 = undefined

0 = disabled

1 = enabled

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 26 of 106

UBATTHISTORY History of the supply voltage state -1 = undefined

0 = was disabled

1 = was enabled
IGNITIONCURRENT State of the ignition -1 = undefined

0 = disabled

1 = enabled
IGNITIONHISTORY History of the ignition state -1 = undefined

0 = was disabled

1 = was enabled
JOBSTATUS Summarized status message of the job (= job APITEXT[]
return value)

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results

4.4.2. Identifying results

The results of a job must be identified or read out of the result field with the following functions:

apiResultxxx(target address,result,result set)

apiResultText(address,result,result set,format)
apiResultBinary(target address,length address,result,result set)
apiResultBinaryExt(target address,length address,target size,result,
result set)

The format of the result stored in the result field is the one defined and returned by the job in the
SGBD.

Irrespective of this, an application program can get a result in any desired format provided conversion
is possible.

The appropriate function must be selected for each result type desired by the application program:

Result function Result format

apiResultChar() APICHAR
apiResultByte() APIBYTE
apiResultInt() APIINTEGER

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 27 of 106

apiResultWord() APIWORD
apiResultLong() APILONG
apiResultDWord() APIDWORD
apiResultReal() APIREAL
apiResultText() APITEXT
apiResultBinary() APIBINARY
apiResultBinaryExt() APIBINARY

The target address is the address of the desired result variable in the application program where API
is to store the result. The name of the result to be read must be entered as the argument result (not
case sensitive).

The result functions apiResultBinary() and apiResultBinaryExt() are exceptions because they also
require the length address of an APIWORD result variable where API stores the number of copied
bytes. The result function apiResultBinaryExt() additionally requires the target size. The result
function apiResultBinary() permits the return of max. APIMAXBINARY characters. With the
result function apiResultBinaryExt() the maximum number of characters, that can be copied,
depends on the given target size (max. APIMAXBINARYEXT characters).

The format argument is another special case and is only available for the target result format
APITEXT. The format argument converts the original result format into the target result format
APITEXT with a definable conversion specification (see also section "Result types and formats"). If
the format argument is a blank string on the other hand, the result is converted to the result format
APITEXT with the default conversion.

Jobs can generate more than one result set (bundling of multiple results, e.g. error memories), which
is why the result set must always be specified (with the result set argument).

The return value of the apiResultxxx() functions indicates the existence of the desired result:

APITRUE Result present

APIFALSE No result present

If a result set contains more than one result with the same name, only the last result can be identified.

A result may be absent for the following reasons:

• there was an error during job execution - no results present

• the result is present but cannot be converted to the desired format

• no result present

By calling the API function apiResultFormat() you can identify the format in which a result is

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 28 of 106

stored in the result field:

The return APIFALSE indicates that the result is not present.

See section "Trouble shooting" for guidance on error correction.

4.4.2.2. Identifying the number of result sets

4.4.2.3. Identifying the number of results in a result set

4.4.2.4. Identifying a result name using the result index

4.4.2.5. Identifying the format of a result

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results > 4.4.2. Identifying results

4.4.2.1. Identifying the name of the control unit variant

If control unit identification is successful when a job is sent then EDIABAS stores the name of the
control unit description in the system result set (result set 0) as the result VARIANTE.

As well as polling with apiResultxxx(), simplified polling using

apiResultVar (target address)

is also possible. The target address is the address of a variable in the application program where API
stores the content of the VARIANTE result.

The description of the return of apiResultxxx() is also valid for apiResultVar().

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results > 4.4.2. Identifying results

4.4.2.2. Identifying the number of result sets

API automatically stores the number of result sets in the system result set (result set 0) as the result
SAETZE .

As well as polling with apiResultxxx(), simplified polling using

apiResultSets (target address)

is also possible. The target address is the address of a APIWORD variable in the application program

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 29 of 106

where API stores the content of the SAETZE result.

The description of the return of apiResultxxx() is also valid for apiResultSets().

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results > 4.4.2. Identifying results

4.4.2.3. Identifying the number of results in a result set

The number of results in a result set can be identified with the function

apiResultNumber (target address,result set)

The target address is the address of an APIWORD variable in the application program where API
stores the number of results of the result set result set.

The description of the return of apiResultxxx() is also valid for apiResultNumber().

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results > 4.4.2. Identifying results

4.4.2.4. Identifying a result name using the result index

The name of a result can be identified with the function

apiResultName (target address,result index,result set)

The target address is the address of a string variable in the application program where API stores the
result name.

The result index is the sequential number of a result in a result set. Valid values are 1..no., where no.
is the number of results in the set result set identified with apiResultNumber().

The description of the return of apiResultxxx() is also valid for apiResultName().

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results > 4.4.2. Identifying results

4.4.2.5. Identifying the format of a result

The format of the result returned by the control unit description file can be identified with the
function

apiResultFormat (target address,result,result set)

The target address is the address of an APIRESULTFORMAT variable in the application program
where API stores the result format. The argument result is the result you are searching for. The result
set must be specified in the argument result set.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 30 of 106

The description of the return of apiResultxxx() is also valid for apiResultFormat().

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results

4.4.3. Result types and formats

4.4.3.2. Result formats

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results > 4.4.3. Result types and formats

4.4.3.1. Result types

The results of a job can exist in or be converted to the following formats:

APICHAR

APIBYTE

APIINTEGER

APIWORD

APILONG

APIDWORD

APIREAL

APITEXT

APIBINARY

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results > 4.4.3. Result types and formats

4.4.3.2. Result formats

The formatting instruction uses the apiResultText(...,Format) function and must be configured as
follows:

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 31 of 106

[Specifications] Conversion characters

Conversion character Conversion

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

Specifications:
[-] [digit1] [.digit2] [e,E]
| | | |
| | | |__ APIREAL: exponential representation
| | |
| | |__ APITEXT: max. number of characters specified
| | APIREAL: number of decimal places
| |
| |____ Minimum field size ²
|
|_____ left-justified formatting, otherwise
right-justified formatting

² Pad with blanks for short arguments

Expand to required number of digits for long arguments

Examples:

Formatting instruction "B": Converts a result (if convertible) to the APIBYTE format, then
further converting and return of a right-justified APITEXT
string.

Formatting instruction "20T": Converts a result (if convertible) to the APITEXT format, then
further converting and return of a right-justified APITEXT
string with a total of 20 digits.

Formatting instruction "-8.2ER": Converts a result (if convertible) to the APIREAL format, then
further converting and return of a left-justified APITEXT

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 32 of 106

string with a total of 8 digits, with the result being stored in exponential representation with 2 decimal
places.

Formatting instruction "": Converts a result (if convertible) to the APITEXT format and
returns the left-justified APITEXT string.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results

4.4.4. Application result fields

(Buffer) storage and delayed evaluation of results fields by the application program is possible using
the routine described below.

CAUTION: This switch affects the result field only, the status of EDIABAS is not stored.

4.4.4.2. Creating a reference to the application result field

4.4.4.3. Deleting an application result field

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results > 4.4.4. Application result fields

4.4.4.1. Creating an application result field

A duplicate of the current result field can be created within API with the function

apiResultsNew( )

The return is a reference to the result field (application result field) dynamically created in the main
memory. NULL indicates creation has failed.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results > 4.4.4. Application result fields

4.4.4.2. Creating a reference to the application result field

By calling the function

apiResultsScope (reference)

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 33 of 106

it is possible to switch to the application result field; a reference to the application result field is
required as a function argument (known from apiResultsNew()).

The results in the application result field can then be accessed using known evaluation methods
(apiResultxxx()).

The link to the application result field exists until new results are stored in API's own result field
(initiated by calling apiJobxxx()).

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.4. API Results > 4.4.4. Application result fields

4.4.4.3. Deleting an application result field

A memory location created with apiResultsNew() can be deleted with the function

apiResultsDelete (reference)

for each application result field (reference as function argument).

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface

4.5. Device switching

Communicating with the diagnostic interface is done by accessing the interface driver .

To access the diagnostic interface (device) you must specify the device connection and the device
application:

Necessary access information for diagnostic interface = device connection + device application

The device connection is the interface to be controlled; the application to be addressed on the
interface is referred to as the device application.

When initializing API with apiInit(), EDIABAS performs system-dependent presets for device
connection and device application.

The preset uses the device driver supplied by Softing for the diagnostic bus interface.

To switch to a different device connection or device application, call the function

apiSwitchDevice ( deviceConnection, deviceApplication )

Both the device connection and the device application must be entered as strings.

Switching to a different device connection or device application is only effective until a further
switch with apiSwitchDevice() or until API is terminated (apiEnd()).

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 34 of 106

The preset for device connection and device application can be determined by entering a blank string.

The function apiSwitchDevice() returns information about the successful switch of the device
connection and the device application:

APITRUE Switch successful

APIFALSE Switch failed

See section "Trouble shooting" for guidance on error correction.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface

4.6. API Sequence control

Basically, the following sequence must be observed. It can be repeated as often as desired:

...

apiInitxxx()

...

Other API functions

...

apiEnd()

...

After successful API initializing (apiInitxxx() with the return APITRUE) all other API function
calls can be executed until API is terminated (apiEnd()).

The API functions for trouble shooting are an exception to this rule - they can also be called when
API initializing fails (see section "Trouble shooting").

4.6.2. Job execution state

4.6.3. Parallel Processing (only WIN32)

4.6.4. Application Locking (not WIN32/WIN64)

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 35 of 106

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.6. API Sequence control

4.6.1. Job control

4.6.1.2. Cyclical polling

4.6.1.3. Call-Back option

4.6.1.4. Job abort

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.6. API Sequence control > 4.6.1. Job control

4.6.1.1. Automatic job execution

The following functions initiate the execution of a job that has been started but not yet finished:

• start a new job (apiJobxxx)

• device change (apiSwitchDevice)

• identify result (apiResultxxx)

The unfinished job is completed before the new action.

The new action is carried out even when there is an error in the automatically executed job.

An error in the automatically executed job is cleared before the new action is carried out.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.6. API Sequence control > 4.6.1. Job control

4.6.1.2. Cyclical polling

In order to carry out time-critical actions of the application program while an API job is running
(e.g. keyboard polling, display configuration etc.), the processing status of the job must be polled
with

apiState ( )

apiStateExt ( suspendTime )

before the result is polled with apiResultxxx().

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 36 of 106

The return from apiState() and apiStateExt() is the job status of the (last) job started:

APIBUSY : job still running

APIREADY : job is done

APIBREAK : job was aborted

APIERROR : job had an error

An ongoing job can be terminated with the function

apiBreak ( )

This also clears any existing results and returns you to the application program.

Unlike the other job states, APIBREAK can only be initiated by the application program.

To do this, either the function apiBreak() must be called or the call-back function must be terminated
by the APITRUE return.

There are no results with the APIERROR job state.

Job states APIBREAK and APIERROR are held until a job is started with apiJobxxx() or API is
re-initialized with apiInitxxx().

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.6. API Sequence control > 4.6.1. Job control

4.6.1.3. Call-Back option

Instead of the EDIABAS sequence control using apiState(), it is possible to use a call-back routine in
the application program.

During an API job EDIABAS will continuously call a user-selectable function of the application
program.

Activating a Call-Back routine

EDIABAS is asked for a Call-Back routine with

apiCallBack (function reference)

Syntax of a Call-Back routine.

The return of the Call-Back routine is interpreted as an abort request to EDIABAS:

Return = APITRUE : Abort order immediately

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 37 of 106

Return = APIFALSE : Continue order

If EDIABAS sees the request for an immediate abort after executing the Call-Back it will terminate
the current API job (condition is APIBREAK), delete any results and return to the application
program.

Run-time request
Since a Call-Back routine is activated continuously during an API job execution, interrupting
EDIABAS every time, Call-Back routines must observe a relatively short run-time.

Constraints
No API functions may be called during a Call-Back routine apart from the apiErrorCode() and
apiErrorText() functions.

The function apiCallBack is not applicable in the following cases:

• EDIABAS multithreading mode (undefined behavior)

• Direct access to DLL interface of API (function is missing)
• Access to .NET interface of API (function is missing)

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.6. API Sequence control > 4.6.1. Job control

4.6.1.4. Job abort

The following events can abort a job in progress:

• Error during execution (indirect abort)

• API is aborted with apiEnd() (indirect abort)

• Direct job abort with apiBreak()
• Direct job abort with return APIFALSE in the Call-Back routine

A direct job abort initiates an error which is why all result data are lost and cannot be accessed.

An API abort with apiEnd() initiates an apiBreak() and so aborts a job in progress.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.6. API Sequence control

4.6.2. Job execution state

During the execution of a job the execution state can be queried using the function apiJobInfo.
This function returns the execution state of a job in percent. The query mechanism must be
supported by special BEST language constructs in the control unit description file. Otherwise the

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 38 of 106

function apiJobInfo will return -1 (i.e. the execution state is undefined)

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.6. API Sequence control

4.6.3. Parallel Processing (only WIN32)

EDIABAS for WIN32 permits simultaneous access to EDIABAS by several different application
programs.

In contrast to the other platforms, EDIABAS for WIN32 is no one single software which runs all
application programs consecutively. Instead, there is a separate EDIABAS for each application
program, which is started and terminated automatically under WIN32.

The interfaces available with EDIABAS may only be accessed by 1 application program at a time.
Therefore, EDIABAS for WIN32 requires an interface locking mechanism which ensures exclusive
access of an application program to an interface (device locking).

Device locking takes place if the functions apiInit(), apiInitExt() or apiSwitchDevice() are called:

apiInit() è default device "_"

apiInitExt() è device according to function call, e.g. "A"

apiSwitchDevice() è device according to function call, e.g. "A"

If several application programs try to access the same device, all except the first one will receive
the error IFH-0029: ACCESS DENIED.

It must be taken into account that when apiInit() is called, exclusive access to the default device "_"
takes place. If another application is already accessing the default device "_", the call of apiInit()
will fail (IFH-0029: ACCESS DENIED).

Therefore, an application program can only access EDIABAS with apiInit() if all currently running
application programs have selected an interface different from “ “ with apiInitExt() or
apiSwitchDevice()!

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface

4.7. Configuration

The EDIABAS configuration consists of several information pairs, each pair of which consists of
the following:

Configuration element and configuration setting

Configuration element and configuration setting each represent string with predefined contents.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 39 of 106

All EDIABAS configuration elements can be interrogated; changing the configuration setting,
however, is not possible for all configuration elements. The configuration can only be modified up
to the next API abort (apiEnd()).

A detailed description of all configuration elements and their configuration settings can be found in
reference [2].

4.7.2. Modify the configuration

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.7. Configuration

4.7.1. Determining the configuration

The setting of a configuration element can be determined by calling the function:

apiGetConfig (configurationelement, destinationaddr)

configurationelement represents the string value of configuration element which is to be

interrogated. destinationaddr represents the address of the string variable where API copies the
corresponding configuration setting.

The return value indicates how the configuration was determined:

Return value = APITRUE : Configuration successful

Return value = APIFALSE : Configuration failed fehlerhaft

Failed configuration does not cause an EDIABAS error to be issued.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.7. Configuration

4.7.2. Modify the configuration

The setting of a configuration element can be modified with the following function, provided this is
permitted by EDIABAS:

apiSetConfig (configurationelement, configurationsetting)

configurationelement represents the string value of the configuration element to be modified;

configurationsetting represents the string value of the new setting.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 40 of 106

The return value indicates the success of the modified configuration:

Return value = APITRUE : Configuration modified

Return value = APIFALSE : Illegal configuration modification

An erroneous configuration modification does not cause an EDIABAS error to be issued.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface

4.8. Trouble shooting

4.8.2. Using an Error Handler

4.8.3. Procedure for error analysis when initializing and identifying results

4.8.4. Clearing an error

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.8. Trouble shooting

4.8.1. Identifying the cause of an error

The error status on which an error is based can be identified by calling the function

apiErrorCode ( )

The default error text of the error can also be identified using the function

apiErrorText ( )

Reference [1] gives a description of all possible errors.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.8. Trouble shooting

4.8.2. Using an Error Handler

For error handling, the application program can define a function without arguments that the run-time
system must activate whenever an error occurs (Error Handler):

apiErrorHandler ( Action )

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 41 of 106

In the Error Handler, the error will be typically analyzed by polling apiErrorCode() or apiErrorText
().

The function apiErrorHandler is not applicable in the following cases:

• EDIABAS multithreading mode (undefined behavior)

• Direct access to DLL interface of API (function is missing)
• Access to .NET interface of API (function is missing)

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.8. Trouble shooting

4.8.3. Procedure for error analysis when initializing and identifying results

As well as the return APIFALSE, for functions with APIBOOL return an API error can be
identified in one of the following two ways (see also the section on "Trouble shooting"):

a) Calling the error code with the API function apiErrorCode()

Return EDIABAS_ERR_NONE : No API error present

Other return : API error(code) present

b) Calling the error text with the API function apiErrorText()

Return = NULL : No API error present

Other return : API error(text) present

By calling the API function apiResultFormat() you can check whether the desired result format
even exists:

The return APIFALSE indicates that the result is not available.

EDIABAS API Developer's Guide > API Interface Description > 4. Operating the API interface >
4.8. Trouble shooting

4.8.4. Clearing an error

Errors remain set until a job is started by apiJobxxx(), the device is changed with apiSwitchDevice(),
or until API is re-initialized with apiInitxxx().

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 42 of 106

The errors API-0005 and API-0014 are special cases; these will also be reset during the next result
query with apiResultXxx().

EDIABAS API Developer's Guide > API Interface Description

5. Application example
/********************************************************************

***

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

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 43 of 106

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

* Quit !!

void quit (int exitCode)

apiEnd();

exit(exitCode);

* Print EDIABAS error and quit !!

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 44 of 106

void error (void)

printf("\nEDIABAS Error %d: %s\n",apiErrorCode(),apiErrorText());

quit(1);

* Output a binary result

* Parameter:

* - fp

* File Pointer of output file

* - yb

* Address of APIBINARY buffer

* - yn

* Number of bytes to be output

void printBinary (FILE fp,APIBINARY yb,APIWORD yn)

/* line format: */

/* line 0 25 */

/* XXX: XX XX XX XX XX XX XX XX XXXXXXXX */

static char line[LINESIZE+1];

static char addr[5];

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 45 of 106

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

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 46 of 106

* Output the result field

* If the displayed File Pointer shows the value NULL

* all results are polled but not output

* Parameter:

* - fp

* File Pointer of output file

* Return is APITRUE if correctly output

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

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 47 of 106

APILONG l;

APIDWORD d;

APIREAL r;

APIRESULTFORMAT format;

APIBOOL ret=APITRUE;

if (fp!=NULL)

fprintf(fp,"RESULTFIELD:\n\n");

/* Identify the number of results */

if (apiResultSets(&s)) {

/* For all result sets */

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

if (fp!=NULL)

fprintf(fp,"SET %3u:",set);

/* Number of results in current result set */

if (apiResultNumber(&i,set)) {

/* For all results */

for(index=1;

(index<=i)&&(apiErrorCode()==EDIABAS_ERR_NONE);

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 48 of 106

index++)

/* Identify result format */

if (apiResultName(text,index,set)) {

if (fp!=NULL)

fprintf(fp," %sRESULT %3u: ",

(index==1)?"":" ",index);

/* Identify result format */

if (apiResultFormat(&format,text,set)) {

/* Download results by format and output */

switch (format) {

case APIFORMAT_CHAR:

if (apiResultChar(&c,text,set))

if (fp!=NULL)

fprintf(fp,"[ CHAR ] %s = %+d",text,c);

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

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 49 of 106

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

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 50 of 106

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;

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 51 of 106

program start

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 upload parameters */

printf("control unit : "); gets(ecu);

printf("Job: : "); gets(job);

printf("Job-Parameter: "); gets(para);

printf("Job-Results : "); gets(result);

printf("Pass number (1-65535): "); gets(buffer);

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

printf("Show status and results (y/N) ?");

gets(buffer);

sscanf(buffer,"%c",&c);

if (c=='y' || c=='Y')

showStatus=TRUE;

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 52 of 106

printf("\nPress ENTER to start processing");

getchar();

printf("\n");

time(&start);

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

if (showStatus)

printf("\Pass #%03d...",i);

if (!apiInit()) {

printf("\nError: apiInit(): %s\n",apiErrorText());

quit(1);

if (showStatus)

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

apiJob(ecu,job,data,result);

while (apiState()==APIBUSY) /* do nothing */;

if (apiState()==APIERROR) {

printf("\nEDIABAS Error %d: %s\n",apiErrorCode(),apiErrorText());

continue;

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 53 of 106

if (showStatus){

printf("Ok.\n");

if(!printResultField(stdout))

error();

apiEnd();

time(&stop);

printf("\n\nAPIDEMO ready (%u), Time = %.1f seconds\n",

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

quit(0);

EDIABAS API Developer's Guide > API Interface Description

A. List of references
[1] EDIABAS: Error Reference

[2] EDIABAS: User Manual

[3] EDIABAS: API Function Primer

[4] EDIABAS: API User Manual

[5] EDIABAS: Transparent Mode

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 54 of 106

EDIABAS API Developer's Guide

API Function Primer

1. Update history

2. Introduction

3. Data types, constants and error messages

4. API function Primer

5. Other Functions

A. List of references

EDIABAS API Developer's Guide > API Function Primer

1. Update history
Version 3.0 First release

Version 4.1 Revised for EDIABAS V4.1.0

Version 5 Inclusion of the new API functions apiJobExt and apiJobInfo

Version 5a API functions apiResultByte/apiResultChar under VB 4.0 available

Version 6 New API function apiInitExt as supplement to apiJobInfo

Version 6c Revised for EDIABAS V6.4.4

Version 7a additions for Windows CE,

additions for .NET Compact Framework und MultiThreading/Win32

additions for EDIABAS V6.5.0
additions for .NET Framework (Win32) and new API functions apiCheckVersion,
apiStateExt, apiResultBinaryExt and apiTrace
additions for EDIABAS V7.1.0
API function apiInitExt with extended max. configuration length

Version 7b Revised for EDIABAS V7.2.0

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 55 of 106

EDIABAS server functions replaced by controller service functions

Version 7c Revised for EDIABAS V7.2.0

Version 7d Revised for EDIABAS V7.3.0

Additions for API functions apiCallBack/apiErrorHandler

Additions for WIN64

EDIABAS API Developer's Guide > API Function Primer

2. Introduction
More:

2.1. About this Manual

2.2. Conventions

2.3. Special features, definitions, acronyms

EDIABAS API Developer's Guide > API Function Primer > 2. Introduction

2.1. About this Manual

This manual describes the constants and functions that are available in the EDIABAS-API
interface. Reference [5] gives a detailed description of their use. Linking into a development
environment is described in Reference [6]. You will find general information about EDIABAS and
control unit description files in Reference [4].

EDIABAS API Developer's Guide > API Function Primer > 2. Introduction

2.2. Conventions

The following typographical conventions are used in this manual:

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 56 of 106

syntax descriptions these words must be written as shown.

expression Italics designate placeholders for values to be entered by

the programmer; e.g., file names.
[option] Words enclosed in square brackets may be optionally
specified.
{ result | Curvy braces and vertical strokes characterize entries from
argument } which only one must be selected, except when in square
brackets.
[constant...] job... An ellipsis (three dots) which directly follows an
expression indicates that several expressions of the same
type can follow.
hallo="Test"; This syntax designates examples, user entries, program
outputs and error messages.
while() { A column or a row comprising three dots indicates that a
section of an example was intentionally omitted.
.

.}
[1] Reference to a document in References.

EDIABAS API Developer's Guide > API Function Primer > 2. Introduction

2.3. Special features, definitions, acronyms

The abbreviations used in this and all other EDIABAS documents are explained in the
"GLOSSARY" section of the "EDIABAS User Manual".

EDIABAS API Developer's Guide > API Function Primer

3. Data types, constants and error messages

3.1. Data types

3.2. Constants

3.3. Error messages

EDIABAS API Developer's Guide > API Function Primer > 3. Data types, constants and error
messages

3.1. Data types

API provides the following predefined data types.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 57 of 106

API Data type Definition Definition Definition Explanation

(C/C++) (Visual Basic) (C#)
APIBOOL enum, values: VB 3.0/4.0/6.0: bool Return value
APIFALSE,
APITRUE Integer

VB.NET:

Boolean
APICHAR char è Byte *) char Result type
APIBYTE unsigned char VB 4.0/6.0/.NET: byte Result type

Byte
APIINTEGER short VB 3.0/4.0/6.0: short Result type

Integer

VB.NET:

Short
APIWORD unsigned short è Integer *) ushort Result type
APILONG long VB 3.0/4.0/6.0: int Result type

Long

VB.NET:

Integer
APIDWORD unsigned long Long uint Result type
APIREAL double Double double Result type
APITEXT[] char[] String string Result type
APIBINARY[] unsigned char[] VB 3.0: byte[] Result type

String

VB 4.0/6.0/.NET:

Array of Byte
è substitute data type *)

As well as the simple data types, this primer also defines the complex data type APIRESULTFIELD
which represents a reference to a result field.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 58 of 106

Variables of the APIRESULTFIELD data type can be used like variables of simple data types (e.g.
APIBYTE).

All API data types are not available under Visual Basic and C#.

EDIABAS API Developer's Guide > API Function Primer > 3. Data types, constants and error
messages

3.2. Constants

API provides the following defined constants :

Constant Purpose
APIMAXCONFIG Maximum recommended buffer size for configurationsetting
(including termination character)
APIMAXDEVICE Maximum length of device arguments connection and
application (including last character)
APIMAXNAME Maximum length of job arguments control unit and name, result
names and format strings (including last character)
APIMAXSTDPARA Maximum length of the job argument Parameter for standard
jobs
APIMAXPARA Maximum length of job argument parameter (including last
character if argument exists as a string) for job calls using
apiJob
APIMAXPARAEXT Maximum length of job argument parameter (including last
character if argument exists as a string) for job calls using
apiJobData and apiJobExt
APIMAXRESULT Maximum length of job argument result (including last
character)
APIMAXTEXT Maximum and recommended size of APITEXT result buffer
(including last character)
APIMAXBINARY Maximum and recommended size of APIBINARY result buffer
for apiResultBinary
APIMAXBINARYEXT Maximum and recommended size of APIBINARY result buffer
for apiResultBinaryExt
APIMAXFILENAME Maximum and recommended size of file names (including final
character)
APIBUSY BUSY status of EDIABAS

Visual Basic: APIBUSY_

APIREADY READY status of EDIABAS

Visual Basic: APIREADY_

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 59 of 106

APIBREAK BREAK status of EDIABAS

Visual Basic: APIBREAK_

APIERROR ERROR status of EDIABAS

Visual Basic: APIERROR_

EDIABAS_XXX_#### Error messages (see section "Error messages")

EDIABAS API Developer's Guide > API Function Primer > 3. Data types, constants and error
messages

3.3. Error messages

An EDIABAS error message comprises the following elements:

Error symbol (error origin, error number)

Error code

Default error text

When an error occurs the application program can get the error code from EDIABAS with the
function apiErrorCode() and/or the default error text with the function apiErrorText().

Each error code is assigned an error symbol that can be referenced as part of error handling in the
application program.

The error symbols are defined in API.H.

The error symbol of each error has the following structure:

EDIABAS_XXX_####

The XXX group of characters denotes the EDIABAS-internal origin area of the error, and the
number #### is the corresponding error number.

Error and program areas:

EDIABAS_API_#### API

EDIABAS_BIP_#### BEST interpreter, run-time system

EDIABAS_SYS_#### Sequential control, run-time system

EDIABAS_IFH_#### Interface handler

EDIABAS_NET_#### Network, run-time system

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 60 of 106

EDIABAS_RUN_#### ECU description file

The pseudo-error EDIABAS_ERR_NONE (error code 0) is an exception, it indicates an error-free

condition.

Document [1] gives a full list of errors together with their error symbol, error code, default error text
and a description of the error message.

EDIABAS API Developer's Guide > API Function Primer

4. API function Primer

The following pages describe the API functions in alphabetical order.

Each function description consists of four sections:

• Summary A brief description of the function, giving C/C++ syntax and arguments.

The syntax of the function for Visual Basic und the DLL interface is
defined in the files API.BAS and APIDLL.H. The syntax of the
function for C# and Visual Basic.NET is defined in the files
APINET32.DLL and APIVBNET32.DLL. These files are described
in [6].

• Remarks A detailed description of the function and its use.

• Return Describes the value returned by the function.

• Interface Lists all interfaces which support the functions (C/C++, Visual Basic, C#
and DLL interface). A detailed description on these interfaces can be
found in reference [6].

• See also Related functions.

apiBreak

apiCallBack

apiCheckVersion

apiEnd

apiErrorCode

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 61 of 106

apiErrorHandler

apiErrorText

apiGetConfig

apiInit

apiInitExt

apiJob

apiJobData

apiJobExt

apiJobInfo

apiResultBinary

apiResultBinaryExt

apiResultByte

apiResultChar

apiResultDWord

apiResultFormat

apiResultInt

apiResultLong

apiResultName

apiResultNumber

apiResultReal

apiResultsDelete

apiResultSets

apiResultsNew

apiResultsScope

apiResultText

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 62 of 106

apiResultVar

apiResultWord

apiSetConfig

apiState

apiStateExt

apiSwitchDevice

apiTrace

EDIABAS API Developer's Guide > API Function Primer > 4. API function Primer

apiBreak

Summary Aborts job in progress

void apiBreak ( )

Remarks The function apiBreak() can be used to abort an ongoing job execution
(automatic call with apiEnd()). Any results are lost.

Return -

Interface C/C++ Visual Basic C# DLL

Summary Installs a call-back routine in the application program (optional)

void apiCallBack ( APIBOOL (*action)() )

action function reference (address) of the call-back routine

Remarks The ongoing job execution can be controlled by the APIBOOL return of the
call-back routine:

Return = APITRUE Job is aborted

Return = APIFALSE Job is continued

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 63 of 106

EDIABAS only calls the call-back routine with the functions apiState/
apiStateExt or apiResultxxx!

The function apiCallBack must not be used in the EDIABAS multithreading

mode (undefined behavior)!

Return -

Interface C/C++ Visual Basic C# DLL

Summary Checks the compatibility of the API

APIBOOL apiCheckVersion ( int *versionCompatibility,

char *versionInfo)

versionCompatibility required API minimum version

versionInfo NULL or address of the version info buffer in the application

program (max. APIMAXCONFIG)

Remarks Check of the compatibility of the API returning the current API version. The
required API minimum version has to be passed in versionCompatibility
(0xMMmm: MM = major version, mm=minor version), e.g. 0x0700 for API
7.0.x. For a compatibility with the current Application Development Kit
APICOMPATIBILITYVERSION has to be passed. The current API
version is copied to the target variable versionInfo.

In case of a current API-Version < 7.0.0 an incompatible API will be

assumed. In that case an empty string will be assigned to versionInfo, if any.
The call is optional and will not be recorded in the API trace. The function
can be called before the call to apiInit/apiInitExt or between
apiInit/apiInitExt and apiEnd.
The function doesn’t influence the API error state. In case of an
incompatible or no found API no EDIABAS error will be caused.

Return APITRUE API is compatible

APIFALSE API is not compatible or API not found

Interface C/C++ Visual Basic C# DLL

Summary Cancels the application lock with EDIABAS

void apiEnd ( )

Remarks The EDIABAS run-time system is released for other applications.

The occupied storage location is returned.

Return -

Interface C/C++ Visual Basic C# DLL

Summary Identifies the current error code

int apiErrorCode ( )

Remarks This function may also be used out of apiInit() and apiInitExt(...). If apiInit
() or apiInitExt(...) return APIFALSE you can get the error code by
apiErrorCode()

Return Error code or EDIABAS_ERR_NONE if there is no error

Interface C/C++ Visual Basic C# DLL

Summary Installs an error handler function in the application program (optional).

void apiErrorHandler ( void (*action)() )

action reference of error handler (function address)

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 65 of 106

Remarks The error handler function in the application program is called by EDIABAS
whenever an EDIABAS error occurs.

The function apiErrorHandler must not be used in the EDIABAS

multithreading mode (undefined behavior)!

Return -

Interface C/C++ Visual Basic C# DLL

Summary Identifies the current error text.

const char *apiErrorText ( )

Remarks This function may also be used out of apiInit() and apiInitExt(...). If apiInit()
or apiInitExt(...) return APIFALSE you can get the error text by
apiErrorText()

Return Pointer to error text or NULL if there is no error.

Interface C/C++ Visual Basic C# DLL

Summary Interrogation of the EDIABAS configuration

APIBOOL apiGetConfig ( const char config, char buf )

config Configuration element to be interrogated

buf Buffer for configuration setting

Remarks Determination of the setting for config. APIMAXCONFIG is the maximum

number of copied characters and thus the recommended buffer size for buf.

The error status is not affected.

All configuration elements and their settings are described in reference [4].

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 66 of 106

Return APITRUE Configuration determined

APIFALSE Erroneous configuration inquiry

Interface C/C++ Visual Basic C# DLL

Return APITRUE Initializing successful, other API functions can be called.

APIFALSE Initializing failed or access denied, other API functions cannot

be called

-> Error handling in application programmed

Interface C/C++ Visual Basic C# DLL

APIBOOL apiInitExt (const char *ifh,

const char *deviceUnit,

const char *deviceApplication,

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 67 of 106

const char *configuration )

ifh interface handler (max. APIMAXFILENAME); default interface
handler if a null string is transferred
deviceUnit device name (one character); default name if a null string is
transferred
deviceApplication device application (max. APIMAXDEVICE); default application
if a null string is transferred
configuration default configuration (max. APIMAXTEXT), default
configuration in case an empty string is passed

Remarks The function apiInitExt (or apiInit) must have run successfully before other
API functions are called, except for apiErrorCode() and apiErrorText().
Those functions return the error, when apiInit() or apiInitExt(...) fails.
The runtime system is initialized and locked for other application programs
(application locking).
Setting a interface handler different from the default setting is only supported
by WIN32/WIN64. The settings for a interface handler, device name and
device application are only valid to the API end (apiEnd).
For the structure of the diagnostic interface file name, the rules

for the EDIABAS configuration apply accordingly.

Configuration settings can be set by the parameter configuration (configuration

sequence or reference to alternative configuration file).
When giving a configuration sequence, the single configurations must be
separated by ';', where space/tab characters are not permitted and all
configurations must be settable via API.
When referencing an alternative configuration file, the complete path of the
configuration file with leading '@' must be given, where all configurations
in the configuration file that cannot be set via API are ignored.
The error status is influenced.

Return APITRUE Initialization without errors; calling other API functions is

possible.

APIFALSE Faulty initialization or access denied; calling other API

functions is not possible.

-> error handling in the application program

Interface C/C++ Visual Basic C# DLL

Summary Sends a job to EDIABAS

void apiJob ( const char *ecu, const char *job, const char *para, const char *result )

ecu Name of the CU group or variant description file to be loaded (max.

APIMAXNAME)

job Job to be sent, the job name is defined in the addressed SGBD (max.
APIMAXNAME)

para Job parameter (max. APIMAXPARA) as a string, several parameters must be

separated by a semi-colon. The job parameters depend on the particular job
(job).

result Results to be identified (max. APIMAXRESULT), several results must be

separated by a semi-colon. A blank string ("") must be defined to process all
results. The results depend on the particular job.

Remarks Sends a job to EDIABAS without waiting for the job to finish executing. The
argument ecu is first processed as the name of a variant description file. If
this file (ecu.prg) does not exist it is processed as a group description file
(ecu.grp)

Return -

Interface C/C++ Visual Basic C# DLL

Summary Sends a job to EDIABAS

void apiJobData ( const char *ecu, const char *job, const unsigned char *parabuf,int
paralen, const char *result )

ecu Name of the CU group or variant description file to be loaded (max.

APIMAXNAME)

job Job to be sent, the job name is defined in the addressed SGBD (max.
APIMAXNAME)

parabuf Job parameter (max. APIMAXPARAEXT) as binary data. The job

parameters depend on the particular job

paralen Number of data bytes of the job parameter.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 69 of 106

result Results to be identified (max. APIMAXRESULT), several results must be

separated by a semi-colon. A blank string ("") must be defined to process all
results. The results depend on the particular job.

Remarks siehe apiJob

Return -

Interface C/C++ Visual Basic C# DLL

Summary Issues a job to EDIABAS

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

ecu Name of the group or variant description file to be loaded

(max. APIMAXNAME)

job Job to be issue; the job name is determined in the addressed ECU description
file (max. APIMAXNAME)

stdpara Job parameter (max. APIMAXSTDPARA) to the standard jobs

Initialisierung, Identifikation, Ende. The parameter data
depend on the respective job.

stdparalen Number of data bytes of the job parameter for the standard jobs

para Job parameters (max. APIMAXPARAEXT) as binary data. The parameter

data depend on the respective job.

paralen Number of data bytes of the job parameter.

result Results to be determined (max. APIMAXRESULT); multiple results are to be

separated with a semicolon. A blank string ("") is to be specified in order to
process all results. The results depend on the respective job.

reserved 0, reserved for extensions.

Remarks siehe apiJob, apiJobData

Return -

Interface C/C++ Visual Basic C# DLL

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 70 of 106

Summary Interrogations of the processing degree for a job

int apiJobInfo (char *infoText)

infoText NULL or address of the buffer variable in the application program

Remarks This function returns the processing degree of a job as a percent. This function
must be supported in the description file. If not, the function returns -1 as a
result (i.e., the processing degree is undefined).
Range of values: 0 ... 100 [%]
In addition, the function apiJobInfo allows for the optional query of an
information text concerning the processing degree. This function must be
supported in the description file.
APIMAXTEXT is the maximum possible length of the information text and,
consequently, the recommended buffer size of the target variable.

If the function parameter value NULL is transferred, no

additional information text query is carried through.

Return Processing degree in percent

Interface C/C++ Visual Basic C# DLL

Summary Identifies an APIBINARY result

APIBOOL apiResultBinary ( APIBINARY buf, APIWORD buflen,

const char *result, APIWORD set)

buf Address of buffer target variable in the application program

buflen Address of length target variable in the application program

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 71 of 106

result Result to be polled

set Result set number

Remarks Identifies an APIBINARY result. Waits for an ongoing job to finish

processing.
The desired result result is downloaded from the result set set in the result
field and copied to the target variable buf in the application program. The
number of copied bytes is copied to the target variable buflen.
APIMAXBINARY is the maximum number of copied characters of the
APIBINARY type and therefore the recommended buffer size of the buffer
target variables. If the result is not in APIBINARY format there is no
conversion to APIBINARY format..
Affects error status. Reading an APIBINARY result with more than
APIMAXBINARY characters causes an error.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies an APIBINARY result

APIBOOL apiResultBinaryExt ( APIBINARY buf, APIDWORD buflen,

APIDWORD bufsize,

const char *result, APIWORD set)

buf Address of buffer target variable in the application program

buflen Address of length target variable in the application program

bufsize Size of buffer target variable in the application program

result Result to be polled

set Result set number

Remarks Identifies an APIBINARY result. Waits for an ongoing job to finish

processing.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 72 of 106

The desired result result is downloaded from the result set set in the result field and copied to the
target variable buf in the application program. The number of copied bytes
is copied to the target variable buflen. The maximum number of copied
characters of the APIBINARY type is either bufsize or
APIMAXBINARY. If the result is not in APIBINARY format there is no
conversion to APIBINARY format.
Affects error status.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies an APIBYTE result

APIBOOL apiResultByte ( APIBYTE buf, const char result, APIWORD set )

buf Address of target variable in the application program

result Result to be polled

set Result set number

Remarks Identifies an APIBYTE result. Waits for an ongoing job to finish processing.
The desired result result is downloaded from the result set set in the result
field and copied to the target variable buf of the application program. If the
result is not in APIBYTE format but type conversion is possible, then it is
converted to APIBYTE format. Affects error status.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies an APICHAR result

APIBOOL apiResultChar ( APICHAR buf, const char result, APIWORD set )

buf Address of target variable in the application program

result Result to be polled

set Result set number

Remarks Identifies an APICHAR result. Waits for an ongoing job to finish processing.
The desired result result is downloaded from the result set set in the result
field and copied to the target variable buf in the application program. If the
result is not in APICHAR format but type conversion is possible, then it is
converted to APICHAR format. Affects error status.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies an APIDWORD result

APIBOOL apiResultDWord ( APIDWORD buf, const char result,

APIWORD set )

buf Address of target variable in the application program

result Result to be polled

set Result set number

Remarks Identifies an APIDWORD result. Waits for an ongoing job to finish

processing. The desired result result is downloaded from the result set set in
the result field and copied to the target variable buf in the application
program. If the result is not in APIDWORD format but type conversion is
possible, then it is converted to APIDWORD format. Affects error status.

Visual Basic: If the result >= 2^31 (2147483648), a negative value is

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 74 of 106

consequently stored.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies the format of a result

APIBOOL apiResultFormat ( APIRESULTFORMAT buf, const char result,

APIWORD set )

buf Address of target variable in the application program

result Result to be polled

set Result set number

Remarks Identifies the format of a result. Waits for an ongoing job to finish processing.
The format of the desired result result is downloaded from the result set set
in the result field and copied to the target variable buf in the application
program.

The following result formats are possible:

APIFORMAT_CHAR

APIFORMAT_BYTE
APIFORMAT_INTEGER
APIFORMAT_WORD
APIFORMAT_LONG
APIFORMAT_DWORD
APIFORMAT_TEXT
APIFORMAT_BINARY
APIFORMAT_REAL

Affects error status.

Return APITRUE Result exists

APIFALSE Job failed or result not present

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 75 of 106

Interface C/C++ Visual Basic C# DLL

Summary Identifies an APIINTEGER result

APIBOOL apiResultInt ( APIINTEGER buf, const char result, APIWORD set )

buf Address of target variable in the application program

result Result to be polled

set Result set number

Remarks Identifies an APIINTEGER result. Waits for an ongoing job to finish

processing. The desired result result is downloaded from the result set set in
the result field and copied to the target variable buf in the application
program. If the result is not in APIINTEGER format but type conversion is
possible, then it is converted to APIINTEGER format. Affects error status.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies an APILONG result

APIBOOL apiResultLong ( APILONG buf, const char result, APIWORD set )

buf Address of target variable in the application program

result Result to be polled

set Result set number

Remarks Identifies an APILONG result. Waits for an ongoing job to finish processing.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 76 of 106

The desired result result is downloaded from the result set set in the result field and copied to the
target variable buf in the application program. If the result is not in
APILONG format but type conversion is possible, then it is converted to
APILONG format. Affects error status.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies the result name

APIBOOL apiResultName ( char *buf, APIWORD index, APIWORD set )

buf Address of target variable in the application program

index Result index

set Result set number

Remarks Identifies the result name, giving the result index and the result set. Waits for
an ongoing job to finish processing. The result name is identified from the
specified result index index (starting with 1) and the result set set of the
result field and copied to the target variable buf in the application program.
APIMAXNAME is the maximum number of copied characters and
therefore the recommended buffer size of the target variables. Affects error
status.

Return APITRUE Result exists

APIFALSE Job failed or results not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies the number of results

APIBOOL apiResultNumber ( APIWORD *buf, APIWORD set )

buf Address of target variable in the application program

set Result set number

Remarks Identifies the number of results in a result set. Waits for an ongoing job to
finish processing. The number of results is identified from the specified
result set set in the result field and copied to the target variable buf in the
application program. Affects error status.

Return APITRUE Result exists

APIFALSE Job failed or results not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies an APIREAL result

APIBOOL apiResultReal ( APIREAL buf, const char result, APIWORD set )

buf Address of target variable in the application program

result Result to be polled

set Result set number

Remarks Identifies an APIREAL result. Waits for an ongoing job to finish processing.
The desired result result is downloaded from the result set set in the result
field and copied to the target variable buf in the application program. If the
result is not in APIREAL format but type conversion is possible, then it is
converted to APIREAL format. Affects error status.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Deletes an application specific result field.

void apiResultsDelete ( APIRESULTFIELD field )

field Reference to the result field to be deleted

Remarks -

Return -

Interface C/C++ Visual Basic C# DLL

Summary Simplified identification of the number of result sets

APIBOOL apiResultSets ( APIWORD *sets )

sets Address of target variable in the application program

Remarks Simplified identification of the number of result sets (of the last job). Waits for
an ongoing job to finish processing. The number of result sets is identified
and copied to the target variable sets in the application program. The result
can also be identified with apiResultWord(sets,"SAETZE",0). Affects
error status.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Dynamic creation of a copy of the current result field

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 79 of 106

APIRESULTFIELD apiResultsNew ( )

Remarks Dynamic creation of a copy of the current result field. Can only create one
copy of the current result field. Waits for an ongoing job to finish
processing. Affects error status.

Return Reference to created result field copy or NULL in the event of an error.

Interface C/C++ Visual Basic C# DLL

Summary Switches to an application specific result field

void apiResultsScope ( APIRESULTFIELD field )

field Reference to the result field to be switched.

Remarks Switches to an application specific result field. The lock onto the result field
persists until the next job or apiResultsScope function call.

Return -

Interface C/C++ Visual Basic C# DLL

Summary Identifies an APITEXT result

APIBOOL apiResultText ( APITEXT *buf, const char *result, APIWORD set, const
char *format )

buf Address of target variable in the application program

result Result to be polled

set Result set number

format Desired format of the result (max. APIMAXNAME), a blank string must be
specified to perform the default conversion.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 80 of 106

Remarks Identifies an APITEXT result. Waits for an ongoing job to finish processing.
The desired result result is downloaded from the result set set in the result
field and copied to the target variable buf in the application program.
APIMAXTEXT is the maximum number of copied characters of the
APITEXT type and therefore the recommended buffer size of the target
variable. If the buffer size is exceeded the result is limited to
APIMAXTEXT. The conversion instruction format can be used to convert
the result to the APITEXT format. If the format argument is a blank string,
then there is default conversion. Affects error status.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies the name of the loaded SGBD

APIBOOL apiResultVar ( APITEXT *ecu )

ecu Address of control unit variant buffer

Remarks Identifies the name of the loaded SGBD of the last job. Waits for an ongoing
job to finish processing. The name is identified and copied to the target
variable ecu in the application program. The name is stored in the system
result set (result set 0) as the result VARIANTE. The result can also be
identified with apiResultText(ecu,"VARIANTE",0,""). The size of the
APITEXT result copied by API can be the maximum length of the
filename. Affects error status.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Identifies an APIWORD result

APIBOOL apiResultWord ( APIWORD buf, const char result, APIWORD set )

buf Address of target variable in the application program

result Result to be polled

set Result set number

Remarks Identifies an APIWORD result. Waits for an ongoing job to finish processing.
The desired result result is downloaded from the result set set in the result
field and copied to the target variable buf in the application program. If the
result is not in APIWORD format but type conversion is possible, then it is
converted to APIWORD format. Affects error status.

Visual Basic: For a result >= 2^15 (32768) a negative value is stored.

Return APITRUE Result exists

APIFALSE Job failed or result not present

Interface C/C++ Visual Basic C# DLL

Summary Modification of the EDIABAS configuration

APIBOOL apiSetConfig ( const char config, const char value )

config Configuration element to be modified

value New configuration setting

Remarks: Modification of the configuration element config by specifying the new

configuration setting value. The modification remains valid until aborted by
API.

The error status is not affected.

All configuration elements and their setting are described in reference[4].

Return APITRUE Modified configuration

APIFALSE Erroneous modification

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 82 of 106

Interface C/C++ Visual Basic C# DLL

Summary Identifies the current status of job execution

int apiState ( )

Remarks: Affects error status.

Return Processing status

APIBUSY Job in progress

APIREADY Job ready

APIBREAK Job aborted

APIERROR Job failed

Interface C/C++ Visual Basic C# DLL

Summary Identifies the current status of job execution

int apiStateExt ( int suspendTime )

suspendTime suspend time in milliseconds

Remarks: The function optionally executes a suspension of the application. The passed
suspend time suspendTime should be understood as an optimum target
value, i.e. the use of the exact given time is not guaranteed. Passing a
suspend time of 0 milliseconds is equivalent to calling the function
apiState.

Affects error status.

Return Processing status

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 83 of 106

APIBUSY Job in progress

APIREADY Job ready

APIBREAK Job aborted

APIERROR Job failed

Interface C/C++ Visual Basic C# DLL

Summary Switches device

APIBOOL apiSwitchDevice ( const char *deviceConnection,

const char *deviceApplication )

deviceConnection Device connection (max. APIMAXDEVICE), preset connection

for transmitting a blank string
deviceApplication Device application (max. APIMAXDEVICE), preset application
for transmitting a blank string

Remarks: A device change is possible by specifying the new device connection and
device application. The new device is valid until apiEnd(), apiInit() or
apiInitExt() are called. Affects error status.

Return APITRUE Device switched

APIFALSE Switch failed

Interface C/C++ Visual Basic C# DLL

Summary Writes a message to the API trace

void apiTrace (char *msg)

msg String to be recorded (max. APIMAXTEXT).

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 84 of 106

Remarks Writes the given message msg to the API trace, if tracing is activated. Does
not affect error status.

Return -

Interface C/C++ Visual Basic C# DLL

EDIABAS API Developer's Guide > API Function Primer

5. Other Functions
More:

enableServer

closeServer

enableMultiThreading

EDIABAS API Developer's Guide > API Function Primer > 5. Other Functions

enableServer

Summary Check or suppress IFH locking

BOOL enableServer ( BOOL onOff )

onOff EDIABAS controller service call:

TRUE Check IFH locking

FALSE Suppress IFH locking

Remarks Check or suppress IFH locking. At the time of call NO application is permitted
to be registered with EDIABAS, i.e. the switch is not permitted between
apiInit()/apiInitExt() and apiEnd() of an application. The function is
available under WIN32/WIN64 (the function has no effect under WIN64).

Return TRUE onOff = TRUE:

IFH locking is enabled.

onOff = FALSE:

IFH locking is disabled.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 85 of 106

FALSE IFH locking is not available, since the EDIABAS

controller service is not running.

Interface C/C++ Visual Basic C# DLL

Summary Function ignored.

void closeServer ( )

Remarks The function call will be ignored.

Return -

Interface C/C++ Visual Basic C# DLL

Summary Switch to multi-threading mode

BOOL enableMultiThreading (onOff )

onOff New mode:

TRUE Multi-threading mode

Remarks This function can be used to switch from single-threading mode (standard) to
multi-threading mode. At the time of switch NO application is permitted to
be registered with EDIABAS, i.e. the switch must be done before the first
call to apiInit()/apiInitExt() of an application. The function is available
under WIN32/WIN64 (the function has no effect under WIN64).

Return TRUE Switch is done

FALSE Switch is not done, since the requested mode

is not supported

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 86 of 106

Interface C/C++ Visual Basic C# DLL

EDIABAS API Developer's Guide > API Function Primer

A. List of references
[1] EDIABAS: Error Reference

[2] EDIABAS: BEST/1 - Language and Interpreter

[3] EDIABAS: Transparent Mode

[4] EDIABAS: EDIABAS: User Manual

[5] EDIABAS: API Interface Description

[6] EDIABAS: API User Manual

EDIABAS API Developer's Guide

Transparent Mode Interface Description

1. Update History

2. Introduction

3. General

4. The Programming Interface

5. The TMODE Functions

A. LIST OF REFERENCES

EDIABAS API Developer's Guide > Transparent Mode Interface Description

1. Update History
Version 3.0 First Version

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 87 of 106

Version 3.0A New: SETZE_TRAP_MASK_REGISTER

New: LIES_TRAP_MASK_REGISTER

Version 3.0B Correction: SETZE_SG_PARAM_ZURUECK

instead of SETZE_SG_PARAMETER_ZURUECK

Version 4.1 revised for V4.1.0

Version 5 revised for EDIABAS V5.1.0

Version 6 revised for EDIABAS V6.0.0

Version 6a revised for EDIABAS V6.4.4

Version 7 revised for EDIABAS V7.0.0

Version 7a revised for EDIABAS V7.2.0

Version 7b revised for EDIABAS V7.2.0

EDIABAS API Developer's Guide > Transparent Mode Interface Description

2. Introduction
More:

2.1. About this Manual

2.2. Conventions

2.3. Special features, definitions, acronyms

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 2. Introduction

2.1. About this Manual

This manual describes the interface of the EDIABAS transparent mode. It has been written for use
by developers of diagnostic software who work with the API interface, and is based on the API
Interface Description [1] and the EIDBSS documentation [2]. API functions and interface functions
are only detailed so far as is necessary for an understanding of the transparent mode. The emphasis
is on descriptions of the individual TMODE functions. These functions are the jobs provided by the
special description file for the transparent mode with the name "TMODE". You will find general
information about EDIABAS and control unit description files in Reference [4].

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 2. Introduction

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 88 of 106

2.2. Conventions

The following typographical conventions are used in this manual:

Example Description
SAMPLE.B2V Upper case characters are used for filenames, registers and
operating system commands.
job, string, while Bold type is used for key words and operators of the
BEST/2 and BEST/1 languages and for API functions. In
syntax descriptions these words must be written as shown.

expression Italics designate placeholders for values to be entered by

.}
[1] Reference to a document in References.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 2. Introduction

2.3. Special features, definitions, acronyms

The abbreviations used in this and all other EDIABAS documents are explained in the
"GLOSSARY" section of the "EDIABAS User manual and installation guide".

EDIABAS API Developer's Guide > Transparent Mode Interface Description

3. General
The transparent mode of EDIABAS enables the developer of diagnostic/coding software to directly
access the interface and control units with the help of a special description file. With the transparent
mode, the data that are interchanged between the interface and the application program or between
the control unit and the application program are not processed in a control unit-specific description
file but in the application program itself.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 89 of 106

This means that the diagnostic data are accessed at message level and not at symbolic level.
EDIABAS still performs error handling however (e.g. communication errors). With the aid of the
transparent mode it is therefore possible to export existing diagnostic software to EDIABAS without
having to make structural changes to the existing application program.

The description file known as "TMODE" provides basic utilities for the transparent mode. These
utilities are referred to in the sections that follow as TMODE functions.

TMODE functions for accessing control units:

• Reset control unit parameters in the interface

• Set control unit parameters in the interface

• Set message answer length
• Get key bytes from control unit
• Send and receive a message
• Start repeated send and receive a message
• Get the current answer message after starting the repeated send of a message
• Stop repeated send and receive a message

TMODE functions for accessing the diagnostic bus interface:

• Reset interface

• Read out the interface type

• Read the interface version number
• Read out the voltage at terminal 30
• Read out the voltage at terminal 15
• Read in analog and digital values
• Set digital outputs
• Set the programming voltage
• Trigger the SI relay
• Test the diagnostic lead
• Read out the interface status
• Send a random byte string to the interface

EDIABAS API Developer's Guide > Transparent Mode Interface Description

4. The Programming Interface

The programming interface used for accessing TMODE functions consists of following API
functions:

apiJobData/apiJobExt

apiResultBinary

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 90 of 106

4.1. The API functions apiJobData/apiJobExt

4.2. The API function apiResultBinary

4.3. Application example

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 4. The
Programming Interface

4.1. The API functions apiJobData/apiJobExt

Access to the interface and beyond it to a control unit is possible by sending an API job to
EDIABAS. In the transparent mode this job always has the following structure:

apiJobData(description file, job, data buffer, data length, result)

apiJobExt( description file, job, standard data buffer, standard data length,

data buffer, data length, result, reserved)

The description file of the transparent mode is called "TMODE", and makes the link to the TMODE
functions. Each TMODE function is implemented in the description file as a separate job.

The name of the TMODE function (e.g. "SENDE_TELEGRAMM") is entered as the job (see the
section on "TMODE Functions").

Data required by the TMODE function are entered in a data buffer (e.g. message data 35,00,05,00 for
reading the identification data from the LSM control unit). Data length gives the number of data
bytes (e.g. number of data is 4 for reading the identification data from the LSM control unit).

In the transparent mode "" is always entered as the parameter result because this parameter is not
evaluated in the TMODE description file.

Using the API function apiJobExt standard data buffer must be set on “”, standard data length must
be set on 0 and reserved must be set on 0.

In transparent mode the same description file ("TMODE") is used for all control units.

Syntax:

void apiJobData(char ecu,char job,

unsigned char *parabuf,int paralen,

char *result)

Parameter:

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 91 of 106

ecu Name of transparent mode description file: "TMODE"

job Name of the TMODE function

parabuf Data bytes. The data bytes depend on the TMODE function.

paralen Number of data bytes (maximum number: APIMAXPARA)

result Results to be identified (max. length of result string: APIMAXRESULT). Several
results must be separated by a semi-colon.
A blank string ("") must be defined to process all results.
The results depend on the TMODE function.

Return: -

Example:

unsigned char telegram[APIMAXPARA]={0x35,0x00,0x05,0x00};

int telegramLength=4;

apiJobData("TMODE","SENDE_TELEGRAMM",
telegram,telegramLength,"");

Syntax:

void apiJobExt(char ecu,char job,

unsigned char *stdparabuf, int stdparalen,

unsigned char *parabuf, int paralen,
char *result, long reserved)

Parameter:

ecu Name of transparent mode description file: "TMODE"

job Name of the TMODE function

stdparabuf Data bytes for standard jobs. This parameter is not supported by

TMODE: ""

stdparalen Number of data bytes for standard jobs. This parameter is not
supported by TMODE: 0

parabuf Data bytes. The data bytes depend on the TMODE function.

paralen Number of data bytes (maximum number: APIMAXPARA)

result Results to be identified (max. length of result string: APIMAXRESULT).

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 92 of 106

Several results must be separated by a semi-colon.

A blank string ("") must be defined to process all results.
The results depend on the TMODE function.
reserved reserved: always 0

Return: -

Example:

unsigned char telegram[APIMAXPARA]={0x35,0x00,0x05,0x00};

int telegramLength=4;

apiJobExt("TMODE","SENDE_TELEGRAMM","",0,
telegram,telegramLength,"",0L);

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 4. The
Programming Interface

4.2. The API function apiResultBinary

In the transparent mode, the application programme gets the results of a job sent by the function
apiJobData/apiJobExt with the function

apiResultBinary(target address buffer, target address length, result, result set)

The target address buffer is the address of a variable in the application programme (field for data
bytes) where EDIABAS stores the result. The target address length is the address of an APIWORD
variable in the application programme where EDIABAS stores the number of bytes received. The
name of the result to be read must be entered as the parameter result (not case sensitive). The result
names are defined in the separate TMODE functions. All results are in result set 1.

The error status is affected, i.e. if an error occurs during processing then the error number and error
text can be polled by API functions (see [1]).

Syntax:

APIBOOL apiResultBinary(APIBINARY buf,APIWORD buflen,char *result, APIWORD

set )

Parameters:

buf Address of buffer target variable

buflen Address of length target variable. Up to APIMAXBINARY characters can be

transmitted
result Name of the result
set Result set number (always 1)

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 93 of 106

Return:

APITRUE Result exists

APIFALSE Job failed or result not present

Example:

APIBINARY telegram[APIMAXPARA];

APIWORD telegramLength;

apiResultBinary(telegram, &telegramLength, "SG_ANTWORT", 1);

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 4. The
Programming Interface

4.3. Application example

In this section an example in language C is used to demonstrate the part of the application program in
which utilities are requested by EDIABAS.

The first part sets the control unit parameters. No result is polled after these parameters are set
because this utility does not return a result.

The second part requests the control unit's identification data. After the message is sent the control
unit's answer message is polled.

First, a job is always sent using the API function apiJobData/apiJobExt. Then apiState is called
cyclically in a loop until EDIABAS has finished processing the job. Actions such as keyboard polling
can be executed in this loop again and again. When the job is finished the result is polled with
apiResultBinary. Depending on the return value of apiResultBinary (TRUE or FALSE), the system
continues processing the result or error handling is carried out. If no result is expected, apiState
checks whether an error has occurred when processing is finished.

unsigned char cuParameter[]= {

0x01,0x01,0x01,0x01,0x0F,0x20,0x03,0x64,0x00};

int cuParameterLength= 9;

unsigned char requestTel[] = {0x35,0x00,0x05,0x00};

int requestTelLength = 4;

APIBINARY answerTel[APIMAXBINARY];

APIWORD answerTelLength;

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 94 of 106

apiJobData("TMODE",

"SETZE_SG_PARAMETER_EIDBSS",

cuParameter,cuParameterLength,

"");

while (apiState() == APIBUSY) {

/* short program part, e.g. keyboard polling */

if (apiState() == APIREADY) {

/* continue processing result or continue program */

else {

/* error handling, e.g. with apiErrorCode */

apiJobData("TMODE","SENDE_TELEGRAMM",

requestTel,requestTelLength,

"");

while (apiState() == APIBUSY) {

/* short program part, e.g. keyboard polling */

if (apiResultBinary(answerTel, &answerTelLength, "SG_ANTWORT", 1)) {

/* continue processing answer message */

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 95 of 106

else {

/* error handling, e.g. with apiErrorCode */

EDIABAS API Developer's Guide > Transparent Mode Interface Description

5. The TMODE Functions

An essential part of the transparent mode is a description file in which all TMODE functions (e.g. set
control unit parameters, send a message etc.) are imaged on jobs. In this section each job is described
by its name, the required parameters, the result name and the result content.

Assignment of API function parameters to names in the job description:

apiJobData("TMODE",

Job <-----------> Jobname

Parameter buffer <-----------> Parameter

Parameter buffer length <-----------> Parameter

Result <-----------> "" or result name

apiResultBinary(

Target address buffer, <-----------> Result content

Target address length,

Result <-----------> Result name

Result set <-----------> 1

A string of characters of the unsigned char type is always specified as parameters. To specify
variables of the int, long etc. type, they must first be converted, in which case the first character is the
least significant and the last is the most significant character (Intel format).

The results are also specified as a string of characters of the APIBINARY type. If the results are to
be interpreted as variables of the int, long etc. type, they must also be converted first. The results
are also specified in Intel format.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 96 of 106

5.1. Overview of all TMODE functions

5.2. INITIALISIERUNG

5.3. SETZE_INTERFACE_ZURUECK

5.4. SETZE_SG_PARAM_ZURUECK

5.5. SETZE_SG_PARAMETER_ALLG

5.6. SETZE_SG_PARAMETER_EIDBSS

5.7. SETZE_ANTWORTLAENGE

5.8. HOLE_KEYBYTES

5.9. SENDE_TELEGRAMM

5.10. SENDE_TELEGR_WIEDERHOLT

5.11. HOLE_ANTWORT_TELEGR

5.12. STOPPE_WIEDERH_ANFORDERUNG

5.13. LESE_INTERFACE_TYP

5.14. LESE_INTERFACE_VERSION

5.15. LESE_SPANNUNG_KL30

5.16. LESE_SPANNUNG_KL15

5.17. LESE_PORT

5.18. SETZE_PORT

5.19. SETZE_PROGRAMMIERSPANNUNG

5.20. SETZE_SIA_RELAIS

5.21. TESTE_DIAGNOSELEITUNG

5.22. HOLE_INTERFACE_STATUS

5.23. REICHE_AN_INTERFACE_DURCH

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 97 of 106

5.24. SETZE_TRAP_MASK_REGISTER

5.25. LIES_TRAP_MASK_REGISTER

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.1. Overview of all TMODE functions

• INITIALISIERUNG

• SETZE_INTERFACE_ZURUECK

• SETZE_SG_PARAM_ZURUECK

• SETZE_SG_PARAMETER_ALLG

• SETZE_SG_PARAMETER_EIDBSS

• SETZE_ANTWORTLAENGE

• HOLE_KEYBYTES

• SENDE_TELEGRAMM

• SENDE_TELEGR_WIEDERHOLT

• HOLE_ANTWORT_TELEGR

• STOPPE_WIEDERH_ANFORDERUNG

• LESE_INTERFACE_TYP

• LESE_INTERFACE_VERSION

• LESE_SPANNUNG_KL30

• LESE_SPANNUNG_KL15

• LESE_PORT

• SETZE_PORT

• SETZE_PROGRAMMIERSPANNUNG

• SETZE_SIA_RELAIS

• TESTE_DIAGNOSELEITUNG

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 98 of 106

• HOLE_INTERFACE_STATUS

• REICHE_AN_INTERFACE_DURCH

• SETZE_TRAP_MASK_REGISTER

• LIES_TRAP_MASK_REGISTER

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.2. INITIALISIERUNG

Jobname: INITIALISIERUNG
Parameters: None
Result name: DONE
Result contents: Value 1 as a 2-byte number
Description: This job is called automatically whenever the description file is loaded or an
EDIABAS error has occurred. It defines which interface is connected. This
job requires the result DONE that is interpreted by the EDIABAS system. In
the transparent mode this result is always 1.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.3. SETZE_INTERFACE_ZURUECK

Jobname: SETZE_INTERFACE_ZURUECK
Parameters: None
Result name: -
Result contents: None
Description: This job puts the interface in the initialising state and tests the diagnostic
interface. The EDIC (IDBSS) will not accept a command for about 2 seconds
after the job.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.4. SETZE_SG_PARAM_ZURUECK

Jobname: SETZE_SG_PARAM_ZURUECK
Parameters: None
Result name: -
Result contents: None

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 99 of 106

Description: This job breaks off communication with a control unit and cancels the
communication parameters. Any message from the control unit still stored in
the EDIC (IDBSS) is lost.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.5. SETZE_SG_PARAMETER_ALLG

Jobname: SETZE_SG_PARAMETER_ALLG
Parameters: The communication parameters are defined as the parameters.
You will find a detailed description of the parameters in [7] in the description
of the set_communication_pars function.
Result name: -
Result contents: None
Description: This job sets the communication parameters required for communicating with a
control unit. The parameter format is independent from the interface. Once
parameters are set with this job it is not necessary to change the user software
when there is a change of interface. The job must be called before any new
control unit is addressed. As well as the communication parameters the
message leader is filled with default values in EDIABAS depending on the
set concept. See 5.7 for further details about message leaders.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.6. SETZE_SG_PARAMETER_EIDBSS

Jobname: SETZE_SG_PARAMETER_EIDBSS
Parameters: The communication parameters are defined as the parameters. The parameters
must have the format requested by the EIDBSS application on the EDIC, see
[2]. The check bytes are not transferred.
Result name: -
Result contents: None
Description: This job sets the communication parameters required for communicating with a
control unit. The parameter format is dependent on the interface. Once
parameters are set with this job the user software must be changed when
there is a change of interface. The job must be called before any new control
unit is addressed. As well as the communication parameters the message
leader is filled with default values in EDIABAS depending on the set
concept. See 5.7 for further details about message leaders.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.7. SETZE_ANTWORTLAENGE

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 100 of 106

Jobname: SETZE_ANTWORTLAENGE
Parameters: The message leader is defined as the parameter. The message leader consists of
two parameters, each comprising two bytes. The first parameter is the answer
length and the second is the answer offset.
Answer length: This indicates the length of the anticipated CU answer.

concepts 1, DS1, DS2 and concept 3:

positive: number of anticipates bytes in answer message from CU

(constant answer length)
negative: position of answer length in answer message (from byte 0)
(variable answer length)

concept 2 and 4:

Maximum number of blocks that contain the desired information. If zero is

specified as the answer length then all answer blocks including the first
acknowledge block will be collected up.

Answer offset: Variable answer length with concept 1, DS1, DS2 only.
The answer length is computed as follows:
Length = (answer length + 1) + answer offset
Default value for the message leader after the control unit parameters are set:

Concept Length Offset

1 -2 0
3 52 0
5,6 (DS1,DS2) -1 0
2,4 1 0
others 1 0

Result name: -
Result contents: None
Description: When it sends a message the interface needs a message leader containing
information about the anticipated answer length and answer offset. This
information is the same for most CU messages. By setting the leader with
SETZE_ANTWORTLAENGE the user can avoid having to transmit it with
every message. The leader is automatically set at the beginning of the
message when it is sent. If the user does not set a leader the system uses the

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 101 of 106

default values used by EDIABAS to set the communication parameters.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.8. HOLE_KEYBYTES

Jobname: HOLE_KEYBYTES
Parameters: None
Result name: KEYBYTES
Result contents: Control unit keybytes
Description: This job reads the key bytes and identification data from a concept 2, concept 3
or a concept 4 control unit. The control unit is woken up automatically if it
has not yet been triggered.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.9. SENDE_TELEGRAMM

Jobname: SENDE_TELEGRAMM
Parameters: Control unit message according to the CU specifications. The checksum is
omitted with concept 2, DS1 and DS2 control units. The ETX at the block
end is omitted with concept 2 and concept 4 control units.
Result name: SG_ANTWORT
Result contents: Control unit answer. With concept 2 and 4 control units the answer blocks are
appended to each other, omitting the last byte of each block (ETX).
Description: This job sends a message to a control unit and gets the answer.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.10. SENDE_TELEGR_WIEDERHOLT

Jobname: SENDE_TELEGR_WIEDERHOLT
Parameters: Control unit message according to the CU specifications. The checksum is
omitted with concept 2, DS1 and DS2 control units. The ETX at the block
end is omitted with concept 2 and concept 4 control units.
Result name: -
Result contents: None
Description: This job sends the defined control unit message to the control unit repeatedly.
This mode can be terminated with the job
STOPPE_WIEDERH_ANFORDERUNG. In this mode a renewed call of
SENDE_TELEGR_WIEDERHOLT or a call of SENDE_TELEGRAMM is
answered with the error message IFH_0006.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 102 of 106

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.11. HOLE_ANTWORT_TELEGR

Jobname: HOLE_ANTWORT_TELEGR
Parameters: None
Result name: SG_ANTWORT
Result contents: Control unit answer message. With concept 2 and 4 control units the answer
blocks are appended to each other, omitting the last byte of each block
(ETX).
Description: If the repeated request for control unit answers has been started with
SENDE_TELEGR_WIEDERHOLT, the answers can now be polled with
this job. It is always the current CU answer which is polled.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.12. STOPPE_WIEDERH_ANFORDERUNG

Jobname: STOPPE_WIEDERH_ANFORDERUNG
Parameters: None
Result name: -
Result contents: None
Description: This job stops the repeated sending and receiving of messages.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.13. LESE_INTERFACE_TYP

Jobname: LESE_INTERFACE_TYP
Parameters: None
Result name: TYP
Result contents: "IDBSS" or "EIDBSS"
Description: This job polls the interface type as a zero-terminating string. "EIDBSS" is the
name of the application (diagnostic software) on the EDIC.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.14. LESE_INTERFACE_VERSION

Jobname: LESE_INTERFACE_VERSION

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 103 of 106

Parameters: None
Result name: VERSION
Result contents: Version number as low and high byte
Description: This job polls the version number of the interface.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.15. LESE_SPANNUNG_KL30

Jobname: LESE_SPANNUNG_KL30
Parameters: None
Result name: SPANNUNG
Result contents: Four byte value that indicates voltage in mV.
Description: This job polls the voltage at terminal 30 in mV.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.16. LESE_SPANNUNG_KL15

Jobname: LESE_SPANNUNG_KL15
Parameters: None
Result name: SPANNUNG
Result contents: Four byte value that indicates voltage in mV.
Description: This job polls the voltage at terminal 15 in mV.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.17. LESE_PORT

Jobname: LESE_PORT
Parameters: One byte indicating the port number.
Result name: PORTWERT
Result contents: Four byte value indicating the port value.
Port 0 -5: analog input 0 - 5 (voltage in mV)
Port 6: analog input T 15 (voltage in mV)
Port 7: analog input T 30 (voltage in mV)
Port 8: jumper field (digital value)
Description: With EDIC nine ports can be read. Ports 0 to 7 are analog inputs, port 8 polls
the value of the jumper field.

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 104 of 106

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.18. SETZE_PORT

Jobname: SETZE_PORT
Parameters: The first byte indicates the port number. Bytes 2 to 4 indicate the value at which
the port is set.
Port 9: digital outputs
Result name: -
Result contents: None
Description: Ports can be set with this job. Only port 9 (digital outputs) can be set in EDIC.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.19. SETZE_PROGRAMMIERSPANNUNG

Jobname: SETZE_PROGRAMMIERSPANNUNG
Parameters: Four byte value giving the programming voltage in mV.
Result name: -
Result contents: None
Description: This job turns the programming voltage on and off. The programming voltage
level can be given in mV (0 - 3300 mV). A 0 V voltage means programming
voltage is "off", otherwise "on".

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.20. SETZE_SIA_RELAIS

Jobname: SETZE_SIA_RELAIS
Parameters: Switching time in milliseconds as a 2 byte value.
Switching time = 0x0000: de-energize permanently
Switching time = 0xFFFF: energize permanently
Result name: -
Result contents: None
Description: This job energizes the EDIC service interval relay for the specified time.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.21. TESTE_DIAGNOSELEITUNG

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 105 of 106

Jobname: TESTE_DIAGNOSELEITUNG
Parameters: None
Result name: ERGEBNIS
Result contents: Test result as a 2 byte value.
0: Error occurred
1: No error occurred
Description: This job tests the diagnostic lead; there must be a short between the RD and TD
leads.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.22. HOLE_INTERFACE_STATUS

Jobname: HOLE_INTERFACE_STATUS
Parameters: None
Result name: IF_STATUS
Result contents: Status bytes of the interface
Description: This job requests the status bytes of the interface (see [2]).

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.23. REICHE_AN_INTERFACE_DURCH

Jobname: REICHE_AN_INTERFACE_DURCH
Parameters: Job to the interface (see [2])
Result name: IF_ANTWORT
Result contents: Answer from interface
Description: This job passes the data bytes sent to the EDIABAS direct to the interface.
EDIABAS does not evaluate the answer from the interface. This job does not
evaluate the status byte from the interface.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.24. SETZE_TRAP_MASK_REGISTER

Jobname: SETZE_TRAP_MASK_REGISTER
Parameters: Sets the trap mask register with the long value defined as parameter 1.
Result name: -
Result contents: None

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020
EDIABAS API Developer's Guide Page 106 of 106

Description: This job sets the trap mask register that can handle the occurrence of an error in
the description file.

EDIABAS API Developer's Guide > Transparent Mode Interface Description > 5. The TMODE
Functions

5.25. LIES_TRAP_MASK_REGISTER

Jobname: LIES_TRAP_MASK_REGISTER
Parameters: -
Result name: TMR
Result contents: Current value of the trap mask register
Description: This job reads the trap mask register that can handle the occurrence of an error
in the description file.

EDIABAS API Developer's Guide > Transparent Mode Interface Description

A. LIST OF REFERENCES
[1] EDIABAS: API Interface Description

[2] SOFTWARE DOCUMENTATION FOR EIDBSS-BMW CU

COMMUNICATION INTERFACE
Softing GmbH, Version 1.4

[3] EDIABAS: BEST/1 - Language and Interpreter

[4] EDIABAS: User Manual and installation guide

[5] EDIABAS: BEST/2 - Language Description

[6] EDIABAS: API User Manual

[7] EDIABAS: BEST/2 - Function Primer

file:///C:/Users/sgtma/AppData/Local/Temp/~hhF68F.htm 7/16/2020

Note Autodesk Revit Mechanical - Essential PDF
No ratings yet
Note Autodesk Revit Mechanical - Essential PDF
38 pages
Javatpoint - The Best Portal To Learn Technologies: Agile
No ratings yet
Javatpoint - The Best Portal To Learn Technologies: Agile
9 pages
Go101 v1.13.m.pdf ForPrinting
No ratings yet
Go101 v1.13.m.pdf ForPrinting
585 pages
Ediabas Best Guide
No ratings yet
Ediabas Best Guide
161 pages
Ediabas - Error Ref
100% (1)
Ediabas - Error Ref
73 pages
Diagnostics With INPA
No ratings yet
Diagnostics With INPA
28 pages
Pioneer MVH-X460UI инструкция пользователя
No ratings yet
Pioneer MVH-X460UI инструкция пользователя
40 pages
Guide A - BMW INPA Installation Manual ALL Win OS
100% (1)
Guide A - BMW INPA Installation Manual ALL Win OS
60 pages
8 Function Phases in Expert Mode
No ratings yet
8 Function Phases in Expert Mode
22 pages
4 Starting WinKFPT
No ratings yet
4 Starting WinKFPT
20 pages
Lenovo Y720 User Guide
No ratings yet
Lenovo Y720 User Guide
28 pages
9 General Functions
No ratings yet
9 General Functions
14 pages
Pro C
No ratings yet
Pro C
8 pages
SAS Syntax Handout 1
No ratings yet
SAS Syntax Handout 1
2 pages
XHP Users Manual
No ratings yet
XHP Users Manual
44 pages
Mad Lab Manual
100% (2)
Mad Lab Manual
173 pages
HerunterladenAutoCAD Raster Design 2012 SCHL Sselgenerator 64 Bits DE PDF
No ratings yet
HerunterladenAutoCAD Raster Design 2012 SCHL Sselgenerator 64 Bits DE PDF
3 pages
Description and Elimination of Frequently Occurring Errors: Errors When Starting Winkfpt
No ratings yet
Description and Elimination of Frequently Occurring Errors: Errors When Starting Winkfpt
8 pages
A Hand Book ON Billing and Customer Care System IN GSM Network
No ratings yet
A Hand Book ON Billing and Customer Care System IN GSM Network
19 pages
Adding / Updating Your Vin & Aif With Tool32
100% (1)
Adding / Updating Your Vin & Aif With Tool32
5 pages
BC Hidden Menus E90 PDF
No ratings yet
BC Hidden Menus E90 PDF
17 pages
Cara Seting Relay DHCP Dlink 1510
No ratings yet
Cara Seting Relay DHCP Dlink 1510
6 pages
SEI 12-02A GT-N7100 JTAG Guide PDF
No ratings yet
SEI 12-02A GT-N7100 JTAG Guide PDF
5 pages
E92&E93 PDC Retrofit
100% (1)
E92&E93 PDC Retrofit
32 pages
10 Error Handling in WinKFPT
No ratings yet
10 Error Handling in WinKFPT
10 pages
About Winkfpt: Multiple Instancing Capability
No ratings yet
About Winkfpt: Multiple Instancing Capability
4 pages
Ediabas User's Guide
100% (2)
Ediabas User's Guide
117 pages
BMW E65 - Coding
100% (1)
BMW E65 - Coding
8 pages
Ediabas, Inpa Und Toolset Faq
No ratings yet
Ediabas, Inpa Und Toolset Faq
54 pages
GitHub - Nickmckay - LiPD-utilities - Input - Output and Manipulation Utilities For LiPD Files in Matlab, R and Python
No ratings yet
GitHub - Nickmckay - LiPD-utilities - Input - Output and Manipulation Utilities For LiPD Files in Matlab, R and Python
3 pages
Dynamics365 AdministrationGuide
100% (1)
Dynamics365 AdministrationGuide
1,097 pages
Winkfpt: Using This User's Guide and The Online Help
No ratings yet
Winkfpt: Using This User's Guide and The Online Help
3 pages
Oper
No ratings yet
Oper
11 pages
Linux Voice January 2016
No ratings yet
Linux Voice January 2016
100 pages
SAF Manual
No ratings yet
SAF Manual
3 pages
Teroson Seam Sealant Applicator Presentation
No ratings yet
Teroson Seam Sealant Applicator Presentation
8 pages
JT Practical List 2019-20
No ratings yet
JT Practical List 2019-20
3 pages
BMW E90 Cic Programing
No ratings yet
BMW E90 Cic Programing
2 pages
ReadMe CSI Etabs 2013
No ratings yet
ReadMe CSI Etabs 2013
8 pages
Load XML Files Using A DataStage Parallel Job
No ratings yet
Load XML Files Using A DataStage Parallel Job
2 pages
Using Python To Interact With The Operating System
No ratings yet
Using Python To Interact With The Operating System
2 pages
E90 Nav Bus To Pro Retrofit
No ratings yet
E90 Nav Bus To Pro Retrofit
15 pages
McMullen Steam Cleaner
No ratings yet
McMullen Steam Cleaner
16 pages
Hadoop & Big Data
No ratings yet
Hadoop & Big Data
36 pages
2017 Cofair Catalog Low Res
No ratings yet
2017 Cofair Catalog Low Res
8 pages
BMW Rheingold ISTA Download
100% (1)
BMW Rheingold ISTA Download
6 pages
IRAP Next User Guide: 1801.1 Status: Released
No ratings yet
IRAP Next User Guide: 1801.1 Status: Released
8 pages
BMW 3series E90 E91
100% (1)
BMW 3series E90 E91
5 pages
How To Update BMW Group ISPI Admin Client ISTA License
No ratings yet
How To Update BMW Group ISPI Admin Client ISTA License
4 pages
BILL AT A GLANCE 12/01/2019: Aaaffadftaafafadttttftdftdftaddffdaffatfdtdfftttfattffdtdatdtfaff
No ratings yet
BILL AT A GLANCE 12/01/2019: Aaaffadftaafafadttttftdftdftaddffdaffatfdtdfftttfattffdtdatdtfaff
4 pages
GM40AVE Series General Purpose Electromechanical Commercial Time Switches Installation & Operating Instructions
No ratings yet
GM40AVE Series General Purpose Electromechanical Commercial Time Switches Installation & Operating Instructions
4 pages
BMW ISTA-D Rheingold 4.23.14 + ISTA-SDP 4.23.12 + ISTA-BLP 4.23.12 + ISTA-P 3.67.1.006 + Tools
0% (2)
BMW ISTA-D Rheingold 4.23.14 + ISTA-SDP 4.23.12 + ISTA-BLP 4.23.12 + ISTA-P 3.67.1.006 + Tools
4 pages
D3.50 ISTA Launcher Kurzanleitung V1.3 ENG
No ratings yet
D3.50 ISTA Launcher Kurzanleitung V1.3 ENG
15 pages
Bluetooth Retrofit After 2010 - EDoc2063971788
No ratings yet
Bluetooth Retrofit After 2010 - EDoc2063971788
21 pages
Assumption of Risk, Release and Waiver of Liability: Release Participant Charity Event
No ratings yet
Assumption of Risk, Release and Waiver of Liability: Release Participant Charity Event
3 pages
SSO Logon Ticket Configuration
No ratings yet
SSO Logon Ticket Configuration
17 pages
What Is Internet?: Regulatory Bodies of Internet
No ratings yet
What Is Internet?: Regulatory Bodies of Internet
5 pages
HTML CSS PDF
No ratings yet
HTML CSS PDF
6 pages
Installation Manual PDC Е60, Е61 PDF
No ratings yet
Installation Manual PDC Е60, Е61 PDF
19 pages
Ediabas and Inpa How To Install
No ratings yet
Ediabas and Inpa How To Install
10 pages
Installation Instructions.: Original BMW Accessories
No ratings yet
Installation Instructions.: Original BMW Accessories
28 pages
Gm40Ave: 40 Amp Auto-Voltage General Purpose Time Switch
No ratings yet
Gm40Ave: 40 Amp Auto-Voltage General Purpose Time Switch
2 pages
Windows API For Red Team #101: Author
No ratings yet
Windows API For Red Team #101: Author
24 pages
BMW CIC FSC Activation
No ratings yet
BMW CIC FSC Activation
16 pages
Disassembly Using IDA
No ratings yet
Disassembly Using IDA
24 pages
Inpa Ediabas User
No ratings yet
Inpa Ediabas User
59 pages
BMW Inpa K+CAN Install
No ratings yet
BMW Inpa K+CAN Install
3 pages
Engine Electronics IPO's
No ratings yet
Engine Electronics IPO's
44 pages
Codigos BMW
No ratings yet
Codigos BMW
26 pages
Info
No ratings yet
Info
4 pages
Introduction To The Windows API
No ratings yet
Introduction To The Windows API
22 pages
3566 Bethune
No ratings yet
3566 Bethune
1 page
MyCANIC User Manual
100% (2)
MyCANIC User Manual
19 pages
X5 Navigation Retrofit
100% (1)
X5 Navigation Retrofit
37 pages
Adjustable V Block System
No ratings yet
Adjustable V Block System
1 page
Your Home Is More Than Just A Home: Built To Last Naturally Sustainable Bring Beauty To Your Home
No ratings yet
Your Home Is More Than Just A Home: Built To Last Naturally Sustainable Bring Beauty To Your Home
1 page
Eurotech: List Extended Qty Description Job Name
No ratings yet
Eurotech: List Extended Qty Description Job Name
1 page
8-Abstraction, Design Issues and Structures of OS-27!04!2023
No ratings yet
8-Abstraction, Design Issues and Structures of OS-27!04!2023
51 pages
Oracle Multitenant 19c - All About Pluggable D
0% (1)
Oracle Multitenant 19c - All About Pluggable D
67 pages
Fstool Installation Readme
No ratings yet
Fstool Installation Readme
1 page
BMW E90 GPS Setup
No ratings yet
BMW E90 GPS Setup
15 pages
Installing ESYS PDF
No ratings yet
Installing ESYS PDF
14 pages
Get 1B File From Exx CIC WITHOUT ICOM
No ratings yet
Get 1B File From Exx CIC WITHOUT ICOM
5 pages
Scripting QTP - CH13 - Win32API
100% (2)
Scripting QTP - CH13 - Win32API
22 pages
84 10 18 - Combox Information Overview
No ratings yet
84 10 18 - Combox Information Overview
7 pages
E-Sys Editors and Viewers
No ratings yet
E-Sys Editors and Viewers
9 pages
Soft Close E60 E61 DIY ENG
100% (1)
Soft Close E60 E61 DIY ENG
4 pages
BMW Codes
No ratings yet
BMW Codes
4 pages
Win32 API Programming: Amulya Acharya-7428 Pradeep Karki-7438 Manjul Bhattarai-7411
0% (1)
Win32 API Programming: Amulya Acharya-7428 Pradeep Karki-7438 Manjul Bhattarai-7411
24 pages
Information Logging Standard: 1. Overview
No ratings yet
Information Logging Standard: 1. Overview
4 pages
Alpina B3 Flash DIY With Winkfp - BMW 3-Series (E90 E92) Forum
No ratings yet
Alpina B3 Flash DIY With Winkfp - BMW 3-Series (E90 E92) Forum
7 pages
BMW 04 04 2014
No ratings yet
BMW 04 04 2014
2 pages
Installation Guide PDF
67% (3)
Installation Guide PDF
6 pages
How To Use NCS Dummy
100% (6)
How To Use NCS Dummy
43 pages
E-Sys - MacOSX Installation and Configuration
No ratings yet
E-Sys - MacOSX Installation and Configuration
4 pages
Cic FSC Ex en
No ratings yet
Cic FSC Ex en
8 pages
E9X ACC Retrofit DIY v1.1 PDF
No ratings yet
E9X ACC Retrofit DIY v1.1 PDF
12 pages
3 Jndi Notes
No ratings yet
3 Jndi Notes
14 pages
Oracle Access Manager Administration Ed 1 - Student Guide Vol I
No ratings yet
Oracle Access Manager Administration Ed 1 - Student Guide Vol I
314 pages
Most BMW Fibra Optica
No ratings yet
Most BMW Fibra Optica
6 pages
How To Hack Someone With His IP Address PDF
100% (2)
How To Hack Someone With His IP Address PDF
8 pages
E-Sys - Editors and Viewers
No ratings yet
E-Sys - Editors and Viewers
9 pages
Mastering AUTOSAR: A Comprehensive Guide for Automotive Engineers
From Everand
Mastering AUTOSAR: A Comprehensive Guide for Automotive Engineers
Mohamad Charara
No ratings yet
E-Sys - Getting Started Coding - Part 1
No ratings yet
E-Sys - Getting Started Coding - Part 1
14 pages
SI B 84 15 05 Retrofitting TCU With BT
No ratings yet
SI B 84 15 05 Retrofitting TCU With BT
3 pages
Chapter - I
No ratings yet
Chapter - I
36 pages
Exclusive DVD in Motion Activation For CIC by BMWCODING v3 PDF
No ratings yet
Exclusive DVD in Motion Activation For CIC by BMWCODING v3 PDF
6 pages
BMW Stering Angle Sensor
No ratings yet
BMW Stering Angle Sensor
3 pages
BMW E6x Code List
No ratings yet
BMW E6x Code List
10 pages
CICfscupdate PDF
100% (1)
CICfscupdate PDF
1 page
Adobe Cs6 Activation
No ratings yet
Adobe Cs6 Activation
4 pages
E60 Hidden Menu Instructions
100% (1)
E60 Hidden Menu Instructions
5 pages