Best2rtl

EDIABAS - BEST/2 FUNCTION PRIMER

EDIABAS Electronic Diagnostic Basic System

BEST/2 FUNCTION PRIMER VERSION 6d

Copyright BMW AG, created by Softing AG

BEST2RTL.DOC


CONTENTS

CONTENTS 2

1. Revision history 8

2. Introduction 9

2.1. About the Runtime Library 9

2.2. Conventions 10

2.3. Special features, definitions, acronyms 11

3. Overview 12

3.1. Using the runtime library 12

3.1.1. Calling library functions 12

3.1.2. Paths and filenames 12

3.2. Functions of the runtime library by categories 13

3.2.1. Communication functions 14

3.2.2. Interface functions 15

3.2.3. Result and parameter management 16

3.2.4. String functions 17

3.2.5. Conversion functions 18

3.2.6. Real functions 19

3.2.7. Data functions 20

3.2.8. File functions 21

3.2.9. Sequence control 22

3.2.10. Error handling 23

3.2.11. Time handling 24

3.2.12. Table handling 25

3.2.13. Configuration 26

3.2.14. Control unit specific functions 27

4. Clamp states 28

2


4. Library functions 31

4.1. Using the function primer 31

ascii2ascii 33

ascii2hex 34

atoi 35

ator 36

atoy 37

bcd2ascii 38

bittest 39

bytetest 40

callPlugIn 41

clear_error 43

close_communication 44

datacat 46

dataclear 47

datacmp 48

datacopy 49

dataerase 50

datainsert 51

datalen 52

datarevers 53

dataset 54

doNewInit 55

enableIfhTrace 56

enableIgnitionHandling 57

enableUbattHandling 58

fclose 59

fopen 60

fread 61

freadln 62

fseek 63

3


fseekln 64

ftell 65

ftellln 66

get_battery_voltage 68

get_error 69

get_error2 70

get_ignition_voltage 71

get_trap_mask 74

generateRunError 75

getasciidate 76

getasciitime 77

getCfgString 79

getdate 80

getETXblock 81

gettickcount 84

gettime 85

hex2ascii 86

ifboot 87

ifgetport 88

ifinfo 89

ifloopt 91

ifrawmode 92

ifrecv 93

ifrequeststate 94

ifreset 95

ifsend 96

ifsetport 97

ifsireset 98

iftype 99

ifvers 100

incProgressPos 101

4


isDebugLevel 102

isSimulation 103

itoad 104

itoax 105

itor 106

make_error 108

new_set_of_results 109

open_communication 110

parcount 111

realadd 113

realdiv 115

realmul 116

realresult 117

realsub 118

recv_frequent 119

recv_keybytes 120

rtoa 121

rtoi 122

send_and_receive 123

send_frequent 124

set_answer_length 125

set_communication_pars 128

set_program_voltage 146

set_repeat_counter 147

set_trap_mask 148

set_variable_result 151

setProgressRange 152

shdataget 153

shdataset 154

stop_frequent 155

strcat 156

5


strcmp 157

strcpy 158

strcut 159

strerase 160

strinsert 161

strlen 162

strncpy 163

strrevers 164

tab2fix 165

tab_suche_index 166

tabget 169

tabline 170

tabseek 171

tabset 172

tabsetext 173

updateInfo 175

userbreak 176

var_result_data 177

var_result_long 178

var_result_real 179

var_result_string 180

wait 181

waitex 182

LIST OF REFERENCES 183

6


7


1. Revision history

Version 5b Revision history is new New chapter 3 (chapter 3 renamed as chapter 4, etc.)

Version 5e New functions: rtoi, updateInfo, setProgressRange, incProgressRange

Version 5f New function: ascii2ascii Version 6 New functions data_to_real, real_to_data, tab_suche_unsigned,

ifinfoExt, realcomp, AdjustKWP2000TesterPr-StartComm, GetKWP2000Block, GetKWP2000BlockIndex, linkPlugIn, callPlugIn, callPlugInExt, set_communication_pars

Version 6a Description of GetKWP2000Block reworked, function GetKWP2000BlockIndex is dropped.

Version 6b In set_communication_pars concept KWP 2000* new.

Version 6d Revised for EDIABAS V6.4.4

8


2. Introduction

2.1. About the Runtime Library The runtime library provides functions for control unit communication, string handling and error handling for use in BEST/2 description files. These functions provide

access to the interface handler access to external data access to host system functions (e.g. time) and functions that are regularly needed for general programming tasks (e.g.

strings).

This runtime library is very important because it provides facilities which the rudimentary BEST/2 language does not have.

All functions have been generated in BEST/1 to avoid performance losses!

9


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.

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 the programmer; e.g., file names.

[option] Words enclosed in square brackets may be optionally specified.

{ result | argument }

Curvy braces and vertical strokes characterize entries from 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.

10


2.3. Special features, definitions, acronyms The job INITIALISIERUNG (initialize) that is needed for correct operation has been omitted from all the examples in this manual.

BEST/2 is the abstract name for the programming language for description files. However BEST2 refers to the compiler as a command at operating system level (cf. "C" <-> "C Compiler" <-> "CC").

The terms function, routine and command have equivalent status in this manual, and refer to self-contained function units in the runtime library.

The term host refers to the computer and operating system on which the EDIABAS runtime system is started.

11


3. Overview

3.1. Using the runtime library

3.1.1. Calling library functions To use a library function in a BEST/2 description file we simply call it in a job with the required parameters. For example, we can write the following job in a description file:

job ( name : SAMPLE; ...) { char buffer[]; ... getasciidate(buffer); . }

This job identifies the current date by means of the getasciidate function and writes it to the variable buffer.

3.1.2. Paths and filenames BEST2 uses B2RUNTIM.LIB as its default runtime library. Although this is expected to be in the same directory as the BEST/2 compiler, another library can be specified with the -L option when calling BEST2.

BEST2 -L \test\dev\neulib.lib test.b2v

This command line calls the BEST/2 compiler which will compile the description file test.b2v in the current directory. It uses the library NEULIB.LIB in the \TEST\DEV directory.

12


3.2. Functions of the runtime library by categories BEST/2 library functions cover a range of job areas. If you know what the task is but do not know exactly which function you need you can search for it in the following sections. The "library functions" section gives a complete function description including syntax and examples.

Essentially, the following function categories are available:

Communication functions Interface functions Result / parameter management String functions Conversion functions Data functions File functions Error handling Time handling Table handling Configuration Functions specific to the ECU

13


3.2.1. Communication functions Communication functions are used to communicate with the control unit. They provide the facility of the interface handler contained in EDIABAS.

Function Purpose

open_communication Opens communication with the interface

close_communication Closes communication with the interface

set_communication_pars Sets communication parameters

set_answer_length Sets the answer length of one or all telegrams

send_and_receive Sends and receives a telegram

recv_keybytes Gets the control unit key bytes

send_frequent Automatic repeat sending of a telegram

recv_frequent Receives a repeat telegram

stop_frequent Stops repeat sending

set_repeat_counter Sets the repeat counter for repeats in the event of an error

14


3.2.2. Interface functions Interface functions are used as an interface with the functions of the diagnostic bus interface. They provide the facility of the interface handler contained in EDIABAS.

Function Purpose

get_battery_voltage Reads out the battery voltage

get_ignition_voltage Reads out the ignition voltage

set_program_voltage Sets the programming voltage

ifboot Resets the interface (warm start)

ifreset Resets the communication parameters

ifgetport Reads out a port

ifsetport Sets a port

ifloopt Tests the diagnostic lead

ifsireset Sets the SIA relay

ifrequeststate Reads out the interface state

iftype Reads out the interface type

ifvers Reads out the interface version

ifrawmode Transmits any desired characters to the interface

ifsend For debugging only

ifrecv For debugging only

ifinfo For debugging only

ifinfoExt For debugging only

15


3.2.3. Result and parameter management These functions are used to manage results and parameters

Function Purpose

new_set_of_results Signals a new result set

parcount Identifies the number of parameters

set_variable_result Produces a result with variable names

var_result_data Produces a data result with variable names

var_result_long Produces a "long" result with variable names

var_result_real Produces a "real" result with variable names

var_result_string Produces a "string" result with variable names

updateInfo Produces a "string" result as the job is being processed

setProgressRange Sets a range for the progress counter

incProgressPos Increases the current position of the progress counter

16


3.2.4. String functions The string functions are used to manage and process C-compatible strings. These strings must end with the zero character ('\0').

Function Purpose

strcat Catenates strings

strcut Shortens strings

strcmp Compares strings

strcpy Copies strings

strncpy Copies a string with length specification

strlen Identifies the string length

strerase Erases a part string

strinsert Inserts a part string

get_token Searches for a token

strrevers Reverses a string

17


3.2.5. Conversion functions The conversion functions are used to convert data from an integer to a string form.

Function Purpose

ascii2hex Converts a string to a binary array

ascii2ascii converts characters to characters of a different code page

atoi Converts a string to an integer

atoy Converts a string to a binary array

bcd2ascii Converts a BCD chain to a BCD string

hex2ascii Converts a hex chain to a hex string

itoad Converts an integer to a decimal string

uitoad Converts an unsigned integer to a decimal string

itoax Converts an integer to a hexadecimal string

18


3.2.6. Real functions The real functions are used to process real numbers.

Function Purpose

itor Converts an integer to a real number

ator Converts a string to a real number

realcomp Compares two real numbers

realadd Adds two real numbers

realsub Subtracts two real numbers

realmul Multiplies two real numbers

realdiv Divides two real numbers

realresult Generates a real result

rtoa Converts a real number to a string

rtoi Converts a real number into an integer

data_to_real Converts data bytes into a real number

real_to_data Converts a real number into data bytes

19


3.2.7. Data functions Data functions move and set data. Unlike strings this data does not end on a zero.

Function Purpose

datacat Appends data bytes to a buffer

dataclear Clears a buffer

datacmp Compare bytes of two buffers

datacopy Copies bytes from one buffer to another

dataerase Erase data bytes from a buffer

datainsert Inserts bytes into a buffer

datalen Identifies the length of a buffer

datarevers Reverses data in a buffer

dataset Sets bytes in a buffer

shdataget Read (get) the global data memory

shdataset Write (set) the global data memory

20


3.2.8. File functions File functions provide read access to files in the host system.

Function Purpose

fopen Opens a file

fclose Closes a file

fread Reads a character from a file

freadln Reads a line from a file

fseek Sets the read position in a file (byte by byte)

fseekln Sets the read position in a file (line by line)

ftell Identifies the read position in a file (byte by byte)

ftelln Identifies the read position in a file (line by line)

21


3.2.9. Sequence control

This function enables access in the job sequence control; i.e., when and in which order standard jobs are called.

Function Purpose

doNewInit Forces the job INITIALISIERUNG before the next job call

22


3.2.10. Error handling The description file can handle error messages with these functions.

Function Purpose

clear_error Clears the error flag

get_error Identifies the error number

get_error2 Identifies the error number

make_error Issue an error

generateRunError Issues error “RUN-00XX”

set_trap_mask Sets the error trap mask

get_trap_mask Reads out the error trap mask

userbreak Produce the error message "BIP-0008: BEST BREAK"

23


3.2.11. Time handling The time handling functions make it possible to access the current time and date, among other options.

Function Purpose

gettime Gets the current time

getdate Gets the current date

getasciitime Gets the current time as an ASCIIZ string

getasciidate Gets current date as an ASCIIZ string

gettickcount Gets tick counter value of millisconds

wait Waits n seconds

waitex Waits n milliseconds

24


3.2.12. Table handling These functions are used to evaluate the constant tables defined in BEST/2.

Function Purpose

tabset Initializes table handling

tabsetext Initializes table handling of an ECU description file (SGBD)

Tabseek Searches a string in the current table

tab_suche_index Searches an integer string in the current table

tab_suche_unsigned Searches an unsigned integer string in the current table

Tabline Jumps to the specified line in the table

tabget Reads out values from the current table line

tab2fix Reads out values from the current table line and converts to an integer

bittest Special function for identifying bit results

bytetest Special function for identifying byte results

25


3.2.13. Configuration

These functions are used to set and read the EDIABAS configuration.

Function Purpose

enableIfhTrace Enable/disable the IFH-Trace

enableIgnitionHandling Enable/disable the ignition monitoring

enableUbattHandling Enable/disable battery monitoring

getCfgInt Read (get) a configuration setting as an integer

getCfgString Read (get) a configuration setting as a string

isDebugLevel Interrogation of the configuration element "BipDebugLevel"

isSimulation Interrogation of the configuration element "Simulation"

26


3.2.14. Control unit specific functions These functions are used to evaluate control unit answer telegrams.

Function Purpose

AdjustKWP2000TesterPr-StartComm

Adapts the TesterPresent and StartCommunication telegrams using the ECU address in the parameters

GetKWP2000Block Reads out a block from the response telegram of a control unit with KWP 2000

getETXblock Reads out a block from the answer telegram of a control unit

27


4. Clamp states

All functions of the Interface Handler which communicate with the interface are listed below. Specification is made for each function as to which error messages are generated based on the EDIC terminal states and which response is made to the error message. If the UBattHandling or IgnitionHandling is disabled in configuration file EDIABAS.INI, neither the error messages UBATT ON/OFF ERROR (or IGNITION ON/OFF ERROR) are generated due set history bits nor is the communicaiton aborted (and the terminal states reset) as response to this. The system results IGNITIONCURRENT; UBATTCURRENT; IGNITIONHISTORY; UBATTHISTORY are onlyassigned the values (0,1) for the current state of the terminal states when at least one of the following functions is executed in the job (except the function ifrawmode). If none of the following functions are executed in the job, the system results above are always labeled as undefined (-1).

Function Error messages Response

set_communication_pars

WRONG UBATT UBATT ON/OFF ERROR IGNITION ON/OFF ERROR

Only in case of error:

Abort active communication with the ECU and reset the terminal states

send_and_receive WRONG UBATT UBATT ON/OFF ERROR IGNITION ON/OFF ERROR


Abort active communication with the ECU and reset the terminal states

28


recv_keybytes WRONG UBATT UBATT ON/OFF ERROR IGNITION ON/OFF ERROR


Abort the active communication with the ECU and reset the terminal states

send_frequent WRONG UBATT UBATT ON/OFF ERROR IGNITION ON/OFF ERROR



recv_frequent WRONG UBATT UBATT ON/OFF ERROR IGNITION ON/OFF ERROR



stop_frequent None None

get_battery_voltage None None

get_ignition_voltage WRONG UBATT None

set_program_voltage

None None

29


ifboot None Always:

The active communication with the ECU is always aborted, and the terminal states are always reset.

ifreset None Always:

The active communicaiton with the ECU is always aborted, and the terminal states are always reset.

ifgetport None None

ifsetport None None

ifloopt None None

ifsireset None None

ifrequeststate None None

ifvers None None

ifrawmode None None

30


4. Library functions

4.1. Using the function primer This section describes the BEST/2 runtime library functions in alphabetical order. Related functions are described together in many cases.

Each function description comprises the following sections:

Summary Summarizes what the function does, illustrates its syntax and briefly describes its arguments.

Remarks A detailed description of the function and its use.

Return value Describes the value that is returned by the function.

See also Refers the reader to related functions.

Example Shows an extract from a job to explain the function's use.

Result The results or effects of the example.

In the description of the arguments, (V) means that a variable must be specified, (C) means that a constant must be specified.

This section lists all the functions of the BEST/2 runtime library in alphabetical order.

31


AdjustKWP2000TesterPrStartComm Summary

void AdjustKWP2000TesterPrStartComm(char params[])

params KWP 2000 parameters in the raw format for EDIC API (V)

Remarks This function enters the control unit address in position 5 of the TesterPresent and StartCommunication telegram parameters and recalculates the checksums in these telegrams.

Return value -

See also -

Example { char parameter[]; parameter = kwp_2000_parameter; parameter[5] = ecuAddress; AdjustKWP2000TesterPrStartComm(parameter);

}

Result -

32


ascii2ascii Summary Converts all text characters into another character set.

void ascii2ascii(char codepage[],char text[])

codepage Character set text String buffer(V)

Remarks This function converts all characters in the string into characters with another ASCII code. Characters are converted according to the passed code page..

Return value -

See also -

Example unsigned char codepage[] = { // 0 1 2 3 4 5 6 7 8 9 A B C D E F /*0*/ 0x00,0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,0x0E,0x0F, /*1*/ 0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,0x1C,0x1D,0x1E,0x1F, /*2*/ 0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x29,0x2A,0x2B,0x2C,0x2D,0x2E,0x2F, /*3*/ 0x30,0x31,0x32,0x33,0x34,0x35,0x36,0x37,0x38,0x39,0x3A,0x3B,0x3C,0x3D,0x3E,0x3F, /*4*/ 0x40,0x41,0x42,0x43,0x44,0x45,0x46,0x47,0x48,0x49,0x4A,0x4B,0x4C,0x4D,0x4E,0x4F, /*5*/ 0x50,0x51,0x52,0x53,0x54,0x55,0x56,0x57,0x58,0x59,0x5A,0x5B,0x5C,0x5D,0x5E,0x5F, /*6*/ 0x60,0x61,0x62,0x63,0x64,0x65,0x66,0x67,0x68,0x69,0x6A,0x6B,0x6C,0x6D,0x6E,0x6F, /*7*/ 0x70,0x71,0x72,0x73,0x74,0x75,0x76,0x77,0x78,0x79,0x7A,0xE4,0xF6,0xFC,0xDF,0x7F, /*8*/ 0x80,0x81,0x82,0x83,0x84,0x85,0x86,0x87,0x88,0x89,0x8A,0x8B,0x8C,0x8D,0x8E,0x8F, /*9*/ 0x90,0x91,0x92,0x93,0x94,0x95,0x96,0x97,0x98,0x99,0x9A,0x9B,0x9C,0x9D,0x9E,0x9F, /*A*/ 0xA0,0xA1,0xA2,0xA3,0xA4,0xA5,0xA6,0xA7,0xA8,0xA9,0xAA,0xAB,0xAC,0xAD,0xAE,0xAF, /*B*/ 0xB0,0xB1,0xB2,0xB3,0xB4,0xB5,0xB6,0xB7,0xB8,0xB9,0xBA,0xBB,0xBC,0xBD,0xBE,0xBF, /*C*/ 0xC0,0xC1,0xC2,0xC3,0xC4,0xC5,0xC6,0xC7,0xC8,0xC9,0xCA,0xCB,0xCC,0xCD,0xCE,0xCF, /*D*/ 0xD0,0xD1,0xD2,0xD3,0xD4,0xD5,0xD6,0xD7,0xD8,0xD9,0xDA,0xDB,0xDC,0xDD,0xDE,0xDF, /*E*/ 0xE0,0xE4,0xDF,0xE3,0xE4,0xE5,0xE6,0xE7,0xE8,0xE9,0xEA,0xEB,0xEC,0xED,0xEE,0xF6, /*F*/ 0xF0,0xF1,0xF2,0xF3,0xF4,0xFC,0xF6,0xF7,0xF8,0xF9,0xFA,0xFB,0xFC,0xFD,0xFE,0xFF }; unsigned char text[] = {0x7B,0xE1,0x7C,0xEF,0x7D,0xF5,0x7E,0xE2}; { ... ascii2ascii(codepage,text); ... }

Result text = {0xE4,0xE4,0xF6,0xF6,0xFC,0xFC,0xDF,0xDF} //ääööüüßß

33


ascii2hex

Summary Converts a hex string into a sequence of bytes

long ascii2hex(char destin[],char source[],int pos)

destin Destination buffer(V) source String buffer pos Position in the destination buffer

Remarks Converts a zero-terminated string source into a sequence of bytes and inserts these in destin beginning at byte position pos. In this process, all characters of the string buffer are converted. Abortion occurs in the case of invalid characters or in case of an uneven number of characters. In the case of an error, destin contains all converted bytes up to the erroneous character.

Return value 0: Source contains invalid characters 1: Source contains only valid characters

See also atoi, atoy, bcd2ascii, itoad, itoax

Example { char source[] = "00FF"; char destin[] = { 0x12, 0x34, 0x56, 0x78 }; ascii2hex(destin,source,1}; ... }

Result destin = { 0x12, 0x00, 0xFF, 0x78 }

34


atoi Summary Converts a string to a value

long atoi(char number[]);

number The string to be converted

Remarks The atoi function converts a string into an integer. If the string begins with the characters "0x" or "0X" then it is interpreted as a hexadecimal number. If the string begins with the characters "0y" or "0Y" then it is interpreted as a binary number. In all other cases the string is interpreted as a decimal number. Conversion is aborted at the first character that does not match the number format.

Return value The converted value (2^31 maximum)

See also atoy, itoad, itoax, bcd2ascii, hex2ascii, ascii2hex

Example { long hexnumber; long binnumber; long deznumber; hexnumber=atoi("0x77"); binnumber=atoi("0y01110110"); deznumber=atoi("014"); ... }

Result hexnumber = 0x77 = 119 binnumber = 0x76 = 118 deznumber = 0x0e = 14

35


ator Summary Converts a string to a real number

void ator(real destin, char value[]);

destin Real number to accept the conversion result value The string to be converted

Remarks The ator function converts a string into an integer. The string is interpreted as a real number. It can have the following format:

[{sign}][digits][{.|,}digits][{d|D|e|E}[sign]digits] sign is either '+' or '-'. digits are one or more digits.

Conversion is aborted at the first character that does not match the number format.

Return value The converted value (maximum double = 1.7E ± 308 (15 digits)).

See also rtoi, rtoa, realadd, realsub, realmul, realdiv

Example { real realnumber; ator(realnumber,"1.22e01"); ... }

Result realnumber = 12.2

36


atoy Summary Converts a string into a binary array.

long atoy(char binary[],char ascii[]);

binary Buffer for binary data ascii String to be converted

Remarks The atoy function converts a string into a binary array. The ASCII string uses the format: [AA] { },{ } [AB] { },{ } … Conversion is aborted at the first character which does not match the format.

Return value The number of binary data in binary.

See also atoi, itoad, itoax, bcd2ascii, hex2ascii, ascii2hex

Example { char ascii[]; char binary[]; ascii="aa,bb,cc,00,01" atoy(binary,ascii); }

Result binary = { 0xAA, 0xBB, 0xCC, 0x00, 0x01 }

37


bcd2ascii Summary Converts a chain of characters to a BCD string

void bcd2ascii(char destin[], char source[], int index, int count)

destin String buffer(V) source Buffer index Position in source buffer count Number of bytes to be converted

Remarks Converts a chain of bytes (two nibbles) from the source buffer source, starting from the byte position index, into a zero-terminated BCD string destin. count nibbles are converted from the source buffer. An '*' stands in the destination string for nibbles with a value greater than hexadecimal 9 (A..F).

Return value -

See also atoi, atoy, itoad, itoax, hex2ascii, ascii2hex

Example { char source[]={ 0x12, 0x34, 0xFF, 0x78, 0x90 }; char destin []; bcd2ascii(destin,source,2,5}; ... }

Result destin = "34**7*"

38


bittest Summary Identifies bit results via a table

long bittest(char name[], char source[], long value)

name Result name source Buffer to be analyzed value Test result

Remarks You must have a table with the columns NAME, BYTE, MASK, VALUE. Table processing must first have been set to this table using the tabset function. The BYTE column indicates which byte in source is to be looked at. The appropriate bits (the bits to be looked at) must be masked in the MASK column. In the VALUE column enter the value which the bits must have to make the status NAME true. The result value is TRUE (1) when all the bits set in MASK have the value specified in VALUE, otherwise it is FALSE (0).

Return value TRUE (1) when the result name was found in the table, otherwise FALSE (0)

See also bytetest

Example table bits[4][]={ { "NAME", "BYTE" , "MASK" , "VALUE" }, { "XON", "0", , "0x07" , "0x06" }, { "XOFF", "0", , "0x07" , "0x01" } }; { int xonvalue; int xoffvalue; char buffer[]; buffer[0]=0x06; tabset("bits"); bittest("XON",buffer,xonvalue); bittest("XOFF",buffer,xoffvalue); }

Result xonvalue = 1 xoffvalue = 0

39


bytetest Summary Identifies byte results via a table

long bytetest(char name[], char source[], long value, long div)

name Result name source Buffer to be analyzed value Test result div Divider

Remarks You must have a table with the columns NAME, BYTE, MIN, MAX, MINDEF, MAXDEF, A, B, DIV. Table processing must first have been set to this table using the tabset function. The BYTE column indicates which byte in source is to be looked at. The MIN and MAX columns indicate the lower and upper limits of the byte in source. If the limits are breached then the value in the MINDEF or MAXDEF columns is returned. If the value of the byte is within the defined limits then the returned value is calculated according to the formula A*x + B. The divider in the DIV column is returned in div. It indicates the value by which the result has to be divided in order to get a correct result.

Return value 0 = in valid range 1 = over range -1 = under range

See also bittest

Example table bytes[3][]={ {"NAME","BYTE","MIN", "MAX", "MINDEF", "MAXDEF","A","B","DIV"}, {"TEMP","0", "07" , "254","-40", "120", "-4","8","1" }}, ... int tempvalue; int tempdiv; char buffer[]; buffer[0]=0x06; tabset("bytes"); bytetest("TEMP",buffer,tempvalue,tempdiv); }

Result tempvalue = -40 tempdiv = 1

40


callPlugIn Summary Calls the main function within the Plugin component.

void callPlugIn(char dataOut[],char dataIn[]);

dataOut input data (V) dataIn output data

Remarks The callPlugIn function calls the main function within the Plugin component. The Plugin component provides the content for the string variable dataOut.

Return value -

See also linkPlugIn, callPlugInExt

Example { char name[]; char dataIn[]; char dataOut[]; long funcID; long status; ... linkPlugIn(name); ... callPlugIn(dataOut,dataIn); ... status = callPlugInExt(funcID,dataOut,dataIn); ... }

Result -

41


callPlugInExt Summary Calls the main function within the Plugin component.

long callPlugInExt(long funcID,char dataOut[],char dataIn[]);

funcID Subfunction number within the Plugin component dataOut Input data dataIn Output data

Remarks The callPlugInExt function calls a subfunction within the Plugin component. The Plugin component provides the content for the string variable dataOut. For this function, the length of dataOut and dataIn is limited to 1019 bytes since 4 bytes of the string variable are needed internally for the subfunction number and the status.

Return value Subfunction status

See also linkPlugIn, callPlugIn


Result -

42


clear_error Summary Clears the error flag

void clear_error()

Remarks The clear_error function clears the error flag. This function must be called when an error has been masked. It clears the entry in EDIABAS that an error had occurred.

Return value -

See also -

Example set_trap_mask(0x60000); ifreset(); set_trap_mask(0x00); clear_error();

Result -

43


close_communication Summary Closes the communication channel to the interface

void close_communication()

Remarks The close_communication function closes the driver. All the communication and interface functions used after this function are answered with the error message IFH_0019 (except open_communication).

Return value -

See also open_communication

Example -

Result -

44


data_to_real

Summary Converts data bytes into a real number

void data_to_real(real destin, char source[], long pos, long double, long byteorder);

destin Real number for recording the conversion result (V) source Source buffer (V) pos Position of the 1st data byte in the source buffer double Real number precision: 0 = single-precision (4 data bytes IEEE) <> 0 = double-precision (8 data bytes IEEE) byteorder Memory format in the source buffer: 0 = Little Endian (Intel) <> 0 = Big Endian (Motorola)

Note The data_to_real function converts 4 (double=0) or 8 data bytes (double=1) of the source buffer source into the real number destin as of the indicated buffer position.

Return value -

See also real_to_data

Example { unsigned char buffer[]; real realzahl; buffer = { 0x66, 0xe6, 0xf6, 0x42 }; data_to_real(realzahl,buffer,0,0,0); ... }

Result realzahl = 123.45

45


datacat Summary Appends data bytes to a buffer

void datacat(unsigned char buffer[], unsigned char bytes[])

buffer Buffer to which the data bytes are appended (V) bytes Data bytes which are appended

Remarks This function appends data bytes to a buffer.

Return value -

See also dataclear, datacopy, datacmp, dataerase, datainsert, datalen, datarevers, dataset

Example unsigned char buffer1[]; unsigned char buffer2[]; buffer1 = {0x01, 0x02, 0x03}; buffer2 = {0x04, 0x05, 0x06}; datacat(buffer1, buffer2);

Result buffer1 = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06};

46


dataclear Summary Clears a buffer

void dataclear(unsigned char buffer[])

buffer Data buffer (V)

Remarks This function clears a data buffer.

Return value -

See also datacat, datacopy, datacmp, dataerase, datainsert, datalen, datarevers, dataset

Example unsigned char buffer[]; buffer = {0x01, 0x02, 0x03}; dataclear(buffer);

Result buffer = {};

47


datacmp Summary Compares two data buffers

long datacmp(char d1[],char d2[])

d1 Data buffer 1 (V) d2 Data buffer 2

Remarks The function compares the two data buffers d1 and d2. If the two buffer have the same length and contain identical characters, they are considered equal, otherwise unequal.

Return value 0 if both data buffers are equal, <> 0 if not equal.

See also datacat, dataclear, datacopy, dataerase, datainsert, datalen, datarevers

Example { int x; int y; int z; unsigned char d1[]; d1 = {1,2,3} x=datacmp(d1,{1,2,3}); y=datacmp(d1,{1,2,3,4}); z=datacmp(d1,{1,2,4}); }

Result x=0, y=1, z=1

48


datacopy Summary Copies data from a source buffer to a target buffer

void datacopy(char destin[], char source[], long pos, long count)

destin Target buffer (V) source Source buffer pos Start position in source buffer count Number of characters to be copied

Remarks The datacopy function copies count characters from position pos from the source buffer source to the target buffer destin. Up to 1024 characters can be copied.

Value ranges: 0 <= pos < 1024 0 <= count <= 1024 pos+count < 1024 Exceeding the value range causes runtime error BIP_0001.

Return value -

See also datacat, dataclear, datacmp, dataerase, datainsert, datalen, datarevers, dataset

Example { char source[]= { 0x12, 0x34, 0x56, 0x78, 0x90 }; char destin[]; datacopy(destin,source,2,3); ... }

Result destin={0x56,0x78,0x90}

49


dataerase Summary Erase data from a buffer

void dataerase (char buffer[],int pos,int count);

buffer Buffer to be modified (V) pos Position at which erasing is to begin count Number of characters to be erased (C)

Remarks The function dataerase erases an arbitrary number of characters from a buffer. The remaining parts of the buffer are combined. Count characters will be erased beginning at position pos. The process is aborted when the end-of-buffer is reached. Only the buffer to pos then remains as the rest.

Return value -

See also datacat, dataclear, datacopy, datacmp, datainsert, datalen, datarevers, dataset

Example { char buffer[] = { 0x12,0x34,0xFF,0x56,0x78 }; dataerase(buffer,1,2); ... }

Result destin={ 0x12,0x56,0x78 }

50


datainsert Summary Inserts data in a buffern

void datainsert (char destin[],char source[],int pos);

destin Buffer to be modified (V) source Buffer to be inserted pos Position to be inserted to

Remarks The function datainsert inserts the buffer source into the buffer destin. Insertion is made beginning with position pos. If the buffer destin becomes longer than a string register

(i.e., 1023 characters), this causes a runtime error BIP_0001.

Return value -

See also datacat, dataclear, datacopy, datacmp, dataerase, datalen, datarevers, dataset

Example { char source[] = { 0xF0,0xF1 }; char destin[] = { 0x12,0x34,0x56,0x78 }; datainsert(destin,source,3); ... }

Result destin={ 0x12,0x34,0x56,0xF0,0xF1,0x78 }

51


datalen

Summary Identifies the buffer length

long datalen(unsigned char buffer[])

buffer Buffer whose length is to be identified

Remarks This function identifies the length (number of characters) of a data buffer.

Return value Number of characters in the buffer.

See also datacat, dataclear, datacopy, datacmp, dataerase, datainsert, datarevers, dataset

Example long length; unsigned char buffer[]; buffer = {0x01, 0x02, 0x03, 0x04}; length = datalen(buffer);

Result length = 4

52


datarevers Summary Reverses a data buffer

void datarevers(unsigned char buffer[])

buffer Buffer whose data bytes are to be reversed (V)

Remarks This function reverses the sequence of data bytes in a buffer.

Return value -

See also datacat, dataclear, datacopy, datacmp, dataerase, datainsert, datalen, dataset

Example unsigned char buffer[]; buffer = {0x01, 0x02, 0x03, 0x04}; datarevers(buffer);

Result buffer = {0x04, 0x03, 0x02, 0x01}

53


dataset Summary Sets the bytes in a buffer to a defined value

void dataset(char destin[],char data, long count)

destin Target buffer (V) data Character to be set count Number of bytes to be set

Remarks This function sets the number of bytes specified by count to the value data in the target buffer destin.

Values ranges: 0 <= count < 1024 Exceeding the value range causes runtime error BIP_0001.

Return value -

See also datacat, dataclear, datacopy, datacmp, dataerase, datainsert, datalen, datarevers

Example { char buffer[]={ 0x12, 0x34, 0x56, 0x78, 0x90 }; dataset(buffer,0x41,2}; ... }

Result buffer ={ 0x41, 0x41, 0x56, 0x78, 0x90 }

54


doNewInit Summary Forces the job INITIALISIERUNG before the next job call.

void doNewInit()

Remarks This function forces the standard job INITIALISIERUNG to be automatically called before executing the next job.

Return value -

See also -

Example doNewInit();

Result -

55


enableIfhTrace Summary Enable/disable the IFH-Trace

void enableIfhTrace(long enable)

enable 0 = disable / <>0 = enable

Remarks This function either enables or disables the IFH-Trace. After changing the ECU description file, this setting is reset again to the application default.

Return value -

See also enableIgnitionHandling, enableUbattHandling, getCfgInt, getCfgString, IsDebugLevel, IsSimulation

Example unsigned char buffer[]; enableIfhTrace(1); iftype(buffer); enableIfhTrace(0);

Result -

56


enableIgnitionHandling Summary Enable/disable ignition monitoring

void enableIgnitionHandling(long enable)


Remarks This function either enables or disables the ignition monitoring. If monitoring is enabled, the error "IFH-0016: IGNITION ON/OFF ERROR" is issued after disabling the ignition at the next interface communication. The current value can be read with "getCfgInt("IgnitionHandling"). After the ECU description file is changed, this setting is reset again to the application default.

Return value -

See also enableIfhTrace, enableUbattHandling, getCfgInt, getCfgString, IsDebugLevel, IsSimulation

Example unsigned char buffer[]; enableIgnitionHandling(0); iftype(buffer); enableIgnitionHandling(1);

Result -

57


enableUbattHandling Summary Enable/disable battery monitoring

void enableUBattHandling(long enable)


Remarks This function either enables or disables the battery monitoring. If monitoring is enabled, the error "IFH-0015: UBATT ON/OFF ERROR" is issued after disabling the battery voltage at the next interface communicaiton. The current value can be read with "getCfgInt("UBattHandling");". After the ECU description file is changed, this setting is reset again to the application default.

Return value -

See also enableIfhTrace, enableIgnitionHandling, getCfgInt, getCfgString, IsDebugLevel, IsSimulation

Example unsigned char buffer[]; enableUbattHandling(0); iftype(buffer); enableUbattHandling(1);

Result -

58


fclose Summary Closes a file

void fclose(int handle)

handle Reference to a file opened by fopen (V)

Remarks The fclose function closes a file opened with fopen. No further file operations are possible after fclose. Error BIP_0006 is activated in the event of an error (failure by EDIABAS host file system) [4].

Return value -

See also fopen, fread, freadln, fseek, fseekln, ftell, ftellln

Example { int handle; handle=fopen("\test\div\test.dat"); ... /* file operations */ ... fclose(handle); }

Result -

59


fopen Summary Opens a text file

int fopen(char filename[])

filename Name of file to be opened

Remarks Opens the specified text file for reading. Up to 5 files can be opened at the same time. A so-called filehandle is returned if the open is successful. The filehandle refers to that and only that opened file and must be specified with all other file operations. When opened, the file's read pointer is moved to the first character of the file. Error BIP_0006 is activated in the event of an error (failure by EDIABAS host file system) [4].

Return value Filehandle

See also fclose, fread, freadln, fseek, fseekln, ftell, ftellln

Example { int handle; handle=fopen("/usr2/test/test.dat"); ... /* file operations with handle */ ... fclose(handle); }

Result -

60


fread Summary Reads a single character from a file

long fread(int handle)

handle Reference to a file opened with fopen (V).

Remarks The fread function reads a character from a file. It reads from the current position of the read pointer. The read pointer is incremented by 1 after the character is read. If an attempt was made to read at the end of a file, then -1 is returned as the value of the character and the read pointer is no longer incremented.

Return value The read character (0x00 - 0xff) or -1.

See also fclose, fopen, freadln, fseek, fseekln, ftell, ftellln

Example { int handle; long c; long i=0; handle=fopen("test.dat"); while((c=fread(handle)) != -1) i++; }

Result i = number of read characters

61


freadln Summary Reads a line from a file

long freadln(char line[],int handle)

line Buffer to accept the read line (V) handle Reference to a file opened with fopen (V).

Remarks The freadln function reads a line from a file. A line is all characters up to an LF character. It reads from the current position of the read pointer. After the line is read the read pointer is incremented until it points to the beginning of the next line. The function returns the length of the line. If an attempt was made to read at the end of a file, then -1 is returned as the length of the line and the read pointer is no longer incremented. Error BIP_0006 is activated in the event of an error (failure by EDIABAS host file system) [4].

Up to 1024 characters per line are allowed!

Return value The number of characters in the read line.

See also fclose, fopen, fread, fseek, fseekln, ftell, ftellln

Example { int handle; char line[]; long i=0; handle=fopen("beispiel.txt"); while(freadln(line,handle) != -1 ) i++; }

Result i = number of read lines

62


fseek Summary Sets the position of the read pointer byte by byte

long fseek(long pos,int handle)

pos New position of the read pointer in the file handle Reference to a file opened with fopen (V).

Remarks The fseek function positions the read pointer on a certain byte in a file. It is always positioned right at the start of the file. The position of the first character is 0. Error BIP_0006 is activated in the event of an error (failure by EDIABAS host file system) [4].

Return value The new position in the file.

See also fclose, fopen, fread, freadln, fseekln, ftell, ftellln

Example { int handle; int c; handle=fopen("Filename"); c=fread(handle); fseek(0,handle); c=fread(handle); ... }

Result The first character in the file is read twice.

63


fseekln Summary Sets the position of the read pointer line by line

long fseekln(long pos,int handle)

pos New line position of the read pointer in the file handle Reference to a file opened with fopen (V)

Remarks The fseekln function positions the read pointer on a certain line in a file. It is always positioned right at the start of the file. The number of the first line is 0. Error BIP_0006 is activated in the event of an error (failure by EDIABAS host file system) [4].

Return value The new line position in the file.

See also fclose, fopen, fread, freadln, fseek, ftell, ftellln

Example { int handle; char line; handle=fopen("test.txt"); fseekln(10,handle); freadln(line,handle); ... }

Result The 11th line of the file is read.

64


ftell Summary Identifies the position of the read pointer

long ftell(int handle)

handle Reference to a file opened with fopen (V)

Remarks The ftell function identifies the current position of the read pointer in bytes from the start of a file. The position of the first character is 0. Error BIP_0006 is activated in the event of an error (failure by EDIABAS host file system) [4].

Return value The current position in the file.

See also fclose, fopen, fread, freadln, fseek, fseekln, ftellln

Example { int handle; long c: handle=fopen("Filename"); c=fread(handle); c=fread(handle); ... c=ftell(handle); }

Result c=2, 2 bytes were read.

65


ftellln Summary Identifies the position of the read pointer in lines

long ftellln(int handle)

handle Reference to a file opened with fopen (V)

Remarks The ftellln function identifies the current position of the read pointer in lines from the start of a file. The position of the first line is 0. Error BIP_0006 is activated in the event of an error (failure by EDIABAS host file system) [4].

Return value The current position in the file.

See also fclose, fopen, fread, freadln, fseek, fseekln, ftell

Example { int handle; char line[]; handle=fopen("xxx.tst"); freadln(line,handle); freadln(line,handle); ... c=ftellln(handle); }

Result c=2, 2 lines were read.

66


getasciitime Summary Determines the current time as ASCII-String

void getasciitime(char time[])

time String buffer to take up the time string (v)

Remarks Determines the current time from the system time as a string of the following form:

"hh:mm:ss"

Return value -

See also getasciidate, getdate, gettime, wait

Example { char time[]; getasciitime(time); ... }

Result time="12:51:15" (example)

67


get_battery_voltage Summary Reads out the battery voltage

long get_battery_voltage()

Remarks This function returns the voltage at clamp 30 (battery voltage) in millivolts.

Return value Voltage in millivolts.

See also get_ignition_voltage

Example long voltage; voltage = get_battery_voltage();

Result -

68


get_error

(get_trap_mask, set_trap_mask ) Summary Checks whether an error has occurred

long get_error(long nr) no Number of error to be checked

Remarks Normally, EDIABAS reacts to an error by automatically aborting the currently active job, and only an error message is returned. In some cases, however, e.g. in case of control unit identification, you may want to analyze certain errors in the control unit description file, and certain bits (trap bits) can be set in the trap mask register for this purpose (see set_trap_mask). Each trap bit is assigned an error message. When this bit is set, the job is not automatically aborted when an error occurs, but a trap bit and the trap number are set in the condition code register. The get_error function now checks whether the trap bit is set and whether the specified error agrees with the trap number. If it does, get_error returns TRUE (!0); if not, it returns FALSE (0). If no = 0, it only checks whether the trap bit is set. If it is, there is an error, and TRUE is returned. See set_trap_mask for a list of possible trap numbers.

Return value TRUE if there was an error; FALSE, if not.

See also get_trap_mask, set_trap_mask, make_error

Example set_trap_mask(0xffffffff); //trap all errors send_and_receive(destin,source); if(get_error(0)) job_status="FEHLER BEI SG-KOMMUNIKATION"; else job_status="SG-KOMMUNIKATION I.O.";

Result job_status="FEHLER BEI SG-KOMMUNIKATION" falls SG nicht antwortet.

69


get_error2 Summary Checks whether an error has occurred.

long get_error2()

Remarks Normally, EDIABAS reacts to an error by automatically aborting the currently active job, and only an error message is returned. In some cases, however, e.g. in case of control unit identification, you may want to analyze certain errors in the control unit description file, and certain bits (trap bits) can be set in the trap mask register for this purpose (see set_trap_mask). Each trap bit is assigned an error message. When this bit is set, the job is not automatically aborted when an error occurs, but a trap bit and the trap number are set in the condition code register. The get_error2 function returns the error number. For the list of available trapnumbers see funtion set_trap_mask.

Return value number of error that occured

See also get_error, get_trap_mask, set_trap_mask, make_error

Example long error; set_trap_mask(0xffffffff); // trap all errors send_and_receive(destin,source);

error = get_error2();

70


get_ignition_voltage Summary Reads out the voltage at the ignition

long get_ignition_voltage()

Remarks This function returns the voltage at clamp 15 (ignition voltage) in millivolts.

Return value Voltage in millivolts.

See also get_battery_voltage

Example long voltage; voltage = get_ignition_voltage();

Result -

71


get_token Summary Identifies a token in a string

void get_token(char destin[],char source[],char trenner[],long nr)

destin Target buffer for the identified token (V) source string to be analyzed separator string with the possible token separators no number of the token to be identified

Remarks A token is a coherent part of a character string that is limited by one or more characters from separator. To split a normal text into tokens, the separator string separator must contain SPACE, TAB and CR. The get_token function analyzes the source string and identifies the tokens within the string that are defined by the characters in separator. The token number no is then copied to destin.

Return value -

See also get_token, strcat, strcmp, strcpy, strcut, strerase, strinsert, strlen, strncpy, strrevers

Example { char source[]; char destin[]; source="DIES IST EIN TEST FUER TOKENS"; gettoken(destin,source," ",4);

}

Result destin = "TEST"

72


getasciidate Summary Determines the current date as ASCII string

void getasciidate(char date[]) date string buffer to take up the date string (v)

Note Determines the current date from system time as a string of the following pattern:

"wt tt.mm.jj KW kw"

wt = weekday = MO, DI (TUE), MI (WED), DO (THU), FR, SA, SO (SUN)

The calendar week (KW) is determined according to the general rules.

Return value -

See also getasciitime, getdate, gettime, wait

Example { char date[]; getasciidate(date); ... }

Result date="FR 31.12.92 KW 52" (example)

73


get_trap_mask Summary Gets the current value of the trap mask register

long get_trap_mask()

Remarks The get_trap_mask function reads the current value of the trap mask register. This register decides which errors will be reported to the runtime system and which will not.

See set_trap_mask for a full description of the trap mask register.

Return value The current value of the trap mask register

See also get_error, set_trap_mask

Example { long x; set_trap_mask(0x00180000); x=get_trap_mask(); }

Result x=0x00180000

74


generateRunError Summary Generates a runtime error „RUN-00XX“

void generateRunError(long errornumber) errornumber number of error that has to be issued

Remarks This function generates an a runtime error „RUN-00XX“ determined by errornumber

Return value -

See also make_error, get_error

Example { ... generateRunError(250); // generate „RUN-0000“ // }

Result -

75


getasciidate Summary Gets the current date as an ASCII string

void getasciidate(char date[])

date String buffer to take the date string (V)

Remarks From the system time this function identifies the current date as a string with the form

"wt tt.mm.jj KW kw" wt = weekday = MO, DI, MI, DO, FR, SA, SO The calendar week (KW) is identified according to generally

applicable rules.

Return value -

See also getasciitime, getdate, gettime, wait

Example { char date[]; getasciidate(date); ... }

Result date="FR 31.12.92 KW 52" (example)

76


getasciitime Summary Gets the current time as an ASCII string

void getasciitime(char time[])

time String buffer to take the time string (V)

Remarks From the system time this function identifies the current time as a string with the form

"hh:mm:ss"

Return value -

See also getasciidate, getdate, gettime, wait

Example { char time[]; getasciitime(time); ... }

Result time="12:51:15" (example)

77


getCfgInt

Summary Reads out a configuration element as integer

long getCfgInt(char cfg[])

cfg Configuration element

Remarks With this function, the setting of EDIABAS configuration elements can be determined.

Return value Current configuration setting

See also enableIIfhTrace, enableIgnitionHandling, enableUbattHandling, getCfgString, IsDebugLevel, IsSimulation

Example long cfgvalue; cfgvalue=getCfgInt("RetryComm");

Result cfgvalue=0..1 // automatic repetition ?

78


getCfgString Summary Reads (gets) a configuration element as a string

long getCfgString(char cfgvalue[],char cfg[])

cfgvalue Buffer for configuration setting cfg Configuration element

Remarks This function can be used to determine the setting of EDIABAS configuration elements.

Return value 0: Configuration element not found 1: Configuration element found

See also enableIIfhTrace, enableIgnitionHandling, enableUbattHandling, getCfgInt, IsDebugLevel, IsSimulation

Example { char cfgvalue[]; getCfgString(cfgvalue,"SimulationPath"); }

Result Example: cfgvalue="c:\ediabas\sim"

79


getdate Summary Gets the current time as an array structure

void getdate(char date[])

date Buffer to take the date structure (V)

Remarks From the system time this function identifies the current date as a structure with the form:

date[0] = day of month (1..31) date[1] = month of year (1..12) date[2] = year (0..99) date[3] = calendar week (1..53) date[4] = weekday (1 = Monday ... 7 = Sunday) The calendar week is identified according to generally applicable

rules.

Return value -

See also getasciidate, getasciitime, gettime, wait

Example {

char date[];// Friday, 6th of August, 1999 (calendar week 31)

getdate(date); ... }

Result date= { 06, 08, 63 } (example)

80


getETXblock Summary Returns the data bytes of a block specified for a KWP 1281

ECU.

long getETXblock(unsigned char antwort[], long status, long block, unsigned char daten[], long blocklaenge)

antwort ECU response message frame (V) status In the function: Expected status byte of the block (V) From the function: Actual status byte of the block (V) block Block number beginning with 1 daten Daten bytes of the block (V) blocklaenge Number of data bytes in the block (V)

Remarks This function filters out the data bytes of a certain block from the response message of an ECU. In addition, the block is checked for correctness by means of a passed status byte (expected status == actual status). If the expected (desired) status byte does no agree with the actual status byte, this function returns the value 0, otherwise 1.

Return value 0 = Fehler 1 = ok

See also -

Example { unsigned char antwort[]; unsigned char buffer[]; unsigned char status = 0xfc; char blockLen; send_and_receive(antwort,tel_fslesen); if (getETXblock(antwort,status,1,buffer,blockLen)) { }

Result -

81


GetKWP2000Block Summary Extracts the data component from a KWP 2000 telegram

in the control unit response.

int GetKWP2000Block(int position, char response[],char format, chartarget, char source, int length, char data[])

position Initial position of a telegram in the control unit response (V)

response Control unit response

format KWP 2000 format byte in the header (V)

target KWP 2000 tester address in the 3-byte header. In a 1- byte header, 0 is entered. (V)

source KWP 2000 control unit address in the 3-byte header. In a 1-byte header, 0 is entered.(V)

length Length of the telegram data (including the ServiceID) (V)

data Telegram data (including the ServiceID) (V)

Remarks This function extracts the data component (including ServiceID) from a KWP 2000 telegram; DataSegmentation is supported. Since the control unit response may consist of several telegrams, position points to the beginning of a telegram. After execution of the function, position points to the next telegram, if available. The function returns the value 1 as long as no error has occurred.

Return value 0: error 1: no error

See also -

82


Example { unsigned char resonse[]; int position; int format; int source; int target; int length; unsigned char data[]; unsigned char dataglobal[]; send_and_receive(resonse,request); position = 0; while(GetKWP2000Block(position,resonse, format,source,target,length,data)) datacat(dataglobal,data); }

Result -

83


gettickcount Summary Gets an iternal tick counter of milliseconds.

unsigned long gettickcount()

Remarks This function gets an internal tick counter of milliseconds. Note: multiple calls of this function may cause a counter overrun. In this case the counter starts again with 0. The precision of the function gettickcount depends on the operating system:

Win16/32: milliseconds since system start Unix: seconds since 00:00 o`clock

Return value value of milliseconds

See also getasciidate, getasciitime, getdate, wait, waitex

Example { unsigned long ticks; ticks=gettickcount(); ... }

Result -

84


gettime Summary Gets the current time as an array structure

void gettime(char time[])

time Buffer to take the time structure (V)

Remarks From the system time this function identifies the current time as a structure with the form

date[0] = hour (0..23) date[1] = minute (0..59) date[2] = second (0..59)

Return value -

See also getasciidate, getasciitime, getdate, wait

Example { char time[]; gettime(time); ... }

Result time= { 14,52.10 } (example)

85


hex2ascii Summary Converts a sequence of bytes to a hex string.

void hex2ascii(char destin[], char source[], int pos, int count)

destin String buffer(V) source Source buffer index Position in source buffer count Number of nibbles to be converted

Remarks Converts a chain of bytes from the source buffer source, starting from the byte position pos, into a zero-terminated string destin. count nibbles are converted from the source string.

Return value -

See also atoi, atoy, bcd2ascii, itoad, itoax, ascii2hex

Example { char source[]={ 0x12, 0x34, 0xFF, 0x78, 0x90 }; char destin []; hex2ascii(destin,source,2,5); ... }

Result destin = "34FF7"

86


ifboot Summary Resets the interface

void ifboot()

Remarks This function returns the interface to initializing status and tests the diagnostic interface. The IDBSS will not accept commands for about 2 seconds after this job.

Return value -

See also -

Example ifboot();

Result -

87


ifgetport Summary Reads out a port

long ifgetport(long port)

port Port number (V,C)

Remarks This function reads out ports. With EDIC up to nine ports can be read out. Ports 0 - 7 are analog inputs (results in millivolts), port 8 returns the value of the jumper field (each bit is a jumper).

EDIC: Port 0 - 5: Analog inputs 0 - 5 (voltage in mV) Port 6: Analog input terminal 15 (voltage in mV) Port 7: Analog input terminal 30 (voltage in mV) Port 8: Jumper field (digital value)

Return value Value of the port

See also get_battery_voltage, get_ignition_voltage

Example long voltageCl30; long jumper; voltageCl30 = ifgetport(7); jumper = ifgetport(8);

Result -

88


ifinfo Summary Function for the purpose of debugging

void ifinfo(char output[], char input[])

output Output data (V) input Input data

Remarks This function only exists for the purpose of debugging. When developing EDIABAS, the internal functionality over the description file can be influenced using this function. The functionality can vary depending on the EDIABAS version. This function must not be used by the user and is only explained for completeness.

Return value -

See also ifinfoExt

Example -

Result -

89


ifinfoExt Summary Function for the purpose of debugging

long ifinfoExt(long funcID,char output[], char input[])

funcID Function ID (V) output Output data (V) input Input data

Remarks This function exists only for debugging purposes. During the development of EDIABAS, the function can influence the internal functionality via the description file. This functionality can vary among the different EDIABAS versions. The user may not use this function; it is only described here for completeness.

Return value Status

See also ifinfo

Example -

Result -

90


ifloopt Summary Tests the diagnostic lead

long ifloopt()

Remarks This function tests the diagnostic lead - there must be a short between the RD and TD leads.

Return value 0: Test failed 1: Test OK

See also -

Example if(ifloopt()) /* execute diagnostic */

Result -

91


ifrawmode Summary Passes data to the interface

void ifrawmode(unsigned char response[], unsigned char request[])

request request to the interface response response from the interface

Remarks This function passes the transmitted data direct to the interface. The interface answer is returned un-interpreted. The control bytes of an answer of the EIDBSS application of the EDIC are not evaluated.

Return value -

See also -

Example unsigned char input[]; unsigned char output[]; input = {0x0A, 0x00}; // read out version number of EDIC ifrawmode(output,input);

Result e.g. output: 0x00, 0x00, 0x03, 0x00

92


ifrecv Summary Function for the purpose of debugging

void ifrecv(unsigned char response[], long time)

response Data from the serial interface (V) time Waiting time in milliseconds

Remarks This function waits the specified time for characters on the serial interface. This function is only used for the purpose of debugging. Never use this function, since it may vary depending on the EDIABAS version.

Return value -

See also ifsend

Example -

Result -

93


ifrequeststate Summary Interrogate the interface status

void ifrequeststate(unsigned char status[])

status Interface status (V)

Remarks This version interrogates the current status of the interface.

Return value -

See also -

Example -

Result -

94


ifreset Summary Resets the communication parameters

void ifreset()

Remarks This function breaks off communication with a control unit and resets the communication parameters. Any control unit telegram that may be stored in the interface is erased.

Return value -

See also ifboot

Example ifreset();

Result -

95


ifsend Summary Function for the purpose of debugging

void ifsend(unsigned char request[])

request Data to the serial interface

Remarks This function sends characters to the serial interface. It is used only for the purpose of debugging. Never use this function, since it may vary depending on the EDIABAS version.

Return value -

See also ifrecv

Example -

Result -

96


ifsetport Summary Sets a port

void ifsetport(long port, long value)

port Port number value Port value

Remarks Ports can be set with this function. Only port 9 can be set in EDIC (digital outputs).

Port 9: Digital outputs

Return value -

See also ifgetport

Example long value; value = 0xff; ifsetport(9, value);

Result -

97


ifsireset Summary Switches the SI relay

void ifsireset(long time)

time Switching time in milliseconds

Remarks This function switches on the service interval relay of the EDIC for the specified time.

time = 0: Continuous off time = -1: Continuous on

Return value -

See also -

Example ifsireset(100); /* switch for 100 ms */

Result -

98


iftype Summary Returns the interface type as a string

void iftype(char type[])

type String to take the interface type (V)

Remarks This function returns the interface type as a zero-terminated string.

Return value -

See also ifvers

Example char typ[]; iftype(typ);

Result -

99


ifvers Summary Returns the interface version number

long ifvers()

Remarks This job returns the version number of the interface (EDIC, IDBSS)

Return value Version number

See also -

Example unsigned int versionno; versionno = ifvers();

Result versionno /* e.g. 0 */

100


incProgressPos Summary Increases the current position of the progress counter.

void incProgressPos(long n)

n Value for which the current progress position is to be increased..

Remarks This function increases the current progress position by the value specified. It only has affect when the progress counter has been previously initialized in a job with setProgressRange.

Return value -

See also setProgressRange

Example setProgressRange(500); incProgressPos(0); // Start with 0 percent : incProgressPos(100); // 20 percent processed : // incProgressPos(300); // 80 percent processed : // incProgressPos(200); // 100 percent processed // /////////////////////////////////////////////////// // In the END job setProgressRange(0); // Reset processing state

Result -

101


isDebugLevel Summary Determines the debug level

long isDebugLevel()

Remarks This function can be used to determine the setting of the EDIABAS configuration element "BipDebugLevel". By means of this value, certain actions can only be performed during the ECU description file test.

Corresponds to: getCfgInt("BipDebugLevel");

Return value 0 = Debug AUS(default), n = Debug- Level

See also enableIIfhTrace, enableIgnitionHandling, enableUbattHandling, getCfgInt, getCfgString, IsSimulation

Example { char antwort[]; // Output sent frame for testing purposes if(isDebugLevel() > 3) SEND_TEL=tel; send_and_reveive(antwort,tel); // Output received frame for testing purposes if(isDebugLevel() > 3) RECV_TEL=antwort; }

Result -

102


isSimulation Summary Determine whether simulation is enabled

long isSimulation()

Remarks This function can be used to determine the setting of the EDIBAS configuration element "Simulation". By means of this value, certain actions can only be performed during the ECU description file test..

Corresponds to: getCfgInt("Simulation");

Return value 0 = Simulation OFF(default), 1 = Simulation ON

See also enableIIfhTrace, enableIgnitionHandling, enableUbattHandling, getCfgInt, getCfgString, IsDebugLevel

Example { char antwort[]; // Use other frame for testing purposes if(isSimulation()) send_and_reveive(antwort,tel_sim); else send_and_reveive(antwort,tel); }

Result -

103


itoad Summary Converts a number to a string in decimal notation

void itoad(char destin[], long value)

destin Buffer to take the string (V) value Number to be converted

Remarks itoad converts the number value to a string with decimal notation with a sign. No leading zeroes are output.

Return value -

See also atoi, atoy, bcd2ascii, hex2ascii, itoax, ascii2hex

Example { char destin[]; itoad(destin,1143); ... }

Result destin="1143"

104


itoax Summary Converts a number to a string in hexadecimal notation

void itoax(char destin[],long value)

destin String buffer to take the string (V) value String buffer to take the (sic)

Remarks itoax converts the number value to a string with hexadecimal notation with a sign. The output string always has the format 0x########. All the positions are always output.

Return value -

See also atoi, atoy, bcd2ascii, hex2ascii, itoad, ascii2hex

Example { char destin[]; itoax(destin,1143); ... }

Result destin="0x00000477"

105


itor Summary Converts an integer to a real value

void itor(real destin ,long value)

destin Real number to take the conversion result (maximum double = 1.7E ± 308 (15 digits)) value Number to be converted

Remarks itor converts an integer to a real number.

Return value -

See also ator, realadd, realsub, realmul, realdiv

Example { real realzahl; itor(realzahl,122); ... }

Result realzahl = 1.22e2

106


linkPlugIn Summary Loads a Plugin component

void linkPlugIn(char name[]);

name Name of the Plugin component

Remarks The linkPlugIn function loads a Plugin component and connects it with EDIABAS. After connecting, access to this component is possible with the functions callPlugIn and callPlugInExt. The component must be located in the ”EDIABAS\BIN“ directory. The following relationship exists between the name of the component and the file name:

Win16: <Name>.dll Win32: <Name>32.dll

Return value -

See also callPlugIn, callPlugInExt


Result -

107


make_error Summary Issues an EDIABAS error

void make_error(long trapnumber);

trapnumber Trap number of the error to be issued

Remarks This function enters the trap number trapnumber in the Trap-Mask-Register and issues the corresponding error in the runtime system.

Return value -

See also get_error

Example { ... make_error(19); // Issue IFH_0009 }

Result -

108


new_set_of_results Summary Opens a new set of results

void new_set_of_results()

Remarks The function new_set_of_results signals the start of a new result set to the runtime system. The results of a job can be split up into several sets. The result information can be grouped in this way. For instance, the results ERROR_NAME and ERROR_VALUE can be returned for each error contained in the control unit without always having to use a new result name.

Return value -

See also parcount, realresult

Example ... result: ERROR_NAME ; type int ... result: ERROR_VALUE ; type int ... { ERROR_NAME = „NAME1“; ERROR_VALUE = 1; new_set_of_results(); ERROR_NAME = „NAME2“; ERROR_VALUE = 2; ... }

Result Result set 1: ERROR_VALUE = 1; Result set 2: ERROR_VALUE = 2;

109


open_communication Summary Opens the communication channel to the interface

void open_communication()

Remarks This function opens the driver. This function must be called before all other that access the interface, and it is advisable to write it as the first function in the job INITIALISIERUNG. If open_communication has not been called yet, then all communication and interface commands are answered by error message IFH_0019.

Return value -

See also close_communication

Example open_communication();

Result -

110


parcount Summary Counts the number of parameters

long parcount()

Remarks Identifies the number of parameters sent as parameter 3 in apiJob or apiJobData. It always counts all the parameters including the ones that are not valid, i.e. blank, so parcount returns the value 5 with apiJob("...","...",";;;;","..."). It even returns 1 when a parameter exists that cannot be evaluated.

Return value The number of transmitted parameters

See also new_set_of_results, realresult

Example { long x; x=parcount(); }

Result apiJob(...,"1;2;3",...); => x=3 apiJob(...,"1",...); => x=1 apiJob(...,";;",...); => x=3 apiJob(...,"1;2;",...); => x=3 apiJobData(...,"",5,...); => x=1

111


real_to_data

Summary Converts a real number into data bytes

void real_to_data(char destin[], real source, long pos, long double, long byteorder);

destin Target buffer for recording the conversion result (V) source Real number (V) pos Position of the 1st data byte in the target buffer double Precision of the real number in the target buffer: 0 = single-precision (4 data bytes IEEE) <> 0 = double-precision (8 data bytes IEEE) byteorder Memory format in the target buffer: 0 = Little Endian (Intel) <> 0 = Big Endian (Motorola)

Remarks The real_to_data function converts the real number source into 4 (double=0) or 8 data bytes (double=1). The data bytes are copied to the target buffer destin as of the position pos.

In case of single-precision (double=0), the error BIP_0011 is triggered if the real number value is not within the range 3.4E±38.

Return value -

See also data_to_real

Example { unsigned char buffer[]; real realzahl; realzahl = atof("123.45"); real_to_data(buffer,realzahl,0,0,0); ... }

Result buffer = { 0x66, 0xe6, 0xf6, 0x42 }

112


realadd Summary Adds two real numbers

void realadd(real destin, real source)

destin First operand and target of the addition (V) source Second operand of the addition (V)

Remarks This function adds the real variables source and destin and writes the result to destin.

destin = destin + source A computer overflow or underflow triggers error messages

BIP_0011.

Return value -

See also ator, itor, realdiv, realmul, realsub

Example { real real1; real real2; ator(real1,"1234e15"); ator(real2,"5678e13"); realadd(real1,real2); }

Result real1 = 1.29078e18 real2 = 5.678e16

113


realcomp Summary Compares two real numbers

long realcomp(real value1, char operator[], real value2)

value1 First operand of the comparison operator String with relation operator: "==", "!=", "<", "<=", ">" oder ">=" value2 Second operand of the comparison

Remarks The function compares the real variables value1 and value2. The comparison to be carried through must be defined with operator.

Return value 0 for an unsuccessful comparison, <>0 with a successful comparison.

See also -

Example { int cmp; real real1; real real2; ator(real1,"1.00"); ator(real2,"2.00"); if (realcomp(real1,"<",real2)) cmp=1; else cmp=0;

}

Result cmp = 1

114


realdiv Summary Divides two real numbers

void realdiv(real destin, real source)

destin Dividend and target of the division (V)

source Divisor (V)

Remarks This function divides the real variables source and destin and writes the result to destin.

destin = destin / source A computer overflow or underflow triggers error messages

BIP_0011.

Return value -

See also ator, itor, realadd, realmul, realsub

Example { real real1; real real2; ator(real1,"1234e15"); ator(real2,"5678e13"); realdiv(real1,real2); }

Result real1 = 21.7330045791 real2 = 5.678e16

115


realmul Summary Multiplies two real numbers

void realmul(real destin, real source)

destin First factor and target of the multiplication (V) source Second multiplication factor (V)

Remarks This function multiplies the real variables source and destin and writes the result to destin.

destin = destin * source A computer overflow or underflow triggers error messages

BIP_0011.

Return value -

See also ator, itor, realadd, realdiv, realsub

Example { real real1; real real2; ator(real1,"1234e15"); ator(real2,"5678e13"); realmul(real1,real2); }


116


realresult Summary Generates a real result

void realresult(char name[],long value,long adjust)

name Name of the result value Value of result as a long integer number adjust Correction factor for the result as a long integer number

Remarks This function generates a real result with result name name and the value value / adjust.

Return value -

See also new_set_of_results, parcount

Example ...result: x; type : int ...){ realresult("x",12345678,1000); }

Result x = 12345.678

117


realsub Summary Subtracts two real numbers

void realsub(real destin, real source)

destin Minuend and target of the subtraction (V) source Subtrahend (V)

Remarks This function subtracts the real variables source and destin and writes the result to destin.

destin = destin - source A computer overflow or underflow triggers error messages

BIP_0011.

Return value -

See also ator, itor, realadd, realdiv, realmul

Example { real real1; real real2; ator(real1,"1234e15"); ator(real2,"5678e13"); realsub(real1,real2); }


118


recv_frequent Summary Receives a telegram in the frequent mode

void recv_frequent(unsigned char telegram[])

telegram Answer telegram from the control unit (V)

Remarks If repeat send and receive (frequent mode) has been started, the current control unit answer can be requested from the interface with the recv_frequent function.

Return value -

See also send_and_receive, send_frequent, stop_frequent

Example unsigned char response[]; send_frequent(request); recv_frequent(response);

Result -

119


recv_keybytes Summary Reads out the control unit key bytes

void recv_keybytes(unsigned char keybytes[])

keybytes Control unit key bytes (V)

Remarks This function reads out the keybytes from a concept 2, concept 3 or concept 4 control unit. The control unit is woken up automatically if it has not already done so.

Return value -

See also -

Example unsigned char keybytes[]; recv_keybytes(keybytes);

Result -

120


rtoa Summary Converts a real number into a string

long rtoa(char destin[],real value,int count);

destin String for storing the conversion result value Real number to be converted count Number of positions to be converted (without decimal point and

minus character)

Remarks The rtoa function converts a real number into a string. In case of too few positions, the value is rounded off. In case of too many positions, the string is filled with zeroes. If 0 is used as count, the real number is converted into a string in exponential notation. With DOS, there is NO conversion into exponential notation, but the value for count is internally set at 10.

Return value Number of the converted characters including terminated zero character.

See also ator

Example { char destin[]; real realzahl; int len; ator(realzahl,"1.234"; ... len=rtoa(destin,realzahl,3); ... }

Result destin ="1.23"; len = 5;

121


rtoi Summary Converts a real number into an integer

long rtoi(real value);

value Real number to be converted

Remarks The rtoi function converts a real number into an integer.

Return value Converted value as integer

See also itor

Example { long destin[]; real realzahl; ator(realzahl,"5.234"; ... destin=rtoi(realzahl); ... }

Result destin = 5;

122


send_and_receive Summary Sends and receives a telegram

void send_and_receive(unsigned char response[], unsigned char request[])

response Control unit answer telegram (V) request Control unit request telegram

Remarks This function sends a telegram to the control unit and receives the answer.

NOTE: Maximum length of telegram is 1018 bytes!

Return value -

See also send_frequent, recv_frequent, stop_frequent

Example unsigned char request[]; unsigned char response[]; request = {0x0D, 0x00, 0x05, 0x00}; // request telegram send_and_receive(response, request);

Result -

123


send_frequent Summary Sends and receives a telegram in the frequent mode

void send_frequent(unsigned char request[])

request Control unit request telegram

Remarks This function repeatedly sends the transmitted telegram to the control unit (frequent mode). In this mode a further call of send_frequent or send_and_receive is answered by the error message IFH_0006. The frequent mode is terminated with stop_frequent (send_frequent and send_and_receive can now be called again).

NOTE: Maximum length of telegram is 1018 bytes!

Return value -

See also send_frequent, recv_frequent, stop_frequent

Example unsigned char request[]; unsigned char response[]; request = {0x0D, 0x00, 0x05, 0x00}; send_frequent(request); recv_frequent(response); recv_frequent(response);

Result -

124


set_answer_length Summary Sets the telegram parameters/response length

void set_answer_length(int telparam[])

telparam Telegram parameter

Remarks To send a telegram, the interface needs telegram parameters. These parameters either control the establishment of the connection to the control unit or transmit the information concerning the expected response length and the response offset. During communication with the control unit, the telegram parameters are generally identical for all control unit telegrams. They can be set by the user with the function set_answer_length so that they do not have to be transmitted with each telegram. During transmission of a telegram, the telegram parameters are always automatically set at the beginning of the telegram. If the user indicates no telegram parameters, the default values that were used to set the communication parameters will be used here as well. If only telegram parameters are to be transferred to the interface, they must first be set with set_answer_length and then transmitted to the interface with send_and_receive. In this case, the telegram to be sent is empty (buffer emptied with dataclear).

telparam[0] Control code/response length:

In connection with the BMW protocols concept 1, concept 2, concept 3, concept 4, DS1 and DS2, telparam[0] is interpreted as response length.

The response length supplies the length of the anticipated control unit response. Concept 1, DS1, DS2 and Concept 3: positive: Number of anticipated bytes in the control unit

answer telegram (fixed answer length) negative: Position of answer length in the answer telegram

(from byte 0) (variable answer length) Concepts 2 and 4: Maximum number of blocks containing the desired information.

In connection with KWP 2000 (KWP 2000 Standard, KWP 2000 BMW, BMW-FAST, KWP 2000*), telparam[0] is interpreted as control code.

125


0x0000: Normal telegram interchange between the interface and the control unit is carried through.

0xFFFF telparam[1] is interpreted as a command.

telparam[1] Command/response offset:

In connection with the BMW protocols concept 1, concept 2, concept 3, concept 4, DS1 and DS2, telparam[0] is interpreted as a response offset.

Concept 1, DS1, DS2 with variable answer length only. In this case the answer length is computed as follows: Length = (answer length + 1) + answer offset

In combination with KWP 2000 (KWP 2000 Standard, KWP 2000 BMW, BMW-FAST, KWP 2000*), telparam[1] is interpreted as a command.

0x0000: Normal telegram interchange between the interface and the control unit is carried through.

0x0010 If telparam[0]=0xFFFF, then “start communication” command.

0x0011 If telparam[0]=0xFFFF, then “stop communication” command.

For a detailed description of the telegram parameters, see the parameterization instructions for the respective diagnostic protocol. Default values for the telegram parameters after setting of the control unit parameters: Concept 1 3 DS1,DS2(5,

6) 2.4 otherwis

e Length Offset

-2 0

52 0

-1 0

1 0

0 0

Return value -

See also set_communication_pars

126


Example int awlen[] = {-2.0}; //With concept 2 the answer length // is at 2nd place in the telegram set_answer_length(awlen);

Result -

127


set_communication_pars Summary Sets the communication parameters

void set_communication_pars(unsigned int param[])

param Communication parameters

Remarks This function sets the communication parameters needed to communicate with the control unit. The parameters have an interface-independent format. Once the parameters have been set with this function, the user software does not have to be changed for an interface change. The concept 0x0000FF00 constitutes an exception. This concept is an identifier which informs the IFH-EDIC that the subsequent parameters are handed over to EDIC unchanged. The parameters for a concept consist of a sequence of either integer or long values. The more significant byte in the concept parameter (param[0]) determines the parameter format. 0x01xx: long values 0x00xx integer values The number and content of the parameters for a concept depend on the concept.

The function set_communication_pars must be called before a new control unit is addressed. As well as the communication parameters the telegram header is assigned default values in EDIABAS according to the preset concept. See set_answer_length for more details about the telegram header.

Integer parameters for the concepts

Concept 1 Concept 2 ISO 9141 Concept 3 Concept 2 DDE Concept DS1

Concept DS2

param[0] Concept Concept 1 = 1 Concept 2 ISO 9141 = 2 Concept 3 = 3

128


Concept 2 DDE = 4 Concept DS1 = 5 Concept DS2 = 6 param[1] Baudrate Evaluated with Concept 1, DS1, DS2 only param[2] Wakeup address Only evaluated by the interface for Concept 2, 3 and 4 but is

needed for EDIABAS param[3] Wakeup Time in ms, 0 ms means no WakeUp (Concept 1 only) param[4] IdleTime Time in ms between WakeUp and the start of the first telegram

(Concept 1 with WakeUp only) param[5] Timeout time Time in ms in which the SG must have responded to a telegram

from the interface param[6] Regeneration time Time in ms that must elapse after the answer from the control unit

before another telegram can be sent param[7] Telegram end time Time in ms by which the telegram end is decided param[8] Byte to byte time (optional) Byte to byte time for DS2 in ms param[9] Checksum (optional) Indicates how the telegram checksum must be created and

checked. If nothing is specified the checksum of the telegram to be sent is formed automatically by the interface and the checksum of the received telegram is formed. Checksum handling is bit-coded.

Bit 0 = 0: The checksum of the telegram to be sent must be created by the user.

Bit 0 = 1: The checksum of the telegram to be sent is created by the interface (default).

Bit 1 = 0: The checksum of the received telegram is checked.

129


Bit 1 = 1: The checksum of the received telegram is not checked.

130


Long Parameters for the Concept BMW-Fast

param[0] concept BMW-FAST = 0x10F

param[1] baud rate 0 to 115200 baud (= 115200 baud)

param[2] timeout time in ms within which the control unit must have replied to a telegram from the interface (= 200 ms)

param[3] regeneration time time in ms which must pass after the control unit response before transmission is again permitted (= 3 ms)

param[4] telegram termination time time in ms after which a decision for telegram termination is made (= 3 ms)

param[5] number Negative response code 0x78 maximum number of Negative response code 0x78 responses of the control unit (= 2)

param[6] timeout Negative response code 0x78 time in ms within which the control unit must have responded after Negative response code 0x78 (= 5000 ms)

param[7] checksum (optional) = 1 (default) Information on how the telegram checksum is to be calculated and checked. If nothing is indicated, the checksum of the telegram to be transmitted is automatically calculated by the interface and the checksum of the received telegram is checked. Checksum handling is bit-coded. Bit 0 = 0: The checksum of the telegram to be

transmitted must be calculated by the user. Bit 0 = 1: The checksum of the telegram to be

transmitted is calculated by the interface. Bit 1 = 0: The checksum of the received telegram is

checked. Bit 1 = 1: The checksum of the received telegram is

not checked.

131


Long Parameters for the Concept KWP2000 BMW

param[0] concept

KWP2000 BMW = 0x10C param[1] baud rate

0 to 115200 baud (= 10400 baud) param[2] timeout

time in ms within which the control unit must have replied to a telegram from the interface (= 200 ms)

param[3] regeneration time time in ms which must pass after the control unit response before transmission is again permitted (= 3 ms)

param[4] telegram termination time time in ms after which a decision for telegram termination is made (= 3 ms)

param[5] time between bytes time between bytes in ms (= 0 ms)

param[6] number Negative response code 0x78 maximum number of Negative response code 0x78 responses of the control unit (= 2)

param[7] timeout Negative response code 0x78 time in ms within which the control unit must have responded after Negative response code 0x78 (= 5000 ms)

param[8] TesterPresent Time time in ms between the last control unit response and the next Tester Present telegram (= 3000 ms)

param[9] TesterPresent Telegram length length of the TesterPresent telegram maximum 11 (= 5)

param[10] to param[20] TesterPresent Telegram

TesterPresent telegram. If the telegram has less than 11 characters, the remaining characters must be 0.

param[21] StartCommunication Telegram length length of the StartCommunication telegram maximum 11 (= 5)

132


param[22] to param[32] StartCommunication Telegram

StartCommunication telegram. If the telegram has less than 11 characters, the remaining characters must be 0.

param[33] Checksum (Optional) = 1 (default) Information on how the telegram checksum is to be calculated and checked. If nothing is indicated, the checksum of the telegram to be transmitted is automatically calculated by the interface and the checksum of the received telegram is checked. Checksum handling is bit-coded. Bit 0 = 0: The checksum of the telegram to be


transmitted must be calculated by the interface.

Bit 1 = 0: The checksum of the received telegram is checked.

Bit 1 = 1: The checksum of the received telegram is not checked.

133


Long Parameters for the Concept KWP2000 *

param[0] Concept

KWP2000 * = 0x10D param[1] Baud Rate

0 to 115200 baud (= 10400 baud) param[2] Timeout

time in ms within which the control unit must have responded to a telegram from the interface (= 200 ms)

param[3] Regeneration Time time in ms which must pass after the control unit response before transmission is again permitted (= 3 ms)

param[4] Telegram Termination Time time in ms after which a decision for telegram termination is made (= 3 ms)

param[5] Time Between Bytes time between bytes in ms (= 0 ms)

param[6] Number Negative response code 0x78 Maximum Number of Negative response code 0x78 responses of the control unit (= 2)

param[7] Timeout Negative response code 0x78 time in ms after Negative response code 0x78 within which the control unit must have responded (= 5000 ms)

param[8] TesterPresent Time (Optional) time between the last control unit response and the next Tester Present telegram in ms (= 3000 ms)

param[9] TesterPresent Telegram Length (Optional) maximum length of the TesterPresent telegram 11 (= 6)

param[10] to param[20] TesterPresent Telegram

TesterPresent telegram. If the telegram has less than 11 characters, the remaining characters must be 0.

param[21] Checksum (Optional) = 1 (default) Information on how the telegram checksum is to be calculated and checked. If nothing is indicated, the

134


checksum of the telegram to be transmitted is automatically calculated by the interface and the checksum of the received telegram is checked. Checksum handling is bit-coded. Bit 0 = 0: The checksum of the telegram to be


transmitted is calculated by the interface. Bit 1 = 0: The checksum of the received telegram is

checked. Bit 1 = 1: The checksum of the received telegram is

not checked.

135


Long Parameters for the Concept KWP2000 Standard param[0] Concept

KWP2000 standard = 0x10B param[1] Control unit address (0 to 0xFF) param[2] Settings

Checksum: Bit 0: 0: The checksum byte is not generated by the

interface during transmission but must be part of the request telegram.

1: The checksum byte is generated by the interface during transmission and may not be part of the request telegram.

Bit 1: 0: The checksum byte is checked by the interface. A faulty checksum is considered an error. 1: A faulty checksum is ignored.

Header Format: Bits 2 to 4 (0,1,2,3,4) The value must be set in any case. The parameter determines which header is used when the header is generated by the interface. 0: CARB header 1: 1-byte header 2: 1-byte header with length byte 3: 3-byte header 4: 3-byte header with length byte

Addressing: Bit 5: 0: physical addressing

136


1: functional addressing

TesterPresent Handling: Bit 6: 0: The TesterPresent Request is transmitted

according to the settings of TimeTesterPresent and Tester Present Message.

1: TesterPresent is not transmitted automatically.

Reserved Bit 7

param[3] BusyRepeatRequest repetitions (0 to 1000) Max. number of repetitions if the control unit answers a request with “BusyRepeatRequest“ (response code $21) = 0: There is no repetition; the response is forwarded to

the host. <> 0: The request is repeated after P3max-5ms until

either no BusyRepeatRequest is signalled by the control unit anymore or until the maximum number of repetitions is reached. The last response is forwarded to the host.

param[4] ErrorRepeat (0 to 1000) Number of repetitions if a communication error occurs = 0: There is no repetition; the error message is

forwarded to the host. <> 0: After a communication error, the communication

process is repeated until either no communication error occurs anymore or the maximum number of repetitions is reached. If no communication error occurs anymore, the received response is forwarded to the host; otherwise, an error message is transmitted.

param[5] P3max (10 to 65500) Maximum waiting time between two requests; used with activated handling after ”Busy-RepeatRequest“ (P3max-5ms) and “RequestCorrectlyReceived-ResponsePending” (P3max).

param[6] ResponsePending Repetitions (0 to 65535)

137


Maximum number of repetitions if the control unit answers a request with “RequestCorrectlyReceived-ResponsePending“ (response code $78). =0: The tester does not wait for the actual response;

RequestCorrectlyReceived-ResponsePending is forwarded as a response to the host.

<> 0: After the response “RequestCorrectlyReceived-ResponsePending“, the waiting time P3max is started. If another RequestCorrectlyReceived-ResponsePending is received during P3max, P3max is restarted if the set number of repetitions is not yet reached. If the control unit returns RequestCorrectly-Received-ResponsePending after the last repetition as well, a timeout is signalled to the host.

param[7] Diagnosis Start Settings (0,1,2) This parameter is evaluated during the Diagnosis Start service. 0: A 5-baud stimulation is carried through with the

indicated control unit address. The setting for Sync-Measurement is taken into account.

1: No stimulation is carried through; communication with the control unit begins with the first request. The baud rate is fixed according to param[9].

2: A fast initialization via a wakeup pattern is carried through. This pattern is defined by WUPt and WUPl. The baud rate is fixed according to param[9].

param[8] SyncMeasurement (0,1) Only taken into account if param[7] = 0. 0: The baud rate is set according to param[9]. 1: The baud rate is measured and adapted in

accordance with the measurement. param[9] Baud Rate

Set baud rate. Only effective if: param[7]= 0 and SyncMeasurement = 1 or if: param[7]<>0.

138


Recommended setting: 10416 b param[10] W0 (5 to 6550 ms)

Waiting time before the communication is initialized (initialization according to the setting of param[7], diagnosis start settings). Recommended setting: 300ms

param[11] W1 (0 to 6550 ms) Timeout: time between the end of the 5-baud stimulation address and the sync byte. Recommended setting: 300ms

param[12] W2 (0 to 6550 ms) Timeout: time between the end of the sync byte and the first key byte. Recommended setting: 20ms

param[13] W3 (0 to 6550 ms) Timeout: time between the end of the first key byte and the second key byte. Recommended setting: 20ms

param[14] W4a (2 to 6550 ms) Time between the second key byte from the control unit and the second key byte inverted by the tester. Recommended setting: 40ms

param[15] W4 (0 to 6550 ms) Timeout: time between the inverted second key byte from the tester and the inverted address from the control unit. Recommended setting: 50ms

param[16] W5 (1 to 6550 ms) Time before the tester starts stimulation after a communication error. Recommended setting: 5000ms

param[17] P1 (0 to 6550 ms) Timeout: time between individual bytes to be respected by the control unit within a response.

139


Recommended setting: 20ms param[18] P2 (0 to 6550 ms)

Timeout: intermessage timeout between tester request and control unit response or between two control unit responses. Recommended setting: 50ms

param[19] P3 (0 to 6550 ms) Time between the control unit response and the next tester request. P3<P2: only with a physical request and DataSegmentation switched off; otherwise, the tester waits at least for P2. Recommended setting: 55ms

param[20] P4 (0 to 3200 ms) Interbyte time to be respected by the tester when sending a request. Value 0 ... 0x7FFF: P4 in ms Value 0x8000 ... 0xFFFF: P4 in 0.1 ms 0x8000 == 0 corresponds to no interbyte time Recommended setting: 10ms

param[21] P3* (1 to 6550 ms) Entry time when sending a request during periodic transmission Recommended setting: P2min-5ms = 5..20ms

param[22] Time Tester Present (0 to 6550 ms) If this time has passed after the last control unit response and the host has not sent a new transmission request to the control unit, the TesterPresent request defined below is transmitted. TimeTesterPresent >= P3 is always true. In addition, the restrictions concerning P2 and P3 must be taken into account. Recommended setting: 4000ms

140


param[23] Length of the TesterPresent Message (0 to 11) 0: The last tester request is used to maintain the

connection. 1-11: Length of the request to be transmitted for

maintaining the connection, including checksum. param[24] to param[34] Characters of the Tester Present Message

If the TesterPresent message has less than 11 characters, the remaining characters must have the value 0. The checksum must always be indicated, independently of the setting for checksum generation (param[2]). The recommended setting depends on the header format (1-,2-,3-,4-byte header). Example of a 3-byte header (physical addressing): 81H, <phys. control unit address>,<tester address>, 3EH, <8-bit addition checksum>, 00H,00H,00H,00H,00H,00H

param[35] WUPt (15 to 65535) Total duration of the wakeup pattern during fast initialization Unit: 100µs Recommended setting: 500

param[36] WUPl (15 to 65535) Duration of the low level within the wakeup pattern. When TWupLow is over, the system waits for TWupGes-TWupLow with the high level. Unit: 100µs Recommended setting: 250

param[37] Length of the StartCommunication Message (0 to 11) Length of the telegram to be sent directly after the wakeup pattern 0: No StartCommunication request is transmitted.

The wakeup pattern is followed directly by the first request.

141


1-11: Length of the request to be transmitted for establishing the connection, including checksum

Recommended setting: 5 param[38] to

param[48] Characters of the StartCommunication Message Characters of the StartCommunication message. If the telegram has less than 11 characters, the remaining characters must have the value 0. The checksum must always be indicated, independently of the setting for checksum generation (param[2]). Example of physical addressing: 81H, <phys. control unit address>,<tester address>, 81H, <8-bit addition checksum>, 00H,00H,00H,00H,00H,00H

param[49] Settings (0,1) 0: Acceptance of all parameters from SetECUPars. If

SetECUPars is transmitted during ongoing control unit communication, communication is interrupted and then reestablished.

1: Acceptance of all parameters relevant during ongoing communication

param[50] Settings

Arbitration Handling Bit 0: Arbitration handling (only with functional addressing) 0: Arbitration handling switched off. In case of

transmission errors during response reception, the tester does not wait whether the control units repeat transmission.

1: Arbitration handling activated. In case of transmission errors during response reception, the tester waits for TimeArbitrationIdle until the reception is restarted.

5-Baud Address Parity Bit 1 and bit 2 (0,1,2) Setting the parity bit in the 5-baud stimulation address

142


0: The 5-baud address is transmitted without alteration (data format 8N1).

1: In the 5-baud address, the 8th bit (MSB) has odd parity (data format 7O1).

2: In the 5-baud address, the 8th bit (MSB) has even parity (data format 7E1).

DataSegmentation Bit 3 DataSegmentation handling (only with physical addressing of the request). With functional request addressing, all responses will be received. 0: DataSegmentation handling activated. After the

reception of each response, P2 is started. If no additional response is received during P2, all responses to the transmitted request have been received and will be signalled to the host.

1: DataSegmentation handling deactivated. After reception of the first response, P3 is started immediately instead of P2. The tester does not wait for additional responses but the received response is signalled to the host.

TesterPresent Handling Bit 4 Setting the behavior in case of communication errors during Tester Present 0: Error or timeout during reception of the response(s)

are ignored; communication with the control unit is not interrupted.

1: In case of errors or timeout during reception of the response(s), communication with the control unit is interrupted and will be reestablished during the next request by the host.

Recommended setting: 0

Header Generation Bit 5

143


0: The header is not generated by the interface but the data in the command SendTelegram must contain the entire header information.

1: The header is generated by the interface. The data in the command SendTelegram may not contain any header information.

Recommended setting: 0

Baudrate Highbits Bit 6 and bit 7 Most significant bits of the baud rate Example: The baud rate is 128000 (0x1F400) baud

param[9] = 62464 (0xF400) bit 6 = 1, bit 7 = 0

param[51] ArbitrationIdle Time (1 to 6500 ms) Time which passes after an arbitration until a useful bit on the bus is interpreted as the beginning of a new message. If, after an arbitration error, more useful bits are received before the TimeTesterArbitration has passed, the time is restarted. If arbitration takes place because of a timeout (P1), the Time ArbitrationIdle is corrected, if possible. The following dependencies apply: P1 >= TimeArbitrationIdle: TimeArbitrationIdle is 1ms, i.e. after P1, the tester waits for 1ms. P1 < TimeArbitrationIdle: TimeArbitrationIdle is used as set. Recommended setting: P1max < TimeArbitrationIdle < P2min (21ms)

param[52] Reserved param[53] Reserved param[54] Reserved param[55] Reserved param[56] Tester Address

The tester address is used if the header is generated by the interface.

param[57] Reserved

144


param[58] Reserved param[59] Reserved

Return value -

See also set_answer_length

Example unsigned int parameter[] = {1,9600,0x0D,0,0,500,100,500};

set communication pars(parameter); // parameters are forwarded to EDIC unsigned char parameter[] = {0x00, 0xff, 0x00,

0x00, ...}; set_communication_pars(parameter);

Result -

145


set_program_voltage Summary Sets the programming voltage

void set_program_voltage(int voltage)

voltage Programming voltage in millivolts

Remarks This function switches the programming voltage on and off. The programming voltage level is specified in millivolts (0 - 33000 mV). Voltage = 0 Volts means programming voltage is "off".

Return value -

See also -

Example set_program_voltage(12000); /* Voltage to 12 Volts */

Result -

146


set_repeat_counter Summary Sets the number of repeats for control unit communication

void set_repeat_counter(long count)

count Number of repeats

Remarks If an error occurs during control unit communication (IFH_0010 or IFH_0009) the communication command to the interface handler is automatically repeated. The number of repeats can be set with the set_repeat_counter function. 2 is default.

Return value -

See also open_communication, close_communication, set_communication_pars, set_answer_length, send_and_receive, send_frequent, recv_frequent, recv_keybytes

Example { /* fast decision whether CU is there */ set_repeat_counter(0); // no repeat send_and_receive(...) /* wait till CU is there */ set_repeat_counter(10000); // 10000 repeats send_and_receive(...) }

Result -

147


set_trap_mask Summary Sets the trap mask register

long set_trap_mask(long mask)

mask Trap mask

Remarks The trap mask register decides which error messages will be reported to the runtime system and which will be evaluated by the description file. A bit is reserved in the trap mask register for some error messages. If this bit is 0, the error is reported to the runtime system. If it is 1 then the error can be evaluated in the description file with get_error. set_trap_mask sets all bits of the trap mask register with the bit pattern of the parameter mask at the same time. The default for all bits is 0, and the original status can be restored at any time using set_trap_mask(0).

Trap mask: Mask = 2^(Trapbit0) + 2^(Trapbit1) + ...

148


Trapbit in Register[1]

Error number and error description [4] Constant Trap-number for get_error

BIT 00 BIT 01 BIT 02 BIT 03

---------undefined-------- reserved BIP_0002: IFH call failed reserved

-- --

0x00000004 --

-- -- 02 --


reserved reserved BIP_0006: User file error reserved

-- --

0x00000040 --

06 --


reserved BIP_0009: Version error BIP-0010: Error during constant access IFH_0001: Error at host interface

-- 0x00000200 0x00000400- 0x00000800

-- 09 10 11


IFH_0002: Interface does not logon IFH_0003: Data transfer to interface fault IFH_0004: Command to interface fault IFH_0005: Interface internal error

(defect)

0x00001000 0x00002000 0x00004000 0x00008000

12 13 14 15


IFH_0006: Interface does not accept command

IFH_0007: Wrong supply voltage at D-bus

IFH_0008: Fault at interface to IFH_0009: Control unit does not logon

0x00010000 0x00020000 0x00030000 0x00040000

16 17 18 19


IFH_0010: Data transfer interface-CU failed

IFH_0011: Unknown interface IFH_0012: Data buffer overflow IFH_0013: Function not available in

0x00100000 0x00200000 0x00300000 0x00400000

20 21 22 23

149


interface


IFH_0014: Concept is not supported IFH_0015: Ubatt was interrupted briefly IFH_0016: Ignition was switched reserved

0x01000000 0x02000000 0x04000000

--

24 25 26 --

BIT 28-31 reserved -- --

Table 1: Breakdown of trap mask register and corresponding trap numbers.

Return value The value of the trap mask register before it is called

See also get_error, get_trap_mask

Example { set_trap_mask(0x00180000); send_and_receive(.....); if(get_error(19)) job_status="DIAGNOSE-FEHLER"; else job_status="OKAY"; }

Result job_status = "DIAGNOSE-FEHLER"; // if CU does not answer.

150


set_variable_result Summary Output variable results

void set_variable_result(char resultName[], long resultType, long longRslt, real realRslt, char stringRslt[], unsigned char dataRslt[])

resultName Name of the result resultType Type of result: 1: long 2: real 3: string 4: data longRslt Result value when result type = 1 realRslt Result value when result type = 2 stringRslt Result value when result type = 3 dataRslt Result value when result type = 4

Remarks This function can be used to return a variable result independent of the job sequence. The result name and the result type must not be defined in the job header; it is determined only at runtime.

Return value -

See also var_result_long, var_result_real, var_result_string, var_result_data

Example { char wert[]="My result value"; unsigned char y[]; real x; set_variable_result("ERGEBNIS",3,0,x,wert,y); }

Result Corresponds to ERGEBNIS = "My result value"

151


setProgressRange Summary Defines a progress range from 0 to Range

void setProgressRange(long range)

range Value of the progress range

Remarks This function specifies a progress range. The current progress position can vary in this range. The progress position is still undefined after called setProgressRange. It must subsequently be initialized with incProgressPos. If the progress position exceeds the progress range, it is automatically shortened to the maximum value.

Return value -

See also incProgressPos

Example setProgressRange(500); incProgressPos(0); // Start with 0 percent : incProgressPos(100); // 20 percent // processed : incProgressPos(300); // 80 percent // processed : incProgressPos(200); // 100 percent // processed /////////////////////////////////////////////////// // Im ENDE-Job setProgressRange(0); // Reset

// processing mode

Result

152


shdataget Summary Copies the contents of the global data memory into a destination

buffer.

long shdataget(char id[], unsigned char destin[])

id ID of the global data memory destin Destination buffer (V)

Remarks This function copies the entire contents of the global data memory into the destination buffer. The destination buffer is cleared prior to copying the contents. The ID (name) of the data memory is an Asciiz string (C-string) which has a maximum of 32 characters. Even an empty string is a valid ID. If an empty string is used as ID, the contents of the data memory are always copied into the destination buffer. Otherwise only the data memory is copied when the same ID has been used for the filling.

Return value TRUE (1) if the global data memory has been found and the contents have been copied. FALSE (0) if the global data memory has not been found and the contents have not been copied.

See also shdataset

Example unsigned char local[]; shdataget("myID",local);

Result -

153


shdataset Summary Fills the global data memory with the contents of the source

buffer.

void shdataset(char id[], unsigned char source[]) id ID of the global data memory source Destination buffer Remarks This function copies the entire contents of the destination buffer

into the global data memory. The global data memory is cleared prior to copying the contents. The ID (name) of the data memory is an Asciiz string (C-string) with a maximum length of 32 characters. Even an empty string is a valid name. When the data memory is subsequently read, either the passed ID or an empty string must be used.

Return value -

See also shdataget

Example unsigned char source[]; shdataset("myID",source);

Result -

154


stop_frequent Summary Terminates the frequent mode

void stop_frequent()

Remarks This function terminates the repeat sending and receiving of telegrams.

Return value -

See also send_frequent, recv_frequent

Example -

Result -

155


strcat Summary Appends one string to another

void strcat(char destin[],char source[])

destin Target string to which the source string is to be appended (V) source Source string to be appended

Remarks The strcat function appends the string source to the existing zero-terminated string destin. Only so many characters are appended so that destin including the zero character can fit in a string register, i.e. 1023 characters max. Both strings can have the length 0. The source string is not changed.

Return value -


Example { char destin[]="01234"; char source[]="56789"; strcat(destin,source); }

Result destin="0123456789" , source="56789"

156


strcmp Summary Compares two strings

long strcmp(char s1[],char s2[])

s1 String1 (V) s2 String2 (V)

Remarks This function compares the two strings s1 and s2. If both strings are the same length and identical in all characters, then the system decides they are equal, otherwise not equal.

Return value 0 when both strings are equal, <> 0 if not.


Example { int x; int y; int z; char s1[]="ABC"; x=strcmp(s1,"ABC"); y=strcmp(s1,"ABCD"); z=strcmp(s1,"abc"); }

Result x=0, y=1, z=1

157


strcpy Summary Copies a string

void strcpy(char destin[],char source[])

destin String to which another is to be copied (V) source String to be copied

Remarks strcpy copies the string source to destin. All characters of source up to the zero character are copied. The target string destin is cleared first.

Return value -


Example { char destin[]="ABC"; strcpy(destin,"XD"); }

Result destin= "XD"

158


strcut Summary Shortens a string

void strcut(char s[],int count )

s String to be shortened (V) count Number of characters to be shortened

Remarks strcut shortens string s by count characters. The string cannot be less than 0 characters long.

Return value -


Example { char buffer[]="ABCDF"; strcut(buffer,3); }

Result buffer= "AB"

159


strerase Summary Erases characters in a string

void strerase(char s[],int pos,int count)

s String to be edited (V) pos Position from which characters are to be erased count Number of characters to be erased

Remarks strerase erases any desired number of characters from a string. the remaining parts of the string are joined together. count characters are erased from position pos. The operation stops when the string end is reached, leaving just the string up to pos.

Return value -


Example { char buffer[]="ABCDEFGHIJKLM"; strerase(buffer,3,3); }

Result buffer= "ABCGHIJKLM"

160


strinsert Summary Inserts characters into a string

void strinsert(char destin[],char source[],long pos)

destin String to be edited source String to be inserted pos Position from which characters are to be inserted

Remarks strinsert inserts the string source into the string destin. The characters are inserted from position pos. If the string destin is longer than a string register, i.e. 1024 characters, the rest is cut off.

Return value -


Example { char buffer[]="ABCGHIJKLM"; strinsert(buffer,"DEF",3); }

Result buffer= "ABCDEFGHIJKLM"

161


strlen Summary Identifies the length of a string

long strlen(char string[])

string String whose length is to be identified

Remarks strlen identifies the length of a string. The length of a string is the number of characters it contains, except the terminating zero.

Return value The length of the string (0 .. 1023)


Example { char string[]="ABCDEF" long x; x=strlen(string); }

Result x=6

162


strncpy Summary Copies a number of characters from a string

void strncpy(char destin[],char source[],int count)

destin String to which another is to be copied (V) source String to be copied count Maximum number of characters to be copied

Remarks strncpy copies the string source to destin. If the string destin is longer than count, then only the first count characters are copied. The target string is not cleared.

Return value -


Example { char destin[]="ABCDEFGH"; strncpy(destin,"XYZABCDEF",3); }

Result destin= "XYZDEFGH"

163


strrevers Summary Reverses a string

void strrevers(char string[])

string String to be reversed

Remarks strrevers turns the string round, i.e. the last character become the first and so on.

Return value -


Example { char destin[]="ABCDEFGH"; strreverse(destin); }

Result destin= "HGFEDCBA"

164


tab2fix Summary Reads the values from the current table line and converts them

into a number

void tab2fix(long value[],char column[])

value Value from the table changed to a number (V) column Column in the table from which the value is taken

Remarks The function tab2fix reads a value from the current table line defined with tabseek or tab_suche_index and converts it into a number. The text of spalte indicates from which column the value must be taken. If the column does not exist the error BIP_0010 (constant data access error)[4] is returned.

Return value -

See also tabget, tab_suche_index, tabseek, tabset, tabsetext

Example int errorNo = 0x11; unsigned long value; tabset("Table"); tab_suche_index("ERRORNO",errorNo); tab2fix(value, "VALUE");

Result -

165


tab_suche_index Summary Searches in a table column for a value with the form 0x##

long tab_suche_index(char column[],char value)

column Column where the value will be searched value Value to be searched

Remarks The function tab_suche_index converts value to a string with the form "0x##" and searches for it in the column column. The search always begins with the second table line. If the search is successful the function returns TRUE (<>0), otherwise FALSE (0). If the value is found, then the read pointer for the table is on the line with the found value, if not it is on the last line in the table (important for default values). The elements of this line can now be read using tabget. If the column does not exist the error BIP_0010 (constant data access error)[4] is returned.

Return value TRUE when value is found, otherwise FALSE

See also tab_suche_unsigned, tabget, tabset, tabsetext

Example table TEST[3][]={ { "NAME", "VALUE", "NUMBER" }, { "ONE", "1000", "0X00" }, { "TWO", "2000", "0X03" }, } { char buffer[]; tabset("TEST"); tab_suche_index("NUMBER",3); tabget(buffer,"NAME"); }

Result buffer = "THREE"

166


tab_suche_unsigned Summary Searches a table column for a predefined unsigned value

long tab_suche_unsigned(char column[], unsigned long value)

column column in which the value is to be searched

value unsigned-long value to be searched

Remarks The function tab_suche_unsigned searches the unsigned value in the column. As value, an unsigned value must be passed; otherwise, an internal arithmetical conversion (if necessary, with sign extension) is carried through. The table elements of the column are internally converted into numerical values and compared with the unsigned-long value. If a table element starts with the characters "0x" or "0X", it is interpreted as a hexadecimal number. In all other cases, the table element is interpreted as a decimal number. The searching process always starts in the second table row. After a successful search, the function returns TRUE (<>0); otherwise, FALSE (0). If the value was found, the reading pointer for the table points to the line where the value is located; if not, it points to the last table row (this is important for default values). The elements in this row can then be read out with tabget. If the column does not exist, the error BIP_0010 (Constant Data Access Error) [4] is triggered.

Return value TRUE if the value was found; otherwise, FALSE

See also tab_suche_index, tabget, tabset, tabsetext

167


Example table TST[3][]={ { "NAME", "WERT", "NUMMER" }, { "A", "0", "0x0000" }, { "B", "768", "0x0300" }

}

{ char buffer[]; unsigned long index; tabset("TST"); index=0x300; tab_suche_unsigned("NUMMER",index); tabget(buffer,"NAME"); }

Result buffer = "B"

168


tabget Summary Reads the values from the current table line

void tabget(char destin[],char column[])

destin String buffer to take the value (V) column Column from which the value is taken

Remarks tabget reads a value from the current table line defined with tabseek or tab_suche_index. The value of column indicates from which column value must be taken. If the column does not exist the error BIP_0010 (constant data access error)[4] is returned.

Return value -

See also tab_suche_index, tabseek, tabset, tabsetext

Example see tabset

Result -

169


tabline Summary Positions the read pointer on the specified line

long tabline(long line)

line Line number in the table (first line is 0)

Remarks tabline positions the read pointer on the specified line. The first line is numbered 0. If there is a line which the number matches, the function return TRUE (!0), otherwise FALSE (0). If there is no line which the number matches, the pointer is on the last line in the table (important for default values). The elements of this line can now be read using tabget.

Return value TRUE when the line exists, otherwise FALSE

See also tab_suche_index, tabseek, tabset, tabsetext

Example see tabseek

Result -

170


tabseek Summary Searches in a table column for a value

long tabseek(char column[],char value[])

column Column where the value will be searched value Value to be searched

Remarks The function tabseek searches for the string value in the column column. The search always begins with the second table line. If the search is successful the function returns TRUE (!0), otherwise FALSE (0). If the value is found, then the read pointer for the table is on the line with the found value, if not it is on the last line in the table (important for default values). The elements of this line can now be read using tabget. If the column does not exist the error BIP_0010 (constant data access error)[4] is returned.

Return value TRUE when value is found, otherwise FALSE

See also tab_suche_index, tabget, tabset, tabsetext

Example see tabset

Result -

171


tabset Summary Sets and resets table processing

void tabset(char tabname[])

tabname Name of table you wish to work with

Remarks Tables are constant two-dimensional arrays of strings. The values in the first line name the columns. A value can be searched in each column (tabseek, tab_suche_index). Each column can be read out of the line in which the value was found (tabget). Table processing must be initialized, and this is done with tabset which sets processing to a certain table. The name of the table must be defined as a string. After tabset, tabseek or tab_suche_index must be called first before tabget can be used. If the table does not exist the error BIP_0010 (constant data access error)[4] is returned.

Return value -

See also tab_suche_index, tabget, tabseek, tabset, tabsetext

Example table TEST[3][]={ { "NAME", "VALUE", "NUMBER"}, { "ONE", "1000", "0" }, { "TWO", "2000", "3" }, } { char buffer[]; tabset("TEST"); tabseek("NAME","ONE"); tabget(buffer,"NUMBER"); // buffer = "0" tabget(buffer,"VALUE"); // buffer = "1000" tabseek("NUMBER","3"); tabget(buffer,"NAME"); // buffer = "TWO" }

Result -

172


tabsetext Summary Set and reset of table handling.

void tabsetext(char tabfile[],char tabname[])

tabfile name of ECU description file with table tabname

tabname Name of table you wish to work with

Remarks Tables are constant two-dimensional arrays of strings. The values in the first line name the columns. Table processing must be initialized, and this is done with tabset which sets processing to a certain table. Is the table located in a different SGBD tabsetext has to be used. The parameters determine the name of the SGBD and the name of the table. If the table resides in the same SGBD set an empty string for tabfile (same functionality as tabset).

The search for tabfile starts in ECU directory, first for a variant SGBD. If it failed then for a group SGBD.

After tabsetext, tabseek or tab_suche_index must be called first before tabget can be used. A value can be searched in each column (tabseek, tab_suche_index). Each column can be read out of the line in which the value was found (tabget). The function call of tabsetext and the function calls for table access has to be in the same job.

Return value -

See also tab_suche_index, tabget, tabseek, tabset

Example tabsetext("file","TST"); // file.prg/grp

Result -

173


uitoad Summary Convert an unsigned interger number to a string in decimal notation.

void uitoad(char destin[],unsigned long value)

destin Buffer to take the string (V) value Number to be converted

Remarks uitoad converts the number value to a string with decimal notation without a sign. No leading zeroes are output.

Return value -

See also itoad, atoi, atoy, bcd2ascii, hex2ascii, itoax, ascii2hex

Example { char destin[]; uitoad(destin,4294967295);

... }

Result destin="4294967295"

174


updateInfo Summary Produces a string result during job processing

void updateInfo()

Remarks This function produces a string result which can still be interrogated as the job is being processing.

Return value -

See also -

Example updateinfo();

Result -

175


userbreak Summary Produces an error message "BIP-0008: BEST BREAK"

void userbreak()

Remarks The function produces the error message "BIP-0008: BEST BREAK".

Return value -

See also make_error

Example userbreak();

Result -

176


var_result_data Summary Produces a data result not defined in the job header.

void var_result_data(char name[], char value[])

name Name of the result value Value of the data result

Remarks The function produces a data result with the result name name and the value value. The result name name is determined first at runtime.

Return value -

See also set_variable_result, var_result_long, var_result_real, var_result_string

Example { char resultname[] = "X"; char resultvalue[] = { 0x12, 0x34, 0xFF }; var_result_data(resultname,resultvalue); }

Result -

177


var_result_long Summary Produces a long result not defined in the job header.

void var_result_long(char name[], long value[])

name Name of the result value Value of the long result

Remarks The function produces a long result with the result name name and the value value. The result name name is determined first at runtime.

Return value -

See also set_variable_result, var_result_data, var_result_real, var_result_string

Example { char resultname[] = "X"; long resultvalue = 0x10; var_result_long(resultname,resultvalue); }

Result -

178


var_result_real Summary Produces a real result not defined in the job header.

void var_result_real(char name[], real value[])

name Name of the result value Value of the real result

Remarks The function produces a real result with the result name name and the value value. The result name name is determined first at runtime.

Return value -

See also set_variable_result, var_result_data, var_result_long, var_result_string

Example { char resultname[] = "X"; real resultvalue; ator(resultvalue,"1.23"); var_result_real(resultname,resultvalue); }

Result -

179


var_result_string Summary Produces a string result not defined in the job header.

void var_result_string(char name[], char value[])

name Name of the result value Value of the string result

Remarks The function produces a string result with the result name name and the value value. The result name name is determined first at runtime.

Return value -

See also set_variable_result, var_result_data, var_result_long, var_result_real

Example { char resultname[] = "X"; char resultvalue[] = "ABC"; var_result_string(resultname,resultvalue); }

Result -

180


wait Summary Wait n seconds

void wait(long time)

time Waiting time in second

Remarks The wait function waits time second. wait waits for a maximum of time seconds and a minimum of time-1 seconds. If time = 0, there is no waiting.

Return value -

See also getasciidate, getasciitime, getdate, gettime

Example { wait(1); }

Result waits 1 second

181


waitex Summary Waits n milliseconds

void waitex(unsigned long time)

time Waiting time in millisecond

Remarks The waitex function waits time milliseconds. If time = 0, there is no waiting. The precision depends on the oprating system.

Win16/32: milliseconds since system start (ovverrun after

2^32 milliseconds) Unix: seconds since 00:00 o´clock (overrun after 24

hours) In case of an counter overrun waitex is cancelled.

Return value TRUE end of waiting time FALSE counter overrun

See also gettickcount, getasciidate, getasciitime, getdate, getdate

Example { waitex(1000); }

Result waits 1 second

182


LIST OF REFERENCES

[1] EDIABAS: BEST/1 Language and Interpreter [2] EDIABAS: BEST/2 Language Description [3] EDIABAS: API Interface Description [4] EDIABAS: Error Primer

183

Documents

Best2rtl