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

EDIABAS - BEST/2 FUNCTION PRIMER

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.

12

3.2.

4.

Using the runtime library 3.1.1.

Calling library functions

12

3.1.2.

Paths and filenames

12

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

Clamp states

28

2

EDIABAS - BEST/2 FUNCTION PRIMER

4.

Library functions

31

4.1.

31

Using the function primer 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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

7

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

2.2. Conventions The following typographical conventions are used in this manual: Example SAMPLE.C job, string, while

expression [option] { result | argument } [constant...] job... hallo="Test"; while() { . .} [1]

Description Upper case characters are used for filenames, registers and operating system commands. 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. Italics designate placeholders for values to be entered by the programmer; e.g., file names. Words enclosed in square brackets may be optionally specified. Curvy braces and vertical strokes characterize entries from which only one must be selected, except when in square brackets. An ellipsis (three dots) which directly follows an expression indicates that several expressions of the same type can follow. This syntax designates examples, user entries, program outputs and error messages. A column or a row comprising three dots indicates that a section of an example was intentionally omitted. Reference to a document in References.

10

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

Function

Purpose

AdjustKWP2000TesterPrStartComm

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

EDIABAS - BEST/2 FUNCTION PRIMER

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:

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

Only in case of error:

send_and_receive

Abort active communication with the ECU and reset the terminal states

Abort active communication with the ECU and reset the terminal states

28

EDIABAS - BEST/2 FUNCTION PRIMER

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

Only in case of error:

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

Only in case of error:

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

Only in case of error:

stop_frequent

None

None

get_battery_voltage

None

None

get_ignition_voltage

WRONG UBATT

None

set_program_voltag e

None

None

recv_keybytes

send_frequent

recv_frequent

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

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

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

29

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

ascii2ascii Summary

Converts all text characters into another character set.

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

Character set String buffer(V) 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}; {

}

Result

... ascii2ascii(codepage,text); ...

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

33

EDIABAS - BEST/2 FUNCTION PRIMER

ascii2hex Summary

Converts a hex string into a sequence of bytes

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

Destination buffer(V) String buffer Position in the destination buffer 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 Example

atoi, atoy, bcd2ascii, itoad, itoax { char source[] = "00FF"; char destin[] = { 0x12, 0x34, 0x56, 0x78 }; ascii2hex(destin,source,1}; ... }

Result

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

34

EDIABAS - BEST/2 FUNCTION PRIMER

atoi Summary

Converts a string to a value

long atoi(char number[]); number Remarks

The string to be converted 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 Example

atoy, itoad, itoax, bcd2ascii, hex2ascii, ascii2hex { 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

EDIABAS - BEST/2 FUNCTION PRIMER

ator Summary

Converts a string to a real number

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

Real number to accept the conversion result The string to be converted 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

EDIABAS - BEST/2 FUNCTION PRIMER

atoy Summary

Converts a string into a binary array.

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

Buffer for binary data 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

EDIABAS - BEST/2 FUNCTION PRIMER

bcd2ascii Summary

Converts a chain of characters to a BCD string

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

String buffer(V) Buffer Position in source buffer Number of bytes to be converted Converts a chain of bytes (two nibbles) from the source buffer source, starting from the byte position index, into a zeroterminated 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 Example

atoi, atoy, itoad, itoax, hex2ascii, ascii2hex { char source[]={ 0x12, 0x34, 0xFF, 0x78, 0x90 }; char destin []; bcd2ascii(destin,source,2,5}; ... }

Result

destin = "34**7*"

38

EDIABAS - BEST/2 FUNCTION PRIMER

bittest Summary

Identifies bit results via a table

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

Result name Buffer to be analyzed 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

EDIABAS - BEST/2 FUNCTION PRIMER

bytetest Summary

Identifies byte results via a table

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

Result name Buffer to be analyzed Test result 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

EDIABAS - BEST/2 FUNCTION PRIMER

callPlugIn Summary

Calls the main function within the Plugin component. void callPlugIn(char dataOut[],char dataIn[]); dataOut dataIn

input data (V) 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

EDIABAS - BEST/2 FUNCTION PRIMER

callPlugInExt Summary

Calls the main function within the Plugin component. long callPlugInExt(long funcID,char dataOut[],char dataIn[]); funcID dataOut dataIn

Subfunction number within the Plugin component Input data 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

Example

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

Result

-

42

EDIABAS - BEST/2 FUNCTION PRIMER

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

Result

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

-

43

EDIABAS - BEST/2 FUNCTION PRIMER

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

EDIABAS - BEST/2 FUNCTION PRIMER

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 source pos double byteorder

Real number for recording the conversion result (V) Source buffer (V) Position of the 1st data byte in the source buffer Real number precision: 0 = single-precision (4 data bytes IEEE) 0 = double-precision (8 data bytes IEEE) 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

EDIABAS - BEST/2 FUNCTION PRIMER

datacat Summary

Appends data bytes to a buffer

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

Buffer to which the data bytes are appended (V) 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

Result

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

46

EDIABAS - BEST/2 FUNCTION PRIMER

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

Result

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

47

EDIABAS - BEST/2 FUNCTION PRIMER

datacmp Summary

Compares two data buffers

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

Data buffer 1 (V) 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

Result

{ 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}); } x=0, y=1, z=1

48

EDIABAS - BEST/2 FUNCTION PRIMER

datacopy Summary

Copies data from a source buffer to a target buffer

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

Target buffer (V) Source buffer Start position in source buffer Number of characters to be copied 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