Execution

Table of Contents

• Preconditions
• Binary Format and Compatibility
• Parameters and Variables Handling
• Synchronous or Asynchronous Execution
• Event Processing
• Execution States
• Connection State Handling
• Timeout

If a Procedure was browsed, the procedure can be executed, see Execute method.

Note: Before a procedure can be executed the preconditions below must be met.

Preconditions

Before execution the following preconditions must be met:

1. A valid license key must be entered, see LicenseManager
2. If diagnostic communication is needed, the DiagManager must be started, see DiagManager Execution and configured, see DiagManager Configuration

   Note: A DiagRuntimeSystem must be installed, configured and accessible, see Installation.

3. An instance of a RuntimeManager must be created

   Note: A RuntimeManager instance can be created inside the main thread or inside a new thread.

4. All needed custom implementations should be registered at the API, see CustomImplementation
5. A PTX or PPX file must be loaded, see LoadPtx

   Note: The executable binary files inside the PTX must be compatible to the version of the OTX-Runtime API, see ApiBinaryFormatCompatibility.

6. All settings for the project, custom implementations, the tracing etc. should be handled, see Configuration
7. If needed, all ProcedureInParameter, ProcedureInOutParameter and ContextVariable should be set, see Parameters and Variables Handling.

Binary Format and Compatibility

The OTX-Runtime API cannot execute OTX procedures directly. Before execution the OTX procedure must be compiled into an executable binary format within the OTX Development Environment. It is the intention that each version of the OTX-Runtime API should be able to execute each version of the binary format. But this cannot be guaranteed over the whole life cycle of the OTX-Runtime API. Therefore the OTX-Runtime API and the binary format contains the following versions, to ensure that the binary format is upward and backward compatible with a certain version of the OTX-Runtime API.

Note: For execution a PTX container must contain executable binary files, which can be created inside the OTX Development Environment.

Version	Storage Location	Description
RuntimeVersion	Property of the OTX-Runtime API	The version of the OTX-Runtime API which executes the the binary files
MinBinVersion	Property of the OTX-Runtime API	The minimum compiler version of the binary file that the OTX-Runtime API can handle
MinRuntimeVersion	Inside the binary files	The minimum version of the OTX-Runtime API that can handle the binary files
CompilerVersion	Inside the binary files	The version of the compiler which builds the binary files

Upward Compatibility: An upwardly compatible binary format means that an older version of the binary format can run on a newer version of OTX-Runtime API. There is upward compatibility if:

     CompilerVersion >= MinBinVersion

Backward Compatibility: A backward compatible binary format means that a newer version of the binary format can run on an older version of OTX-Runtime API. There is backward compatibility if:

     RuntimeVersion >= MinRuntimeVersion

Note: The OTX-Runtime API checks the compatibility by itself and will throw an exception, if an incompatible binary format tried to use.

Note: The versions of the binary files are stored inside the PTX besides the binary files, see /CppOutput/buildinfo.json.

Parameters and Variables Handling

Before, during and after procedure execution parameters and variables must be handled.

Parameters and Variables Handling before, during and after procedure execution

Before the execution of a Procedure, see Execute the following settings should be set:

• ProcedureInParameter
• ProcedureInOutParameter
• ContextVariable

During the Procedure execution, see Execute the following settings can be set or get:

• ProcedureInOutParameter
• ContextVariable
• StateVariable

After the Procedure execution, see Execute the following settings can get:

• ProcedureOutParameter
• StateVariable

Synchronous or Asynchronous Execution

A Procedure can be executed in two similar modes: synchronously or asynchronously, see Execute or ExecuteAsync. Synchronously means that the thread where the procedure is executed will be stopped until the procedure execution will finished. Asynchronously means that the thread where the procedure is executed will not be stopped during the procedure execution. In this case, the application must handle the procedure events like ProcedureFinished, see RuntimeManager.

Note: It is possible to execute more than one Procedure at the same time. One possibility is the asynchronous execution with one RuntimeManager. The other possibility is to start more than one RuntimeManager in different threads and execute the procedure synchronous.

Note: Each procedure will be executed inside a new RuntimeContext. With RuntimeContext the lifetime of a procedure can be handled. For example a running procedure can be paused, continued or stopped or the state of the execution can be determined, see Execution States.

Event Processing

The following sequence diagram shows the possible events while procedure execution. The events will be handled inside the RuntimeManager.

Event processing while procedure execution

Execution States

The following state diagram shows the different execution states during procedure execution. If a procedure was executed successfully the initial execution state is Running. This state can only be changed by

• Calling a method of the unique RuntimeContext,
• Normal and of the procedure,
• An unhandled OTX exception inside or
• If a procedure timeout occurs.

Each change of the execution state will signaled by an appropriate event: ProcedureStarted, ProcedurePaused, ProcedureContinued, ProcedureStopped, ProcedureFinished, ProcedureTimeout and ProcedureAborted.

Execution states while procedure execution (synchronous and asynchronous) together with calling methods (bold) and events

Connection State Handling

With the Diag-Connection-State feature the procedure execution can be implicit controlled via the state of the battery (clamp 30) and/or the ignition (clamp 15). The procedure execution can be implicit paused if an expected state is not fulfilled and continued if the expected state is fulfilled. To use the connection state the procedure must be executed via an Execute method with an expected state not equal to None.

During the procedure execution the connection state will be checked cyclically, see PollingTime and BatteryVoltageThreshold. The DiagConnectionStateChanged event will be fired if the connection state will be changed.

The following sequence diagram shows the possible events while procedure execution with connection state handling:

Execution states while procedure execution (synchronous and asynchronous) with connection state handling

Timeout

A procedure can be executed with a timeout. The timeout must be set in the Execute method. If a timeout is greater then zero and the procedure execution duration exceeds the timeout value, the execution will be stopped (same like calling the RuntimeContext.Stop() method) and a ProcedureTimeout event will be fired.

Note: The timeout value will be only counted if the procedure is in execution state Running, see Execution States.