IPG_CarMaker Programmers Guide

(1)

Cover

Programmer’s Guide

Version 2.1

(2)

2

The information in this document is furnished for informational use only, may be revised from time to time, and should not be construed as a commitment by IPG Automotive GmbH. IPG Automotive GmbH assumes no responsibility or liability for any errors or inaccuracies that may appear in this document.

This document contains proprietary and copyrighted information and may not be copied, reproduced, translated, or reduced to any electronic medium without prior consent, in writ-ing, from IPG Automotive GmbH.

FailSafeTester, CAR, CONTROL, DRIVER, ENGINE, GRAPH, IPG-KINEMATICS, IPG-LOCK, IPG-MOTORCYCLE, IPG-MOVIE, IPG-ROAD, IPG-ROADDA-TA, IPG-TIRE, IPG-TRAILER, IPG-TRUCK are trademarks of IPG Automotive GmbH. CarMaker, TruckMaker, MotorcycleMaker, MESA VERDE are

registered trademarks of IPG Automotive GmbH.

(3)

3

1 The CarMaker Environment

10

1.1 CarMaker architectural breakdown . . . 10

CarMaker user interface programs . . . 10

CarMaker simulation program . . . 10

Data file organisation . . . 11

Program interaction . . . 12

Interaction of HIL systems . . . 12

1.2 Inside the CarMaker simulation program . . . 14

User accessible modules . . . 15

1.3 CarMaker Flow Process Charts . . . 17

Modified Cycle Clock Generation if Oversampling is used . . . . 18

1.4 The main cycle explained . . . 21

An pseudo code excerpt from HilMain.c . . . 22

Basic tasks of the main routine . . . 23

The event loop of the main routine . . . 23

1.5 A stripped down CM_Main.c . . . 25

1.6 Main Loop . . . 26 1.7 SimStart . . . 27 1.8 SimStop . . . 29

2 Logging Module

30

2.1 General information . . . 30 2.2 Recommended use . . . 31 List of functions . . . 31

(4)

4

3 Infofile Module

33

3.1 Infofile format . . . 33 3.2 Access functions . . . 34 3.3 Error handling . . . 35 3.4 C Function List . . . 36 General Functions . . . 36 Read Functions . . . 40 Write Functions . . . 44 Add/Move Functions . . . 45 Help Functions . . . 47 Additional Functions . . . 48 3.5 Tcl/Tk Procedure List . . . 48 Library . . . 48 ifile . . . 48 <handle> . . . 49

4 Data Dictionary

53

4.1 Defining DataDict Variables . . . 53

5 Integrating Simulink models

57

5.1 Starting Matlab . . . 57

5.2 Step-by-step: Integrating a Simulink model . . . 59

Creating the Simulink model . . . 59

Setting simulation parameters . . . 59

Generating and compiling the model C code . . . 62

Integrating the model into CarMaker . . . 62

Running the model . . . 63

5.3 The CarMaker interface blockset . . . 65

Accessing the CarMaker dictionary . . . 65

Defining CarMaker dictionary variables . . . 66

Accessing C variables . . . 68

5.4 The CarMaker target for Real-Time Workshop . . . 70

Code generation with the CarMaker target . . . 70

Choosing the right model wrapper . . . 70

Customizing the wrapper . . . 71

Integrating the model library . . . 72

5.5 CarMaker’s tunable parameter interface . . . 74

Introduction . . . 74

(5)

5

Modifying tunable parameters in the model wrapper . . . 76

Parameter values in Infofiles . . . 77

Adding tunable parameters to the CarMaker dictionary . . . 78

Known limitations . . . 79

Tunable parameter interface functions . . . 80

5.6 Miscellaneous . . . 87

Upgrading to a new CarMaker version . . . 87

Integration of more than one model . . . 87

Using blocks from the CarMaker for Simulink blockset . . . 87

CarMaker and Matlab installed on different computers . . . 87

Troubleshooting . . . 89

5.7 Demonstration examples . . . 90

Contents of the examples directory . . . 90

Preparing the examples . . . 90

Rebuilding an example . . . 91

6 CarMaker for Simulink

92

6.1 CarMaker for Simulink basics . . . 93

Creating a new CarMaker project directory . . . 93

Starting Matlab . . . 93

Creating a new model . . . 94

Starting the CarMaker GUI . . . 95

Running a simulation . . . 95

Switching between several Simulink models . . . 96

Switching between several CarMaker project directories . . . 96

Dealing with the start values of your model . . . 96

Working in a non-default model directory . . . 97

Upgrading to a new CarMaker version . . . 97

Troubleshooting . . . 97

6.2 Using the C language interface . . . 99

Rebuilding the model library . . . 99

Identifying which model library you are using . . . 99

Integrating model C code built with Real-Time Workshop . . . 100

6.3 The CarMaker for Simulink blockset . . . 101

General information . . . 101

Utility blocks . . . 102

CarMaker dictionary blocks . . . 103

(6)

6 CarMaker subsystem . . . 107 6.4 Demonstration examples . . . 117 ABSdemo . . . 118 BodyCtrl . . . 119 ESPTemplate . . . 120 SoftABS . . . 121 TractCtrl . . . 122 UserBrake . . . 123 UserPowerTrain . . . 124 UserSteer . . . 126 UserSteerTorque . . . 127 UserTire . . . 129

7 CarMaker utilities for Matlab

130

7.1 Importing simulation results with cmread . . . 130

7.2 Accessing CarMaker Infofiles . . . 132

8 MIO – M-Module Input/Output

133

8.1 Supported M-Modules . . . 133

M3 / M27 / M43: Binary / Relay Outputs (8/16 channels) . . . . 133

M4: Analog Outputs (4 channels) . . . 134

M15: Frequency Generator (2 channels) . . . 135

M31 / M32: Binary Inputs (16 channels) . . . 136

M5 / M34 / M35 / M35N: Analog Inputs (16/8 channels) . . . 137

M51: Quadruple CAN Interface . . . 138

M72: Motion Counter . . . 141

M77: Quadruple RS232/423 - RS422/485 UART . . . 142

M392 / M393: Analog Inputs (16/8 channels) . . . 143

M461/3: Pulse Width and Angle Measurement (4 channels) . 144 8.2 Programming M-Module I/O . . . 145

MIO Initialization . . . 145

M-Module Carrier Board Configuration . . . 147

M-Module Configuration . . . 148

Error Handling . . . 149

8.3 Administrative Functions . . . 152

Initialization and M-Module Configuration . . . 152

MIO and M-Module Information . . . 154

(7)

7

Shared Memory Management . . . 156

Error Handling Functions . . . 157

8.4 M-Module Function Description . . . 159

M3: Binary Outputs (16 channels) . . . 159

M5: Analog Inputs (16/8 channels) . . . 161

M15: Frequency Generator (2 channels) . . . 162

M27: Binary Output (16 channels) . . . 164

M31: Binary Inputs (16 channels) . . . 165

M32: Binary Inputs (16 channels) . . . 165

M34: Analog Inputs (16/8 channels) . . . 166

M35/M35N: Analog Inputs (16/8 channels) . . . 167

M43: Relay Outputs (8 channels) . . . 168

M51: Quadruple CAN Interface . . . 169

M72: Motion Counter . . . 182

M77: Quadruple RS232/423 - RS422/485 UART . . . 188

M392: Analog Inputs (16 channels) . . . 192

M393: Analog Inputs (8 channels) . . . 196

M461/3: Pulse Width and Angle Measurement (4 channels) . 198 8.5 mioutil - MIO configuration utility . . . 203

Version History . . . 204

9 CANiogen – CANdb import tool

207

9.1 Overview . . . 208

Basic information . . . 208

Features . . . 209

9.2 Using CANiogen . . . 211

The CANiogen Command Line . . . 211

Importing Electronic Control Units (ECU) . . . 213

Receiving CAN messages and signals of special interest . . . 214

Sending arbitrary CAN messages . . . 214

Suppressing of I/O variables in the Data Dictionary . . . 215

Optimizing the output of CANiogen . . . 215

Disabling range checking of Signal values . . . 216

Naming of generated files, I/O variables and functions . . . 216

Extended features . . . 217

9.3 CANiogen’s output . . . 219

(8)

8

The header file IO_CAN.h . . . 219

The list of generated I/O variables in IO_VarList.txt . . . 223

The C module IO_CAN.c . . . 223

9.4 Integration into CarMaker/HIL . . . 226

Modifications to IO.c . . . 226

Modifications to User.c . . . 228

Modifications to the Makefile . . . 230

9.5 Version History . . . 233

10 APO Messages

236

11 ScriptControl

237

11.1 Introduction . . . 237

11.2 Using the ScriptControl Window . . . 238

11.3 ScriptControl By Example . . . 239

Example 1 – “Hello World!” . . . 239

Example 2 – Starting a Testrun . . . 239

Example 3 – Subscribing to Quantities . . . 240

Example 4 – Postprocessing and Report Generation . . . 241

More Examples . . . 243

Tcl/Tk Documentation Links . . . 243

11.4 ScriptControl Command Reference . . . 245

Running a Simulation . . . 245

Subscribing to Quantities . . . 248

Clock Timers . . . 250

Logging . . . 252

Accessing CarMaker Parameters in Infofiles . . . 255

Managing Simulation Results . . . 257

Direct Variable Access (DVA) . . . 261

Executing Matlab Commands . . . 262

Power Control (KL15) . . . 264

FailSafeTester Commands . . . 265

Miscellaneous Commands . . . 268

Deprecated Commands . . . 271

12 Working With the FailSafeTester

274

12.1 How it Works . . . 276

(9)

9

Inside the FailSafeTester . . . 279

12.2 FailSafeTester Cards . . . 282

12.3 Configuring the FailSafeTester . . . 283

FailSafeTester Cards Naming Convention . . . 283

FailSafeTester Configuration Settings . . . 284

12.4 Addition FailSafeTester Configuration . . . 286

12.5 FailSafeTester C-functions . . . 287

Add the FST Global Variables . . . 287

Configure the M51 CAN module . . . 287

Add Functions to CarMaker . . . 287

12.6 Using the FailSafeTester . . . 289

The FailSafeTester GUI . . . 289

12.7 FailSafeTester Commands with Mini-Maneuvers . . . 297

Complete List of FailSafeTester Commands . . . 299

Using a Command . . . 302

FailSafeTester Example 1 . . . 304

13 CarMaker Graphical User Interfaces

305

13.1 CarMaker Main GUI . . . 305

13.2 Car Parameter Editor . . . 305

13.3 Instruments . . . 305

14 Vehicle Model Exchange

306

14.1 Exchange, Step by Step . . . 306

Vehicle Model coded in C . . . 307

(10)

10 The CarMaker Environment

CarMaker architectural breakdown

Chapter 1 The CarMaker Environment

1.1 CarMaker architectural breakdown

Let’s first have a look at CarMaker and some of its basic architectural concepts. We’ll take the perspective of a user whose job it is to build testruns, run simulations with the testruns he created, and to postprocess the results of these simulations. What he sees when he’s working with CarMaker will be the basis for a first glance at the CarMaker architecture. We will need the concepts explained here later, when we describe the vehicle module, its inter-face and its connection to the outside world in greater detail.

1.1.1 CarMaker user interface programs

The first thing the user will notice is that CarMaker consists of several individual programs. The one program that he almost certainly knows he has to start in order to use CarMaker, is the CarMaker GUI. The CarMaker GUI’s main tasks are to let the user create testruns, edit vehicle parameters and start and stop simulations of testruns.

When simulating a testrun, the user certainly wants to have some kind of feedback of what’s going on during the simulation. From within the CarMaker GUI he starts the 3D animation tool IPG-MOVIE, because he wants to see the vehicle driving on the given course. He may start the online data visualization tool IPG-CONTROL to be able to inspect the time depen-dent behaviour of certain physical quantities of vehicle during the simulation. Or he might want to start Instruments to visualize vehicle behaviour using instruments and lights he knows from a car’s dashboard.

IPG-MOVIE, IPG-CONTROL and Instruments are all implemented as individual programs, that can be started from the CarMaker GUI (they may as well be started outside the CarMaker GUI), and which run independently of each other. Together they comprise the graphical user interface of CarMaker. You find them on the left hand side of Figure 1.1.

1.1.2 CarMaker simulation program

Since the tasks of the programs you read about in the previous section have nothing to do with any calculation of physical quantities for the simulation, this leads us to the next impor-tant concept of CarMaker. It is the concept of a separately running CarMaker simulation pro-gram. Its task is not to provide any kind of elaborate user interface, but to perform the actual

(11)

simulation of a testrun and – in case of CarMaker/HIL – to interface with external hardware being part of the control loop, e.g. a real controller unit. The CarMaker simulation program and possibly connected hardware can be found in the middle and on the right of Figure 1.1.

1.1.3 Data file organisation

Work with CarMaker always takes place in a so called CarMaker project directory that keeps the user’s files needed by CarMaker well organized in several subdirectories. A look at Figure 1.1 shows some typical subdirectories that can be found in a project directory. Each subdirectory serves a special purpose; the following paragraphs give you an impres-sion how file data is used and shared by the individual CarMaker programs.

As we’ve said, the user creates testruns and edits vehicle parameters using the CarMaker GUI. The CarMaker GUI stores testrun data in files in the Data subdirectory.

Each time a simulation is started, the CarMaker simulation program reads information about the current testrun from exactly these files in the Data subdirectory. Files needed in addition to that might be taken from the SimInput subdirectory. During the simulation a log file and simulation results are written to files in the SimOutput subdirectory.

Also at the start of a simulation, the CarMaker GUI is responsible for providing 3D road geometry data to IPG-MOVIE. This becomes necessary if a testrun doesn’t use pre-existing real-world digitized road data but a course constructed of individual road segments. IPG-MOVIE then reads road geometry data and 3D vehicle geometry data from the Movie sub-directory.

At a later time, for the purpose of postprocessing, IPG-CONTROL or other software like e.g. Matlab can read the simulation results in SimOutput written by the CarMaker simulation pro-gram.

Figure 1.1: Basic CarMaker Architecture CarMaker GUI IPG-MOVIE IPG-CONTROL Instruments CarMaker Simulation Program Data/... Hardware

SimInput/... SimOutput/... Movie/... Apo

(12)

1.1.4 Program interaction

Having the user interface tools and the simulation program run absolutely independent of each other would not make much sense – there needs to be some kind of coordination between them. For the purpose of program interaction, the CarMaker simulation program plays a central role.

The user interface tools connect to the simulation program. They may send commands to them, like the CarMaker GUI with its “Start simulation!” or “Stop simulation!” commands. These are sent each time the user clicks on the Start or Stop button. The interface tools may also request some kind of service, e.g. ask for a list of available quantities and request regular transmission of quantity values. This is what IPG-CONTROL does in order to dis-play them graphically during the running simulation.

The CarMaker simulation program, in turn, must provide these services. It must react to commands sent by the CarMaker interface tools. It must register quantities that tools might want to receive on a regular basis, e.g. the quantity that contains the current simulation time, or physical quantities calculated by the vehicle module inside the simulation program. Also, at simulation start, the simulation program sends a special message to IPG-MOVIE telling it about the current geometry configuration of the vehicle.

Communication between the CarMaker programs is done using standard network commu-nication mechanisms. A special CarMaker module, the Apo library, implements communi-cation services for the CarMaker programs and defines the “language” being used between them. The lightning titled “Apo” in Figure 1.1 should illustrate these facts. For the curious: Apo is an abbreviation of “Applications online”.

1.1.5 Interaction of HIL systems

CarMaker HIL systems use different computers to distribute the applications on.Figure 1.3

shows a realtime computer which hosts the CarMaker/HIL application. All models and ser-vices have to meet realtime conditions. Therefore the realtime operating system LynxOS is used on this machine. The realtime system is diskless and shares the disk with the user worksation over network file system.

The user workstation hosts all user interface programs and possibly the LynxOS cross development kit to generate custom CarMaker/HIL applications for the realtime computer. All network communication is done by ethernet by the use of the following protokolls: tftpboot, rarp, DHCP: boot realtime computer over network, determine network adress rlogin (UNIX) or telnet: remote terminal

(13)

APO: CarMaker communication stack (developed by IPG), based on TCP/IP (UDP and TCP sockets)

Figure 1.3: Programm interaction for HIL systems

APO

DVA

Info

Files

DStore

Log

MIO

Log

Basic Services

Realtime System

Linux or Windows

User Workstation

LynxOS

IPG-CAR

IPG-DRIVER

IPG-TRAILER

IPG-TIRE

IPG-ROAD

DDict

CarMaker/HIL

Application

other Models

IIO

CarMaker GUI

IPG-MOVIE

IPG-CONTROL

Instruments

Custom Panels

LynxOS

Dev. System

Ethernet

diskless

NFS – network file system

APO virtual

(14)

Inside the CarMaker simulation program

1.2 Inside the CarMaker simulation program

As we know from the previous section, the central component within the CarMaker archi-tecture is the CarMaker simulation program. We will now take a closer look at this program to see which modules it consists of and find out about the role that each of these modules plays within the simulation program. Emphasis will be on the vehicle module; this section should give you an impression how the vehicle module is connected to the surrounding CarMaker environment.

Figure 1.5 shows the basic building blocks of the CarMaker simulation program. The files and libraries are more or less the same ones that will be linked together when you rebuild the simulation program. What we can see is that there are four major groups of modules: user accessible C code modules (at the top)

the CarMaker library libcarmaker.a (left block in the middle) the vehicle module libcar.a (right block in the middle) special purpose libraries (at the bottom)

We will examine each group more closely in a moment.

The figure also shows the call hierarchy inside the program: each module calls only func-tions of other modules of the same level or on a lower level.

Figure 1.5: Modules of the CarMaker simulation program

HilUser.c IO.c ... libcarmaker .a libcar .a Global Variables

Car Power Brake

Ambient DrivMan DataDict Log ... Apo Infofile libipgdriver.a libipgroad.a Train ... HilMain.c

(15)

1.2.1 User accessible modules

Here we find all the files the user has direct access to, because they are located in the project directory’s src subdirectory. The user may add his own modules by modifying the Makefile also found here.

CM_Main.c

This is the main module of the simulation program. It initializes the application and runs the application’s main loop. Individual simulations are started and controlled in this module. All calls to functions in User.c, IO.c are done within this module, as well as almost all calls to functions of the vehicle module. Normally there’s no need for the user to modify this module. User.c

This and the following module IO.c are the modules the user may taylor to the specific needs of his application. He is provided with a predefined set of functions that are called at different stages of the simulation and at different points during each simulation step. The functions provided have more or less empty bodies, they do nothing. The idea is that the user fills the bodies with his own code, adding application specific functionality to the CarMaker simulation program. Possible tasks the user might handle in User.c are the cal-culation of additional physical quantities, e.g. to be used IO.c (which should be kept clean of such calculations), or the integration of additional model code.

IO.c

This module is intended solely for the task of accessing application specific HIL hardware components.

The CarMaker library: libcarmaker.a

This library contains nearly all service modules of the simulation program. The code in Hil-Main.c relies heavily on this library to control execution of the program and of the simulation. Initialization, data administration, file i/o, hardware i/o, communications and real-time ser-vices are handled by (not necessarily public) modules of this library. The library provides a lot of utility functions available to application specific code written by the user.

Global variables

Internal communication between modules inside the CarMaker simulation program is partly done using global struct variables. Three of them are central to the simulation: SimCore, Ambient and DrivMan. SimCore belongs to an internal module and contains data pertaining to control and overall functioning of the simulation program, i.e. most of its struct members do not represent physical quantities during a simulation. User code should therefore treat this variable as ‘read only’. To get an idea what the Ambient and DrivMan structs might con-tain, read the description of the concerning modules of the same name below.

Ambient

The Ambient module provides information about environmental conditions of the CarMaker virtual simulation environment, e.g. temperature and wind. Road data is also available here. This information is kept in the Ambient struct, which is mostly used by the vehicle module. DrivMan

The DrivMan module is responsible of letting the virtual driver perform the maneuvers defined in testrun. This is one of the most important modules inside the simulation program since its actions directly control the vehicle. The vehicle module should read the DrivMan

(16)

struct to find out which direction the virtual driver wants to the vehicle to go. The virtual driv-er in turn calls the vehicle module to find out about the current state of the vehicle, i.e. its position, velocity, etc.

DataDict

The DataDict module organizes all CarMaker quantities into a central data dictionary. The dictionary contents are shared with the Apo module, providing online quantity access to CarMaker interface tools like IPG-CONTROL. The second task of the DataDict module is to record and write simulation results. The vehicle modules registers quantities, that might be of interest to others, in the data dictionary. Availability of certain phyiscal quantities of the vehicle is also prerequisite to animation of the vehicle with IPG-MOVIE.

Log

During a simulation, whenever something happens that the user should know about (e.g. most often some kind of error condition), information about the event should be recorded in the simulation’s log file. The information is stored persistenly so as to be available for later evaluation. The CarMaker GUI takes care of notifying the user about important events that appear in the log file. The log module has a set of functions that allow for writing formatted messages of different log levels into the logfile of the current simulation. The vehicle module uses this functionality to inform the user, if e.g. the vehicle during initialization encounters a critical variable’s value to be completely out of range.

Apo

This is the communications module within CarMaker. It contains all the functions that a CarMaker application might need if it wants to communicate with other CarMaker applica-tions over a network using Apo services. Most of the communication tasks using Apo are already handled inside libcarmaker.a. The user might want to add some Apo code to Hilus-er.c, e.g. providing services to a user’s interface tool written in the Tcl language. Normally, there’s no need for the vehicle model to make use of the functionility offered by the Apo module.

Infofile

The infofile module contains functions that are used to access information stored in infofiles, e.g. CarMaker testrun data and vehicle parameters in the Data subdirectory are stored as infofiles. The vehicle module uses this module to read vehicle parameters from file during initialization.

(17)

CarMaker Flow Process Charts

1.3 CarMaker Flow Process Charts

CarMaker is a multi-threaded application. Hardware IO (if used) and most calculations are done in the realtime context of the main thread.

Figure 1.7: CarMaker Flow Process Charts

IO_In

Read Input Signals

Calc

from IO Hardware stop go Calculation of all Models.

One Integration Step

IO_Out

Write Output Signals to IO Hardware

APO

Communication with User Front End Tools.

GUI, IPG-MOVIE, Instruments, ...

Initialisation

Helper Threads

Low Priority

Cleanup

Write Output Signals to IO Hardware

Log

Output to stdout or Log File

DStore

Write Values of selected Variables to Results File

Read TestRun

Main Thread

High Priority

TestRun

Very Low Priority

Start/Stop Thread

Model

Initialisation &

Parameterization

Preparation

Calculating Start Confitions Simulation TestRun Start

Finish

Model

Finish & Cleanup

TestRun Stop

Operating Mode

Idle Operating Mode 1ms

(18)

Even if CarMaker is not running on a realtime computer the pricipals explained here are still the same.

Main Thread Restrictions

• Cycle time must allways be less than 1ms! • No file i/o

• No terminal output (printf...) • No otherwise blocking operations

• Reading and generation of files is done in seperate threads with lower priority. CarMaker provided Services: Log and DStore

• Parameter files are read in a separate “Testrun Start” Thread.

1.3.1 Modified Cycle Clock Generation if Oversampling is used

Sometimes the cycletime of 1 ms of the main thread is too restricitve and one wants to have parts of the CarMaker application running with a faster sample time. This can be because the acqusition of some input or output signals should be done with a higher frequency than 1 kHz. Only those signals are processed in the oversampling thread. The oversampling rate can only be a multiple of 1ms.

Figure 1.8shows how the oversampling thread triggers the main thread by sending an event every n-th cycle. This means that the clock timer moved from the main thread to the oversampling thread and triggers the clockless main thread.

(19)

Data is exchanged between the threads using data buffers containing the values of each oversample step. It is job of the main thread to process those values, e.g. through multiple calls (n times) of calculation models (with 1/n ms sample time) requiering or providing the data.

Figure 1.8: Interactions of oversampling thread and main thread

IO_In

Calc

stop go

IO_Out

APO

Initialisierung

Oversampling Thread

Very High Priority

Main Thread

High Priority

IO_In_fast

Minimal

Pre-/Post-stop go

IO_Out_fast

Oversampling

1/n ms

processing

Counter n:1

Datenpuffer

Main Cycle Timer Event

generate event on every n-th cycle

(20)

Figure 1.10depicts the timeline of the oversampling procedure. Imporant is that the over-sampling thread has higher priotrity than the main thread to ensure favored execution.

Figure 1.10: Timing Diagram

t Oversampling Thread Main Thread Main Cycle, 1ms Oversampling Cycle Idle Priority collected data to be handled in Main Thread

(21)

The main cycle explained

1.4 The main cycle explained

We now take a look at HilMain.c, the module that controls execution of the CarMaker sim-ulation program and represents the main cycle of CarMaker. It is important to get an idea of what’s going on in the main cycle in order to understand which tasks the vehicle module has to perform, how the interface to the vehicle module is organized and how it works.

Figure 1.12: Main Cycle – Detailed View stop go 1ms

IO_In

User_In

DVA IO_In

Driving Manager

includes IPG-DRIVER

DVA IO_DM

Calculation of

all Models

One integration step.

User_Calc

xyz_Calc.

User_Out

IO_Out

DVA IO_Out

DStorePutVec

AposPoll, Apos...

Handle recieved Messages, Send Messages

DStore

Write Values of selected Variables to Results File IPG-MOVIE IPG-CONTROL Instruments ring buffer (8 MB)

(22)

1.4.1 An pseudo code excerpt from HilMain.c

Note: The CASE statement is not considered to be “fall-through” like in C. /* Things done only once. */

Setup all modules

Register quantities of all modules in the data dictionary Export current configuration of the simulation program SimCore.State = ’Idle’

FOREVER {

/* Do next 1 ms simulation step */

Read hardware inputs

SWITCH SimCore.State { CASE ’SimStart’:

Prepare the simulation

Initialize DrivMan and vehicle module

Calculate static equilibrium position of the vehicle IF everything is prepared THEN

SimCore.State = ’Simulate’

CASE ’Simulate’:

Perform DrivMan calculations Perform vehicle calculations

IF end of testrun THEN

SimCore.State = ’SimStop’

CASE ’SimStop’:

Run down the simulation

IF everything is finished THEN

SimCore.State = ’Idle’

CASE ’Idle’:

Do nothing special }

Put calculated vehicle quantities into interface variable Write hardware outputs

IF SimCore.State == ’Simulate’ THEN

Store simulation results of current simulation step Perform Apo background communication tasks

Read Apo messages from CarMaker interface tools

IF message ’Start simulation!’ received THEN

SimCore.State = ’SimStart’

ELSE IF message ’Stop simulation!’ received THEN

SimCore.State = ’SimStop’

Send Apo messages to CarMaker interface tools }

The pseudo code listing above gives you a simplified high-level picture of the main actions that go on inside HilMain.c. A first look at the code reveals two important points about the program:

• The basic tasks of the main routine: Program setup, calculations, hardware i/o, storage of results, Apo communication.

(23)

We will now inspect each of these points more closely since they are crucial to an under-standing of the vehicle module interface.

1.4.2 Basic tasks of the main routine

Program setup is done only once and before entering the event loop. This is the time for all modules to register any quantities in the data dictionary for later access by CarMaker interface tools using Apo services and for the storage of simulation results. Also, information about the current configuration of the simulation program and of its modules (i.e. when it was built, version numbers of libraries and modules, etc.) are gathered and exported to a file later read by the CarMaker GUI.

Calculations are split among the DrivMan module and the vehicle module. The term also include the tasks performed e.g. at the beginning and end of a testrun simulation.

Hardware input/output is done before and after all calculations have been done. First the hardware is read, providing input for the calculations to be done next. After the calculations have been accomplished, the calculated values are output to the hardware. Of course this is only relevant for CarMaker/HIL. In case of CarMaker/Offline the functions called are emp-ty.

Storage of results takes place after the calculations. A vector containing all values of inter-est of the current time step is put into a buffer, that gets written to a results file asynchro-nously by a separate background thread.

Apo communication is handled at the end of the event loop. It consists of three tasks. First, Apo must be given a chance to handle its internal communication tasks, e.g. answering an interface tool that likes to connect to the CarMaker simulation program. Next, the program must read and interpret all Apo messages that may have been sent by CarMaker interface tools since the beginning of the current simulation cycle. Third, there might be some mes-sages the simulation program might want to send to connected interface tools itself. Other tasks like reading input from file and direct variable access (DVA) are not shown in the pseudo code. They do not directly interfere with the tasks of the vehicle module and have been left out for the purpose of clarity.

1.4.3 The event loop of the main routine

The basic principle of the main routine is that it’s event driven. In case of the CarMaker sim-ulation program, this is just a short term for the following (abstract) behaviour:

• The program runs in an endless loop, the so called event loop.

• During each cycle the program is always in exactly one of several well-defined states. Each state has a certain, well-defined meaning, and depending on the current state some action is performed.

• During the cycle one or more events may occur, provoking some reaction of the program. One possible reaction is a change of the current state. If no event occurs, the current state doesn’t change.

In theory, the simulation program should only be in one of two states: Either it is simulating a testrun, or it isn’t. In reality, finer control of the sequence of events requires more states to be used. Nevertheless, all states fall into one of the two categories mentioned: simulating or not simulating.

There are several kinds of events that can happen and that may cause a change of state in the simulation program. One possible event is some kind of error condition, e.g. the vehicle leaves the road during simulation or a connected hardware controller unit reports a problem with one of its sensors, so that the current testrun should be aborted. Other events are of a

(24)

more harmless nature, e.g. the preparation phase of a simulation is over and the program should proceed with the actual simulation. A third kind of events are messages sent by CarMaker interface tools that are connected to the simulation program. Think of a user pressing the Start or Stop button of the CarMaker GUI. In this case the CarMaker GUI sends an Apo message to the simulation program, telling it to start or stop the simulation of the current testrun.

When the program is not simulating a testrun, it is in state Idle. We may call it the default state of the program. Immediately after initialization and between testruns the program is in state Idle. This does not imply that the program is doing nothing. Maybe a good circumscrip-tion of the accircumscrip-tions performed in this state is “simulacircumscrip-tion of a vehicle standing still”.

The three states pertaining to the simulation of a testrun are SimStart, Simulate and Sim-Stop.

If a simulation is started, the program first enters state SimStart. This state is mainly asso-ciated with preparations at the beginning of the simulation. E.g. the vehicle reads its current parameters from file and tries to find its static equilibrium position. Maybe ignition is turned on, the engine is started, and so on.

If all preparations are done (and everything is ok), the current state changes to Simulate. Now the program is really performing the simulation of the testrun. It normally remains in this state until the testrun ends or is aborted because of some error condition or manual intervention of the user.

To end a simulation, the simulation program changes its state to SimStop. The idea of this state is to run down the simulation gracefully and bring the vehicle to a stop. When this has been accomplished, the program automatically changes to state Idle.

(25)

A stripped down CM_Main.c

1.5 A stripped down CM_Main.c

Below you find C code fragments that correspond to the pseudo code listing in the previous section. The correspondence is not 100%, but you will recognize all important points. We added most of the calls to functions defined in HilUser.c, so that the code is more complete. What we left out is the code to change the current state of the simulation program, i.e. changes made to SimCore.State; this would have added unnecessary complexity, since in fact there are more well defined states than the four mentioned in the previous chapter. Nev-ertheless, the C code provides you with all the necessary detail needed for a deeper under-standing of HilMain.c.

DrivManClear(); Vhcl_Clear(); IO_Init();

HilUser_SystemInit(); /* via Hil_GetSystemParameters() */ DrivManDeclareQuantities();

Vhcl_DeclareQuantities(); HilUser_DeclareQuantities()

Vhcl_ExportConfig(); /* via Hil_ExportConfig() */ for (;;) {

IO_In();

HilUser_IO_In();

switch (SimCore.State) { case State_SimStartXXX:

Vhcl_NewInit(); /* via Hil_SimStart() */ Vhcl_StaticCond(); /* via Hil_SimStart() */ HilUser_SimStart(); /* via Hil_SimStart() */ break; case State_Simulate: Vhcl_GetVhclState(); DrivManCalc(); Vhcl_Calc(); break; case State_SimStopXXX: HilUser_IOGetIdle();

HilUser_SimStop(); /* via Hil_SimStop() */ break; case State_Idle: Vhcl_GetVhclState(); break; } Vhcl_Out(); HilUser_IO_Out(); IO_Out(); DStorePutVec(); AposPoll();

while (/*any Apo message received */) { Hil_ApoMsgEval();

(26)

Main Loop } Hil_ApoSend(); HilUser_ApoSend(); }

1.6 Main Loop

(27)

SimStart

1.7 SimStart

State

Funktionen, Module In Out

I d l e I n it S i m S t o p ✗ State_Idle SimStart()

State_SimStart1: wait until Hil_SimStart() is finished

State_SimStart2: start engine, if desired

in MainLoop: DrivManCalc() State_SimStart3: _{PreSimulate()} OffsetTStart = 0 SimCore.State = State_Simulate in MainLoop: DrivManCalc() ✗ _{SimStart (Project, ... )} (SimCore.State = State_Idle) Project User Name FName OutFName SimCore.State = State_SimStart ApoMsg: SimStart ✗ _{Hil_SimStart()}

in MainLoop as seperate thread (SimCore.State = State_SimStart1) SimCore.T = 0.0 SimCore.State = State_SimStart1 ✗ in Hil_SimStart(): SimCore.SimPhase = SimPhaseInit LogReset() Car.Distance, ... = 0 Trailer.<xyz> = 0 SimCore.SimStartNo++ Eintrag in’s Logbuch Hil_TestRunInit() HilUser_SimStart() CarModelStaticCond() i = SimCore.SimPhase SimCore.SimPhase = SimPhaseSim CarModelCalc(0.0) CarModel_Out() SimCore.SimPhase = i; SimCore.Trailer.Active == 1 TrailerCalcStaticCond() CreateMovie() CreateCarMovieObject() CreateTrailerMovieObject() SimCore.SimPhase = SimPhaseSim DStoreSaveBegin(0, -1)

(28)

SimStart

Hil_TestRunInit()

* Hil_SaveSystemParameters() Parame-ter sichern

* Info-Files einlesen für Versuch, Fahr-zeug, Reifen * Hil_GetSystemParameters() * PrepareStoring() * PSChs_fromFileInit() * AmbientInit() * DrivManNewInit() * BrakeInit() * PowerTrainInit() * CarModelNewInit() * TrailerInit() * VerifyMode? -> CarModelVerify() HilUser_SimStart() Parametrierung anwendungsspezifischer Teile, Unterscheidung nach IO-Konfigura-tion

HilUser_GetSystemParameters ()

IO_GetConfig() State

I d l e I n it S i m S t o p

(29)

SimStop

1.8 SimStop

State

I d l e I n it S i m S t o p ✗ SimStop () SimCore.State = State_SimStop ✗ State_SimStop SimCore.State = State_SimStop1 SimCore.SimPhase = SimPhaseEnd SimCore.SimEndKl15Off -> Kl15 DStoreSaveEnd(0)

✗ State_SimStop1 run down IO quantities into idle conditions

Warten, bis SaveStatus gleich DStore_SaveInactive SimCore.State = State_SimStop1a

State_SimStop1a set I/O quantities to idle conditions

SimCore.State = State_SimStop2

State_SimStop2 Hil_SimStop() in extra Thread

SimCore.State = State_SimStop3

State_SimStop3 warten, bis Hil_SimStop() beendet

State_SimStop4 SimCore.State = State_Idle

SimCore.SimPhase = SimPhaseIdle

HilUser_SimStop()

Hil_SimStop()

Freigeben einiger Strukturen: TrailerDelete()

DrivManDelete() AmbientDelete() PSChs_fromFileDelete()

HilUser_IOGetIdle()

Überprüfen, ob sich das Fahrzeug bereits in Ruhe befindet.

Überführen relevanter Signale in den Ruhezustand.

(30)

30 Logging Module

General information

Chapter 2 Logging Module

Inside your CarMaker code, e.g. during a simulation, there might arise situations where it would seem useful to leave a short informational note about the current situation or inform the user about the circumstances of an error, that just occured. You may consider using printf() for this purpose, but this is not recommended under real-time conditions. Also, when the CarMaker simulation program is running on the real-time CPU, there is not necessarily a terminal available where the output of printf() could go.

In general it seems useful to keep a history of important or unusual situations and events during the simulation of a testrun, that does not disappear when the simulation is finished or the user turns off his his computer. This is why CarMaker offers a logging facility that keeps a record of events for each simulation in a log file. The log file can then be inspected at a later time or kept as a protocol e.g. of a driving maneuver that the connected hardware controller unit is still unable to handle.

In this section we’d like to show you how to use basic functionality of the Log module in your own code. Advanced features exists but are out of scope of this text.

2.1 General information

Each time a CarMaker simulation program is started it creates a new log file in the SimO-utput subdirectory of the CarMaker project directory. Log messages are recorded in the log file with a time stamp relative to the start of the current simulation.

Log messages fall into one of the following three categories, that determine the importance of a message:

• Errors

Issuing an error log message causes the current simulation to be aborted, so messages of this category should be reservered for cases where the program code is unable to cope with the current situation.

• Warnings

This category should be used for situations that are unnormal, but not critital. It means that the program code is able to handle the situation gracefully. A typical

(31)

Recommended use

example would be a parameter read during initialization that is out of range and has to be overridden with a more meaningful value.

• Purely informational messages

Use this category to inform about special events or conditions, like e.g. an ABS controller that is deactivated. It is also intended for debugging purposes. E.g. while customizing CarMaker for your real-time application, you may find it useful to tell that a certain point in initialization has been reached, or log the results of some critical computation.

Furthermode, warnings and errors are categorized by the time they are issued: • The fault happended during inititialization

• The fault happened during simulation

• The fault happened neither during initialization nor during simulation, it is considered to be a more general fault

2.2 Recommended use

As a rule of thumb, the number of log file entries should be kept to a minimum so as to increase readability. Entries should be kept short and informational. It is not useful to clutter the log file with lots of messages, especially under real-time conditions. It does not make sense to issue one or more log message in each simulation cycle, i.e. every millisecond; this unnecessarily wastes CPU power and network bandwidth.

2.2.1 List of functions

A look at the available functions should make clear, that they are quite straightforward to use. Use them as you use any function of the printf() family.

Please note the following peculiarity, though: Except for Log(), all functions automatically add a line feed character (\n) to the string to be added to the log file.

#include “Log.h”

void LogErrStr (unsigned ECId, const char *msg);

void LogErrF (unsigned ECId, const char *format, ...); void LogWarnStr (unsigned ECId, const char *msg);

void LogWarnF (unsigned ECId, const char *format, ...);

void Log (const char *format, ...); /* no line feed added automatically */ /* Constants to be used for the ECId parameter */

enum {

EC_Init /* Initialization fault */

EC_Sim /* Simulation fault */

EC_General /* General fault */ };

(32)

Recommended use

Example

#include “Log.h”

LogErrF(EC_Init, “Tyre parameter file ’%s’ not found.“, fname); LogWarnStr(EC_Sim, “Controller unit not responding.”);

(33)

33 Infofile Module

Infofile format

Chapter 3 Infofile Module

In the CarMaker environment, configuration and parameter information is stored in ASCII files that use a special format for easy access by program code. Such files are called info-files and the CarMaker library libcarmaker.a contains the Infofile module functionality used for opening, reading and writing to infofiles and accessing infofile data, all in a keyword ori-ented manner. For user code this offers a standardized and easy to use method to organize and access data in a file. It also avoids the difficulties of defining appropriate data struc-tures, learning the syntax and checking for errors.

When the simulation of a testrun starts, almost all testrun configuration data is contained in infofiles in the Data subdirectory of the current CarMaker project directory. This includes information about the configuration of the virtual driver, the vehicle, tires etc. At the begin-ning of a simulation the modules that need specific configuration and initialization data must retrieve this data from the appropriate infofile.

This sction gives a basic overview and also gives a concise list of the infofile functions in both the C and Tcl/Tk programming environments.

3.1 Infofile format

Normally, in the CarMaker environment the user can edit most data stored in infofiles com-fortably using specifically tailored programs like the CarMaker GUI. This does not mean, however, that the data stored is totally inaccessible outside the CarMaker environment. Infofiles are human-readable ASCII files, i.e. they can be viewed and edited with an ordinary ASCII text editor, making them much easier to handle than the binary data files often used by other Software.

(34)

Access functions

Data is stored as key-value pairs. The order in which key-value pairs appear in an infofile is not important. Keys names can (and should) be hierarchically organized using the dot char-acter as a separator. A value is basically a number, a strings or a text (i.e. a sequence of strings). This is best illustrated by a short example:

As you surely have noticed, there’s a difference between keys with a numeric or string value and keys with a text value. A text key is always delimited by a colon (‘:’) character and the following lines containing its value (the text lines) must be indented with a single tab char-acter.

It is not our objective to discribe the exact syntactic conventions of infofiles in this section. Please refer to existing infofiles in the Data subdirectory of your CarMaker project directory. As you will quickly see, infofile syntax is not at all a terribly complicated matter.

3.2 Access functions

Functions for opening and reading an infofile exist. They return a so called infofile handle of type “struct tInfos *”, that is a pointer to the data read from the infofile. This handle can be used to access individual keys and retrieve their value. Normally the CarMaker library auto-matically opens and reads all important infofiles of the current testrun and stores the infofile handles in the global variable SimEnv. Also, when the CarMaker environment invokes an initialization function like e.g. Vhcl_NewInit(), an infofile handle is automatically passed as a parameter. This means that in most cases you should not have to worry about how to read an infofile into memory. For more details see the example code below.

Access functions named iGetXXX() retrieve different types of values from keys: Strings, texts, double precision floating point values and signed or unsigned long integer values. Parameters to these functions are an infofile handle and a key name. Non-existence of a key accessed using these functions is considered to be an error.

For the purpose of retrieving values from keys that are only optionally contained in an info-file, a second set of functions named iGetXXXOpt() is available. They take an additional parameter to be used as the key’s default value in case the key doesn’t exist. (The iGetTx-tOpt() function is an exception to this rule; check for a NULL pointer returned by this func-tion.) Non-existence of a key accessed with these functions is not considered to be an error. Functions for the retrieval of other, higher level data types like tables and vectors also exist, Please refer to the functions description in this section for more information.

Composer = Sergej Prokofjef Title = Peter and the Wolf, Op. 67 Premiere.Year = 1936

Premiere.Month = May Movements:

Introduction The Story Begins The Bird

(35)

Error handling

3.3 Error handling

In case of an error an appropriate log message is automatically issued by the functions described above. In addition, an internal infofile error counter is maintained by the Infofile module. In case an error occurs (i.e. a non-optional key doesn’t exist or a key’s value could not be retrieved), the error counter is automatically incremented. This counter provides an efficient way of error checking for your code (see next paragraph for an outline of how to use this feature). The current value of the infofile error counter can be read using the Get-InfoErrorCount() function.

Error handling is best implemented as follows: before reading any infofile keys store the cur-rent infofile error counter’s value in a variable. Then access all necessary infofile keys (optional or not) in a row. After that, compare the current error counter with the value stored at the beginning. If the two values differ, at least one key’s value could not be retrieved and your code should report an error. The example below illustrates this technique.

(36)

36 Infofile Module C Function List

Example

3.4 C Function List

3.4.1 General Functions

InfoNew ()

Prototype

extern tInfos *InfoNew (void); Arguments

none Description

Creates a new instance of type tInfos. Return Value

Pointer (handle) to the newly created tInfos instance, or a NULL pointer on failure. # Infofile read by the example code (taken from Data/Vehicle/DemoCar)

Body.Mass = 1301 PowerTrain.Kind = Front

#include “infoc.h” #include “InfoUtils.h”

#include “Environment.h” /* for SimEnv global variable */ int

Vhcl_NewInit (const struct tInfos *Inf /*vehicle parameters*/) {

int count = GetInfoErrorCount(); double vel, pos, mass;

char *ptkind;

mass = iGetDbl(Inf, "Body.mass");

ptkind = iGetStr(Inf, “PowerTrain.Kind”); /* testrun parameters */

vel = iGetDblOpt(SimEnv.TestRun.Inf, "DrivMan.Velocityt0", 0.0); pos = iGetDblOpt(SimEnv.TestRun.Inf, "Road.CarStartPos", 1.0); if (GetInfoErrorCount() != count)

return -1; /* Error */ return 0;

(37)

C Function List

InfoDelete ()

Prototype

extern int InfoDelete (tInfos *inf); Arguments

• inf - handle of the data type tInfos to be deleted Description

Deletes the specified tInfos data type. Return Value

(check with frank)

InfoRead ()

Prototype

extern int InfoRead (tErrorMsg **perrors, tInfos *inf, const char *filename); Arguments

• perrors- pointer to an array that will contain any errors generated during the reading of the infofile

• inf - handle of type tInfos that will be used to store the information read • filename - name of the infofile to be read

Description

Reads from the file specified infilenameand writes to the tInfos buffer pointed to byinf. Return Value

Returns the number of errors that were generated during the read and that are contained in the perrors list. If the value is (0) then no errors were generated, if the value is ( greater than 0 ) then there were syntax errors during the read, if the value is (less than 0) then there were access, i.e., hard errors during the read which caused the read to fail.

InfReadMem ()

Prototype

extern int InfoReadMem (tErrorMsg **perrors, tInfos *inf, char *bufStart, int bufSize); Arguments

• perrors- pointer to an array that will contain any errors generated during the reading of the buffer

• inf - handle of type tInfos that specifies the memory location where the information read will be stored

• bufStart - pointer to the buffer to be read • bufSize- length, in bytes, of the buffer to be read Description

(38)

C Function List

Return Value

Returns the number of errors that were generated during the read and that are contained in the perrors list. If the value is (0) then no errors were generated, if the value is ( greater than 0 ) then there were syntax errors during the read, if the value is (less than 0) then there were access, i.e., hard errors during the read which caused the read to fail.

InfoWrite ()

Prototype

extern int InfoWrite (tInfos *inf, const char *filename); Arguments

• inf - tInfos handle to the infofile buffer • filename - name of the file to be written to Description

Writes the information contained in the tInfos bufferinfto the file specified byfilename. Return Value

Returns -1 on failure, and 0 otherwise.

InfoListKeys ()

Prototype

char **InfoListKeys (tInfos *inf, const char *prefix, tIterKind kind); typedef enum { Keys, Subkeys, Unread_Keys, All_Keys, } tIterKind; Arguments

• inf - tInfos handle to the infofile buffer

• prefix - specified the key prefix to be matched when searching for keys

• kind - the kind of key that will be included in the list. Must be one of the following enum types: Keys, Subkeys, Unread_Keys, or All_Keys.

Description

Used to get a list of the keys that match the specified search criteria. Searching is done using the two argumentsprefixandkind. Prefix specifies a character string to match. Kind specifies the key search type to be used. The following kinds are possible:

• Keys - Once the all keys are identified with the specified prefix, will list the key seg-ments that have a unique top level key segment. For example, if the prefix = AA, kind = Keys and the following list of key is used in a search:

AA.XX.11 AA.XX.22 AA.YY.11 AA.YY.22

(39)

C Function List

... then, the keys that would match the search criteria would be AA.XX, AA.YY, AA.ZZ. The third part of the key will play no role in this case and would be truncated from the key name when shown in the list. The list returned would be:

AA.XX, AA.YY, AA.ZZ

• Subkeys - The same as Keys except the list will be generated without the prefix part listed and only the matching subkey portion. The same search as described before would then return:

XX, YY, ZZ

• Unread_Keys - Only those keys with the matching prefix that have not been accessed (read or write) will be included in the list.

• All_Keys - All keys with the matching prefix will be returned. The whole key name will be listed. for example, using the same table and prefix as was used before, the returned list would be:

AA.XX.11, AA.XX.22, AA.YY.11, AA.YY.22, AA.ZZ.11, AA.ZZ.22

Return Value

Returns a NULL terminated list of keys, i.e. an array of char arrays.

InfoKeyKind ()

Prototype

tKeyKind InfoKeyKind (tInfos *inf, const char *key); typedef enum { No_Key, Empty_Key, String_Key, Text_Key, Prefix_Key } tKeyKind; Arguments

• inf - tInfos handle to the infofile buffer • key - name of the key

Description

Returns the type of value assigned to the specified key. Return Value

The return value is an enum type that can be one of the following: • No_Key - There is no key with the name specified

• Empty_Key - The key is not assigned a value

• String_Key - The key contains a string of data (i.e. the value is on a single line) • Text_Key - The key contains text or a table of data (i.e. the value spans more than one

line)

• Prefix_Key - The specified key is a prefix and not a complete key. AA.ZZ.11

(40)

C Function List

InfoDelKey ()

Prototype

int InfoDelKey (tInfos *inf, const char *key); Arguments

Description

Deletes the keys from the infofile buffer specified withinf that have the exact name as

key.

Return Value

Returns 0 on success, -1 on failure.

InfoDelTree

Prototype

int InfoDelTree (tInfos *inf, const char *key); Arguments

Description

Deletes the keys from the infofile buffer specified withinfthat have the same root as (i.e. begin with) key.

Return Value

3.4.2 Read Functions

InfoGetStr ()

Prototype

int InfoGetStr (char **pval ,tInfos *inf, const char *key); Arguments

• pval- pointer to the string that is read from the infofile buffer. The memory associated with this variable should NOT be freed by the user.

• inf - tInfos handle to the infofile buffer • key - name of the key to read

Description

(41)

C Function List

Return Value

InfoGetLong ()

Prototype

int InfoGetLong (long *pval, tInfos *inf, const char *key); Arguments

• pval- pointer to the value of type long int that is read from the infofile buffer. The mem-ory associated with this variable should NOT be freed by the user.

Description

Gets the long int value ofkeylocated in the infofile buffer that is specfied with the handle

inf.

Return Value

InfoGetDbl ()

Prototype

int InfoGetDbl (double *pval ,tInfos *inf, const char *key);

Arguments

• pval- pointer to the value of type double that is read from the infofile buffer. The mem-ory associated with this variable should NOT be freed by the user.

Description

Gets the double value ofkeylocated in the infofile buffer that is specfied with the handle

inf.

Return Value

InfoGetTxt ()

Prototype

(42)

C Function List

Arguments

• pval - pointer to the text string value that is read from the infofile buffer. The memory associated with this variable should NOT be freed by the user.

Description

Gets the text string value ofkeylocated in the infofile buffer that is specfied with the handle

inf. Used to read key values that span multiple lines.

Return Value

InfoGetStrDef ()

Prototype

int InfoGetStrDef (char **pval , tInfos *inf, const char *key, const char *def); Arguments

• pval- pointer to the string value that is read from the infofile buffer. The memory asso-ciated with this variable should NOT be freed by the user.

• def - default key value Description

Gets the string value ofkeylocated in the infofile buffer that is specfied with the handleinf. If there is no value assigned to it then the default value will be used.

Return Value

Returns 0 on success, 1 if the key doesn’t exist and -1 on failure.

InfoGetLongDef ()

Prototype

int InfoGetLongDef(long *pval, tInfos *inf, const char *key, long def); Arguments

• pval - pointer to the long int value that is read from the infofile buffer. The memory associated with this variable should NOT be freed by the user.

(43)

C Function List

Description

Gets the long int value ofkeylocated in the infofile buffer that is specfied with the handle

inf. If there is no value assigned to it then the default value will be used.

Return Value

InfoGetDblDef ()

Prototype

int InfoGetDblDef (double *pval ,tInfos *inf, const char *key, double def); Arguments

• pval - pointer to the double value that is read from the infofile buffer. The memory associated with this variable should NOT be freed by the user.

Gets the double value ofkeylocated in the infofile buffer that is specfied with the handle

inf. If there is no value assigned to it then the default value will be used.

Return Value

InfoGetStrDef ()

Prototype

int InfoGetTxtDef (char ***pval, tInfos *inf, const char *key, char **def); Arguments

• pval - pointer to the text string value that is read from the infofile buffer. The memory associated with this variable should NOT be freed by the user.

Gets the text string value ofkeylocated in the infofile buffer that is specfied with the handle

inf. Used to read key values that span multiple lines. If there is no value assigned to it then the default value will be used.

(44)

C Function List

Return Value

3.4.3 Write Functions

InfoSetStr ()

Prototype

int InfoSetStr(tInfos *inf, const char *key, const char *val); Arguments

• inf - tInfos handle to the infofile buffer • key - name of the key to be set

• val - new string value to be written to the key Description

Sets the value of the key. If the specified key does not exist then one will be created. Return Value

Returns 0 on success, and -1 on failure.

InfoSetLong ()

Prototype

int InfoSetLong(tInfos *inf, const char *key, long val); Arguments

• val - new long int value to be written to the key Description

InfoSetDbl ()

Prototype

(45)

C Function List

Arguments

• val - new double value to be written to the key Description

InfoSetTxt ()

Prototype

int InfoSetTxt(tInfos *inf, const char *key, char **val); Arguments

• val - new text string value to be written to the key Description

3.4.4 Add/Move Functions

InfoMoveKeyBefore ()

Prototype

int InfoMoveKeyBefore (tInfos *inf, const char *destkey, const char *key); Arguments

• destkey - name of the destination key used as a reference for the move • key - name of the key to be moved

Description

(46)

C Function List

Return Value

InfoMoveKeyBehind ()

Prototype

int InfoMoveKeyBehind (tInfos *inf, const char *destkey, const char *key); Arguments

• destkey - name of the destination key used as a reference for the move • key - name of the key to be moved

Description

Moves the key specified bykey behind the key specified bydestkey. Return Value

InfoAddLineBefore ()

Prototype

int InfoAddLineBefore (tInfos *inf, const char *destkey, const char *val); Arguments

• destkey - name of the destination key used as a reference for the line insertion • val - character string to be inserted

Description

Used to insert a comment or a blank line before the key specified bydestkey. Return Value

InfoAddLineBehind ()

Prototype

int InfoAddLineBehind (tInfos *inf, const char *destkey, const char *val); Arguments