OTX-Runtime for DotNet  
Data Type Handling

To interact with OTX sequences the following parameters and variables can be handled at the API:

From the OTX point of view each parameter and variable can have an arbitrary OTX data type. But at the level of the API not all OTX data types are supported, because most of them are only valid inside the OTX runtime context. The table below describes all data types supported at the API.

Note: This does not mean, that no other data type can be used, but it will be not exchangeable with all systems! The DotNet API supports more data types like the APP in C++. As example a List with 10 levels is possible at DotNet API but not at C++ API. At C++ API it is limited to 3 levels.

OTX Data Types Supported at the API

Data type Is complex Description Example in OTL Literal notation Corresponding C# data type for direct usage
String Simple string "MyText" or "" System.String
Boolean Boolean value TRUE or FALSE true or false System.Boolean
Integer 64 bit integer number 123 System.Int64
Float Floating point number with double precision 1.23 System.Double
ByteField x Array of bytes, see also ByteField at API &123456789ABCDEF0 or &NULL OpenTestSystem.Otx.Runtime.Api.DataTypes.ByteField
List x Array of a data type listed here in any combination. Only 3 levels are supported! { "Value1", "Value2", "Value3" } or {}  System.Collections.Generic.List<T>
Map x Dictionary of key, value pairs. The key must be of data type String or Integer. The value an be a data type listed here in any combination. Only 3 levels are supported! { "Key1":"Value1","Key2":"Value2","Key3":"Value3" } or {} System.Collections.Generic.Dictionary<TKey,TValue>
Enumeration Named Integer, see also Enumeration at API Element1 OpenTestSystem.Otx.Runtime.Api.DataTypes.EnumerationElement
Structure x Structure with arbitrary elements of data types listed here in any combination. Only 3 levels are supported! See also Structure at API {BooleanElement1 = true, IntegerElement2 = 3, StringElement3 = "Text"}
Please see note below!
OpenTestSystem.Otx.Runtime.Api.DataTypes.Structure
ResourceLocation x ResourceLocation represents a string value which addresses a location of a resource associated with an ID. See also ResourceLocation at API. @ResourceLocation:"MyResource"/"file:///C:/path/to/resource.res" OpenTestSystem.Otx.Runtime.Api.DataTypes.ResourceLocation

Note: Currently OTX (ISO 13209-4:2022) does not support literals for Structures. Structure literals will be supported in edition 2 of ISO 13209-4. Structure literals are only supported at the API for the conversion of structure values, see Literal Conversion.

Note: The Literal from a String must start and end with double quotes, e.g. "Hello World".

Data Type Conversion

In certain situations values with complex OTX data types, e.g. List, Map, Enumeration, Structure or ResourceLocation, must be handled by the application. Data types from the application must be mapped to data types available at the API (OTX data types), see picture.

The OTX-Runtime API supports two ways for OTX Data Type Mapping for all supported data types.

  1. Direct usage (Data Type Reflexion)
  2. Literal Conversion

Note: The conversion of OTX data types into the data types of the application must handled within the application, since only the application knows their data types.

Direct usage (Data Type Reflexion)

For the direct usage all supported data types have a corresponding data type of the certain target system (C++, DotNet, Java), see table above. Most simple data types are delivered as native data types of the target system. They do not need a special handling. Dependent from the target system some complex OTX data types needs a special handling. This data types are listed in the DataTypes section of the OTX-Runtime API. This data type support methods or properties to get detailed inner information of that data type, so that values can be read or written.

Literal Conversion

The Literal Conversion is a convenient and fully generic way. The following two conversion methods are provided:

Value2String(Object value)
This method converts a value from an element of the API like a ProcedureParameter to a string. The string is formated in OTL Literal notation and is therefore independent from the underlying software platform.

String2Value(String literal, String dataType)
This method converts a string in OTL Literal notation (e.g. given from Value2String(Object value)) into a value of the given data type. The string for the data type is also formated in OTL notation and is therefore independent from the underlying software platform. The data type string can be get via the related method or property of the related OTX element, e.g. procedure parameter data type.

Note: To convert a value of a supported data type from a string to a value the application must create a literal in OTL notation. This can become complex, especially with nested complex data types. In this case the usage of Direct usage (Data Type Reflexion) is recommended.

Note: Do not use a certain ToString method of the application! To convert a value of a supported data type to and from a string, these methods are recommended to use!

Code Example

The example shows the pseudo code of the principle handling of data types of the OTX-Runtime API.

// Pseudo-Code example to convert values to string and vice versa
// ==============================================================
// Please note that the exact syntax of C++, DotNet and Java is different!
void main()
{
// ...
// Set and Get datatype List
// Assume the parameter[0] is a ProcedureInParameter of data type List of String (List<String>)
String newlyAddedListStringLiteral = SetParameterValue(procedure.Parameters[0], "{\"Value1\", \"Value2\", \"Value3\"}");
// ...
// ...
// Set and Get datatype Map
// Assume the parameter[1] is a ProcedureInParameter of data type Map with key of type String and value of type String (Map<String, String>)
String newlyAddedListStringLiteral = SetParameterValue(procedure.Parameters[1], "{\"Key1\":\"Value1\", \"Key2\":\"Value2\", \"Key3\":\"Value3\"}");
// ...
// ...
// Set and Get datatype ByteField
// Assume the parameter[2] is a ProcedureInParameter of data type ByteField
String newlyAddedListStringLiteral = SetParameterValue(procedure.Parameters[2], "&121212");
// ...
// Set and Get datatype ResourceLocation
// Assume the parameter[3] is a ProcedureInParameter of data type ResourceLocation
String newlyAddedListStringLiteral = SetParameterValue(procedure.Parameters[3], "@ResourceLocation: \"ID_1\"/\"path/to/resource/file\"");
// ...
}
// Set value to a parameter using string literal
// and Get the newly added value back as a string literal
String SetParameterValue(OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureParameter parameter, String stringLiteral)
{
if (parameter is null)
{
return String.Empty;
}
try
{
// The string literal will be converted to an OTX Data Types Supported at the API
Object value = OpenTestSystem.Otx.Runtime.Api.DataTypes.ValueConverter.String2Value(stringLiteral, parameter.DataType);
{
(parameter as OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInParameter).Value = value;
}
{
(parameter as OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInOutParameter).Value = value;
}
// Get value from the parameter and convert it back to a string literal
// This should be nearly the same as the new string literal set to the Parameter
}
{
throw e;
}
}
OpenTestSystem.Otx.Runtime.Api.DataTypes.Structure CreatePersonStructureWithValueConverter()
{
// Structure: Person{Name, Age}
// Name: String
// Age: Integer
// Structure Person is locate inside Document1 in Package1
String structureDataType = "Package1.Document1.Person<String, Integer>";
String structureLiteral = "{Name=\"Chris\",Age=25}";
// Use ValueConverter.String2Value to convert the string literal
// then cast the result from Object back to OpenTestSystem.Otx.Runtime.Api.DataTypes.Structure
return person1;
}
void ChangePersonStructure(OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInParameter inParameter)
{
// Structure: Person{Name, Age}
// Name: String
// Age: Integer
// Structure Person is locate inside Document1 in Package1
// Assume that the given inParameter datatype is Person Structure
// and default value is Person{Name="Chris",Age=25}
// Get StrutureElements from Structure chris
// This Collection should contains only 2 values (Name and Age StructureElement)
ReadOnlyCollection<OpenTestSystem.Otx.Runtime.Api.DataTypes.StructureElement> chrisInfoCollection = chris.Elements;
String newNameLiteral = "\"Christopher\"";
String newAgeLiteral = "40";
foreach (OpenTestSystem.Otx.Runtime.Api.DataTypes.StructureElement info in chrisInfoCollection)
{
// Create new StructureElement Name
if (info.Name == "Name")
{
Object newNameValue = OpenTestSystem.Otx.Runtime.Api.DataTypes.ValueConverter.String2Value(newNameLiteral, info.Type);
info.Name
, newNameValue
, info.Type
);
newChrisInfoCollection.Add(nameStructureElement);
}
// Create new StructureElement Age
else if (info.Name == "Age")
{
Object newAgeValue = OpenTestSystem.Otx.Runtime.Api.DataTypes.ValueConverter.String2Value(newAgeLiteral, info.Type);
info.Name
, newAgeValue
, info.Type
);
newChrisInfoCollection.Add(ageStructureElement);
}
}
// Create new Chris Structure with the new Information
chris.Signature
, newChrisInfoCollection
);
}
OpenTestSystem.Otx.Runtime.Api.DataTypes.EnumerationElement CreateColorEnumerationWithValueConverter()
{
// EnumerationSignature name: Color
// EnumerationElements in Color: Red, Green, Blue
// EnumerationSignature Color is locate inside Document1 in Package1
String enumerationDataType = "Package1.Document1.Color";
String enumerationLiteral = "Blue";
// Use ValueConverter.String2Value to convert the string literal
// then cast the result from Object back to OpenTestSystem.Otx.Runtime.Api.DataTypes.EnumerationElement
// This will only work after the Otx Runtime Api loaded a PTX contains EnumerationSignature Color like above
OpenTestSystem.Otx.Runtime.Api.DataTypes.EnumerationElement color1 = OpenTestSystem.Otx.Runtime.Api.DataTypes.ValueConverter.String2Value(enumerationLiteral, enumerationDataType) as OpenTestSystem.Otx.Runtime.Api.DataTypes.EnumerationElement; // On success, this will return Color EnumerationElement Blue
return color1;
}
void ChangeColorEnumerationElement(OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInParameter inParameter)
{
// EnumerationSignature name: Color
// EnumerationElements in Color: Red, Green, Blue
// EnumerationSignature Color is locate inside Document1 in Package1
// Assume that the given inParameter datatype is EnumerationElement from Color EnumerationSignature
// and the default Color is Red
OpenTestSystem.Otx.Runtime.Api.Otx.Signatures.IEnumerationSignature colorEnumeration = redColor.Enumeration;
// Get all Color EnumerationElements
List<OpenTestSystem.Otx.Runtime.Api.DataTypes.EnumerationElement> colors = colorEnumeration.Elements;
// Get Blue Color EnumerationElement
{
if (color.Name == "Blue")
{
blueColor = color;
break;
}
}
// Set Blue Color into inParameter
inParameter.Value = blueColor;
}
void ChangeLocationPropertyOfResourceLocation(OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInParameter inParameter)
{
// Assume that the given inParameter datatype is ResourceLocation
// and the default ID is "ID_1" and Location is "current/path/to/resource"
// Update ResourceLocation
// Since this is a reference to the ResourceLocaiton inside inParameter
// , the ResourceLocation's Location should also be updated, inParameter.Value does not need to be set again
resourceLocation.Location = "new/path/to/resource";
}
void CreateNewResourceLocationWithResourceLocationConstructor(OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInParameter inParameter)
{
String id = "Logo";
String location = "/home/chris/pictures/myLogo.ico";
// Assume that the given inParameter datatype is ResourceLocation
inParameter.Value = logoResource;
}
Represents an element of an OTX Enumeration
Definition: EnumerationElement.cs:17
long Value
Gets the value of the enumeration element
Definition: EnumerationElement.cs:79
Represents the data type ResourceLocation
Definition: ResourceLocation.cs:7
string Location
Gets default resource location
Definition: ResourceLocation.cs:32
Represents OTX StructureElement DataType.
Definition: StructureElement.cs:7
Represents OTX Structure DataType.
Definition: Structure.cs:13
Converts OTX Value to Literal in OTL notation and vice versa.
Definition: ValueConverter.cs:22
static object String2Value(string literal, string targetType)
Converts a Literal into a value of the given data type.
Definition: ValueConverter.cs:55
static string Value2String(object value)
Converts a value from an element of the API to a Literal in OTL notation.
Definition: ValueConverter.cs:189
Thrown when a literal string cannot be converted to OTX Object.
Definition: InvalidLiteralException.cs:14
Represents class for InOutParameter of a Procedure. The parameter is identical to a related parameter...
Definition: IProcedureInOutParameter.cs:8
Represents class for InParameter of a Procedure. The parameter is identical to a related parameter in...
Definition: IProcedureInParameter.cs:8
Represents base class for InParameter, OutParameter and InOutParameter of a Procedure....
Definition: IProcedureParameter.cs:8
Represents an OTX Enumeration Signature.
Definition: IEnumerationSignature.cs:14
Namespace which contains all supported data types
Definition: BlackBox.cs:5
Namespace containing exceptions
Definition: ConnectionStateException.cs:7
Namespace for browsing at OTX signatures.
Definition: IConstructorSignature.cs:10
Namespace for browsing at OTX data structure.
Definition: IContextVariable.cs:5
Namespace containing the programming interface for browsing and execution of OTX procedures in own ap...
Definition: ApiConstants.cs:5
Namespace containing all objects for browsing and execution of OTX procedures
Definition: ApiConstants.cs:5
Namespace containing all objects which are standardized according to ISO 13209 (OTX)
Namespace containing all objects related to testing inside automotive industry