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.

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);
        if (parameter is OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInParameter)
        {
            (parameter as OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInParameter).Value = value;
        }
        else if (parameter is OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInOutParameter)
        {
            (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
        return OpenTestSystem.Otx.Runtime.Api.DataTypes.ValueConverter.Value2String(parameter.Value);
    }
    catch (OpenTestSystem.Otx.Runtime.Api.Exceptions.InvalidLiteralException e)
    {
        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
    OpenTestSystem.Otx.Runtime.Api.DataTypes.Structure person1 = OpenTestSystem.Otx.Runtime.Api.DataTypes.ValueConverter.String2Value(structureLiteral, structureDataType) as 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}
    OpenTestSystem.Otx.Runtime.Api.DataTypes.Structure chris = inParameter.Value as OpenTestSystem.Otx.Runtime.Api.DataTypes.Structure;
 
    // 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;
 
    List<OpenTestSystem.Otx.Runtime.Api.DataTypes.StructureElement> newChrisInfoCollection = new List<OpenTestSystem.Otx.Runtime.Api.DataTypes.StructureElement>();
    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);
            OpenTestSystem.Otx.Runtime.Api.DataTypes.StructureElement nameStructureElement = new OpenTestSystem.Otx.Runtime.Api.DataTypes.StructureElement(
                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);
            OpenTestSystem.Otx.Runtime.Api.DataTypes.StructureElement ageStructureElement = new OpenTestSystem.Otx.Runtime.Api.DataTypes.StructureElement(
                info.Name
                , newAgeValue
                , info.Type
            );
            newChrisInfoCollection.Add(ageStructureElement);
        }
    }
 
    // Create new Chris Structure with the new Information
    OpenTestSystem.Otx.Runtime.Api.DataTypes.Structure updatedChrisStructure = new OpenTestSystem.Otx.Runtime.Api.DataTypes.Structure(
        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.DataTypes.EnumerationElement redColor = inParameter.Value as OpenTestSystem.Otx.Runtime.Api.DataTypes.EnumerationElement;
 
    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
    OpenTestSystem.Otx.Runtime.Api.DataTypes.EnumerationElement blueColor = colors.First();
    foreach (OpenTestSystem.Otx.Runtime.Api.DataTypes.EnumerationElement color in colors)
    {
        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"
    OpenTestSystem.Otx.Runtime.Api.DataTypes.ResourceLocation resourceLocation = inParameter.Value as OpenTestSystem.Otx.Runtime.Api.DataTypes.ResourceLocation;
 
    // 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";
 
    OpenTestSystem.Otx.Runtime.Api.DataTypes.ResourceLocation logoResource = new OpenTestSystem.Otx.Runtime.Api.DataTypes.ResourceLocation(id, location);
 
    // Assume that the given inParameter datatype is ResourceLocation
    inParameter.Value = logoResource;
}

Table of Contents

OTX Data Types Supported at the API

Data Type Conversion

Direct usage (Data Type Reflexion)

Literal Conversion

Code Example