data access data analysis - highqsoft hql highqsoft query language andreas hofmann - 2014 sep 25...

Anzeige A4

Anzeige 4C (Darst. 50%)

HighQSoft GmbH I Erscheinungsbild I Seite 9

Beispiele Print

HighQSoft GmbH • Schloßborner Weg 6b • D - 61479 Glashütten • phone: +49 6174 2032408 • fax: +49 6174 62935 • www.highqsoft.de

Data Storage Data AnalysisData Import, -Export & Archiving

Data Access

Hier steht eine HeadlineAt aspiet peliquunt peribus doluptio. Illam, site volorecto molupta epelendant, sus ariam apel ent venisi tem ut pa nitati num sinctot atempor eperchic temque dita que pereni quaeptatia veles-ciet aut acescitate volorposam et escimol.

uptate lam eum et fugia coriam faci ut doluptur, occaerae qui sandem incium se volentia volo-rerupta qui aut remped molupti cum, consequid mos restiis ellati nos aut quis magnitas digent repta corporrovid mos volorat re, rehenduci quam vendus voluptaque verrumque.

HQL Specification

Simple ASAM ODS Query and Control

2 | Introduction |

Notice

Impressum

The authors and the publisher have taken care in the preparation of thisbook, but make no expressed or implied warranty of any kind and assumeno responsibility for errors or omissions. No liability is assumed forincidental or consequential damages in connection with or arising out ofthe use of the information or programs contained herein.

This document is generated automatically from the PVMsys developmentenvironment. The sections are kept separately in a repository. Therefore acommon version of the document doesn't exist.

If somebody has found a mistake, please send a comment [email protected]

creation date: Sep 07 2015copyright © 2015 by HighQSoft GmbHwww.highqsoft.de

4 | Impressum |

| TOC | 5

Contents

HQL.............................................................................................................................................7HQL HighQSoft Query Language..................................................................................................................7

What is HQL?.....................................................................................................................................7Introduction........................................................................................................................................ 8Literal Values..................................................................................................................................... 9Identifiers..........................................................................................................................................13Values............................................................................................................................................... 17Options..............................................................................................................................................19Columns of Result............................................................................................................................ 19Operators.......................................................................................................................................... 20Join....................................................................................................................................................24Ordering............................................................................................................................................24Grouping...........................................................................................................................................24References........................................................................................................................................ 24Flags..................................................................................................................................................25Relation Range................................................................................................................................. 25Keywords..........................................................................................................................................26HQL Commands...............................................................................................................................26Using HQL in JAVA OSGi Environment........................................................................................ 49Using HQL in JAVA bound as Library............................................................................................52Using the Command Line Version................................................................................................... 53Extended Aggregation Functions..................................................................................................... 55Frequently Asked Questions.............................................................................................................55

6 | TOC |

HQL

HQL HighQSoft Query Language

Andreas Hofmann - 2014 Sep 25de.highqsoft.ods.query.hql

What is HQL?

is a fast query and control language for ASAM ODS servers. It simplifies the usage of the generic ASAMODS API by using the business objects of the underlying ASAM ODS data model. provides an OOAPI as well as an interpreter for a query language similar to SQL. Complex generic ASAM ODS API querystructures can be avoided by developers. This makes code shorter, better to read and more maintainable. Astandalone option allows the user to send commands directly from command line to ASAM ODS server. can handle multiple transactions and is extendable by own aggregation functions. is a 100% pure JAVAimplementation, except the part that is dealing with the Reprise License.

ASAM ODSServer

HQL

ASAM ODS API

Command Line User ASAM ODSbased

Application(e.g. WEB or standalone)

OO API

Figure 1: System Context

Goals

• Efficiency - Maintenance of code becomes easy because bridges and simplifies the complex genericASAM ODS API calls. It ensures that translation to the ASAM ODS API is done highly efficient.

• Flexibility - The library can be used as command line tool or as a library being part of a complex ASAMODS client application. Developers can use it either via an OO API or by sending command strings. command strings can be provided by application configuration. It can also be used by system administrators tocontrol and observe ASAM ODS based systems.

• Modularity - can be used as library in every JAVA based program. In parallel it can be used as bundlein OSGi based systems.

• Learnability - syntax is well documented and can be easily learned.

8 | HQL |

Introduction

This component is an implementation of the service com.pvmsys.infra.query.service that ispart of the PVMSys infrastructure layer.

The ASAM ODS interfaces define interfaces and methods to create, select, update, insert and delete instancesof the ASAM ODS model. Additionally it is possible to retrieve information about the model and the serverside features and configuration. The ASAM ODS model is not fixed, therefore the interfaces are generic and acomplex calling sequence is necessary to communicate with the ASAM ODS server. A detailed knowledge isnecessary to create these calling sequences effectively.

For this reason we defined a language similar to SQL called (HighQSoft Query Language) to encapsulte thecomplexity into simple strings.

Just as a starting example, have a look to the JAVA code to get a list of names of all available physical units. Toshorten the example we omitted catching exceptions and null objects.

AoSession aoSession = ... // Get the model structure. ApplicationStructure as = aoSession.getApplicationStructure(); ApplElemAccess aea = aoSession.getApplElemAccess(); // Get the application element. ApplicationElement ae = as.getElementsByBaseType("aounit")[0]; T_LONGLONG aeId = ae.getId(); // Get the name attribute. ApplicationAttribute attr = ae.getAttributeByBaseName("name"); String aeName = attr.getName(); // Create the query structure. QueryStructureExt qse = new QueryStructureExt(); // Request the name of the unit. qse.anuSeq = new SelAIDNameUnitId[1]; AIDName aidName = new AIDName(aeId, aeName); qse.anuSeq[0] = new SelAIDNameUnitId(aidName, new T_LONGLONG(), AggrFunc.NONE); // Initialize the whole structure. qse.condSeq = new SelItem[0]; qse.groupBy = new AIDName[0]; qse.joinSeq = new JoinDef[0]; qse.orderBy = new SelOrder[0]; // Get the result. ResultSetExt[] res = aea.getInstancesExt(qse, 0); // Get the names. String[] names = res[0].firstElems[0].values[0].value.u.stringVal();

Using we can simplify this complex calling sequence to one single line:

hql aounit.name;

is a domain specific language that can be used as a query language for ASAM ODS servers. Thiscomponent can be used in the PVMsys Application Abstract layer to abstract from ASAM ODS and to hide theASAM ODS complexity from developers. The translation from input to execution is done in two steps. The firststep is a parsing step and the second step translates the parser result into ASAM ODS calls. As result we have aPVMsys component that always translates the sentences and returns a result set. Every command returns a resultset, even if a delete command is executed. The result set is similar to a table definition and allows to retrieve thevalues independently of ASAM ODS.

To define the language and to generate the parser code we are using the JAVA tool ANTLR (ANother Tool forLanguage Recognition). ANTLR is a parser generator that automates the construction of language recognizers.

| HQL | 9

From a formal language description, ANTLR generates a program that determines whether sentences conform tothat language.

There are some requirements that are fulfilled:

• all keywords are case insensitive• it must be possible to set implementation specific options• recursive sub-queries must be possible

is running as a normal ASAM ODS client. The business logic of the ODS model by database constraintsis not known by . That means it is possible that the thows exceptions caused by database constraints.

doesn't care about these kind of problems. The business layer that uses must know what is allowed inthe data model and what kind of operations are prohibited.

The following chapters describe the rules for writing statements into a string.

Literal Values

This section describes how to write literal values in . This includes strings, numbers, hexadecimal values,octal values and boolean values.

String Literals

A string is a sequence of characters. If this character sequence does not contain any white space or quotes, it isnot necessary to encapsulate it in quotes.

HighQSoftTestEquipmentAndreas

If the sequence contains white spaces, it must be quoted.

"a string""Mike's handy"'Hans said: "good morning"'

or

"Hans said: 'good morning'"

A list of escaped characters can be used to express the white spaces.

Character Literal Description

\b for backspace character

\t for tabulator character

\n for new line character

\f for form feed character

\r for line feed character

\" for double quote character

\' for single quote character

\\ for backslash character

Escape sequences can be build by octal code or unicode character sequences.

10 | HQL | � �� Figure 2: String Literals� �� Figure 3: Escape Sequences� ��

Figure 4: Hexadecimal Characters� �� Figure 5: Unicode Characters� ��

Figure 6: Octal Characters

The following unicode sequence has a meaning in japanese language.

\u7686\u3055\u3093\u3001\u3053\u3093\u306b\u3061\u306f

Figure 7: Japanese Characters

| HQL | 11

The german mutated vowel (umlaut) characters can be used directly in UTF-8 encoding.

äöüÄÖÜß

Number Literals

Integers are represented as a sequence of digits. Floats use dot ('.') as a decimal separator. Float values areinternaly mapped to double representation and integers to long representation. Either type of number may bepreceeded by '-' or '+' to indicate a negative or positive value.

614790-190

Examples of valid floating point numbers are.

-273.153.844e+5� ��

Figure 8: Number Literals� �� Figure 9: Integer Literals

int

+

-

'0'..'9'

float

+

-

'0'..'9'

'0'..'9'.

E

e

+

-

'0'..'9'

Figure 10: Float Literals

Date Literals

Date literals are defined as it is done in ASAM ODS. The literal is built by the pattern yyyyMMddHHmmssSSS(s.a. java.text.SimpleDateFormat) and can be reduced until just the year specification is remaining - atleast year specification is mandatory.

20130725201307251155000002013

It is not possible to specify a time difference with this format. Therefore we defined some methods that can beused for that issue. The functions are not case sensitive and can be used everywhere where you have to use a datestring for DT_DATE values. These functions enable you to specify the following dates:

now()-years(2)

12 | HQL |

now()-months(2)-days(5)-hours(23)now()+days(2)

or even a combination of both

"20090101-hours(30)"

If this kind of function is used in commands, you have to quote the date specification.

Date Literal Description

NOW() This function returns the date value of the runtime environment in that moment it isevaluated.

YEARS(value) This function returns the time difference to the specified years. If there is no parameterthe current year is used.

MONTHS(value) This function returns the time difference to the specified months. If there is no parameterthe current month of the year is used.

WEEKS(value) This function returns the time difference to the specified weeks. If there is no parameterthe current week of the year is used.

DAYS(value) This function returns the time difference to the specified days. If there is no parameterthe current day of the month is used.

HOURS(value) This function returns the time difference to the specified hours. If there is no parameterthe current hour of the day is used.

MINUTES(value) This function returns the time difference to the specified minutes. If there is no parameterthe current minute in the hour is used.

SECONDS(value) This function returns the time difference to the specified seconds. If there is no parameterthe current second in the minute is used.

Boolean Literals

The interpreter parses a boolean value from string literal.

Boolean Literal Description

true or 1 as true (case insenstive)

false or 0 as false (case insenstive)

The interpreter uses just the first character to get the boolean value. That means f is a legal value for false.

trueTruef0

ASAM ODS Enumerations

The ASAM ODS data model defines enumerations. If you use a value in the context of these enumerations youcan use either the numeric value or the name of the enumeration item comming from the ODS model. The itemname is case sensitive! If you want to assign a data type for long, the following values are equivalent:

DT_LONG6

| HQL | 13

Identifiers

Identifiers are strings to identify objects defined by the ASAM ODS data model, such as elements and attributes.If these objects are part of the application model we can use a simple string literal.

UnitVehicleNameDate

Even if the identifier names contain white space characters or other foreign characters, we can use the stringliteral defintion. (But this is not really advisable for the model design.)

"Creation Date"'Evaluation Bundle'

Sometimes we need to address all attributes of an element. In that case the asterix character (*) is allowed. Theorder of the attributes is determined by the server implementation.

An attribute can be identified by a combination of an identifier and an attribute identifier separated by a dotcharacter (.). This is necessary if the interpreter is not able to uniquely identify the element just by the attributename. We will see some cases below.

Unit.NameTestEquipment.IdTest.*

Sometimes we want to use the base model definitions, because we have to solve a problem by generic approach.For this case the interpreter allows a prefix for the base model identifiers. Base model identifiers are caseinsensitive.

Prefix Description

be. or BE. for base element name prefix

ba. or BA. for base attribute name prefix

br. or BR. for base relation name prefix

be.aounitba.id

The interpreter will optimize your request, that means normally it is not necessary to use that prefix.

Example

If you are using aounit instead of be.aounit, the interpreter tries to get the application element aounit.If this element is not available it tries to get the base element named aounit. If there is no application elementnamed aounit, it is not necessary to use the be. prefix. Same rule is followed by the attribute search method.

This dot rule drags a disadvantage: The identifier name cannot contain dots! If the identifier name in the databasecontains dots, it is necessary to enclose it by quotes.

A combination of this definitions is also allowed.

be.aounit.ba.id

In that case you are looking for the base attribute id of the base element aounit.

This rule works fine, if there is no similar element and attribute name definition available in the model. Thesyntax parser and the content interpreter have problems for some reasons with attribute naming. Imagine to havethe following list of attributes for the Application Element BadElement

14 | HQL |

Application Attribute Name Base Attribute Name

ID name

Name id

Question is: What are the meanings of the following identifiers?

BadElement.ID;BadElement.id;

But this is bad model design and might not be permitted by ASAM ODS definitions. As we can see there aremultiple solutions, but we want to define it as restriction that this kind of naming cannot be used in conjunctionwith statements. May be that there is a result from , but it is not defined what kind of decision wasdone internally.� ��

Figure 11: ID� �� Figure 12: Identifier� �� Figure 13: Element Identifier

attr_ident

identifier

ba.

elem_ident . identifier

*

column_ident

identifier

*

Figure 14: Attribute Identifier

For a column specification in a value matrix command there is no option for an element specification. Thereforewe have a specific syntax for column requests.

| HQL | 15

attr_ident

identifier

ba.

elem_ident . identifier

*

column_ident

identifier

*

Figure 15: Column Identifier

ASAM ODS defines also attributes with units. If you request an attribute, it is possible to get the value for aspecific unit, even if it was written in another unit. But the physical dimension must be same.

An attribute can be assigned to a value of 3.218 [km]. If you retrieve it by requesting the value using Miles,you will get the value 2 [miles].

For that reason defines the unit identifier, that is nothing else than a normal attribute identifier followed bya unit in brackets ([]).� �� Figure 16: Unit Identifier

TrackLength [miles]

or

Track.Distance [km]

defines also a column identifier with unit specification, that is nothing else than a normal column identifierfollowed by a unit in brackets ([]).

unit_ident

[ identifier

attr_ident

]

unit_column_ident

[ identifier

column_ident

]

Figure 17: Unit Column Identifier

Distance[km]

Because we are using ASAM ODS language, we can identify relations by name too. The specification is like anormal attribute.� ��

Figure 18: Relation Identifier

br.parent_testtoTest

In a list of requested attributes each of it can be aggregated.

AggregateFunction

Description

avg Gets the average value of the selected attributes.

16 | HQL |

AggregateFunction

Description

count Gets the total number of seletced attribute values.

dcount Gets the distinct total number of seletced attribute values.

distinct Gets the distinct list of attribute values.

max Gets the maximum value of the selected attribute values.

min Gets the minimum value of the selected attribute values.� �� Figure 19: Aggregation

count(id)

From that definition we can define an aggregated identifier.� �� Figure 20: Aggregated Identifier

In a list of requested attributes we can alias attributes like we can do it in SQL.� �� Figure 21: Alias Identifier

City as StadtAddress as Adresse

A sequence of identifiers can be specified by a comma searated list of identifiers. The example here is a list ofelement identifiers.

| HQL | 17� �� Figure 22: Element Sequence

aotest, Project, be.aounit, aomeasurement

Values

A value can be defined by one of the following fragments:

• a single atomic value• an array of atomic values enclosed by brackets ([]) and separated by comma• an encapsulated command enclosed by parentheses ({})• A value that is returned by a function. The idea behind the function is to have a possibility to extend the

dialect of this language by a plug-in that provides the missing functions a method or object.

The routine that uses a value has to decide how to react on multi dimensional values.� �� Figure 23: Atomic Value� �� Figure 24: Function� �� Figure 25: Value

18 | HQL | � �� Figure 26: Value Sequence� �� Figure 27: Value Definition

External References

External references point to files that are just referenced by the ASAM ODS data storage. There are somequestions that have to be answered before we can write meaningful values to the reference attribute.

• Where is the real location of the files?

This depends on server configuration and is specific for each installation.• What kind of protocol can be used to transport the files to the destination location?

This depends on the actual system environment and is specific for each installation.• Even if we are able to send the files and we are able to get the server side location of the files what is the file

location value to be used in the ASAM ODS reference?

This also depends on the system settings of the ASAM ODS server and is specific for each installation.• Normally the attribute is able to carry multiple references, that means an array of references

(DS_EXTERNALREFERENCE). Check what data type is assigned to the attribute you need to write.

If all questions are answered, we can use language to write the information to an attribute of base typeexternal_reference. The external reference value contains three string values:

• the file location string• the file MIME type• the file description string

For that reason language defines a specific syntax for external references.

location[mimetype, description]

The location string is mandatory, mimetype and description is optional.

Examples

Be aware in case of using these examples in a statement, you must double all backslashes (\).

c:\data\72387z519.txt[text, a simple configuration file]

Because the description is optional you can use the following command without this description field.

c:\data\72387z519.txt[text]

Same without MIME type.

c:\data\72387z519.txt[, a simple configuration file]

| HQL | 19

Same with URL only.

c:\data\72387z519.txt

Options

It is common for all commands that options can be passed to the command. Options are specified inbrackets ([]). An option is defined by a keyword and a value. An option sequence is a comma separated list ofkeyword/value pairs.

A keyword for the option is given by the ID definition and are evaluated case sensitive. Now we have everythingrequired for an option and an option sequence.� ��

Figure 28: Option� �� Figure 29: Option Sequence

Example

[MAX_ROWS=200, TRANSACTION=4711, user="my name"]

Columns of Result

Most of the commands need at least a list of attributes to be selected. If the attribute specifications can beassigned to ASAM ODS attribute objects, no more information is needed to execute the command.� ��

Figure 30: Annotation Sequence

aounit.name, aomeasurement.*

If it is not possible to assign the object from attribute sequence, we need to specify the elements in from clause.

hql name from aounit

If we want to specify columns for value matrix in a hqlvm command, we need to use a column sequence.

20 | HQL |

alias_ident

as identifier

aggr_ident

column_seq

,

column_ident

anu_seq

,

alias_ident

*

Figure 31: Column Sequence

Speed, Temperature[K]

In contrast to the attributes, in this case no applciation element specifications are required.

Operators

All operators in syntax definition are handled case insenstive and can be used in lower and upper case letters aswell.

Comparators

The syntax allows all comparators defined by the ASAM ODS specification. In parallel all thesecomparators can be expressed alternatively and used by the interpreter case insensitive.

Operator Type Description

eq or == or = equals

neq or != or <> not equals

le or <= lower than or equals

ge or => greater than or equals

lt or < lower than

gt or > greater than

ci_eq case insensitive equals (for string values only)

ci_neq case insensitive not equals (for string values only)

ci_le case insensitive lower than or equals (for string values only)

ci_ge case insensitive greater than or equals (for string values only)

ci_lt case insensitive lower than (for string values only)

ci_gt case insensitive greater than (for string values only)

between Needs an array of two values and compares the range of these values (attr >=value[0] and attr <= value[1]). Example: hql * from aounitwhere factor between [0,10];

| HQL | 21� �� Figure 32: Comparators

Locical Operators

The syntax allows all logical operators defined by the ASAM ODS specification. In parallel all thesecomparators can be expressed alternatively.

• and or && can be used for and• or or || can be used for or• not can be used in conjunction with both operators above� ��

Figure 33: Logical Operators

Comparator Methods

ASAM ODS defines a set of methodical operators for comparison. The syntax interpreter uses the methodnames case insensitive.

• like: Used in conjunction with wildcards. As defined by ASAM ODS *(multi character) and ?(singlecharacter) can be used as wildcard.

• not_like or notlike: Used if the you want to get the inverse result of the like method.• ci_like: Used for case insensitive mode.• ci_not_like or ci_notlike: Used for inverse case insentive mode.

22 | HQL | � �� Figure 34: Comparator Methods

Condition

A condition is used to shrink a list of objects. It is used in the where clause of a command. This clause is similarto that of a SQL statement. In the where clause we can combine different conditions by an operator.� �� Figure 35: Condition Sequence

The condition is separated into four different kinds of conditions.� �� Figure 36: Condition� ��

Figure 37: Void Condition

| HQL | 23� �� Figure 38: Scalar Condition� �� Figure 39: Array Condition� ��

Figure 40: Opcode Condition

A general problem for beginners is the handling of invalid values. An invalid value is defined by ASAM ODS asan attribute that has a NULL entry in the database instead of a legal value.

As an example let's have a look at the a boolean attribute called checked as part of the element calledMeasurement. Assume that we have the following instance information in the database:

Id Name checked

1 Measurement-1 true

2 Measurement-2 false

3 Measurement-3 NULL

If you have the following condition

Measurement.check != true

you will get the Measurement-2 only. If you want to include the invalid attribute also, you have explicitly toask for it.

Measurement.check != true or Measurement.check IS_NULL()

24 | HQL |

That means invalid attributes will not be returned, if they are not explicitly requested!

Join

If your command contains attributes from multiple elements, joining is necessary. The server is able to find theright attributes, if the elements are connected by father child relations. In case of other relation types or multiplerelations between the elements, the command must specify the joining sequence.� ��

Figure 41: Join Sequence

Each join must specify the elements and the type of joining (inner or outer (words are defined by SQL in case ofjoin)). If there are multiple relations between elements you can use the keyword via to assign a specific relationby name.� �� Figure 42: Join Defintion

Ordering

Ordering results is nothing else but a sequence specification of attribute identifiers. An optional plus character(+ ascending) or minus character (- descending) sign can be used to specify the kind of ordering. The default isascending order.� ��

Figure 43: Order Sequence

Grouping

To group result is nothing else than a sequence specification of attribute identifiers.� �� Figure 44: Group Sequence

References

For some commands it is necessary to define references. The syntax for that clause is shown here.

| HQL | 25� �� Figure 45: Reference Sequence

A reference itself can be used to specify how instance elements are linked together.� �� Figure 46: Reference

Flags

In ASAM ODS a value can be bound to an optional flag that signals the validity of the value. The interpreter usesthe following rules for evaluation:

• v, V or 1 is used to assign a valid value. This is the default, even if there is no flag value specified.• i, I or 0 is used to assign an invalid value. Even if the value is invalid afterwards, a value must be specified

to fulfill the syntax!• A four bit combination that can be handled as ASAM ODS flag definition. The first (first left) value is

interpreted as the VALID flag, the second as NOT_MODIFIED, the third as VISIBLE and the fourth asDEFINED. These are the definitions done by the ASAM ODS API specification.� ��

Figure 47: Flags

Relation Range

To manipulate relations it is necessary to specifiy the relation range. For that reason a relation identifier can bedescribed by an identifier and the cardinality given in pointy brackets.� ��

Figure 48: Relation Range

26 | HQL |

Keywords

The following character sequences are reserved for use as keywords and cannot be used as identifiers. Thekeywords are found by a case insensitive detector. If you need a keyword as identifier you have to quote it.

ABORT AND APPEND AS AVG

BA. BASEDON BETWEEN BE. BR.

CI_EQ CI_GT CI_GTE CI_INSET CI_LIKE

CI_LT CI_LTE CI_NEQ CI_NOT_INSET CI_NOT_LIKE

CI_NOTINSET CI_NOTLIKE COMMIT COUNT DCOUNT

DISTINCT EQ FATHER_CHILD FROM GROUPBY

GT GTE HQL HQLATTR HQLCREATEATTR

HQLCREATEELEM HQLCREATEREL HQLDELETE HQLELEM HQLENUM

HQLINFO HQLINSERT HQLREF HQLREL HQLTRANSACTION

HQLUPDATE INFO INSERT INSET INTO

IS_NOT_NULL IS_NOTNULL IS_NULL JOIN LIKE

LINK LT LTE MAX MIN

NEQ NOT NOT_INSET NOT_LIKE NOTINSET

NOTLIKE OBLIGATORY ON OR ORDERBY

REFFROM REFTO REMOVE START TO

TOOUTER UNIQUE UPDATE VALUES VIA

WHERE

HQL Commands

This topic describes all implemented commands in detail. These commands can be sorted into four categories.

• Instance Element Commands• Model Queries• Model Changes• System Commands

| HQL | 27

hql commands

hqlcreateattr

hqlcreateelem

hqlcreaterel

Model Changes hqltransaction

hqlinfo

hqlcontext

System Commands

hql

hqldelete

hqlref

hqlinsert

hqlupdate

Instance Commands

hqlvm

hqlattr

hqlelem

hqlrel

Model Queries

hqlenum

hqlpath

Figure 49: Commands

HQL Query

can help to reduce the complexity of the frequently used ASAM ODS Extended Queries. The selection ofinstances is one major use case for this syntax definition. Most of the definitions used for this purpose can bereused for other commands. Therefore it is recommended to read this section before you dive into the descriptionof other commands.

The commands work like SQL commands but the syntax of the ASAM ODS data model is applied. Theimplementation itself runs against the ASAM ODS server, not against the ASAM ODS data storage. This ensuresthe right usage of the security features of the ASAM ODS defintion but it shrinks the possibilities by the means ofASAM ODS.

Here is an overview of the command:� �� Figure 50: Command

28 | HQL |

Options

The command accepts the following option keywords.MAX_ROWS (int, optional)

Use this keyword to specify the maximum number of rows to be selected.

TRANSACTION (string, optional)

Use this keyword to specify the transaction identifier (returned by the hqltransactioncommand) for this operation.

IDENTIFIER (int|string, optional)

Use this keyword to specify the column that should be used as identifier column. If the valueis an integer, it is treated as the index number inside the array of specified columns. It is nottreated as the index number inside the array of columns in the result table. If that option is notspecified, this column is derived from columns that is derived from base attribute id. If theoption value is a string, it is treated as an attribute identifier. The column in result assigned tothat attribute is used as identifier column.

Examples

hql aouser.name where name like ('m*') orderby -name;

Select the name attribute from base element aouser with name pattern m* descending order by name.

hql name, id from aounit where id not_inset([39, 815, 4711]);

Select name and id from base element aounit not assigned to the ids 39, 815 or 4711.

hql name from aounit where id inset( {hql id from aoquantity where name like('A*')});

The above example is a little bit strange, because the encapsulated query is not meaningful. Therefore use it as anexample only. It selects name from base element aounit where the ids are in the set of ids defined by the subquery, that returns the ids from base element aoquantity where the names start with A.

hql * from Document where RealDocuments like("url[*,*]");

Select all instances from element Document where the location attribute of the application attributeRealDocuments is url. The application attribute RealDocuments is of type DS_EXTERNALREFERENCE.

hql Vehicle.name, Track.name where Result.id=49 join ResultGroup toouter Track, Result to ResultGroup, ResultGroup to Configuration, Configuration to Vehicle;

This is a select statement with a complex join sequence, that retrieves name of the elements Vehicle and Trackbelong to the Result with the id value fo 49. Vehicle (AoTest), Configuration (AoSubTest),ResultGroup (AoSubTest) and Result (AoMeasurement) is the main ASAM ODS father-childtree. Track(AoAny) is optional bound to the ResultGroup (AoSubTest) by an informational relation.

| HQL | 29

VehicleAoTest

ConfigurationAoSubTest

1:n

ResultGroupAoSubTest

1:n

TrackAoAny

n:1

ResultAoMeasurement

1:n

Figure 51: Vehicle Tree

hql name from aouser where aousergroup.id=1 join aouser to aousergroup;

Selects all user names where the instances are bound to the user group with id 1. Important to know is that therelation between user and user group is n:m relation. Therefore we need the join.

hql aounit.name, count(AoQuantity.id) from aounit, aoQuantity where name like (*) join aounit toouter aoquantity orderby aounit.name groupby aounit.name;

Selects all unit names and the count of quantities that are bound to the unit.

hql aouser.name, aousergroup.name from aouser where aousergroup.id>0 join aouser to aousergroup;

Selects all user names and group names that are bound together.

hql distinct(aouser.id) from aouser where aousergroup.id>0 join aouser to aousergroup;

Selects all user records that are bound to at least one group.

hql id, name from aouser where id not_inset( {hql distinct(aouser.id) from aouser where aousergroup.id>0 join aouser to aousergroup});

Select all user records that are not bound to any group.

The next query that can be applied to the major meta data stored about the mass data of one measurement.Perhaps it can be used to write the header information of the local columns bound to a measurement for a CSVfile. It is using generic types only and can be used for every data model. Every other model dependent attributecan be added, if necessary.

hql aosubmatix.id, aosubmatrix.name, aosubmatrix.number_of_rows, aomeasurementquantity.name, aomeasurementquantity.datatype, aolocalcolumn.independent, aounit.name where aomeasurement.id=2 join aomeasurementquantity toouter aounit, aomeasurementquantity to aolocalcolumn, aolocalcolumn to aosubmatrix, aosubmatrix to aomeasurement orderby aosubmatrix.number_of_rows, aomeasurementquantity.name;

30 | HQL |

How to ask for attributes having invalid values? Invalid attributes are kept in database as null values. So we canuse the following command to ask for it:

hql id, name from aoMeasurement where version_date is_null();

Joining by base releation

Some ASAM ODS element can use the same base relation name for different releations. Of course the referencedelements must be derived from the same base element. But if the model is changed by the time, it will be difficultto find the bound elements. In openMDM model it is possible that the applciation creates new UnitUnderTestPartelements. In that case it is difficult to use the join, because you don't know the element name at developmenttime.

Example:

hql * from Test where id=19961 join Test to TestStep, TestStep to UnitUnderTest, UnitUnderTest to Wheel

At development time you don't know the element Wheel. Therefore allows base element names in joinclause. Normally tries to get the first definition assigned to the given base model reference. In that case ittries to use every relation that is defined.

hql * from Test where id=19961 join Test to TestStep, TestStep to UnitUnderTest, UnitUnderTest toouter AoUnitUnderTestPart

This query uses every relation between UnitUnderTest and UnitUnderTestPart. Take care to use thetoouter joining type, if the relations are optional.

Be aware of memory problems, because it is possible to create a huge temporary joining table in the underlyingdatabase system!

Mass Data Value Access

There is one restriction defined by ASAM ODS API for accessing values attached to the base elementAoLocalColumn.

The base attributes

• id

• values

• flags

• generation_parameters

cannot be selected in one API call together with other attributes from aolocalcolumn.

That means the following command is not possible and results in an error:

hql name, version, values from AoLocalColumn;

The ASAM ODS API is able to transfer exactly one data type for the based attribute values. The ASAM ODSAvalon takes the data type which is found first in the list of the local columns where the values are requestedfrom.

hql ba.id, ba.values from aolocalcolumn where id = 2366;hql id, values from aolocalcolumn where id = 2366;

Select the local column values where the local column id is 2366.

| HQL | 31

Retrieve Value Matrix

The hqlvm command can be used to retrieve value matrix from sub-matrix or measurement instances. This is thereason why the from clause just accepts sub-matrix or measurement application element specification.

The hqlvm command can retrieve only one sub_matrix. If the condition clause selects more than one instancethe command fails.

Multiple columns with the same name can be retrtieved, even if they have different unit specification.

Result Set Columns

The result of this operation are the column values of the value matrix of the given instance element. Each columnrepresents a column in value matrix and each row represents a measurement point.

hqlvm

option_seq

column_seq

from elem_seq

where cond_seq

join join_seq

hql

Figure 52: HQLVM

Options

The command accepts the following option keywords:MAX_ROWS (int, optional)

Use this keyword to specify the total number of rows to be retrieved. If this value is notspecified all values from the value matrix are returned. Regarding to the OFFSET option, iffewer values are avasilable, the command adjust the given value of that option.

OFFSET (int, optional)

This value specifies the row offset in value matrix. If this otpions is not available, it is assumedto 0.

TRANSACTION (int, optional)

Use this keyword to specify the transaction id for the operation.

Examples

hqlvm [MAX_ROWS=10] Timestamp, SunnyMinutes[h] from aosubmatrix where id=152932;

The result set contains 10 rows fomr offset 0 of the column Timestamp with default unit and the columnnamed SunnyMintes in unit hours. The value matrix is generated from the sub-matrix instance element withthe id 15293.

hqlvm [MAX_ROWS=10, OFFSET=3] * from aosubmatrix where id=4711;

Gets all columnns with default unit from the value matirx defined by the sub-matrix with id 4711.

hqlvm [offset=160, MAX_ROWS=10] SunnyMinutes[s], SunnyMinutes[h] from aosubmatrix where id=152581;

This command retrieves the column SunnyMinutes with unit s and unit h. The value matrix is generated fromthe sub-matrix instance element with the id 15293.

32 | HQL |

Query the Model Elements

The hqlelem command can be used to retrieve element information from the application model.

Result Set Columns

The result set knows just the columns derived from org.asam.ods.ApplElem.

Column Name Description

aid The application element id.

aename The application element name.

bename The base name of the application element.� �� Figure 53: HQLElem

Options


Use this keyword to specify the total number of rows to be selected.

TOPLEVEL (boolean, optional)

Use this keyword to retrieve root elements. The keyword ROOT can be used in parallel.

ROOT (boolean, optional)

Same meaning as keyword TOPLEVEL.

Examples

hqlelem *;

Retrieves aid, aename and bename for all application elements.

hqlelem aid, bename from *;

Retrieves aid, bename for all application elements.

hqlelem aid, bename from aounit;

Retrieves aid, bename for the application element assigned to the aounit base element.

hqlelem * from * where bename like ('*unit*');

| HQL | 33

Retrieve aid, aename and bename for elements assigned to a base element with sub-string unit in name.

hqlelem * from * where aid=10 or aid=20;

Retrieve aid, aename and bename for elements with aid equal 10 or 20.

hqlelem [root=true] *;

Retrieves aid, aename and bename for all root application elements.

Query the Model Attributes

The hqlattr command can be used to retrieve attribute information from application model.

Result Set Columns

The result set knows just the columns derived from org.asam.ods.ApplElem andorg.asam.ods.ApplAttr. Additionally in case of enumeration data type the name of the enumeration canbe queried. This information cannot be retrieved from the ApplElem or ApplAttr data structures.




bename The base name of the application element.

aaname The application attribute name.

baname The base name of the application attribute.

length The length of the attribute.

unitid The data storage id of the unit assigned to the attribute.

obligatory A boolean indicating that the attribute is obligatory.

unique A boolean indicating that the attribute is unique.

autogen A boolean indicating that the attribute is auto generated.

type The data type of the attribute.

enumeration_type If the type is DT_ENUM or DS_ENUM, this column is the name of theenumeration type.� ��

Figure 54: HQLAttr

34 | HQL |

Options



Examples

hqlattr *

Omit the from clause and use a * to retrieve all attributes defined in the model.

hqlattr * from aounit;

Select all attributes from base element aounit.

hqlattr [max_rows=2] aid, baname, aaname from * where unique=true && obligatory=true && length > 10 orderby bename;

Select two rows where the attributes unique and obligatory are true and where the length is greater than 10,order the result by the base element name.

hqlattr [max_rows=10] * from * where type = DS_EXTERNALREFERENCE;

Get the first 10 entries where the attribute type is DS_EXTERNALREFERENCE.

hqlattr * from aolocalcolumn where type=8;

Get all attributes from the local column that have data type 8 (DT_LONGLONG). That means enumeration valuecan be specified by numerical value as well as by string value.

Query the Model Relations

The hqlrel command can be used to retrieve relation information from application model.

Result Set Columns

The result set knows just the columns derived from org.asam.ods.ApplRel.


arname The application relation name.

invarname The inverse application relation name.

brname The application base relation name.

invbrname The inverse application base relation name.

elem1 The id of the first application element.

elem1name The name of the first application element.

elem2 The id of the second application element.

elem2name The name of the second application element.

type The type of the relation.

range The relation cardinality. It can be 0:1, 0:n, 1:n

rmin The relation minimum range.

rmax The relation maximum range. If the value is -1, the range can vary arbitrary.

invrange The relation inverse cardinality. It can be 0:1, 0:n, 1:n

| HQL | 35


invmin The relation minimum inverse relation range.

invmax The relation maximum inverse relation range. If the value is -1, the range can varyarbitrary.� ��

Figure 55: HQLRel

Options



Examples

hqlrel * from aounit;

Select all relations from base element aounit.

hqlrel [max_rows=2] * from * where type = INFO;

Select 2 relations where the relation type is INFO.

hqlrel [max_rows=2] * from * where type = FATHER_CHILD;

or

hqlrel [max_rows=2] * from * where type = 0;

Because type is an enumeration, it selects 2 relations where the relation type is FATHER_CHILD.

hqlrel [max_rows=2] * from * where type like ('F*');

Of course enumerations can be used as strings also. The result is the same as the previous example.

hqlrel * from aotest;

Retrieves of all relations belongs to the application element of base element AoTest.

hqlrel arname from aotest where elem2name = TestPlan;

36 | HQL |

Gets the relation name of all relations belonging to the application element of base element aotest going toTestPlan.

Retrieve Navigation Paths

The hqlpath command can be used to retrieve possible navigation paths between two application elements.

Result Set Columns

Each row of the result set represents a path from one direct element relation belongs to the found path. The fourthree columns are the structure level, the application element id, the base name and the name of the startingelement. The following, the fifth column, if the name of the relation to be followed to the related element. Theremaining columns describe the relation in detail, like it is done by the hqlrel command.

Each row defines one navigation level.

Developers Hint: The QueryResult Iterator that is returned by this query can have multiple entries! Later in thisdocument it is described how to retrieve multiple result sets using the iterator methods.


level The structure level of the element represented by the row.

aid The application element id of the starting element.

aename The application element name of the starting element.

bename The application element base name of the starting element.















invmax The relation maximum inverse relation range. If the value is -1, the range can varyarbitrary.

| HQL | 37

hqlpath

hqlpath anu_seq

to elem_identifier

from elem_identifier

Figure 56: HQLPath

Options

The command doesn't accept any options.

Examples

hqlpath * from aomeasurement;

Retrieves all possible paths from the aomeasurement element to the ASAM ODS top level layer elements.

hqlpath * from aomeasurement to aotest;

Retrieves all possible paths from the aomeasurement element to the element derived from aotest.

hqlpath aename, arname, elem2name from aomeasurement;

Out weather demo environment delivers the following:

--------------------------------| aename | arname | elem2name |--------------------------------| Station | Years | Year || Year | Months | Month || Month | | |--------------------------------3 rows selected.---------------------------------| aename | arname | elem2name |---------------------------------| Project | Station | Station || Station | Years | Year || Year | Months | Month || Month | | |---------------------------------4 rows selected.Query time: 4,79 msPrinter time: 7,00 msExecution time: 7,64 ms

For the first result set it means:

You can navigate from Station to Year unsing the named relation Years. In the next level you can navigatefrom year to Month unsing the named relation Month. The last line is the destination element Month, that isof type aomeasurement.

Retrieve Enumerations

The hqlenum command can be used to retrieve enumerations.

Result Set Columns

The result set knows just three columns.

38 | HQL |


type The enumeration type.

keyword The keyword that assigns the value.

value The value that belongs to the keyword.

hqlenum

option_seq

anu_seq

where cond_seq

orderby order_seq

hqlenum

Figure 57: HQLEnum

Options





Examples

hqlenum *;

Retrieves all enumerations.

hqlenum keyword, value where type = datatype_enum orderby value;

Retrieves the keywords and values belong to the enumeration datatype_enum and order it by value.

Retrieve System Information

The hqlinfo command can be used to retrieve the setting of the system process environmet, the JAVA VM andthe ASAM ODS session.

Result Set Columns

The result set knows just three columns.


type The type specifies from what area the properties was retrieved.

• JAVA for JAVA system property.• ODS for ASAM ODS session context property.• SYSTEM for OS process environment.



| HQL | 39� �� Figure 58: HQLInfo

Options





The command adds some ASAM ODS context variables that are listed and described here.

Keyword Description

AoSession.IOR This keyword assigns the IOR string belongs to the current session.

Model.Type The value belongs to that keyword is a combination of the values belongto the base attributes application_model_version and versionof the base element AoEnvironment separated by semicolon (';').Example:Powertrain;model.atfx 2013/08/30 09:30 AndreasHofmann

Examples

hqlinfo *;

Retrieves all columns from all properties.

hqlinfo value where keyword="AoSession.IOR";

Retrieves the IOR string of the actual session object.

hqlinfo value where keyword="Model.Type";

Retrieves the Model.Type string of the actual session object. This value identifies the ASAM ODS model.

hqlinfo * where type=ODS orderby keyword;

Gets all properties provided by ASAM ODS context and order the record by keyword.

Write ASAM ODS Context Variables

The hqlcontext command can be used to write variables as ASAM ODS context key/value pairs.

If there is no transaction specified, the implementation uses the top level session to start a transaction. In that casethe transaction is closed after the command executed.

Result Set Columns

The result set knows just two columns.

40 | HQL |




hqlcontext

option_seq anu_seq

values value_seq

hqlcontext

Figure 59: HQLContext

Options

The command accepts the following option keywords.TRANSACTION (int, optional)


Examples

hqlcontext values(myValue=andy);

Writes the value andy bound to the keyword myValue as a context variable to the current session.

hqlcontext values(myValue=DS_LONG([1,2,3]));

Writes the long array value containing the values 1,2,3 bound to the keyword myValue as a context variableto the current session.

Handling Transactions

The hqltransaction command can be used to control transactions.

Result Set Columns

The result set of the transaction start command should contain an identifier that can be used to commit or abortthe transaction.

START, ABORT or COMMIT

This column contains the identifier of the transaction. In case of START the value must bepassed to other commands to identify the transaction.� ��

Figure 60: HQLTransaction

There are not options, that can be passed to that command.

| HQL | 41

Examples

hqltransaction start;

Assume that the first cell in result set is 4711. The value depends on the runtime environment and is just forreuse only and that is an identifier for the transaction. The following commands have to use this transactionidentifier in the option list to be executed inside that transaction.

hqlinsert [transaction=4711] values(name=Andy) refto aousergroup on name=MDMSysAdmin into aouser;hql [transaction=4711] name from aouser;

... any other command. To finalize or abort the changes use

hqltransaction commit 4711;

or

hqltransaction abort 4711;

Insert Instances

The hqlinsert command can be used to insert new instances into the ASAM ODS data storage. The result setcontains the inserted record, that can be shrunken by a column specification. The datatypes of the given valuesare given by the datatypes of the assigned attributes. The interpreter converters the specified values to requireddatatypes. The datatype can be specified optionally.


Result Set Columns

The result of this operation can be specified by the attribute list. The base attribute id is always a column in resultset, even it is not specified, because it is required for operation itself.� ��

Figure 61: HQLInsert

Options


Use this keyword to specify the total number of rows to be selected after operation.



IDENTIFIER (int, optional)

Use this keyword to specify the column that should be used as identifier. If the value isan integer, it is treated as the index number inside the array of specified columns. It is nottreated as the index number inside the array of columns in the result table. If that option is notspecified, this column is derived from columns that is derived from base attribute id. If that

42 | HQL |

value is a string, it is treated as an attribute identifier. The column in result assigned to thatattribute is used as identifier column.

Examples

hqlinsert values (name=kg, factor=1, offset=0) into aounit;

Creates a new unit called kg. The result contains all attributes. The relation to the element of typePhysicalDimension is optional in ASAM ODS base model.

hqlinsert id values (name=kg, factor=1, offset=0) into aounit;

Creates a new unit called kg. The result contains just the id.

hqlinsert [transaction=1] values(name=Andy) refto aousergroup on name=MDMSysAdmin into aouser;

Creates a new instance of AoUser and set the relation to an instance of AoUserGroup named MDMSysAdmin.

hqlinsert values(name=abc, DefDataType=DT_LONG, ValidFlag=1) into aoquantity;

Creates a new quantity, where DefDataType and ValidFlag are enumeration attributes. As you can see, it ispossible to use string as well as integer representation of the enumeration.

hqlinsert values(name=myPoint, XPosition[km]=3) into MeaPoint;

Insert an instance with an attribute (xPosition) value with different unit than default unit.

hqlinsert values(name=abc, value=DS_LONG([1,2,3,4])) into MyCatalog;

Creates a new instance of type MyCatalog. The value attribute is assigned to a long array with values1,2,3,4.

hqlinsert values ( Name='Analysis creation tool') refto AnalysisTool via toAnalysisTool on id inset ([1, 2]) into AnalysisCat;

Creates a new instance of AnalysisCat with name 'Analysis creation tool' that references theAnalysisTool with id 1 and 2 using the relation toAnalysisTool.

Writing password

ASAM ODS defines a mandatory base attribute password in the base element aouser. The ASAM ODS APIdoesn't allow to read any information about this attribute. Therefore it is not possible to know the name of theattribute in application model. For that reason it is not possible to write that attribute directly using hqlinsertor hqlupdate like this:

hqlinsert value(name="Anton" password="äö456") into aouser;

Update Instances

The hqlupdate command can be used to update existing instances of the ASAM ODS data storage. The resultset contains the updated record, that can be shrunken by a column specification. The datatypes of the given valuesare given by the datatypes of the assigned attributes. The interpreter converters the specified values to requireddatatypes. The datatype can be specified optionally.

Relations are always updated (SelType.Update). Use hqlref to perform a specific reference operation.


| HQL | 43

Result Set Columns

The result of this operation can be specified by the attribute list. The base attribute id is always a column in resultset, even it is not specified, because it is required for operation itself.� ��

Figure 62: HQLUpdate

Options


Use this keyword to specify the total number of rows to be updated.

IDENTIFIER (int, optional)

Use this keyword to specify the column that should be used as identifier. If the value isan integer, it is treated as the index number inside the array of specified columns. It is nottreated as the index number inside the array of columns in the result table. If that option is notspecified, this column is derived from columns that is derived from base attribute id. If thatvalue is a string, it is treated as an attribute identifier. The column in result assigned to thatattribute is used as identifier column.



Examples

hqlupdate values(name=xyz) into aoquantity where name=abc;

Update the quantity name abc to have the value xyz.

hqlupdate values(name=andy) refto aousergroup on name=MDMPlanner into aouser where name=Andy;

Update the user name and role, the relation to the user group.

hqlupdate values(values=DS_LONG([1,2,3,4,5])) into aolocalcolumn where id=275161;

Update the mass-date for a local column.

hqlupdate values(version_date='20090101-hours(30)') into TestPlan where id=35;

Use date function to specify the date.

hqlupdate values(description="junk")

44 | HQL |

into TestSpecification where id=3 or id=7;

Update command can be used to update multiple instances also.

hqlupdate values(XPosition[km]=3) into MeaPoint where id=168;

Update attribute value with different unit than default unit.

How to set an attribute to an invalid value? Depending on the derived base attribute type, some attributes cannot be set to an invalid value (e.g. id and name). ASAM ODS uses the flags to indicate the validation state of anattribute. Beside the valid/invalid state ASAM ODS knows three other states:

• not modified• visible• defined

These additional states are not of interest for the attributes. An invalid attribute is kept as null value in database.So we have just the option for the attribute to set the state value to be valid or invalid. Here are some rules:

• If you use and update or insert command to set the attribute, the status of the value is set to be valid.• All omitted attributes in insert statement are set to be invalid automatically.• If we use the update command to set a specific attribute, we can set the <i> postfix to make an attribute

invalid. Unfortunately a value specification must be available, that is not of interest afterwards.

hqlupdate values(description=""<i>) into aoMeasurement where id=1;

Setting References

The hqlref command can be used to change the references between instance elements.

If there is no transaction specified, the implementation uses the top level session to start a transaction. In this casethe transaction is closed after the command is executed.

Result Set Columns

The result of this operation is a list of ids included by that operation.� �� Figure 63: HQLUpdate

Options


Use this keyword to specify the total number of rows.



Examples

hqlref APPEND reffrom aouser on name=Andy refto aousergroup on id=10;

| HQL | 45

Creates a reference between the existing instance elements of AoUser and AoUserGroup. The user is namedAndy and the aousergroup has the id 10.

hqlref REMOVE reffrom aouser on name=Andy refto aousergroup;

Removes all relations from aouser instance element named ''Andy'' to aousergroup instances.

hqlref APPEND reffrom TestPlan on id=6 refto User via toCreatedByUser on id=2, User via toOwner on id=4;

This example fills two relations between the same elements. Of course the relations are used for different instanceelements.

Delete Instances

The hqldelete command can be used to delete a record from data storage. Constraints of the data storage arenot considered, it must be known by the calling layer. This operation deletes father child relation recursively.

If there is no transaction specified, the implementation uses the top level session to start a transaction. In this casethe transaction is closed after the command is executed.

Result Set Columns

The result of this operation can be specified by the attribute list. The base attribute id is always a column in theresult set, even it is not specified, because it is required for operation itself.� ��

Figure 64: HQLDelete

Options


Use this keyword to specify the total number of rows to be deleted.



Examples

hqldelete id, name from aounit where name = kg;

The result set contains the deleted record with columns id and name. The transaction of the operation is handledby the command itself.

hqldelete name from aounit where name = kg;

46 | HQL |

The id column is automatically added and the result set contains the deleted record with columns id and name.The transaction of the operation is handled by the command itself.

hqldelete [transaction=4711] id, name from aounit where name = kg;

The transaction 4711 is used for that operation.

hqldelete [transaction=4711] id from aotest where id=42;

Delete the instance of the base element aotest with the id 42 recursively. All related measurements, localcolumns and measurement quantities are included.

Create Attribute

The hqlcreateattr command can be used to create application element attributes.

Result Set Columns

The result is similar to the result of the hqlattr command that describes the newly created element.




bename The base name of the application element.

aaname The application attribute name.

baname The base name of the application attribute.

type The data type of the attribute.

obligatory A boolean indicating that the attribute is obligatory.

unique A boolean indicating that the attribute is unique.

length The length of the attribute.

unitid The data storage id of the unit assigned to the attribute.� �� Figure 65: HQLCreateAttr

Options

The command accepts the following option keywords.

| HQL | 47

TRANSACTION (int, must)

Use this keyword to specify the id of the transaction that should be used for that operation.

Examples

hqlcreateattr [transaction=1] dt_date(Created)<17> obligatory basedon version_date into Parameter;

This command adds the attribute Created with data type DT_DATE and length 17 to the application elementParameter. The attribute is derived from the base attribute version_date and should be obligatory.

hqlcreateattr [transaction=1] dt_string(Description)<1024> obligatory basedon description into Parameter;

This command adds the attribute Description with data type DT_STRING and length 1024 to theapplication element Parameter. The specified data type is of interest, because the data type of the baseattribute has data type DT_STRING. The attribute is derived from the base attribute description and shouldbe obligatory.

hqlcreateattr [transaction=1] dt_string(UserData)<1024> into Parameter;

This command adds the attribute UserData with data type DT_STRING and length 1024 to the applicationelement Parameter. The attribute isn't derived from any base attribute.

Create Element

The hqlcreateelem command can be used to create application elements.

Result Set Columns

The result is similar to the result of the hqlelem command that describes the newly created element.




bename The base name of the application element.� �� Figure 66: HQLCreateElem

Options

The command accepts the following option keywords.TRANSACTION (int, must)


Examples

hqlcreateelem [transaction=1] MyNewElement basedon AoParameter;

48 | HQL |

This command creates a new element named MyNewElement that is derived from the base elementAoParameter.

Create Relation

The hqlcreaterel command can be used to create a new relation between exiting application elements. If abase relation is specified the relation ranges can be omitted.

Result Set Columns

The result is similar to the result of the hqlrel command and describes the newly created element.
















invmax The relation maximum inverse relation range. If the value is -1, the range can varyarbitrary.

hqlcreaterel

hqlcreaterel

basedon identifier

option_seq

to elem_identifier

relrange_ident

info

father_child

( )

from elem_identifier

relrange_ident

Figure 67: HQLCreateRel

| HQL | 49

Options

The command accepts the following option keywords.TRANSACTION (int, must)


Examples

hqlcreaterel [transaction=1] info(toUser <1:n>) toParameter <0:1> from Parameter to AoUnit;

This command creates a new INFO relation between the base element AoUnit and the application elementParameter. It is defined to have just one Unit for each Parameter. toUser is the name of the relation atParameter element and toParameter is the name of the inverse relation. The relation ranges are specifiedafter the relation names in <x:y> notation.

hqlcreaterel [transaction=1] toParameterSet basedon parameter_set toParameter from Parameter to ParameterSet;

This command creates a new relation between the elements ParameterSet, that is derived fromAoParameterSet, and Parameter that is derived from AoParameter. In this case the relationdefinition should be based on the base relation parameter_set that is defined between the base elementsAoParameterSet and AoParameter. The name of the relation on Parameter is toParameterSet andon ParameterSet it is toParameter. The relation range must not be specified, because it is defined by thebase relation.

Using HQL in JAVA OSGi Environment

This section describes how we can use the from JAVA code.

Example code will omit existence and exception checks to shorten the code snippets.

Query Service

To use the service we need to have the QueryFactory that must be registered at the OSGi serviceregistry.

BundleContext ctx = .....ServiceReference[] ref;ref = ctx.getServiceReference( com.pvmsys.infra.query.service.QueryFactroy.class.getName(), "(query.language=HQL)");QueryFactory factory = ctx.getService(ref[0]);...

Once we have that factory, we use the component either by sending complete command string or creatingobject trees.

Create a Statement by Command String

Sending a string is easy by using the factory directly.

String command = "HQL......";QueryStatement statement = factory.createStatement(command);

Create a Statement by API Calls

As described in preface we can save important CPU time, if we omit the parser process and build the statementdirectly. For that reason the QueryFactory provides a method to retrieve a statement build object.

HQLStatementBuilder builder;builder = factory.prepareStatement(HQLStatementBuilder.class);

50 | HQL |

The statement builder object can be used to create every available command by method call. Have a look tothe JavaDoc pages to get more detailed information. The following example shows how to create a statement thatis equivalent to the command

hql * from AoUnit where Id < 10 && (name like("A*") and PhysDimension.Id > 18);

AoUnit value is used as base element and PhysDimension as application element. The Id attribute of unitand physical dimension is used as application attribute name and the name as base attribute name.

Important to know is that the builder and statement method implementations always retrieve immutable objects.The same rule applies to java.lang.String or java.lang.Number objects in Java definition. Thebuilder can also be used to create all objects necessary to describe the statement like attributes and condition.

HQLStatementBuilder builder = ...HQLStatement statement;

// HQL * ...statement= builder.hql(builder.column("*"));

// ... from AoUnit ...statement= statement.from("AoUnit");

// ... name like(A*) ...HQLCondition condition;condition = builder.condition( builder.attribute(null, true, "name", true), HQLOperator.LIKE, "A*");

// ... and PhysDimension.id > 18 ...condition = condition.and( builder.attribute("PhysDimension", false, "Id", false), HQLOperator.GT, 18); // ... Id < 10 && (....) ....condition = builder.condition ( builder.attribute(null, false, "Id", false), HQLOperator.GT, 10).and(condition); // ... where ... statement = statement.where(condition);

For each call of builder.condition the newly created condition is logically encapsulated in braces.

Getting Result from Statement

If we created the statement object either by command string or by creating the object tree directly, we canexecute the command and can retrieve the results.

QueryStatement statement = ....QueryFactory factory = ....Query query = factory.createQuery(statement);QueryResult rs = query.execute();

The result is an object that describes a table containing the values. The table defines rows and columns withheaders. Have a look at the JavaDoc pages for more details.

Retrieving Identifier

Once you have got the QueryResult object, it is possible to loop through rows. If the row isn't able todetermine the cell used for the identifier, you will get a null.

Iterator<Row> rows = result.getRows();while (rows.hasNext()) { Row row = rows.next();

| HQL | 51

QueryIdentifier ei = row.getIdentifier(); .....}

It is also possible to ask the column if it is the column for an identifier.

Column<?>[] columns = result.getColumns();for (int i = 0; i < width.length; i++) { if (columns[i].isIdentifier()) { ... }}

Getting the Command String from Statement

From statement we can get the command string by calling the toString() of the statement object.

QueryStatement statement = ....String command = statement.toString();

Because we have some operator alternatives the string must not exactly the same as the input string.

May be we are using the following condition part:

Id > 100 && Id < 200

Once we created the statement we can use the toString() method of the statement to get a string presentation.The result might be:

Id GT 100 AND Id LT 500

Getting QueryStructureExt Object from Statement

It might be interesting to get the ASAM ODS QueryStructureExt object in case we want to change only apart of the statement by user actions. For that reason we defined the getNative method in Query interface.

Query query = ...QueryStructureExt qse;qse = query.getNative(QueryStructureExt.class);

Using HQL String in code

Here is an example how we can use the string in code directly. The example code reads all local columnvalues of all local columns and updates the base attributes minimum, maximum and average in the associatedmeasurement quantities.

EntityReference<QueryFactory> ref = EntityReference.request(FrameworkUtil .getBundle(HQLIntegration.class).getBundleContext(), QueryFactory.class, "(query.language=HQL)");try { QueryFactory factory = ref.getService();

boolean stopped = false; long gCount=0; long maxId=0; do { Query query = factory.createQuery("hql "+ "aolocalcolumn.id, aomeasurementquantity.id " + "where aolocalcolumn.id > "+maxId+" and " + "aolocalcolumn.independent = 0 "+ "orderby aolocalcolumn.id"); QueryResult result = query.execute(); Column<?>[] columns = result.getColumns();

52 | HQL |

if (columns != null && columns.length > 0 && columns[0].getRowCount() > 0) { long[] colIds = columns[0].getNative(long[].class); long[] meaIds = columns[1].getNative(long[].class); for (int i=0; i<colIds.length; i++) { query = factory.createQuery("hql id, values, flags " + "from aolocalcolumn where id = "+colIds[i]); result = query.execute(); columns = result.getColumns(); double max=-Double.MAX_VALUE, min=Double.MAX_VALUE, tot=0; int count=0; short[][] flags = columns[2].getNative(short[][].class); // There are only short or float mass data available. try { float[][] fValues = columns[1].getNative(float[][].class); for (int v=0; v<fValues[0].length; v++) { if (flags[0].length == 0 || flags[0][v] > 0) { min = Math.min(min, fValues[0][v]); max = Math.max(max, fValues[0][v]); tot += fValues[0][v]; count++; } } } catch (Throwable t) { short[][] sValues = columns[1].getNative(short[][].class); for (int v=0; v<sValues[0].length; v++) { if (flags[0].length == 0 || flags[0][v] > 0) { min = Math.min(min, sValues[0][v]); max = Math.max(max, sValues[0][v]); tot += sValues[0][v]; count++; } } } if (count > 0) { System.out.println (min+" "+max+" "+tot/count); query = factory.createQuery("hqlupdate " + "values (minimum="+min+", maximum="+max+", "+ "average="+tot/count+") " + "into aomeasurementquantity where id="+meaIds[i]); result = query.execute(); } gCount++; maxId = colIds[i]; System.out.println (gCount+" "+maxId); } } else { stopped = true; } } while (!stopped);} finally { ref.release();}

Using HQL in JAVA bound as Library

is designed to be used in none OSGi JAVA environments also. In that case it is bound just as a normallibrary. The library is normally delivered in the lib/hql folder of the distribution. Every dependencyneeded can be found in the lib sub-folder, that means all JAR files of that folder must be referenced by the classpath of the JVM runtime environment.

The main JAR file follows the pattern de.highqsoft.ods.query.hql_<version>-library.jar,that can be used to start a command line version also. How to start and configure the command line version isdescribed in the next section.

| HQL | 53

If you want to use as a library you must take care about the separation of the concern. doesn't care about the ASAM ODS login and the model caching. This should be another businesspart of your application. Therefore provides interfaces that must be fulfilled to retrievethe required objects. The interface is described in detail at the end of this topic and is namedde.highqsoft.ods.query.hql.service.ServiceProvider. For testing purposes you can use thede.highqsoft.ods.query.hql.cmd.ServiceProviderCMD, that has some limitations referred bythe class documentation in details.

// Creating a service provider.

AoSession aoSession = ...

// Change to your licnese server setting.Properties p = new Properties();p.put("LICENSESERVER", "5053@hqscrm");

// Create HQL by the command line service provider.SerivceProvider sp = new ServiceProviderCMD(aoSession, p);...

Assuming that there is a valid implementation of the ServiceProvider interface, we can give some exampleshow to create the Query or the Statement object using . Once you have these objects you can use as described in previous OSGi environment section.

// Creating a Query object from hql command string.

SerivceProvider sp = ...HQL hql = new HQL(sp);

String hqlCommand="hql * from aounit";Query query = hql.createQuery(hqlCommand);...

// Creating a query object form hql statement. SerivceProvider sp = ...HQL hql = new HQL(sp);HQLStringStatementBuilder statement = hql.prepareStatement(HQLStringStatementBuilder.class);...Query query = hql.createQuery(statement);...

As you can see the main effort is to implement the ServiceProvider interface. But, if you have the ASAMODS server connection, means the org.asam.ods.AoSession, you can use the default implementation for afirst evaluation.

Using the Command Line Version

The library can be used as command line tool also. This tool provides a console input for commandstring and a string output for the results. The main problem is to establish the connection to the ASAM ODSdata storage. For that reason arguments can be passed to the tool. There are some rules for the syntax of thearguments:

1. Initially the argument interpreter starts with an empty property table. All incoming values are written to thattable in the order they are specified. That means, if a property is specified more than once, the last value isstored in the table at the end.

2. If a parameter starts with a minus sign ('-'), it is treated as a property keyword.3. If a parameter starts with a minus sign ('-') and the previous parameter was also a keyword, then the value

of the previous keyword is set to 'true'.4. If the parameter is quoted, it is treated as a value.5. Property keywords are case insensitive.

54 | HQL |

6. If an argument doesn't start with a minus sign ('-') and if it is the first argument or the previous argument isa value, it is treated as a property file that will be read directly.

7. White space characters can be used, if the argument is quoted. It depends on the command shell, what kind ofquotes should be used.

Example

... startup.properties -NameServiceHost hermes -CreateCoSessionAllowed -ConsoleLog -Prefix '-hql' "-very special"

• If the NameServiceHost property is already defined in startup.properties with a value that is notlocalhost, the final property table entry for that keyword is the value localhost.

• The values of the property keys CreateCoSessionAllowed and ConsoleLog are true.• The value of the property key Prefix is -hql.• The value of the property key very special is true.

Here is the list of properties that are available:

Keyword Description Default

NAMESERVICE The CORBA locator of theCORBA Naming Service. Example:NameService=corbaloc::1.2@localhost:2809/NameService

none

NAMESERVICEHOST The host where the CORBA Naming Service is running.It can be a hostname or an IP address. This property isevaluated, if the property NameService is not specified.

localhost

NAMESERVICEPORT The port that must be used to connect to the CORBANaming Service. This property is evaluated, if the propertyNameService is not specified.

2809

SERVICENAME This property must be specified and defines the ASAM ODSservice name to be connected.

none

USER or Username The name of the ASAM ODS user to be connected. none

PASSWORD The password of the ASAM ODS user to be connected. Ifthis property is not provided, the command line shell will askfor it.

none

LICENCEFOLDER The folder where the license file can be found. It must bespecified for node locked licenses only.

none

LICENSESERVER This property can be used to specify the location of the RLM(Reprise License Manager). This property is optional if thereis just one license server running. It must be given in thefollowing format: <port>@<host>

5053@hqscrm

AUTHENTICATION.STRING.ONLYThis property is parsed for a boolean value. If the value istrue it signals that the ASAM ODS server to be connectedsupports an authentication string only for login. In othercases the provider will use the login method that uses anarray of org.asam.ods.NameValue. This feature isnew in ASAM ODS 5.3 to prevent misinterpretations in loginstring.

false

To start the console version just use the de.highqsoft.ods.query.hql_<version>-library.jar as parameter for the JRE -jar option.

| HQL | 55

Example

java -jar de.highqsoft.ods.query.hql_2.0.0.v20140711-library.jar <parameters>

To exit the command line interpreter use the command exit.

Some Hints

• Because the character encoding of the shell must not match the character encoding of the database, problemsarise when using none ASCII characters in command or in the display of the results.

• Command line controls, like recall, depend on the shell environment.• It depends on the shell environment how to use quoting in the command.

Easy to use startup scripts

provides startup scripts for MS Windows (hql.cmd) and Linux (hql.sh) that make it easy to start aspecific configuration. These scripts expect a name for a configuration as parameter.

hql <config-name>

It is expected that in the folder where the scripts are located a property files <config-name>.propertiesis placed named. By this method you can easily collect and use different configurations. A confiugrationexample.properties is provided that can be reused for other ASAM ODS environments.

Extended Aggregation Functions

With we can extend the available aggregation functions provided by ASAM ODS. This aggregation mustbe calculated on client side, but having it in syntax can simplify your code dramatically. This section liststhe available aggregation functions.

ASAMPATH

ASAM ODS defined the ASAM Path. It is a string value that can be used to identify an element. It is aconcatenation of application element names, instance element name and instance element version. Please havea look to the ASAM ODS documentation to get the definition. But this definition has some restrictions. If theinstance element version is not available or not used in a way to unify this identifier, the definition can not beused.

This aggregation is called asampath and expects a base attribute id as parameter.

Example

hql asampath(id) from aomeasurement where id < 800;

Frequently Asked Questions

How to write a NULL value?

Depending on the derived base attribute type, some attributes cannot be set to an invalid value (e.g. id andname). ASAM ODS doesn't know NULL values. Instead of this definition it uses the flags for an attribute value.A flag value of 0 signals an invalid value and is stored in database as NULL value. If an optional attribute has novalue at creation time, it will be written as invalid, that means NULL, value.

Here are some rules:

• If you use and update or insert commands to set the attributes, the status of the values is set to be valid.• All omitted attributes in insert statements are set to be invalid automatically.• If we use the update command to set a specific attribute, we can set the <i> postfix to make an attribute

invalid. Unfortunately a value must be set for syntax reasons only. It is not used in the further processing.

56 | HQL |

We can use the hqlupdate command to set an attribute value to an invalid value.

hqlupdate values(description=""<i>) into aoMeasurement where id=1;

This command is the same like this:

hqlupdate values(description=""<0000>) into aoMeasurement where id=1;

How to ask for invalid values?

Invalid attributes are kept in database as NULL values. So we can use the following command:

hql id, name from aoMeasurement where version_date is_null();

What is difference between identifier and reference?

A result can have identifier and/or reference columns, but what is the meaning and the diffenrence?

An identifier column is always a reference column too. It can be used to retrieve the ASAM ODS instanceelement, that belongs to the row of data. Normally it is the column belongs to the base attribute id. In the othercase it can be treated as reference value of the whole result set matrix that clamps the matrix.

If the result set represents an ASAM ODS ValueMatrix, we cannot find the base attribute id>. But we have atleast one independent column that is the reference column of the result set and clamps the matrix. But this columnis not an identifier column!

How IDENTIFIER option works?

There are two possibilities how the IDENTIFIER option works.

1. Index into array of specified columns.2. Identifier of an attribute that is assigned to one of the columns of the result set.

Here is an example for the column index, assuming that the element has 5 attributes.

hql [IDENTIFIER=2] aounit.*, id;

We have 6 columns in result set and the last one is the identifier, because the second column in the commandrequests the last column in the result set.

hql [IDENTIFIER=4] aounit.*, id;

The identifier is not assigned to any column, because we have just two (aounit.* and id) specified columns.That means 4 is out of range.

Here is an example for the attribute identifier, assuming that the aounit element has 5 attributes.

hql [IDENTIFIER=id] aounit.*;

The result set contains all attributes of aounit element, where the ID column is assigned to be the identifiercolumn.

Because the first column that is derived from base attribute id, the result of the following command is the sameas the previous one.

hql aounit.*;

How to retrieve multiple result sets?

There are some commands that can provide multiple result sets, but how can we retrieve more than one reuslt set.

The hqlpath command is an example for a command that can provide multiple result sets. One for eachpossible path.

hqlpath * from aomeasurement;

| HQL | 57

If you model enables multiple paths you have to use the result set iterator mehtods to get all of them.

HQLStatement sts = ...;Query query = hqlObject.createQuery(sts);QueryResult result = query.execute();do { Column<?>[] columns = result.getColumns(); // do what you want ....while (result.hasNext() && (result=result.next()) != null);

58 | HQL |