ods object oriented api - highqsoft.com · ods object oriented api interface implementation version...

ODS Object Oriented API

Interface Implementation

Version 1.33

HighQSoft GmbH Karst Schaap 2015/08/19

Contents

1 General information 1

1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 Pools and maps in the implementation . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.3 Performance of the implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.4 There is no return. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.5 Return is a single value or object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.6 Return is an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.7 Return is an iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.8 Handling of the values of the AoLocalcolumn. . . . . . . . . . . . . . . . . . . . . . 13

1.9 Usage of the value �ags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.10 Logging of the server behaviour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.11 Usage of e�ective rights in ODS API. . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.12 Transaction handling in ODS API. . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.13 Usage of the new base attributes of ODS 5.3.1 . . . . . . . . . . . . . . . . . . . . . 17

2 Explanation of the documentaion 19

2.1 Explanation of the method documentation . . . . . . . . . . . . . . . . . . . . . . . 19

3 Connect to an ASAM ODS server using the implementation of HighQSoft 21

3.1 Getting the AoFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.2 Connect to the ODS API using the implementaion of HighQSoft. . . . . . . . . . . 21

3.3 AoServiceFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3.4 AoService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4 Hints for using ASAM ODS 27

4.1 Avoid instance attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4.2 Avoid N:M relations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4.3 DT_LONGLONG as datatype of based attribute values of AoLocalColumn . . . . 27

4.4 DT_DATE as datatype of based attribute values of AoLocalColumn . . . . . . . . 28

ii CONTENTS

5 ASAM ODS Interface 29

5.1 AoFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

5.2 AoSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

5.3 ApplElemAccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

5.4 ApplicationAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

5.5 ApplicationElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

5.6 ApplicationRelation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

5.7 ApplicationStructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

5.8 BaseAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

5.9 BaseElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

5.10 BaseRelation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

5.11 BaseStructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

5.12 Blob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

5.13 Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

5.14 ElemResultSetExtSeqIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

5.15 EnumerationDe�nition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

5.16 InstanceElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

5.17 InstanceElementIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

5.18 Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

5.19 NameIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

5.20 NameValueIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

5.21 NameValueUnitIdIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

5.22 NameValueUnitIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

5.23 NameValueUnitSequenceIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

5.24 ODSFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

5.25 ODSReadTransfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

5.26 ODSWriteTransfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

5.27 Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

5.28 QueryEvaluator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470

5.29 SMatLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

5.30 SubMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

5.31 ValueMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

6 ASAM ODS Structures 525

6.1 De�nitions of the ACL structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525

6.2 De�nitions of the AIDName structure. . . . . . . . . . . . . . . . . . . . . . . . . . 525

6.3 De�nitions of the AIDNameUnitId structure. . . . . . . . . . . . . . . . . . . . . . 526

ODS OO API Interface Implementation

© 2015/08/19 Version 1.33

HighQSoft Karst Schaap

http://www.highqsoft.com

CONTENTS iii

6.4 De�nitions of the AIDNameValueSeqUnitId structure. . . . . . . . . . . . . . . . . 526

6.5 De�nitions of the AIDNameValueUnitId structure. . . . . . . . . . . . . . . . . . . 526

6.6 De�nitions of the ApplAttr structure. . . . . . . . . . . . . . . . . . . . . . . . . . 527

6.7 De�nitions of the ApplElem structure. . . . . . . . . . . . . . . . . . . . . . . . . . 528

6.8 De�nitions of the ApplicationRelationInstanceElementSeq structure. . . . . . . . . 529

6.9 De�nitions of the ApplicationStructureValue structure. . . . . . . . . . . . . . . . . 529

6.10 De�nitions of the ApplRel structure. . . . . . . . . . . . . . . . . . . . . . . . . . . 530

6.11 De�nitions of the AttrResultSet structure. . . . . . . . . . . . . . . . . . . . . . . . 531

6.12 De�nitions of the ElemId structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . 532

6.13 De�nitions of the ElemResultSet structure. . . . . . . . . . . . . . . . . . . . . . . 532

6.14 De�nitions of the ElemResultSetExt structure. . . . . . . . . . . . . . . . . . . . . 532

6.15 De�nitions of the EnumerationAttributeStructure structure. . . . . . . . . . . . . . 533

6.16 De�nitions of the EnumerationItemStructure structure. . . . . . . . . . . . . . . . 533

6.17 De�nitions of the EnumerationStructure structure. . . . . . . . . . . . . . . . . . . 534

6.18 De�nitions of the InitialRight structure. . . . . . . . . . . . . . . . . . . . . . . . . 534

6.19 De�nitions of the JoinDef structure. . . . . . . . . . . . . . . . . . . . . . . . . . . 535

6.20 De�nitions of the NameUnit structure. . . . . . . . . . . . . . . . . . . . . . . . . . 535

6.21 De�nitions of the NameValue structure. . . . . . . . . . . . . . . . . . . . . . . . . 536

6.22 De�nitions of the NameValueSeqUnit structure. . . . . . . . . . . . . . . . . . . . . 536

6.23 De�nitions of the NameValueSeqUnitId structure. . . . . . . . . . . . . . . . . . . . 537

6.24 De�nitions of the NameValueUnit structure. . . . . . . . . . . . . . . . . . . . . . . 537

6.25 De�nitions of the NameValueUnitId structure. . . . . . . . . . . . . . . . . . . . . . 538

6.26 De�nitions of the QueryStructure structure. . . . . . . . . . . . . . . . . . . . . . . 538

6.27 De�nitions of the QueryStructureExt structure. . . . . . . . . . . . . . . . . . . . . 539

6.28 De�nitions of the RelationRange structure. . . . . . . . . . . . . . . . . . . . . . . 540

6.29 De�nitions of the ResultSetExt structure. . . . . . . . . . . . . . . . . . . . . . . . 541

6.30 De�nitions of the SelAIDNameUnitId structure. . . . . . . . . . . . . . . . . . . . . 541

6.31 De�nitions of the SelOrder structure. . . . . . . . . . . . . . . . . . . . . . . . . . . 542

6.32 De�nitions of the SelQuery structure. . . . . . . . . . . . . . . . . . . . . . . . . . 542

6.33 De�nitions of the SelQueryItem structure. . . . . . . . . . . . . . . . . . . . . . . . 542

6.34 De�nitions of the SelValue structure. . . . . . . . . . . . . . . . . . . . . . . . . . . 543

6.35 De�nitions of the SelValueExt structure. . . . . . . . . . . . . . . . . . . . . . . . . 543

6.36 De�nitions of the T_COMPLEX structure. . . . . . . . . . . . . . . . . . . . . . . 544

6.37 De�nitions of the T_DCOMPLEX structure. . . . . . . . . . . . . . . . . . . . . . 544

6.38 De�nitions of the T_ExternalReference structure. . . . . . . . . . . . . . . . . . . 544

6.39 De�nitions of the T_LONGLONG structure. . . . . . . . . . . . . . . . . . . . . . 545


© 2015/08/19 Version 1.33



iv CONTENTS

6.40 De�nitions of the TS_Value structure. . . . . . . . . . . . . . . . . . . . . . . . . . 545

6.41 De�nitions of the TS_ValueSeq structure. . . . . . . . . . . . . . . . . . . . . . . . 546

7 ASAM ODS Unions 547

7.1 De�nitions of the SelItem union. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547

7.2 De�nitions of the TS_Union union. . . . . . . . . . . . . . . . . . . . . . . . . . . 547

7.3 De�nitions of the TS_UnionSeq union. . . . . . . . . . . . . . . . . . . . . . . . . . 550

8 ASAM ODS Enumerations 553

8.1 De�nitions of the AggrFunc enumeration. . . . . . . . . . . . . . . . . . . . . . . . 553

8.2 De�nitions of the AttrType enumeration. . . . . . . . . . . . . . . . . . . . . . . . 554

8.3 De�nitions of the BuildUpFunction enumeration. . . . . . . . . . . . . . . . . . . . 554

8.4 De�nitions of the DataType enumeration. . . . . . . . . . . . . . . . . . . . . . . . 555

8.5 De�nitions of the ErrorCode enumeration. . . . . . . . . . . . . . . . . . . . . . . . 558

8.6 De�nitions of the JoinType enumeration. . . . . . . . . . . . . . . . . . . . . . . . 564

8.7 De�nitions of the QueryStatus enumeration. . . . . . . . . . . . . . . . . . . . . . . 565

8.8 De�nitions of the Relationship enumeration. . . . . . . . . . . . . . . . . . . . . . . 565

8.9 De�nitions of the RelationType enumeration. . . . . . . . . . . . . . . . . . . . . . 566

8.10 De�nitions of the RightsSet enumeration. . . . . . . . . . . . . . . . . . . . . . . . 566

8.11 De�nitions of the SelOpcode enumeration. . . . . . . . . . . . . . . . . . . . . . . . 566

8.12 De�nitions of the SelOperator enumeration. . . . . . . . . . . . . . . . . . . . . . . 568

8.13 De�nitions of the SelType enumeration. . . . . . . . . . . . . . . . . . . . . . . . . 569

8.14 De�nitions of the SetType enumeration. . . . . . . . . . . . . . . . . . . . . . . . . 569

8.15 De�nitions of the SeverityFlag enumeration. . . . . . . . . . . . . . . . . . . . . . . 570

8.16 De�nitions of the ValueMatrixMode enumeration. . . . . . . . . . . . . . . . . . . . 570

9 ASAM ODS Constants 571

9.1 De�nitions of the LockMode constant. . . . . . . . . . . . . . . . . . . . . . . . . . 571

9.2 De�nitions of the ODSReadTransfer constant. . . . . . . . . . . . . . . . . . . . . . 571

9.3 De�nitions of the QueryConstants constant. . . . . . . . . . . . . . . . . . . . . . . 572

9.4 De�nitions of the ResultType constant. . . . . . . . . . . . . . . . . . . . . . . . . 572

9.5 De�nitions of the SecurityLevel constant. . . . . . . . . . . . . . . . . . . . . . . . 573

9.6 De�nitions of the SecurityRights constant. . . . . . . . . . . . . . . . . . . . . . . . 573

10 ASAM ODS Types 575

10.1 De�nition of the CORBA types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

10.2 De�nitions of the Scalar type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576

10.3 De�nitions of the Sequence type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578


© 2015/08/19 Version 1.33



CONTENTS v

11 ASAM ODS Exceptions 589

11.1 AoException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

12 ASAM ODS Interface Short Reference 591


© 2015/08/19 Version 1.33



Chapter 1

General information

1.1 Introduction

The ASAM ODS OO API is de�ned in the Corba Interface De�nition Language. The interfacecan be used as a Client/Server interface. The server part in implemented in the Avalon. Theclient part can be generated by an IDL compiler. Most corba implementations have his own IDL-Compiler to generate the client stub. For other language the same procedure must be done withjust another IDL compiler and language compiler.

Figure 1.1: IDL-Compiler

The interfaces de�ned in the ASAM ODS API are in the Corba objects which will stay on theserver and the access will be done by methods. On the client there is only a proxy object availableso each access will cause a network round trip. These network round trips can leads to badperformance. It is required to get a good balance between the access to structures and to theinterfaces. The access to the interfaces is easier to program but as soon as a large number ofinstances will be accessed the performance will be to low.

The number of objects access by the client in one session have also in�uence on the performanceof the server, because the server have to store the object reference in a map. Each time a newobject is created and the access to one object the server will search in the map for the object, theperformance will reduce when there are more objects stored in the map. The server needs alsomemory for the objects, so a high number of objects will increase the memory requirements ofthe server. When there are a lot of objects to clean up in the server, the server will reduce theresponse of the client request to get time to cleanup the memory.

Since ASAM ODS 5.0 there are destroy-methods de�ned in the interface, so the client can tell theserver to remove an object from the map. It is the reponsable of the client to call these destroy-methods. The server can destroy the objects, except when the client calls the destroy-methods,at close of the session.

The AoFactory is published at the Corba-NameService, the client get the proxy object from theCorba-NameService and from this object with the interface methods of AoFactory, the clientcan connect to the server using the methods newSession. From the session, the client can get theapplication structure or the base structure and so on. The methods of the interface are so designedthat from the most interfaces there is a way back to the session, an enterprise client don't need to

2 General information

transport the connect information, if only an instance element is required at another component ofthe client software, which can make the client more reliable for username and password protection.

ATHOS o�ers some client side classes, AoServiceFactory and AoService, which hide the access tothe Corba-NameService. The classes are documented in the Framework-documentation and areno part of this document.

Athos o�ers the client side classes for the direct access, these classes don't use Corba and theperformance di�erence can be signi�cant but there is no scalability and the client must run on thesame engine as the ODS server.

The main interfaces of the ASAM ODS API are given below:


© 2015/08/19 Version 1.33



1.1 Introduction 3

AoSession

BaseStructure

BaseRelation

BaseElement

AoFactory

ApplicationRelation

ApplicationAttribute

Measurement

ValueMatrix Column

ApplicationStructure

ApplicationElement

BaseAttribute

SubMatrix

InstanceElement

ApplElemAccess

Figure 1.2: The main components


© 2015/08/19 Version 1.33




1.2 Pools and maps in the implementation

The pools and maps in the implementation are important for the performance and the actuality ofthe instance data. The pools and maps can be controlled by some INI-�le variables and depends onthe used implementation. The following �gure shows the pools and maps in the implementation.

Avalon / Corba with Active Object Map

ODS API with instance pool

Athos Runtime System with instance cache and local column value cache

MME*-Translator

Oracle

Figure 1.3: The pools and map's in the implementation

When the number of objects in a pool or map increase the performance of the system will be lessbecause of search in the pool or map takes time. The balance between the number of objects in apool and the usage of the pool depends on the application.

1.2.1 Avalon / Corba with Active Object Map

The corba implementation of the avalon uses according the de�nition in ASAM ODS the PortableObject Adapter (POA) of the objects. POA is the implementation independent transfer of theobjects between di�erent corba implementations. The POA objects are all stored in an active


© 2015/08/19 Version 1.33



1.2 Pools and maps in the implementation 5

object map, all access from a client to an object on the server the corba implementation at theserver search for the object in the active object map. The more objects in the active objectmap the less the throughput of the client / server communication. To prevent in�uence of thenumber of objects in the active object map of other clients for each session (AoSession) an ownactive object map is created. To reduce the number of objects in the active objects the ODS APIhave de�ned the destroy() method at di�erent instances like InstanceElement. The destroy()method only removes the object from the active object map, the destroy method have no in�uenceon the persistance of the object in the server.

Down here the results of some performance measurements are shown. The performance measure-ment have 4 di�erent ways measurement with di�erent number of instances.

1. Destroy, the instances are accessed with an iterator. During the measurement loop eachinstance is loaded from the iterator to the client, the name and an attribute value are loadedfrom the instance, at the end the instance is destroyed. There are 5 access for each instance,1. loading from the iterator, 2. get the name, 3. get the attribute value, 4. get the applicationelement, which will cause also a search in the active object map for the returning object and5. destroy the instance. The number of objects in the active object map is constant, whenan instance is loaded the number is increase with 1 and at destroy the number of objects isreduced again with 1.

2. ArrayDestroy the instances are accessed with an iterator. All instances used for the mea-surement loop are loaded into an array at the client. For each instance the name and anattribute value are loaded from the instance, at the end the instance is destroyed. There are4 access for each instance, 1. get the name, 2. get the attribute value, 3. get the applicationelement, which will cause also a search in the active object map for the returning objectand 4. destroy the instance. The number of objects in the active object map is increasedwith the number of instances in the measurement and reduce with 1 each time an instanceis handled.

3. NoDestroy, the instances are accessed with an iterator. During the measurement loop eachinstance is loaded from the iterator to the client, the name and an attribute value are loadedfrom the instance. There are 4 access for each instance, 1. loading from the iterator, 2. getthe name and 3. get the attribute value, 4. get the application element, which will causealso a search in the active object map for the returning object. The number of objects inthe active object map starts low and will increase with each instance. At the end of themeasurement loop there are at least so many instances in the active object map as instancesare handled in the measurement.

4. ArrayNoDestroy the instances are accessed with an iterator. All instances used for themeasurement loop are loaded into an array at the client. For each instance the name andan attribute value are loaded from the instance. There are 3 access for each instance, 1.get the name and 2. get the attribute value and 3. get the application element, which willcause also a search in the active object map for the returning object. The number of objectsin the active object map is constant high. when the instances are loaded in the array oninstances at the client the number of objects in the active object map is at least the numberof instances of the measurement. Because the destroy method is not called the number ofinstances stay constant until the session is close.


© 2015/08/19 Version 1.33




NoInst Destroy ArrayDestroy NoDestroy ArrayNoDestroy1000 10075 7307 7166 74833000 10586 8586 9606 92345000 10859 9738 11894 108627000 12017 10604 13823 128109000 13288 11912 16060 1467211000 14266 13270 18384 1657613000 16296 14562 19982 1837015000 17846 15990 22638 1998317000 19520 16639 25893 2121319000 20630 18698 27969 23324

The times in the table are in milliseconds (msec). The graphic below shows the content of thetable.

Performance of method destroy

Seite 1

0 2000 4000 6000 8000 10000 12000 14000 16000 18000 200000

5000

10000

15000

20000

25000

30000

Performance of method Destroy

DestroyArrayDestroyNoDestroyArrayNoDestroy

Number of instances

Tim

e (m

sec)

The table and graphic shows when the number of instances and therefor also the number ofobjects in the active objects map are low, the time for the destroy method is higher then thesearch time in the active objects map. When the number of instances increase the performanceget less. Each time an access is down the Corba implementations search in the active object mapfor the object, during the measurement there where only 3 access to the server for each instance,when this number of access increase the search time has more in�uence on the complete systemperformance.

1.2.2 ODS API with instance pool

The instance pool in the ODS API have a little in�uence on the size of the active object mapof Avalon. When the instance pool is activated the instances with from the same instance inthe athos runtime system becomes the same entry in the active object map. An instance pool iscreated at each application element so there are less instances in the instances pool as there areobjects in the active object map.

The INI-�le variable ODSAPI_USE_INSTANCE_POOL switch the usage of the instance pool in the odsapi on or o� at startup of the implementation. For a detail description of the INI-�le variableslook in the Technical Reference Sheet of the ASAM-ODS API.


© 2015/08/19 Version 1.33



1.2 Pools and maps in the implementation 7

1.2.3 Athos Runtime System with instance cache and local column valuecache

At the Athos Runtime System there is a cache for instances and for the values of the local column.The cache for the instances is important for the performance of the translator / server. Translatorswith a database and fast database access should no use the cache of the instances in the AthosRuntime System, however translators with slow access to the instances (reading �les / scanningdirectories) can get a lot of performance when the cache of the instances is used.

With the INI-�le variable NO_INSTANCE_CACHE can the instance cache be deactivated. When thecache of the instances is not active the pool with instances will be removed before the next accesstime the instances are loaded from the translator into the Athos Runtime System. The cache ofthe instances use the Id as index, all access to the instance with the Id will not cause that theinstances are removed from the cache. The instances are not removed from the cache when asession (AoSession) is closed except when the INI-�le variable CLEAR_INSTANCE_CACHE (availablesince Athos 3.5c) is set.

The INI-�le variable CHECK_ID_ALWAYS for the implementation for each new instance to check theId of the instance element, so that no two instances with the same Id are stored in the pool. Theimplementation knows either there are instances already in the pool or the pool is empty before theinstances are loaded from the data storage. When no instance cache is used (NO_INSTANCE_-CACHE=YES), the pool will be often empty and the there are no instances with the same Id inthe storage then the check of the Id is not required.

1.2.3.1 The cache of local column values.

The cache of the values of the local column is used for faster access to the values of the localcolumn,normally the values of the same local column are accessed by the client more then once. The cacheis pro session. This cache is also the maximum of the size of one value of the local column. Thecache can be controlled by the following INI-�le variables MAX_LC_MEMORY, MAX_NUMBER_LC andFREE_NUMBER_LC. The INI-�le variable MAX_LC_MEMORY de�nes the number of memory in MBytes,the INI-�le variable MAX_NUMBER_LC de�nes the number of local columns in the cache, the INI-�levariable FREE_NUMBER_LC de�nes the number of local columns removed from the cache when thereare to much local columns in the cache. These two last INI-�le variables controls the local columnvalue cache when the are a lot of local columns with only a few number of values. The cache iscleared on close of the session (AoSession) when the INI-�le variable CLEAR_LOCALCOLUMN_MEMORYis set.

When there are a lot of local columns with only a few values the cache of the values of thelocalcolumn is not required.

Before the values of a local column are loaded the required memory is calculated and check if thereis enough space left in the cache. For the calculation of the required memory for local columnwith datatype DT_STRING the content of the variable MAXSTRLEN is used. For the calculationof the required memory for local column with datatype DT_DATE the content of the variableMAXDATELEN is used. For the calculation of the required memory for local column with datatypeDT_BYTESTR the content of the variable MAXBYTESTRLEN is used. When there is no space inthe local column cache for the values of the next local column the values of loaded local columnsare unloaded, starting with the local columns which are longest not accessed. When the requiredmemory of the values of a local column exceeded the maximum size of the local column cache theerror AO_NO_MEMORY is reported. When the values are loaded the used memory is counted in thecache, the values from the calculation of the required memory is only used before the values areloaded.

The cache is turned o� when the INI-�le variable MAX_LC_MEMORY is set to 0. In this case there is


© 2015/08/19 Version 1.33




no restriction of the used memory for the values of the local columns. A client is able to load thevalues of the local column until the memory of the system exceed. When the local column is notreferenced anymore the values are freed from the memory, this happen at least when the sessionis closed.

The cache is normally pro session, when the number of values of a localcolumn is big and thenumber of session is big, the

For a detail description of the INI-�le variables look in the Technical Reference Sheet.

1.3 Performance of the implementation.

In the section Pools and maps in the implementation (p. 4) the usage of the di�erent poolsand maps is explained, besides the pool there are a lot of other in�uences on the performance ofthe system. The antivirus is one of the main performance killer in a multi computer environment.Also the application model have in�uence on the performance of the system.

1.3.1 ASAM ODS and antivirus programs

The antivirus programs have in�uence on di�erent places in an ASAM ODS implementation. Thefollowing �gure shows the system components, the antivirus program can have in�uence on eachlevel.

«executable»ODS Client

«executable»Avalon

«database»Physical Storage (Oracle)

«file»Mixed Mode Storage

Corba

SQL-Net File access

«file»Database files

Oracle file access

«file»Log-filesFile access

Figure 1.4: The system components


© 2015/08/19 Version 1.33



1.3 Performance of the implementation. 9

The corba communication between the ODS Client and the Avalon.

The antivirus program normally checks the incoming packages from the network. All thecommunication between the ODS Client and the Avalon is checked either at the Avalon sideor on the ODS Client side. At each network round trip, call from client to server, the antiviruswill run �rst on the Avalon side to check the incoming request and then at the ODS Clientside to check the return of the request.

The �le access to the LOG-�les.

The antivirus program normally checks the writing to the �les system. The LOG-�les of theAvalon are stored on the �le system, so the antivirus will run every time the Avalon writesomething in the LOG-�les. Avalon �ushes every line to the LOG-�les to guarantee that nolines get lost at the end of Avalon so the antivirus runs at every line written from the Avalonin the LOG-�le. Antivirus programs normally scans the complete �le, so when the LOG-�les are big, the scan of the antivirus will cost time. This can be controlled by the INI-�levariables DEBUGLEVEL , ERR_MAX_LINES and ERR_MAX_LINES. When the LOG-�les are locatedon a network drive the antivirus run another time during the network transfer.

The �le access to the Mixed Mode Storage.

Like the �le access to the LOG-�les the antivirus will check the access to the Mixed Mode �lesalso. The Mixed Mode �les are big binary �les, so the antivirus program will have problemsto check the �les. When the antivirus checks the �les only when they are written �les arechecked not at every read access so the in�uence on the performance is only during the writeof the Mixed Mode �les. Avalon writes the values of one localcolumn in one write access soat every local column the antivirus will run once. When the Mixed Mode �les are located ona network drive the antivirus run another time during the network transfer.

SQL-Net from the Avalon to the Oracle database.

The SQL-Net is also a network transfer between the Avalon and Oracle so here can be also arun of the antivirus program. We are no oracle specialist, maybe oracle use not the operatingsystem functionality for the transfer but has it own and the antivirus will not run during thiscommunication.

Oracle �le access

Oracle stores the information also in �le an the �le system, so here can the antivirus be alsoactive. We are no oracle specialist, maybe oracle use not the operating system functionalityfor writing the �les and the antivirus will not run when oracle update there �les. The Oracledatabase �les are huge �les so when the antivirus runs it will have big in�uence on theperformance.

1.3.2 The application model and the performance.

The application model have in�uence on the performance of the implementation. The ASAM ODSphysical storage for relational database de�nes that the attributes of an element is stored in onetable, so there is a fast access to these attributes. However there are some datatypes or relationswhich can not be stored in a single column of the table and stored in a separate table or specialcolumn. The application model designer should try to avoid these datatypes because the reducethe performance of the implementation.

N:M-relations

N:M-relations are stored in a separate table. Access to these relations force the implementationto an extra access on the data storage. This access is done for each N:M relation at each


© 2015/08/19 Version 1.33




instance. It is not possible to load the relation information for multiple instances at once likeit is done for the 1:N relations. Modi�cation of a N:M relation force the implementation to loadthe relation for both instances, so all N:M relations for both instances are loaded. Try to reducethe N:M relations to the static part of the application model like AoUser and AoUserGroup andavoid the N:M relation at the dynamic parts like AoMeasurement or AoMeasurementQuantity.The worst thing according the performance is a N:M relation between the static part anddynamic part of the application model.

Datatype with DT_BLOB and DT_BYTESTR

Attributes with the datatype DT_BLOB and DT_BYTESTR are stored in the oracledatatype 'long raw', to load these oracle datatype from the data storage a special call isrequired. The implementation need for these datatype an additional call to the data storagefor each instance element. As long as the attribute is not requested by the client the attributeis not loaded from the data storage. When the instance is modi�ed the attribute must beloaded from the data storage.

Sequence datatypes or complex datatypes.

Attributes with a sequence datatype or complex datatypes are store in a separate table. Whenthe extended query is used these attributes can be combined with a join and the access tothese attributes is only one request together with the other attributes from the storage. Theimplementation needs to compress the result from the data storage as result for the client.When the instances are not loaded with the extended query the access to these attributesforce an additional request from the implementation to the data storage. When the instanceis modi�ed the attribute must be loaded from the data storage. A database index on thecolumns iid and ord can improve the performance.

Instance attributes.

Instance attributes are not part of the application model but attribute missing in the appli-cation model. All instance attributes are stored in the same separate table SVCINST. Theinstances attributes can not be loaded with a query. The implementation need the instanceattributes an additional call to the data storage for each instance element. When the at-tributes are not requested by the client the instance attributes are not loaded, except whenthe instance element is modi�ed the instances attributes are loaded. Even when no instanceattributes are given for the instance as soon as there is one instance attribute for any instanceof an application element the implementation checks the table SVCINST when any instanceof the element is modi�ed. A database index on the columns aid and iid can improve theperformance.

1.3.3 INI-�le variables for communication with the data storage.

The performance fo the system depends on the performance on the communication between theimplementation and the data storage (Oracle database). There are some variables which havein�uence on the behaviour of the implementation.

Oracle sequences for the Id

The speci�cation of the ASAM ODS Physical Storage requires oracle sequences for the Id.The implementation accepts also a physical storage without these oracle sequence. The usageof the oracle sequences are much faster then calculating the MAX and add one for the nextinstance element especially for element with a lot of instances. The INI-�le variable USE_-

ID_SEQUENCE controls the usage of the these sequences. With the tool UpdatStorage you cancreate the sequences.


© 2015/08/19 Version 1.33



1.3 Performance of the implementation. 11

The number of instances loaded from the database.

The number of instances loaded from the data storage has in�uence on the performance ofthe implementation. The number reduce also the amount of memory allocated before the therequest is done, when a lot of attributes are requested with a high number of instances theimplementation tries the allocate memory for each attribute according the datatype for thatnumber of instances. Allocating this memory can force other memory to be swapped out inthe virtual memory which will reduce the performance. This can be controlled by the INI-�levariable SQL_MAX_ROWS and the how_many argument at the query methods of the interfaceApplElemAccess. Besides the total number of instances also the number of instances loadedin one package from the data storage have in�uence on the performance. The number ofinstances in one call requested from the storage is controlled by the INI-�le variable ORACLE_-HOST_ARRAY_SIZE. Here also the bigger the number of the host array size is the more memoryis required. This works also only on the query methods of the interface ApplElemAccess.

1.3.4 Oracle performance optimizing.

Optimizing the oracle storage is a special job. We are no oracle specialist and therefor no able tooptimize the oracle storage. We give here only a few hints for optimizing the data storage.

Index on the table SVCVAL.

An index on all columns except the column VALBLOB increase the read access to the tableSVCVAL where the values of the localcolumns are stored. An index reduce the performanceduring write but the advantage at read access is must better.

Index on columns for relational attributes.

A relation attribute is an attribute at an element which points to another element. TheFather/Child relations are always relational attributes at the child element. The relationalattributes are used in common for the navigation. A database index on the columns ofthese relational attributes can increase the performance, especially in the area below theelement of type AoMeasurement. The relational attribute from AoMeasurementQuantity orAoSubMAtrix to AoMeasurement are used to �nd the values of the localcolumns. An indexreduce the performance during write but increase the performance at read access, so theimplementation must be check that the complete performance is increased. When writinginstances the implementation have also read access to the data storage.

Analyze of the storage.

Oracle o�ers the opportunity to analyze the tables or the complete data storage. After ananalyze of the data storage the access is normally faster but can also reduce the performanceof the system. An analyze of the table SVCVAL had always better performance at our systems.

A constraint on the relational attribute from AoLocalcolumn to AoMeasurementQuantity.

When an instance of AoMeasurement is deleted the instances of AoMeasurementQuantity,AoSubMatrix, AoLocalColumn and AoExternalComponent must be deleted also. Theimplementation deleted frist the instances in the following order AoExternalComponent,AoLocalColumn, AoSubMatrix and AoMeasurementQuantity. When an instance ofAoMeasurementQuantity is deleted, the corresponding instances of AoLocalColumn must bedeleted also, the implementation have to check this. When a database constraint exist thedata storage checks it an gives an error message so the implementation knows that thereare instance of AoLocalColumn to delete. With the INI-�le variable ORACLE_CONSTRAINT_-

LC_MEQ the implementation knows that the constraint exist and don't check the instance ofAoLocalColumn.


© 2015/08/19 Version 1.33




1.4 There is no return.

The methods in the ASAM ODS OO_API which have no return have the same behaviour withinthe API.

The method throws an exception when an error occurs.

1.5 Return is a single value or object.

The methods in the ASAM ODS OO_API which return a single value have the same behaviourwithin the API.

The method will throw only an exception if an error occurs. A null-pointer or null-object will bereturned if the null-object is a valid return. E.g getBaseAttribute of interface Application-Attribute (p. 149) will return a null-object if the application attribute is not derived from a baseattribute.

1.6 Return is an array

The methods in the ASAM ODS OO_API which return an array have the same behaviour withinthe API.

The method will always returns an array as long as no error is occurred. If there are no elementsfor the requested method an empty array, length = 0 will be returned.

1.7 Return is an iterator

The methods which will return an iterator have all the same behavior.

An iterator will be returned always as long as there happens no error in the methods. If there areno entries available in the iterator, the iterator will be returned by the method.

All iterators have the following methods

� getCount(), this method will return the number of elements which by the iterator.

� nextOne(), will return the next element of the iterator, if the last element is reached themethod returns a null-element. If there are no elements in the iterator at all the �rst call ofthe method nextOne() will return also null-object. See also Return is a single value orobject. (p. 12)

� nextN(), will return an array of elements. If there are less elements left in the iterator asrequested by the client, the array will be �lled with the availabile number of elements. Ifthere are no elements left the returned array will be an empty array, length of array = 0.See also Return is an array (p. 12)

� reset(), will reset the 'current element pointer' to the beginning of the of the iterator.

� destroy(), will destroy the iterator-objects on the server, any access to the iterator after thedestroy method will lead to an error. The objects, returned with the methods nextOne()and nextN() returned to the client will stay active and will not be destroyed by this method.


© 2015/08/19 Version 1.33



1.8 Handling of the values of the AoLocalcolumn. 13

1.8 Handling of the values of the AoLocalcolumn.

In this section when we talk about the values of the AoLocalColumn we mean the values of theattribute derived from the base attribute values at an instance element from an application elementof AoLocalColumn. The same naming is used for the other base attributes. We use the names fromthe base model but at the client programmer should be aware that the names of the applicationattributes and application elements can di�er from the names of the base model.

The values of the AoLocalColumn can be accessed on two di�erent ways:

1. Using the attribute methods of the interface InstanceElement (p. 351). With these meth-ods such as getValue of interface InstanceElement (p. 374) use the stored values. So aninstance of AoLocalColumn with a sequence_representation of implicit_linear will returnexactly two values. These two values are also accessable with the baseattribute generation_-parameters. If the sequence_representation tells the client the values are stored in an ex-ternal component (external_component) the server will load the values from the external�le and returns the values to the client when the client asks for them. If the values are rawvalues, e.g. sequence_representation is raw_linear, these methods returns the raw values ifrequested for the values and the generation parameters will be returns of the request for thegeneration_parameters. Only access to all values is possible.

2. Using the interface ValueMatrix (p. 487). With the methods of the ValueMatrix the accessto the values is always to the calculated values. The sequence_representation of the AoLo-calColumn makes no di�erent for the access and interpretation of the values by the client.Access to pieces of the values is possible. The names of the columns are the names of thecorresponding AoMeasurementQuantities and not the names of the AoLocalColumns.

1.9 Usage of the value �ags.

The basemodel de�ned for the base element AoLocalColumn two base attributes, global_flagand flags, which are used for the �ags of the values. If the global_flag is de�ned then the flagscan be ignored and all values will have the �ag like the global_�ag. As soon as the global_-

flag is unde�ned, the flags de�nes the �ag for each value. The flags is a sequence of shorts(DS_SHORT), the length of the sequence is identical with the number of values. The index inthe sequence match with the index of the values.

The �eld flag of the De�nitions of the TS_Value structure. (p. 545) is used for the state ofthe attribute. If this �eld is 0, the value of the structure is unde�ned. If this �eld is 15, the valueof the structure is de�ned. Using this �eld the global_flag can be set in a de�ned to unde�nedstate. If the global_flag is in a de�ned state, the client doesn't and to load the flags.

When the client writes the values and both the global_flag and flags are both in an unde�nedstate, the server will automatically set the global_flag in a de�ned state and the attribute �ag(flag �eld of De�nitions of the TS_Value structure. (p. 545)) of the values will be the valueof the global_flag.

/*

* Meaning of flags:

* AO_VF_VALID(0x01) The value is valid.

* AO_VF_VISIBLE(0x02) The value has to be

* visualized.

* AO_VF_UNMODIFIED(0x04) The value has not been

* modified.

* AO_VF_DEFINED(0x08) The value is defined. If

* the value in a value matrix


© 2015/08/19 Version 1.33




* is not available this bit

* is not set.

* The normal value of the flag is 15.

*/

// The following example shows a defined global_flag with the value

// (AO_VF_VALID|AO_VF_VISIBLE|AO_VF_DEFINED)

NameValueUnit globalF = new NameValueUnit();

globalF.valName = "global_flag"; /* Name of the attribute, in this

* example the name of the base

* attribute is used.

*/

globalF.unit = ""; // There is no unit

globalF.value = new TS_Value();

globalF.value.u = new TS_Union();

globalF.value.u.shortVal((short)(1|2|8)); // All values are modified.

globalF.value.flag = (1|2|4|8); // global_flag is defined.

// The following example shows an undefined global_flag

NameValueUnit globalF = new NameValueUnit();

globalF.valName = "global_flag"; /* Name of the attribute, in this

* example the name of the base

* attribute is used.

*/

globalF.unit = ""; // There is no unit

globalF.value = new TS_Value();

globalF.value.u = new TS_Union();

globalF.value.u.shortVal((short)(15)); // This value has no influence.

globalF.value.flag = 0; // global_flag is undefined.

1.10 Logging of the server behaviour

The ODS API implementation allows switching of the debuglevel and log-�le during runtime. TheODS API implementation changes the debuglevel or the log-�le when the context variables arewritten. The context variable DEBUGLEVEL changes the debuglevel. The context variable ODS_-

LOGFILE close the current log-�le and opens a new log �le. The DEBUGLEVEL and ODS_LOGFILEare identical with the INI-�le variable, see for more detail information in the technical referencesheet.

The following lines shows how to change the debuglevel and the log-�le.

session.setContextString("DEBUGLEVEL", "10"); // Set the debuglevel to 10.

session.setContextString("ODS_LOGFILE", "c:\\mylog.txt"); // close the current log-file

// open log-file c:\mylog.txt

1.11 Usage of e�ective rights in ODS API.

In case an user likes to edit the content of the ASAM ODS storage it is important to knowsthat the user has the credentials to modify the ASAM ODS storage. The user will not edit thenew information and get an AoException AO_ACCESS_DENIED when the user has not thecredentials. Therefor the client should not o�er the user to edit the content of the storage whenthe user has not enough credentials. The client have to read the access rights of the object of theASAM ODS storage and check if the user have the credentials.

The ASAM ODS security supports many levels of security and ways how the rights are appliedto the object in the ASAM ODS storage. When the client want to know if the user have the


© 2015/08/19 Version 1.33



1.12 Transaction handling in ODS API. 15

correct credentials the client has to implement the ASAM ODS security. An ASAM ODS serverhas already implemented the ASAM ODS security so the easiest and fasted way is the client canask the ASAM ODS server to give the e�ective rights of an object in the ASAM ODS storage.However for administration of the security the real rights of the objects are required.

An context variable called EFFRIGHTS is de�ned in ASAM ODS, depending on the content ofthis variable the either the real rights or the e�ective rights are reported to the client. When thevalue of this variable is 0 the real rights are reported, when the value is 1 the e�ective rights arereported. This variable has in�uence of the result of the following methods:

� getAttributeRights of interface ApplElemAccess (p. 105)

� getElementRights of interface ApplElemAccess (p. 107)

� getInstanceRights of interface ApplElemAccess (p. 111)

� getRights of interface ApplicationAttribute (p. 155)

� getRights of interface ApplicationElement (p. 205)

� getRights of interface InstanceElement (p. 373)

The reported AccessControlList (ACL) when the variable EFFRIGHTS has the value 1 dependson the user logged in.

The user is member of usergroup where superuser_�ag is 1.

The user is a superuser and has no access restrictions, The ACL will have one entry with theusergroup Id where the superuser_�ag and all rights set.

Normal user.

The normal user can have access restrictions. In case there is no security de�ned the ACL willhave an entry with the Id of one of the usergroups where of he is member and all rights set.In case there security de�ned the ACL will have an entry with the Id of one of the usergroupswhere of he is member and combined rights of all his usergroups.

1.12 Transaction handling in ODS API.

It is only allowed to open one transcation in a session, when the second transaction is start anAoException with the error code AO_TRANSACTION_ALREADY_ACTIVE will be thrown.When a session is closed and a transaction is still active depending on the stting of the INI-�le or context variable SESSION_CLOSE_COMMIT the active transaction is aborted orcommited.

Depending on the mode of the translator there are di�erent ways of transaction handling.

1.12.1 Transaction handling with full database storage

When using a translator with full database access, the server can use the transaction handling ofthe database when for each session has an own database connection is con�gured (REOPEN_-ALWAYS = YES). The methods of the interface ApplElemAccess will insert and update directto the database, the database transaction handling is used. Create of the instances at the objectoriented methods createInstance of interface ApplicationElement will write the new instance at thecommit transaction to the database, query will not return the instances until commit transaction is


© 2015/08/19 Version 1.33




done. Update existing instances will update direct the database also with object oriented methods,so query on the modi�ed attributes is possible.

Don't use the OO-API method together with the methods of the interface ApplElemAccess at thesame time in the same session, this will most times leads to problems.

Modi�cation of the application structure

The modi�cation of the application structure or the enumerations will be written to thedatabase during commit transaction. The modi�cation will be available for the current sessionand all following new created sessions, the paralell open sessions will not see the modi�cationsof the application structure. Before instances of the new or modi�ed elements arecreated, it is best practice to close the session and create new session, whichallows also faster access to the instances of the elements. The paralell sessions arenot able to modify the application structure. As soon as the application structure is modi�edin a session the session must be closed and none of the paralell sessions is able to modi�ythe application structure, also not after the session with the which modi�ed the applicationstructure is closed, they must be closed also only new session opened after the session whichhas modi�ed the application structure are able to modify the application structure again. AcoSession is also a new session.

Note

Modi�cation of the application structure can only be done by the superuser, the superusersof an ODS storage should communication with each other and do not modify the applicationstructure parallel. Modi�cation of the application structure should be done very carefulbecause it can lead to the complet crash of the application, which can not be prevended bythe ODS server.

Modi�cation of the security

The modi�cation of the security information will go direct to the database.

Modi�cation of the values of the columns with the interface

ValueMatrix will update direct the database or external component �les with the databasetransaction handling, the external component �les are part of the transaction handling. Thevalues of the localcolumn will be copied to a new �le and the existing �le will be deletedwhen not used anymore by another localcolumn. Modi�cation of instances AoSubmatrix andAoLocalcolumn with the methods setValue or setValueSeq of the interface InstanceElementwill goes directly to the database, the new instances are stored at the end of the transaction.

Note

A mixture of writing/creating instances with the methods of the interface ApplElemAccessand the object oriented methods can cause to problems because the objects created with theobject oriented methods are not directly stored in the database storage.

1.12.2 Transaction handling with RPC-API translators and databasestorages

At commit transaction the instances are transfered to the server, query will return the new andupdate instances after commit transaction. Any other transaction handling is not possible deuto the missing transaction handling in the RPC-API. The modi�cations of the values in thevaluematrix are written direct to the server and there is no transaction handling.


© 2015/08/19 Version 1.33



1.13 Usage of the new base attributes of ODS 5.3.1 17

1.12.3 Transaction handling with �le based translators (ATF)

The transaction handling of the �le bases translators in done in Athos Runtime System. The queryis also done by the Athos Runtime System so direct after creating or modifying the instances theinformation is available for all accessing the datastorage. The inform ation is written to the �lewhen the service is closed. This is a close of the session and delete (deconstructor) of the sessionand the factory.

1.13 Usage of the new base attributes of ODS 5.3.1

The new base attributes for all elements.

� ao_created, the date/time the instance is created. (The attribute value is autogeneratedby the server)

� ao_created_by, the user which created the instance. (The attribute value is autogeneratedby the server)

� ao_last_modified, the date/time the instance is last modi�ed. (The attribute value isautogenerated by the server)

� ao_last_modified_by, the user which did the last modi�cation of the instance. (The at-tribute value is autogenerated by the server)

When these attributes are available at an application element and �ag autogenerated is set theAvalon will �ll these attributes. The attributes ao_created and ao_created_by when an instancesis created E.g with the method insertInstances of interface ApplElemAccess (p. 129) orcreateInstance of interface ApplicationElement (p. 182).

In case the autogenerated �ag is not set these attributes will not be �lled by Avalon and the importprocess have to �ll these attributes. Which can be exact customer business case. E.g. the importruns always with the same user (import user) but the customer likes the user which executed thetest to be the �lled in ao_created_by. The same can be required for ao_created the Avalon will�ll the date of the import but the customer likes the date of the test is executed. In these casesthe information must be transferred with the test information to the importer and the importwill write the information into Avalon and Avalon will not change the content of these attributesbecause they are not autogenerated.

The attributes ao_last_modified and ao_last_modified_by have the same behavior as theao_created and ao_created_by attribute, they are �lled when an attribute of the instance ismodi�ed. In case the autogenerated �ag is not set at these attributes Avalon will not �ll theseattributes and it is up to the client (E.g. importer) to �ll these attributes.

In case the autogenerated �ag are set at the attributes the attributes ao_created and ao_-

created_by can be �lled by the client with an update of the instance and ao_last_modified andao_last_modified_by can be initial written when the instances is created.

The new base attributes at AoMeasurement

� ao_values_accessed, the date/time of the last access to the values of the measurement.(The attribute value is autogenerated by the server)

� ao_values_accessed_by, the user of the last access to the values of the measurement. (Theattribute value is autogenerated by the server)


© 2015/08/19 Version 1.33




� ao_values_modified, the date/time of the last modi�cation of the values of the measure-ment. (The attribute value is autogenerated by the server)

� ao_values_modified_by, the user of the last modi�cation to the values of the measurement.(The attribute value is autogenerated by the server)

� ao_storagetype, the user of the last modi�cation to the values of the measurement. (Theattribute value is autogenerated by the server)

� ao_mea_size, the approximate size of the measurement values. (The attribute value isautogenerated by the server)

Set always the autogenerated �ag at the attributes ao_values_accessed and ao_values_-

accessed_by because no reading client can �ll these attributes.

The attributes ao_values_modified and ao_values_modified_by are written by Avalon whenvalues are written by with the API to Avalon, in case the external component �les are moved tothe data storage and only the attributes of AoExternalComponent are written these attributesare not �lled by Avalon. When a modi�cation in the �le is done by the client these attributes arenot updated by Avalon. The attribute are updated when a SubMatrix or LocalColumn object arestored.

The attribute ao_storagetype will be �lled when values are written by with the API to Avalon.When the values are modi�ed this attribute will not be updated. The attribute are updated whena SubMatrix or LocalColumn object are stored.

The attribute ao_mea_size will be �lled when values are written by with the API to Avalon.In case the attributes of AoExternalComponent are modi�ed by the client with or without theexternal component �les these attributes are not updated. The attribute are updated when aSubMatrix or LocalColumn object are stored.

Note

The update of these attributes are only implemented in the translator mme.


© 2015/08/19 Version 1.33



Chapter 2

Explanation of the documentaion

2.1 Explanation of the method documentation

The documentation of the methods in the ASAM ODS Interface have all the same �elds, someof the �elds are explained below.

2.1.1 Explanation of the Return.

Return:

NameValue contextVariable The requested context variable.

� NameValue The type of the return variable.

� contextVariable The name of the return variable.

� The description of the return parameter in italic

2.1.2 Explanation of the Parameter.

Parameter:

Name varName (in) The name of the requested context variable.

� Name The type of the parameter.

� varName The name of the parameter.

� (in) describes the direction of the parameter, the direction can be 'in', 'out' or 'in/out' forin and out

� The description of the paramater in italic

2.1.3 Explanation of the Tested by.

Tested by:

In this paragraph test methods are listed which uses this method during the test. Not all testmethods are in the list and when the paragraph don't exist it does not means the method isnot test at all.

20 Explanation of the documentaion

2.1.4 Explanation of the examples.

In the examples of this chapter, the Corba and AoException are not catched. This is required inthe client programming but to leave the example smaller we decided to leave out the catch of theexception.

The example of getContext of interface AoSession (p. 60) should be:

import org.asam.ods.AoSession;

import org.asam.ods.NameValue;

import org.asam.ods.NameValueIterator;

// Create a new session with aoFactory.

AoSession session=null;

try {

session = aoFactory.newSession("");

try {

// Session successfully created ?

if (session != null) {

// Create holder for return values.

NameValueIterator nvIte;

NameValue[] nvSeq;

// Ask for all variables with any name pattern.

nvIte = session.getContext("*");

// Get for max. 40 variables.

nvSeq = nvIte.nextN(40);

...

// Print the result variable list to standard output.

for (int i=0; i<nvSeq.length; i++) {

System.out.println (nvSeq[i].name + " = \"" +

nvSeq[i].value.u.stringVal()

+ "\"");

}

}

} catch (AoException aoEx) {

// Handle the AoException.

}

// Close the session.

session.close();

} catch (AoException aoEx) {

}

}


© 2015/08/19 Version 1.33



Chapter 3

Connect to an ASAM ODS server

using the implementation of

HighQSoft

3.1 Getting the AoFactory.

An ASAM ODS Server publishes his factory of type AoFactory (p. 29) at an CORBA-NamingService. At most CORBA implemetations there is example how to connect to the CORBA-Naming Service, this is also explained from the OMG. For the client development there is animplementation of the Highqsoft to connect to an ASAM ODS server using the CORBA-NamingServer.

3.2 Connect to the ODS API using the implementaion of

HighQSoft.

The JAVA implementation of HighQSoft allows the client to use the same code for the directbinding with JAVA to the implemetation of the CORBA- binding to an ODS API Server such asthe HighQSoft Avalon. The class AoFactory is the entry point of the ASAMODS API. An object ofthe class AoFactory will be published at the CORBA-Naming Service by the ODS API Server. Theclient have to connect to the CORBA-Naming Service and query for the published objects and bindto one of these objects. The HighQSoft de�ned interface com.highqsoft.odsfactory.AoServicehides the connect, list and bind to the CORBA-Naming Service. With the HighQSOft de�ned classcom.highqsoft.odsfactory.AoServiceFactory you can get an object implement this interface.There is also an implementation of the interface com.highqsoft.odsfactory.AoService for thedirect binding with JAVA.

Note

The classes AoService and AoServiceFactory where in the package com.highqsoft.ods andare moved to the package com.highqsoft.odsfactory with the ATHOS version 4.1.

22 Connect to an ASAM ODS server using the implementation of HighQSoft

client AoServiceFactory aoService aoFactorynewService()

aoService

listServices()

services

newFactory()

aoFactory

newSession()

aoSession

Sequnce diagram connect to the ODS API

The following code snipper shows how to connect an ODS Server with the implementation inFramework, using the HighQSoft de�nitions.

// CORBA plugable modul

String plumCorba = "com.highqsoft.ods.corba.AoService";

// The option with the connect information for the ORB NameService

String option = "NameServicePort=2809, NameServiceHost=testserver";

// Get the service from the package 'plumCorba'

// with the services from the NameService

AoService aoService = AoServiceFactory.newService(plumCorba, option);

// Get the desired ASAM ODS session factory (without factory options),

// in the example "TestModel/DB".

AoFactory aoFactory = aoService.newFactory("TestModel/DB", null);

// Connect user karst and password secret

AoSession aoSession = aoFactory.newSession("USER=karst, PASSWORD=secret");

// Close the session at the end.

aoSession.close();

3.2.1 Connect to an ATF-File

The implementation allows to connect to an ATF �le. It makes no di�erence to open an ATF/CLA(classic) or ATF/XML �le, the way to do is the same only another translator must be availablein the service of the INI-�le.

The following code snipper shows how to connect an ATF-�le with java and the HighQSoft javalanguage binding.

// Athos plugable modul

String plumAthos = "com.highqsoft.ods.athos.AoService";

// The option with the INIFILE

String option = "INIFILE=myAthos_ini_File";

// Get the service from the package 'plumAthos' with the services form the INI

-file

AoService aoService = AoServiceFactory.newService(plumAthos, option);

// Get the desired ASAM ODS session factory (without factory options),

// in the example "XATF/TestModel/Out".


© 2015/08/19 Version 1.33



3.2 Connect to the ODS API using the implementaion of HighQSoft. 23

AoFactory aoFactrory = aoService.newFactory("XATF/TestModel/Out", null);

// Connect with a filename TestModel.xml for reading.

AoSession aoSession = aoFactory.newSession("FILENAME=TestModel.xml, OPENMODE=r

";);

// Close the session at the end.

aoSession.close();

The example service in the INI-�le is given below, important in the service is the lineREOPEN_-VARIABLE = FILENAME which force the implementation to reopen each time newSessionis called the ATF �le is reopened.

[SERVICE "XATF/TestModel/Out"]

DRIVER = xatf

DIRECTORY = "file:///$(ATHOS_ROOT)/bin/$(OSTYPE)/"

FILENAME = "any.xml"

MODEL_FILENAME = "TestModel.xml"

NOSECURITYACTIVE = YES

IGNORE_SECURITY = YES

SEARCH_FOR_BASE_REF = NO

WRITEMODE=CHANNEL

REOPEN_VARIABLE = FILENAME

XATF_LOGFILE = "xatf_out.log"

ODS_LOGFILE = "xatf_ods_out.log"

ODSVERSION = "5.0 readonly"

LOAD_NEXT_ID = NO

When the service must be open to write in anf ATF-File use at the method newSession theargument OPENMODE=w. With the abbove example INI-�le the application model and the instancesare read from the �le given with the entry MODEL_FILENAME and the instances will be writtento the �le given with the FILENAME as argument of the method newSession. When no applicationmodel �le is given the client must write the complete application model and all instances to theATF �le. The line LOAD_NEXT_ID = NO force the implementation to create Id's for theinstances, so the client have to write also the Id's of the instances.

The session, factory and service must be closed and deleted properly otherwise the implementationwill not write the ATF File. Languages with an automatic garbage collector like java will �nalize(delete) the objects when garbage collectors runs. The implementation writes only the ATF-�lewhen all the objects are deleted. If there are any objects such as the ApplicationStructure oranything else used as a static objects, JAVA will not delete these objects and the implementationdon't know that they are not used anymore and will wait unitil they are deleted before the �lewill be written.

Give the implementation time to write the �le after delete of the objects. The implemetation willstart to write the �le when all the objects are deleted in the application but it needs some timeto write the �le.

// Close the session

aoXmlSess.close();

aoXmlSess = null;

aoXmlFac = null;

aoService = null;

// Call the garbage collector to free the session and write the ATF file..

try {

System.gc();

Thread.sleep(60000);

} catch (Throwable t) {

}


© 2015/08/19 Version 1.33




3.3 AoServiceFactory

Package:

com.highqsoft.odsfactory

Description:

The ASAM-ODS Service Factory. The ASAM-ODS Service Factory allows to deploy di�erentASAM-ODS transport services. This is essential to create plugable ASAM-ODS components - nomatter if these components use CORBA, local native calls or other communication (transport)mechanisms.

For an example of the usage of this class look at AoFactory (p. 29).

3.3.1 Static method newService of AoServiceFactory

Purpose:

Creates a new service via the requested plugable component.

Return:

AoService aoService The requested ASAM-ODS service of the plugable component.

Parameter:

T_STRING plugableComponent (in) The name of the requested plugable com-ponent. Two classes of HighQSoft are com.highqsoft.ods.corba.AoService orcom.highqsoft.ods.athos.AoService.

T_STRING serviceOptions (in) Service dependent options.Example 1 (Athos implementation): "INIFILE=ATHOS_INI"Example 2 (Corba implementation): "NameServicePort=2809, NameServiceHost=locahost"

Errors:

AO_BAD_PARAMETERAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORY

3.4 AoService

Package:

com.highqsoft.odsfactory

Description:

The ASAM Service interface.

The ASAM Service is the implementation of HighQSoft to connect to an object of AoFactory(p. 29) This interface hides the communication layer and is part of the client software.

For an example of the usage of this class look at AoFactory (p. 29).

There are some special features of the implemention to connect to


© 2015/08/19 Version 1.33



3.4 AoService 25

3.4.1 listServices of interface AoService

Purpose:

Returns a list of available services.

Return:

NameSequence services The names of the available services..

Parameter:

T_STRING servicePattern (in) The name or the search pattern of the requested service. Thepattern "∗" is equivalent to NULL.

Errors:


3.4.2 newFactory of interface AoService

Purpose:

Creates a new session factory of the requested service.

Return:

AoFactory aoFactory The factory of the service sessions.

Parameter:

T_STRING serviceName (in) The name of the service for which a new session factory shallbe instantiated.

T_STRING factoryOptions (in) A string that contains optional name-value pairs, e.g. DE-BUGLEVEL=3. The options are implementation dependent. An implementation must havereasonable defaults for proper operation.

Errors:



© 2015/08/19 Version 1.33



Chapter 4

Hints for using ASAM ODS

In this section we like to give some hints about the usage of ASAM ODS. We like to give somehints for better performance which are related to the application model and the data in the modeland how the data storage is used.

4.1 Avoid instance attributes.

Instance attributes are de�ned in ASAM ODS to add for certain instances extra attributes notde�ned in the model. Avoid to use instance attributes, the better way is to extend the applicationmodel and use attributes or use the elements AoParameterSet / AoParameter to store these values.

Query on instance attributes is not possible. The result set of the query will also never have theinstance attributes. So for reading the instance attributes for each instance an extra turn-aroundwith the server is required and the server need an extra turn-around with the storage. THis willreduce the performance of the application. Write of instance attributes is also a separate call formthe client to the server.

4.2 Avoid N:M relations.

N:M relations are de�ned in ASAM ODS and also part of the base model. Try to reduce the NMrelation as much as possible becuase each N:M relation what can be also a 1:N relation will reducethe performance of the application.

The N:M relation are stored in a separate table in the physical storage. Using an N:M relationforces the server to handle with this intermediate table. Query with N:M relations is no problem,the server build up a join with this intermediate table and will bring the load the storage. Readingthe N:M relation explicit an extra turn-around with the server is required because the N:M relationsare not part of the result set of a query.

4.3 DT_LONGLONG as datatype of based attribute values

of AoLocalColumn

The based attribute values of the element AoLocalColumn can have all possible datatypes. Themost used datatypes are the numeric datatypes such as DT_FLOAT or DT_LONG. Some in-

28 Hints for using ASAM ODS

stances of AoLocalColumn represents a values where the range of the DT_LONG is not preciseenough. In this case the datatype DT_LONGLONG is used.

Transfer of values with a datatype such as DT_LONG can use the native system types and arefast, when the values have the datatype DT_LONGLONG the values are transferred in the typeT_LONGLONG which is a structure de�ned in the ASAM ODS idl. The usage of this structurewill reduce the performance because on client- and server- side the structure must be handled,which is less fast as using native system datatypes.

An alternative is to store the values as DT_LONG and store the high part of the DT_-LONGLONG value in a seperate attribute or instance of AoParameter when the values within ameasurement are all in the same range.

The same problem with handling the structures is also given with the datatypes DT_COMPLEXand DT_DCOMPLEX but here the values are complex values and it will be hard to split them.An alternative is storing the real and imaginair part in seperate localcolumn but this is not de�nedby ASAM ODS so only a special client is able to handle it.

4.4 DT_DATE as datatype of based attribute values of

AoLocalColumn

The based attribute values of the element AoLocalColumn can have all possible datatypes. Themost used datatypes are the numeric datatypes such as DT_FLOAT or DT_LONG. At someapplications the values of a localcolumn are the absolute timestamp, this timestamp can be storedwith the datatype DT_DATE. A value with the datatype DT_DATE is transferred as a String.Even when the string has only numbers the character set convertion of a string is done. Build upa string cost more performance then building up an integer value.

Avoid the usage of this absolute timestamp, save the values of the absolute timestamp as relativetime to the values of the based attribute measurement_begin at AoMeasurement. At import theabsolute timestamp must be converted to a relative timestamp but the network transfer can handlebetter interger values as string values and also the server is faster handling the interger values.The integer values are also smaller (4 bytes) as an absolute timestamp (14+x bytes) which alsoreduce the cost for the storage. The client program generall can handle better the integer datatypeinstead as the absolute time. In case the client needs the absolute time again it can convert therelative time again in an abloute time by adding the measurement_bigin to the relative time.

Event when the data of the absolute time channel starts before the timestamp of measurement_-begin an interger value can be a negative value and the absolute time can also be calculated.


© 2015/08/19 Version 1.33



Chapter 5

ASAM ODS Interface

5.1 AoFactory

Package:

org.asam.ods

Description:

The ASAM factory interface.

The factory is the object published at the NameService. The Avalon publisch an object withthe name of the service in the ATHOS_INI �le. The object is publisched twice, in the rootcontext with the kind "ASAM-ODS" and in the context "org/asam/ods" without any kind. If thename of the service in the ATHOS_INI �le contains '/' they will be used as cild contexts of the"org/asam/ods" context.

Note

The description, type and interfaceVerseion are not loaded from the instance of AoEnviron-ment as de�ned in ASAM ODS but are loaded from the INI-File.

The following example show how the factory can be loaded using the Athos tools.

/* @(#) $Id: ExamplesConnect.java,v 1.14 2017/04/28 14:29:25 karst Exp $

****************************************************************************

* COPYRIGHT (c), HighQSoft GmbH, All Rights reserved. *

****************************************************************************

* HighQSoft GmbH *

* Black-und-Decker-Strasse 17c, D-65510 Idstein, Germany *

* www.highqsoft.de *

****************************************************************************

* *

* This software is the confidential and proprietary information of *

* HighQSoft GmbH. *

* *

* All brand names and product names used in this software are trademarks, *

* registered trademarks, or trade names of their respective holders. *

* The authors of this software are not associated with any product or *

* vendor mentioned in the code or documentation. *

* *

****************************************************************************

*/

30 ASAM ODS Interface

import org.asam.ods.AoException;

import org.asam.ods.AoFactory;


import com.highqsoft.odsfactory.AoService;

import com.highqsoft.odsfactory.AoServiceFactory;

/*

* Modification History:

*

* $Log: ExamplesConnect.java,v $

* Revision 1.14 2017/04/28 14:29:25 karst

* Update copyright, move import list.

*

* Revision 1.13 2014/11/03 16:45:14 karst

* Remove ODsHelper and ODSxHelper.

*

* Revision 1.12 2010/11/29 09:34:19 andy

* Adapted to the new AoService package name.

*

* Revision 1.11 2010/01/11 07:56:11 karst

* Update header comment to current

*

* Revision 1.10 2009/01/05 09:24:42 karst

* Modify copyright to 2009

*

* Revision 1.9 2008/01/10 09:22:36 karst

* Change copyright to current.

*

* Revision 1.8 2005/09/22 11:59:38 andy

* dd a main method to use it as a standalone testing tool.

*

* Revision 1.7 2005/04/26 15:13:13 karst

* Organize the import list

*

* Revision 1.6 2005/01/07 15:55:30 karst

* Move the org.asam.ods.AoService to the directory com.highqsoft.ods.

* The org.asam.ods.AoService is a remaining of the ASAM ODS 4.0.

*

* Revision 1.5 2005/01/04 08:10:20 karst

* Change copyright to current.

*

* Revision 1.4 2004/09/20 08:00:46 karst

* Little correction, after remove of AoService.

*

* Revision 1.3 2004/09/20 07:45:40 karst

* Remove the import of the AoService (ODS 4.0).

*

* Revision 1.2 2004/05/21 08:17:12 karst

* Added the NoVerbose.

*

* Revision 1.1 2003/09/03 08:05:52 andy

* Move the source codes to the java subdirectory.

*

* Revision 1.1 2003/08/08 07:09:58 karst

* Initial version 3.0.

*

*

*/

public class ExamplesConnect {

public static String getArgumentValue(String argName, String defVal) {

String argValue = System.getProperty(argName, defVal);


© 2015/08/19 Version 1.33



5.1 AoFactory 31

return(argValue);

}

public static AoSession connectService(String[] args) throws AoException {

// Athos plugable modul

String plumAthos = "com.highqsoft.ods.athos.AoService";

// Corba plugable modul

String plumCorba = "com.highqsoft.ods.corba.AoService";

// Selected plugable modul

String plum;

// Convert the arguments to options and write them to the system properties

.

String options = Convert.argsToOptions(args);

boolean verbose = false;

String noVerbose = System.getProperty("NoVerbose", "no");

if (noVerbose.compareToIgnoreCase("yes") == 0) {

verbose = true;

}

if (verbose) {

// Say in which example we are.

System.out.println("\nExamplesConnect.connectService");

System.out.println( "------------------------------");

}

// Select the plugable modul.

String plugCom = System.getProperty("PlugableComponent", "CORBA");

if (plugCom.compareToIgnoreCase("athos") == 0) {

plum = plumAthos;

if (verbose) {

System.out.println("Connect to ATHOS: using: " + plum);

}

} else {

plum = plumCorba;

if (verbose) {

System.out.println("Connect to CORBA: using: " + plum);

}

}

AoFactory aoFactory = null; // The ASAM ODS factory.

AoSession aoSession = null; // The ASAM ODS session.

// Create a new service via the HighQSoft Athos or Corba client.

AoService aoService = AoServiceFactory.newService(plum,options);

String serviceName = System.getProperty("ServiceName", "ZEUS/DB.ASAM-ODS");

if (verbose) {

System.out.println("Try to connect to service: " + serviceName);

}

// Get the desired ASAM ODS session factory (without factory options).

aoFactory = aoService.newFactory(serviceName, null);

// Establish a session to the service (session options).

String userLogin = System.getProperty("UserAuthentication", "USER=rat44052,

PASSWORD=honda20148");

if (verbose) {

System.out.println("Try to connect to session with: " + userLogin);

}

aoSession = aoFactory.newSession(userLogin);


© 2015/08/19 Version 1.33




return aoSession;

}

public static void main (String args[]) {

try {

AoSession aoSession = connectService (args);

if (aoSession != null) {

org.asam.ods.ApplicationStructure asObj = aoSession.getApplicationStr

ucture();

} else {

System.err.println ("Got no session from server.\nSee server site log

file for more information.");

}

} catch (Throwable t) {

t.printStackTrace();

}

}

}

An example how to use the AoFactory interface is given below.

/* @(#) $Id: UsingAoFactory.java,v 1.13 2017/04/28 14:29:27 karst Exp $

****************************************************************************


****************************************************************************

* HighQSoft GmbH *



****************************************************************************

* *


* HighQSoft GmbH. *

* *





* *

****************************************************************************

*/






public class UsingAoFactory {

// Java application entry.

public static void main(String[] args) {


System.out.println("\nExample UsingAoFactory...");

System.out.println("-------------------------");

// Timestamp for performance check.

long mSeconds = System.currentTimeMillis();

// Create the ASAM ODS service via an ASAM ODS ServiceFactory.

// The classes AoServiceFactory and AoService are not part of

// the ASAM ODS standard and therefore proprietary. The first

// parameter of the method "newService" is a plugable ASAM ODS

// implementation. Any name of a class that implements the

// ASAM ODS interface com.highqsoft.odsfactory.AoService may be


© 2015/08/19 Version 1.33



5.1 AoFactory 33

// passed as first parameter. Make sure the specified class file

// can be found in the Java classpath. The second parameter is

// an implementation dependent string which allows to pass

// proprietary service initialization information to the

// service factory.

//

// Corba example:

// AoService aoService = AoServiceFactory.newService(

// "com.highqsoft.ods.corba.AoService",

// "CorbaImplementation=JacORB, jacorb.verbosity=3");

//

// Athos example:

// AoService aoService = AoServiceFactory.newService(

// "com.highqsoft.ods.athos.AoService",

// "INIFILE=ATHOS_INI");

//

try {

// Create a new service via the HighQSoft Athos or Corba client.

AoService aoService = AoServiceFactory.newService(

"com.highqsoft.ods.athos.AoService",

Convert.argsToOptions(args));

// Print a list of available services.

String names[] = aoService.listServices("*");

System.out.println("Available service:");

for (int i=0; i<names.length; i++) {

System.out.println(" :" + names[i] + ":");

}


AoFactory aoFactory = aoService.newFactory("AOP3Server", null);

// ASAM ODS session factory found ?

if (aoFactory != null) {

// The results of the factory interface.

System.out.println("\nASAM ODS Factory results:");

// Get the factory name.

try {

String name = aoFactory.getName();

System.out.println(" Factory name : " + name);

} catch (AoException aoException) {

System.err.println("\nUsingAoFactory, getName failed, " + aoExcept

ion.toString() + ":" +

"\n " + aoException.reason);

}

// Get the factory type.

try {

String type = aoFactory.getType();

System.out.println(" Factory type : " + type);


System.err.println("\nUsingAoFactory, getType failed, " + aoExcept

ion.toString() + ":" +


}

// Get the factory description.

try {

String description = aoFactory.getDescription();

System.out.println(" Factory description: " + description);


System.err.println("\nUsingAoFactory, getDescription failed, " + a

oException.toString() + ":" +



© 2015/08/19 Version 1.33




}

// Get the interface version.

try {

String interfaceVersion = aoFactory.getInterfaceVersion();

System.out.println(" Interface version : " + interfaceVersion);


System.err.println("\nUsingAoFactory, getInterfaceVersion failed,

" + aoException.toString() + ":" +


}

// Get a session.

try {

AoSession aoSession = aoFactory.newSession("");

System.out.println(" Session : " + aoSession);

if (aoSession != null) aoSession.close();


System.err.println("\nUsingAoFactory, newSession failed, " + aoExc

eption.toString() + ":" +


}

}


System.err.println("\nUsingAoFactory, " + aoException.toString() + ":" +


if (aoException.reason.startsWith("org.omg.CosNaming.NamingContextPackag

e.NotFound")) {

System.err.println(" Specified service not found. Check name in fir

st parameter to:");

System.err.println(" aoService.newFactory(\"<check_this_name>\",

...)");

}

}

// Print elapsed time.

System.out.println ("\nElapsed Time (in ms): " + (System.currentTimeMillis(

)-mSeconds));

// Exit the application.

System.exit(0);

}

}

5.1.1 Connect to Avalon for another user.

There are some applications which will do the authentication of the user by external systems.The external systems will handle security guidelines of the customer. These applications don'tknow the password of the user in the ASAM ODS database. These application needs to handleth econnect to the ASMA ODS Server. The correct login of the user at the ASAM ODS server isrequired to use the correct ASAM ODS security. Such applications needs to know the superuserauthentication of the ASAM ODS Server then they can connect to the ASAM ODS Server andforce a session with the credentials of the user. When in the parameter auth is extended withthe string "FOR_USER=" the session will be created for the user, when the authentication is asuperuser.

The following API call gives a example:

AoSession userSession = aoFac.newSession("USER=admin, PASSWORD=secret, FOR_USER=k


© 2015/08/19 Version 1.33



5.1 AoFactory 35

arst");

When the user 'admin' with the password 'secret' is a superuser, the session 'userSession' will becreated for the user 'karst' which must be available in the ASAM ODS storage.

5.1.2 getDescription of interface AoFactory

Purpose:

Get the description of the ASAM ODS factory. If the description is not available an emptystring is returned and no exception is thrown. The server loads the description from the baseattribute "description" of the instance of AoEnvironment.

Note

The description is loaded from the INI-File, using the variable DESCRIPTION of the service.

Return:

T_STRING description The description of the ASAM ODS factory.

Parameter:

None.

Java Calling Sequence:

String description = aoFactory.getDescription();

Java Example:

package api.methods.aofactory;




public class GetDescription {

/** We use CORBA to connect to the server */

protected static String plumCorba = "com.highqsoft.ods.corba.AoService";

/** The name of of the service is TestModel/DB */

protected static String serviceName = "TestModel/DB";

/** The CORBA NaminService is running on the host testserver at the port 2809 */

protected static String options = "NameServiceHost=testserver, NameServicePort=2809";

/**

* The main program.

* @param args not used.

*/



try {

// Create a new service via the HighQSoft Corba NameService client.

AoService aoService = AoServiceFactory.newService(plumCorba,options);



System.out.println("Description of the aoFactory is: " + aoFactory.getDescription());


© 2015/08/19 Version 1.33




} catch (org.asam.ods.AoException ex) {

// Report the error

System.err.println("AoException: error code = " + ex.errCode.value() + " and reason : " + ex.reason);

}

}

}

Errors:

AO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORY

Tested by:

test.highqsoft.avalon.AoFactoryTestIT.tearDown()

5.1.3 getInterfaceVersion of interface AoFactory

Purpose:

Get the interface version of the ASAM ODS factory. The interface version is for each ODSversion a �xed string. The string is the version of the interface implemented at the server.The format of the string is:V<Major Version Nr>.<Minor Version Nr>.<Revision Nr>- Major Version Nr (numeric: [0-9]+)- Minor Version Nr (numeric: [0-9]+)- Revision Nr (numeric: [0-9]+)Example of the version speci�cation is 'V5.1.0'.

Note

The interface version is loaded from the INI-File, using the variable ODSVERSION of theservice.

Return:

T_STRING interfaceVersion The interface version of the ASAM ODS factory.

Parameter:

None.


String interfaceVersion = aoFactory.getInterfaceVersion();

Java Example:





public class GetInterfaceVersion {


© 2015/08/19 Version 1.33



5.1 AoFactory 37







/**

* The main program.


*/



try {





System.out.println("Interface version of the aoFactory is: " + aoFactory.getInterfaceVersion());


// Report the error


}

}

}

Errors:


Tested by:


5.1.4 getName of interface AoFactory

Purpose:

Get the name of the ASAM ODS factory. If the name is not available an empty string isreturned and no exception is thrown.

Note

The name of the service in the INI-File is returned.

Return:

T_STRING factoryName The name of the ASAM ODS factory.

Parameter:

None.


String factoryName = aoFactory.getName();


© 2015/08/19 Version 1.33




Java Example:





public class GetName {







/**

* The main program.


*/



try {





System.out.println("Name of the aoFactory is: " + aoFactory.getName());


// Report the error


}

}

}

Errors:


Tested by:


5.1.5 getType of interface AoFactory

Purpose:

Get the type of the ASAM ODS factory. If the type is not available an empty string isreturned and no exception is thrown. The server loads the type from the base attribute"Application_model_type" of the instance of AoEnvironment.

Note

The type is loaded from the INI-File, using the variable TYPE of the service.

Return:

T_STRING factoryType The type of the ASAM ODS factory.


© 2015/08/19 Version 1.33



5.1 AoFactory 39

Parameter:

None.


String factoryType = aoFactory.getType();

Java Example:





public class GetType {







/**

* The main program.


*/



try {





System.out.println("Type of the aoFactory is: " + aoFactory.getType());


// Report the error


}

}

}

Errors:


Tested by:


5.1.6 newSession of interface AoFactory

Purpose:

Establish a new session to an ASAM ODS server. The server normally checks the activity ofthe session and will close the session after a time period of inactivity.


© 2015/08/19 Version 1.33




Note

The user/password is check, there is no check if the user have access rights of any element,this is done when the ApplicationStructure is loaded. At the 'auth' argument all contextvariables can be used in this string. There is a special con�guration variable OPENMODEwhich de�ned the open mode of �le translators. Use 'r' for read and 'w' for write.

Return:

AoSession aoSession The new created ASAM ODS session.

Parameter:

T_STRING auth (in) A string containing the authentication information. The followingvalues are currently supported:USERPASSWORDCREATE_COSESSION_ALLOWEDFOR_USERThe values may be speci�ed in any order and have to be separated by comma.The variable CREATE_COSESSION_ALLOWEDValue (DT_STRING) TRUE or FALSEDefault for CREATE_COSESSION_ALLOWED = FALSE.The variable CREATE_COSESSION_ALLOWED is a read-only variable in the session.The variable FOR_USER is the name of the user for which this session shall be created. Ifthis value is given, USER must be a superuser. Otherwise the exception AO_CONNECT_-REFUSED will be thrown.Example:"USER=hans, PASSWORD=secret, CREATE_COSESSION_ALLOWED = TRUE"


AoSession aoSession = aoFactory.newSession(auth);

Java Example:






public class NewSession {







/** The authentication for the ASAM ODS storage, the user is karst with the password secret */

protected static String userAuthentication = "USER=karst, PASSWORD=secret";

/**

* The main program.


*/



© 2015/08/19 Version 1.33



5.1 AoFactory 41


try {





// Get the session

AoSession aoSess = aoFactory.newSession(userAuthentication);

System.out.println("We have the session");

// Close the session when not used any more.

aoSess.close();


// Report the error


}

}

}

See also:

AoFactory.newSessionNameValue of interface AoFactory

Errors:

AO_CONNECT_FAILEDAO_CONNECT_REFUSEDAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_OPEN_MODE_NOT_SUPPORTEDAO_SESSION_LIMIT_REACHED

Tested by:

test.highqsoft.avalon.AoFactoryTestIT.main()test.highqsoft.avalon.AoFactoryTestIT.tearDown()test.highqsoft.avalon.AoFactoryTestIT.ThreadtestNewSession.run()test.highqsoft.avalon.AoFactoryTestIT.ThreadTestNewFactory.run()test.highqsoft.avalon.AoSessionTestIT.main()....

5.1.7 newSessionNameValue of interface AoFactory

Purpose:

Establish a new session to an ASAM ODS server, using an authentication string as set ofname-value-pairs. The server normally checks the activity of the session and will close thesession after a time period of inactivity. The authentication is a list of NameValue which isan argument of the method.

Return:

AoSession aoSession The new created ASAM ODS session.

Parameter:

NameValueSequence auth (in) The authentication string as set of pairs (NameValue) consist-ing of a name and a value each. The name may be the name of any context valiable, the valuemay be any allowed value for that context variable.


© 2015/08/19 Version 1.33




With this argument the values of NameValue can contain also comma because these are notused as separator.


AoSession aoSession = aoFactory.newSessionNameValue(auth);

Java Example:





import org.asam.ods.TS_Union;

import org.asam.ods.TS_Value;



public class NewSessionNameValue {








protected static String user = "karst";

protected static String password = "secret";

/**

* The main program.


*/



try {





// Create the array with the parts of the authentication

NameValue[] userAuth = new NameValue[2];

userAuth[0] = new NameValue("USER", new TS_Value(new TS_Union(), (short)15));

userAuth[0].value.u.stringVal(user);

userAuth[1] = new NameValue("PASSWORD", new TS_Value(new TS_Union(), (short)15));

userAuth[1].value.u.stringVal(password);

// Get the session

AoSession aoSess = aoFactory.newSessionNameValue(userAuth);

System.out.println("We have the session");

// Close the session when not used any more.

aoSess.close();


// Report the error


}

}

}

Since

ASAM ODS 5.3.0


© 2015/08/19 Version 1.33



5.2 AoSession 43

See also:

AoFactory.newSession of interface AoFactory

Errors:

AO_CONNECT_FAILEDAO_CONNECT_REFUSEDAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_OPEN_MODE_NOT_SUPPORTEDAO_SESSION_LIMIT_REACHED

Tested by:


5.2 AoSession

Package:

org.asam.ods

Description:

The ASAM ODS session interface.

Each time a client intends to access an ASAM ODS server it will need to open a session. When theclient has �nished its task, it should close the session. Though this is the recommended behaviorof a client, it cannot be guaranteed to the server because

� there may be client implementations which under some conditions keep the session activefor very long time periods (if not forever)

� it may happen that the network connection between the client and the server breaks, so thatthe client is no longer able to close the session.

Nevertheless it must be avoided that the number of unintentionally active sessions at the serverincreases more and more over time. Therefore an ASAM ODS server will close all sessions thatdo not interact with the server for a speci�c period of time. This timeout period may be set atthe server usually when starting the server (with a recommended default value of 30 minutes).How the timeout value is speci�ed is up to the server implementation. Client implementers shouldnote that the server administrator may have set the timeout period to a di�erent value. If a clienttries to access the server after its session is closed, a CORBA exception will be thrown. Clientimplementations must be aware that this will happen after the timout has expired; they shouldcatch and handle this exception.

The objects created by the server on request of the client stay in memory of the server untilthe session is closed. The client can tell the server which objects are not used anymore withthe destroy() methods of the interfaces (ASAM ODS 5.∗) and allows the server to remove theobjects from memory. The server will remove all remaining objects from memory when the sessionis closed. The performance of the server is related to the number of objects in memory, the moreobjects in memory, the less the performance, so it is an advantage for the performance to createa new session for object intensive work and close the session again when the work is done. When


© 2015/08/19 Version 1.33




the client access an object which it has destroyed before an corba exception will be thrown. Whena client don't use the server for a long time, the server will close the session and any access by theclient to an object of that session will cause a corba exception.

Note

The description, type and name are not loaded from the instance of AoEnvironment as de�nedin ASAM ODS but are loaded from the INI-File.

An example how to use the AoSession interface is given below.

/* @(#) $Id: UsingAoSession.java,v 1.13 2017/04/28 14:29:27 karst Exp $

****************************************************************************


****************************************************************************

* HighQSoft GmbH *



****************************************************************************

* *


* HighQSoft GmbH. *

* *





* *

****************************************************************************

*/



import org.asam.ods.ApplicationElement;

import org.asam.ods.ApplicationStructure;

import org.asam.ods.ApplicationStructureValue;

import org.asam.ods.BaseStructure;



public class UsingAoSession {




System.out.println("\nExample UsingAoSession...");




try {

// Establish the session.

AoSession aoSession = ExamplesConnect.connectService(args);

try {

// Get the application structure value.

try {

ApplicationStructureValue as = aoSession.getApplicationStructureVa

lue();

System.out.println("Application StructureValue: " + as);


System.err.println("\nUsingAoSession, getApplicationStructureValue


© 2015/08/19 Version 1.33



5.2 AoSession 45

failed:" +

"\n " + aoException.toString() +


}

// Get the application structure.

try {

ApplicationStructure as = aoSession.getApplicationStructure();

System.out.println("Application Structure: " + as);

ApplicationElement[] aes = as.getElements("*");

if (aes != null) {

for (int i = 0; i < aes.length; i++) {

System.out.println(aes[i].getName());

}

}


System.err.println("\nUsingAoSession, getApplicationStructure fail

ed:" +



}

// Get the base structure.

try {

BaseStructure bs = aoSession.getBaseStructure();

System.out.println("Base Structure: " + bs);


System.err.println("\nUsingAoSession, getBaseStructure failed:" +



}

// Using context variables.

// Get all known context variables.

NameValueIterator vars = aoSession.getContext("*");

int n = 0;

if (vars != null) {

n = vars.getCount();

}

System.out.println("\nNumber of context variables: " + n);

// List all variable names and values.

if (n > 0) {

NameValue[] nvs = vars.nextN(n);

for (int i=0; i<n; i++) {

System.out.println(" " + nvs[i].valName + " = " +

nvs[i].value.u.stringVal());

}

System.out.println("");

}

// Set a new context variable.

String varName = "UsingAoSessionVariable";

aoSession.setContextString(varName, "The_test_value");

// Retrieve the new context variable value via iterator.

NameValueIterator varList = aoSession.getContext(varName);

if (varList != null) {

System.out.println("Value of the test variable: " +

varList.nextOne().value.u.stringVal());

}

// Retrieve the new context variable value by name.

NameValue var = aoSession.getContextByName(varName);

if (var != null) {

System.out.println("Value of the test variable: " +


© 2015/08/19 Version 1.33




var.value.u.stringVal());

}

// Remove the test context variable.

System.out.println("\nRemoving test variable...");

aoSession.removeContext(varName);

// Retrieve the new context variable value.

try {

var = aoSession.getContextByName(varName);

System.out.println(" " + var.valName + " = " +

var.value.u.stringVal());

} catch (AoException aoex1) {

if (aoex1.errCode.value() == org.asam.ods.ErrorCode._AO_NOT_FOUND)

{

System.out.println("The test variable does no longer exist.");

} else {

throw aoex1;

}

}

// Using transactions. Randomly commit or abort.

System.out.println("\nTesting transaction methods:");

try {

aoSession.startTransaction();

System.out.println("\nExample transaction started.");

if (Math.random() > 0.5) {

aoSession.abortTransaction();

System.out.println("Example transaction intentionally aborted."

);

} else {

aoSession.commitTransaction();

System.out.println("Example transaction commited.");

}


System.err.println("\nUsingAoSession, transaction example failed:"

+



}

aoSession.close();


System.err.println("\nUsingAoSession, session close failed:" +



}


System.err.println("\nUsingAoSession, " + aoException.toString() + ":" +


}



)-mSeconds));


System.exit(0);

}

}


© 2015/08/19 Version 1.33



5.2 AoSession 47

5.2.1 How to get the Id of the session

The implementation gives each new session an unique session id. There is at the moment nomethod to get these session id at the client. The implemetation has de�ned a context variableSESSIONID to read the id of the current session. This session id is unique for the run of theimpelementation, when the implementation restarts the session id will restart also. This session idis also reported in the log �le, see also Logging of the server behaviour (p. 14). The SESSIONIDis only reported with the method getContextByName of interface AoSession

Note

Since ODS 5.3.0 there is a new method getId() in the session interface which will returnthe Id of the session. for more details look in getId of interface AoSession

5.2.2 The co-session

5.2.2.1 What is a co-session.

A co-session is a clone of a session. The co-session have the same credentials as the session fromwhich the co-session is created. The co-session is indenpendent of the session, any changes of thesession after the co-session is created will have no in�uence on the co-session. The co-session islike a new session with exact the same authentication of the session from which the co-session iscreated.

5.2.2.2 When is a co-session needed.

A co-session is most time required when a session is forwarded to any other application. When bothapplications handles with the same session, there must be a very di�cult communication betweenthe two applications, when each application has it own session there is not such a problem. It is forexample only allowed to start one transaction, when both applications likes to write in the samesession, they have to synchronize which application starts and commit or abort the transaction.When one application close the session the other application can not do any thing in that session.With two di�ernt session both application can start and commit or abort any transaction and alsoclose the session when they are ready.

5.2.2.3 How to create a co-session.

The co-session can be created from the session (org.asam.ods.AoSession), the AoSession inter-face has a method called createCoSession() which will create the co-session. It is not allowed tocreate from each session a co-session, this must be allowed at the moment the session is created.ASAM ODS has speci�ed a authentication parameter which allows for that session to create aco-session. The following example shows a create of a new session and then create the co-session.

AoFactory factory .....

String auth = "USER=karst, PASSWORD=secret, CREATE_COSESSION_ALLOWED=TRUE";

AoSession aoSess = factory.newSession(auth);

// Create the co-session

AoSession coSess = aoSess.createCoSession();

// Now close the session and continue working with the session

aoSess.close();

ApplicationStructure as = coSess.getApplicationStructure()


© 2015/08/19 Version 1.33




5.2.3 Java Examples of AoSession

The Java example given at the methods of this interface are all derived from the class given below.

package api.methods.aosession;






/** The examples of the methods of AoSession are all derived from this class */

public class AoSessionExampleAbstract {

/** We use CORBA to connect to the server, required for HighQSoft way to connect to the NameService */



protected static String serviceName = "TestModel/DB.ASAM-ODS";




protected static String userAuthentication = "USER=karst, PASSWORD=secret";

/** The ASAM ODS date format. */

protected static final String ODS_DATE_FORMAT = "yyyyMMddHHmmss";

/**

* Connect to the ODS Server.

* @return the session to the ODS server.

* @throws AoException any occurring ASAM ODS exceptions

*/

protected static AoSession connect() throws AoException {

AoSession aoSess = null;


// Create a new service via the HighQSoft CORBA NameService client.

AoService aoService = AoServiceFactory.newService(plumCorba, options);



// Get the session

aoSess = aoFactory.newSession(userAuthentication);

return (aoSess);

}

}

5.2.4 abortTransaction of interface AoSession

Purpose:

Abort (rollback) a transaction. The changes made in the transaction are lost.

Note

See Transaction handling in ODS API. (p. 15)

Return:

void

Parameter:

None.


aoSession.abortTransaction();


© 2015/08/19 Version 1.33



5.2 AoSession 49

Java Example:



public class AbortTransaction extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {

AoSession aoSess = connect();

// Start the transaction

aoSess.startTransaction();

// Make some changes ...

// Abort the transaction

aoSess.abortTransaction();


aoSess.close();


// Report the error


ex.printStackTrace();

}

}

}

See also:

startTransaction of interface AoSessioncommitTransaction of interface AoSession

Errors:

AO_ACCESS_DENIEDAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.booleans.UpdateQueryTest.testCreateQuery()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.changemodel.CheckLockTest.testCheckLock()....

5.2.5 close of interface AoSession

Purpose:

Close session to an ASAM ODS server. Active transactions are committed.


© 2015/08/19 Version 1.33




Note

Depending of the INI-File variable SESSION_CLOSE_COMMIT the active transaction is abortedor commited.

Return:

void

Parameter:

None.


aoSession.close();

Java Example:



public class Close extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {



aoSess.close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.AoFactoryTestIT.tearDown()test.highqsoft.avalon.AoFactoryTestIT.ThreadtestNewSession.run()test.highqsoft.avalon.AoFactoryTestIT.ThreadTestNewFactory.run()test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()....


© 2015/08/19 Version 1.33



5.2 AoSession 51

5.2.6 commitTransaction of interface AoSession

Purpose:

Commit a transaction. The changes made in the transaction become permanent.

Note


Return:

void

Parameter:

None.


aoSession.commitTransaction();

Java Example:



public class CommitTransaction extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {





// Commit the transaction

aoSess.commitTransaction();


aoSess.close();


// Report the error



}

}

}

See also:

abortTransaction of interface AoSessionstartTransaction of interface AoSession

Errors:

AO_ACCESS_DENIEDAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEM


© 2015/08/19 Version 1.33




AO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.bosch.MultiSessionIT.threadCreate.threadCreate()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()....

5.2.7 createBlob of interface AoSession

Purpose:

Create a new object with the Interface Blob on the server. This object can be used to createan attribute value of the data type DT_BLOB.

Return:

Blob blobObj The reference of the blob object which is generated at the server.

Parameter:

None.


Blob blobObj = session.createBlob();

Java Example:



import org.asam.ods.Blob;

public class CreateBlob extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


// Create a BLOB

Blob blob = aoSess.createBlob();

System.out.println("We have a new blob.");

blob.destroy();


aoSess.close();


// Report the error



© 2015/08/19 Version 1.33



5.2 AoSession 53


}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.bosch.MultiSessionIT.threadCreate.threadCreate()test.highqsoft.odsapi.bosch.MultiSessionIT.threadUpdate.threadUpdate()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.createNewInstance()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()....

5.2.8 createCoSession of interface AoSession

Purpose:

Create a co-session. The co-session is the same session as the original session was at logintime.The co-session has no relation to the original session except that the same authentication isused.A client application with components can give all components its own session to the ASAMODS Server. So the component can close the session when it is ready, the component canstart his own transaction without any con�ict with other components.Only when the context variable CREATE_COSESSION_ALLOWED has been set to TRUEin the 'auth' parameter of the method newSession or method newSessionNameValue at theinterface AoFactory, a new session will be created when calling createSession, otherwise theexception AO_ACCESS_DENIED is thrown.

Return:

AoSession coSession The co session.

Parameter:

None.


AoSession coSess = aoSess.createCoSession();

Java Example:




© 2015/08/19 Version 1.33








public class CreateCoSession extends AoSessionExampleAbstract{

/** The authentication for the ASAM ODS storage, the user is karst with the password secret,

* allow create of cosession */

protected static String userAuthentication = "USER=karst, PASSWORD=secret, CREATE_COSESSION_ALLOWED=TRUE";

/**

* Connect to the ODS Server.

* @return the session to the ODS server.

* @throws AoException any occurring ASAM ODS exceptions

*/

protected static AoSession connect() throws AoException {

AoSession aoSess = null;


// Create a new service via the HighQSoft CORBA NameService client.

AoService aoService = AoServiceFactory.newService(plumCorba, options);



// Get the session

aoSess = aoFactory.newSession(userAuthentication);

return (aoSess);

}

/**

* The main program.


*/


try {


// Create the CoSession

AoSession coSession = aoSess.createCoSession();

System.out.println("We have the a cosession with the Id " + coSession.getId());

// Close the cosession.

coSession.close();


aoSess.close();


// Report the error



}

}

}

Since

ASAM ODS 5.1

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_ACCESS_DENIED

Tested by:

test.highqsoft.avalon.AoSessionTestIT.tearDown()


© 2015/08/19 Version 1.33



5.2 AoSession 55

test.highqsoft.avalon.ApplicationStructureRelationTestIT.testApplicationStructureRelation()test.highqsoft.avalon.ExtQueryTestIT.main()test.highqsoft.avalon.ExtQueryTestIT.runNoResultExt()test.highqsoft.avalon.ExtQueryTestIT.runSimpleQueryExt()....

5.2.9 createQueryEvaluator of interface AoSession

Purpose:

Create a QueryEvaluator object. The object supports the query execution in synchronousand asynchronous mode.

Note

Not jet implemented, Query with query language not well de�ned in ASAM ODS.

Return:

QueryEvaluator queryEvaluator The new created query evaluator object

Parameter:

None.


QueryEvaluator queryEvaluator = aoSession.createQueryEvaluator();

Errors:

AO_ACCESS_DENIEDAO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

5.2.10 �ush of interface AoSession

Purpose:

Make the pending changes of the current transaction permanent.

Note

Not yet implemented.

Return:

void


© 2015/08/19 Version 1.33




Parameter:

None.


aoSession.flush();

Errors:

AO_ACCESS_DENIEDAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

5.2.11 getApplElemAccess of interface AoSession

Purpose:

Get the application element access object from the current session.

Return:

ApplElemAccess applElemAccess The application element access object.

Parameter:

None.


ApplElemAccess applElemAccess = aoSession.getApplElemAccess();

Java Example:


import org.asam.ods.ApplElemAccess;


AoSession session;




// Get ApplElemAccess.

ApplElemAccess aea = session.getApplElemAccess();

...


session.close();

}


© 2015/08/19 Version 1.33



5.2 AoSession 57

Errors:

AO_ACCESS_DENIEDAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.ApplicationStructureTestIT.testGetInstances()test.highqsoft.avalon.DescElemQueryTestIT.testQueryChildren()test.highqsoft.avalon.ExtQueryTestIT.main()test.highqsoft.avalon.ExtQueryTestIT.runNoResultExt()test.highqsoft.avalon.ExtQueryTestIT.runSimpleQueryExt()....

5.2.12 getApplicationStructure of interface AoSession

Purpose:

Get the application model from the current session by returning an object with the interfaceApplicationStructure. The complete information on the application model is available throughthat interface.

Return:

ApplicationStructure applicationStructure The application structure.

Parameter:

None.


ApplicationStructure applicationStructure = aoSession.getApplicationStructure();

Java Example:




public class GetApplicationStrurture extends AoSessionConnect {

/**

* The main program.


*/


try {


// Get the application structure

ApplicationStructure as = aoSess.getApplicationStructure();

System.out.println("We have the application structure");



© 2015/08/19 Version 1.33




aoSess.close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.AoFactoryTestIT.ThreadtestNewSession.run()test.highqsoft.avalon.AoFactoryTestIT.ThreadTestNewFactory.run()test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.avalon.ApplicationElementTestIT.testExistBaseAttributes()test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()....

5.2.13 getApplicationStructureValue of interface AoSession

Purpose:

Get the application model as values from the current session.

Return:

ApplicationStructureValue applicationStructureValue The application structure as value.

Parameter:

None.


ApplicationStructureValue applicationStructureValue = aoSession.getApplicationStructureValue();

Java Example:




public class GetApplicationStrurtureValue extends AoSessionConnect {

/**

* The main program.


*/


© 2015/08/19 Version 1.33



5.2 AoSession 59


try {


// Get the application structure as complete structure to client.

ApplicationStructureValue asv = aoSess.getApplicationStructureValue();

System.out.println("We have the application structure value");

for (int i = 0; i < asv.applElems.length; i++) {

System.out.print("element: " + asv.applElems[i].aeName);

System.out.println(" with base type " + asv.applElems[i].beName);

}


aoSess.close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadTestEnumerationDe�nition.threadTestEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureRelationTestIT.ThreadGetRelations.ThreadGetRelations()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()....

5.2.14 getBaseStructure of interface AoSession

Purpose:

Get the ASAM ODS base model from the current session by returning an object with theinterface BaseStructure. The complete information on the base model is available through thatinterface; it includes all possible base elements with all possible base attributes as speci�edby ASAM ODS.

Return:

BaseStructure baseStructure The base structure.

Parameter:

None.


BaseStructure baseStructure = aoSession.getBaseStructure();


© 2015/08/19 Version 1.33




Java Example:




public class GetBaseStrurture extends AoSessionConnect {

/**

* The main program.


*/


try {


// Get the base structure

BaseStructure bs = aoSess.getBaseStructure();

System.out.println("We have the base structure.");


aoSess.close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()....

5.2.15 getContext of interface AoSession

Purpose:

Get context variables from the session. A pattern string can be speci�ed to select groups ofvariables.

Note

The variables from the INI-File are reported as context variables. The global INI-File variablesand the variables of the service. Environment variables used in ATHOS are part of the contextvariables, these varaibles are read-only.

Return:

NameValueIterator nvIterator A list of context variables.


© 2015/08/19 Version 1.33



5.2 AoSession 61

Parameter:

Pattern varPattern (in) The name or the search pattern for the context variable(s).


NameValueIterator nvIterator = aoSession.getContext(varPattern);

Java Example:





public class GetContext extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


// Get the all context variables

NameValueIterator ni = aoSess.getContext("*");

NameValue var;

int varCount = ni.getCount();

for (int i = 0; i < varCount; i++) {

var = ni.nextOne();

// We expect all context variables are strings.

System.out.println(var.valName + "=" + var.value.u.stringVal());

}

ni.destroy();


aoSess.close();


// Report the error



}

}

}

See also:

getContextByName of interface AoSessionlistContext of interface AoSessionremoveContext of interface AoSessionsetContext of interface AoSessionsetContextString of interface AoSession

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_FOUNDAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE


© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.odsapi.read.AoSessionTest.testAoSessionContextFilter()

5.2.16 getContextByName of interface AoSession

Purpose:

Get a context variable by its name from the session.

Note

The variables from the INI-File are reported as context variables. The global INI-File variablesand the variables of the service. Environment variables used in ATHOS are part of the contextvariables, these varaibles are read-only. The context variable SESSIONID reports the Id ofthe current session. The variable is a readonly variable and only supported at this method.

Return:

NameValue contextVariable The requested context variable.

Parameter:

Name varName (in) The name of the requested context variable.


NameValue contextVariable = aoSession.getContextByName(varName);

Java Example:




public class GetContextByName extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


// Get the context variable ATHOS_ROOT

NameValue var = aoSess.getContextByName("ATHOS_ROOT");


System.out.println(var.valName + "=" + var.value.u.stringVal());


aoSess.close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33



5.2 AoSession 63

See also:

getContext of interface AoSessionlistContext of interface AoSessionremoveContext of interface AoSessionsetContext of interface AoSessionsetContextString of interface AoSession

Errors:


Tested by:

test.highqsoft.avalon.AoFactoryTestIT.tearDown()test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureBase.threadApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureElements.threadApplicationStructureElements()....

5.2.17 getDescription of interface AoSession

Purpose:

Get the description of the ASAM ODS session. The description of the session is identical withdescription of the ASAM ODS factory. If the description is not available an empty string isreturned and no exception is thrown. The server loads the description from the base attribute"description" of the instance of AoEnvironment.

Note

The description is loaded from the INI-File, using the variable DESCRIPTION of the service.

Return:

T_STRING description The description of the ASAM ODS session.

Parameter:

None.


String description = aoSession.getDescription();

Java Example:



© 2015/08/19 Version 1.33





public class GetDescription extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


System.out.println("Description of the session is: " + aoSess.getDescription());


aoSess.close();


// Report the error


}

}

}

Errors:

AO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_CONNECTION_LOST

Tested by:

test.highqsoft.avalon.AoFactoryTestIT.tearDown()test.highqsoft.avalon.AoFactoryTestIT.ThreadtestNewSession.run()test.highqsoft.avalon.AoFactoryTestIT.ThreadTestNewFactory.run()test.highqsoft.odsapi.read.AoFactoryTest.tearDown()

5.2.18 getEnumerationAttributes of interface AoSession

Purpose:

Get a list of all attributes of all elements in the application model which are of enumerationtype. Each entry of this list provides information about- the name of the application attribute that has an enumeration data type- the id of the application element to which this application attribute belongs- the name of the enumerastion whose items may be selected as value for the applicationattribute.The method also returns based application attributes (where the enumeration is already spec-i�ed by ASAM ODS).In the (unusual) case the application model does not show any enumerastion type attribute,an empty list is returned.

Return:

EnumerationAttributeStructureSequence enumAttrList The list with attribute and there enu-meration.

Parameter:

None.


© 2015/08/19 Version 1.33



5.2 AoSession 65


EnumerationAttributeStructure[] enumAttrList = aoSess.getEnumerationAttributes();

Java Example:



import org.asam.ods.EnumerationAttributeStructure;

public class GetEnumerationAttributes extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {



EnumerationAttributeStructure[] eas = aoSess.getEnumerationAttributes();

System.out.println("We have the enumerations and attributes");

for (int i = 0; i < eas.length; i++) {

System.out.print("The attribute " + eas[i].aaName);

System.out.print(" of element with the id " + eas[i].aid.low);

System.out.println(" has the enumeration " + eas[i].enumName);

}


aoSess.close();


// Report the error



}

}

}

Since

ASAM ODS 5.2

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_NOT_FOUND

Tested by:

test.highqsoft.avalon.EnumerationReadTestIT.testEnumerationRead()

5.2.19 getEnumerationStructure of interface AoSession

Purpose:

Get all enumerations used in the application model. A list of all enumerations available inthe application model is returned to the client. This list contains for each enumeration itsname and all of its items (including item index and item name).


© 2015/08/19 Version 1.33




The method also returns all enumerations of the ODS speci�cation (which are speci�ed byASAM ODS), no matter whether these enumerations are used in any attribute of the appli-cation model.

Return:

EnumerationStructureSequence enumList The enumeration with there Items.

Parameter:

None.


EnumerationStructure[] enumList = aoSess.getEnumerationStructure();

Java Example:



import org.asam.ods.EnumerationStructure;

public class GetEnumerationStructure extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {



EnumerationStructure[] es = aoSess.getEnumerationStructure();

System.out.println("We have the enumerations ");

for (int i = 0; i < es.length; i++) {

System.out.print("The Enumeration " + es[i].enumName + " has the following items;");

for (int j = 0; j < es[i].items.length; j++) {

System.out.println("\t" + es[i].items[j].itemName +"="+es[i].items[j].index);

}

}


aoSess.close();


// Report the error



}

}

}

Since

ASAM ODS 5.2

Errors:



© 2015/08/19 Version 1.33



5.2 AoSession 67

Tested by:

test.highqsoft.avalon.EnumerationReadTestIT.testEnumerationRead()

5.2.20 getId of interface AoSession

Purpose:

Returns the Id of the session. The ODS server will give each session an unique Id. The ODSserver returns this Id to the client.

Return:

T_LONG sessionId The Id of the session.

Parameter:

None.


int sessionId = aoSession.getId();

Java Example:



public class GetId extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


int sessId = aoSess.getId();

System.out.println("Id of the session is: " + sessId);


aoSess.close();


// Report the error


}

}

}

Since

ASAM ODS 5.3.0

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORY

Tested by:

test.highqsoft.odsapi.security.SubTestCheckTest.tearDown()


© 2015/08/19 Version 1.33




5.2.21 getLockMode of interface AoSession

Purpose:

Get the current lock mode. The lock mode tells the server which objects to lock for upcomingchanges. Application elements, instance elements or children of elements can be locked.

Note


Return:

T_SHORT lockMode The current lock mode. The lock mode constants are de�ned in theinterface LockMode. The interface de�nition language IDL does not allow to set the values ofenumerations thus the constant de�nitions had to be done in an interface.

Parameter:

None.


LockMode lockMode = aoSession.getLockMode();

Errors:

AO_ACCESS_DENIEDAO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

5.2.22 getName of interface AoSession

Purpose:

Get the name of the ASAM ODS session. The name of the session is identical with the nameof the ASAM ODS factory. If the name is not available an empty string is returned andno exception is thrown. The server loads the name from the base attribute "name" of theinstance of AoEnvironment.

Return:

Name sessionName The name of the ASAM ODS session.

Parameter:

None.


© 2015/08/19 Version 1.33



5.2 AoSession 69


String sessionName = aoSession.getName();

Java Example:



public class GetName extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


System.out.println("Name of the session is: " + aoSess.getName());


aoSess.close();


// Report the error


}

}

}

Errors:


Tested by:

test.highqsoft.avalon.AoFactoryTestIT.tearDown()test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureRelationTestIT.testApplicationStructureRelation()....

5.2.23 getType of interface AoSession

Purpose:

Get the type of the ASAMODS session. The type of the session is identical with the type of theASAM ODS factory. If the type is not available an empty string is returned and no exceptionis thrown. The server loads the type from the base attribute "Application_model_type" ofthe instance of AoEnvironment.

Note

The type is loaded from the INI-File, using the variable TYPE of the service.


© 2015/08/19 Version 1.33




Return:

T_STRING sessionType The type of the ASAM ODS session.

Parameter:

None.


String sessionType = aoSession.getType();

Java Example:



public class GetType extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


System.out.println("Type of the session is: " + aoSess.getType());


aoSess.close();


// Report the error


}

}

}

Errors:


Tested by:


5.2.24 getUser of interface AoSession

Purpose:

Returns the instance element of the user logged in. This is the instance element from theapplication element derived from AoUser, with the name given in the 'auth' parameter of themethod newSession at the interface AoFactory (variable USER).When the client settings of the user are stored in the ASAM ODS application model, thismethod helps the client to get its settings.


© 2015/08/19 Version 1.33



5.2 AoSession 71

Return:

InstanceElement ieUser The instance element of the logged in user.

Parameter:

None.


InstanceElement ieUser = aoSession.getUser();

Java Example:



import org.asam.ods.InstanceElement;

public class GetUser extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


// Get the instance of the user of the current session.

InstanceElement ieUser = aoSess.getUser();

// Destroy the instance, otherwise the POA map get full.

ieUser.destroy();


aoSess.close();


// Report the error



}

}

}

Since

ASAM ODS 5.1

Errors:


Tested by:

test.highqsoft.odsapi.read.AoFactoryTest.tearDown()test.highqsoft.odsapi.security.LoginTest.testForUser()test.highqsoft.odsapi.security.SecurityTestCase.printUserGroups()


© 2015/08/19 Version 1.33




5.2.25 listContext of interface AoSession

Purpose:

List the names of context variables from the session. A pattern string can be speci�ed toselect groups of variables.

Note

The variables from the INI-File are reported as context variables. The global INI-File variablesand the variables of the service. Environment variables used in ATHOS are part of the contextvariables.

Return:

NameIterator nameIterator A list of context variable names.

Parameter:

Pattern varPattern (in) The name or the search pattern for the context variable(s).


NameIterator nameIterator = aoSession.listContext(varPattern);

Java Example:



import org.asam.ods.NameIterator;

public class ListContext extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


// Get the context variables ends with ROOT

NameIterator ni = aoSess.listContext("*ROOT");

String var;

int varCount = ni.getCount();

for (int i = 0; i < varCount; i++) {

var = ni.nextOne();


System.out.println(var);

}

ni.destroy();


aoSess.close();


// Report the error



}

}

}

See also:

getContext of interface AoSession


© 2015/08/19 Version 1.33



5.2 AoSession 73

getContextByName of interface AoSessionremoveContext of interface AoSessionsetContext of interface AoSessionsetContextString of interface AoSession

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NOT_FOUNDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.odsapi.read.AoSessionTest.testAoSessionContextFilter()test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()

5.2.26 removeContext of interface AoSession

Purpose:

Remove context variables from the session. A pattern string can be speci�ed to remove groupsof variables.

Note

The variables which are read-only will throw an exception. Global INI-File variables andvariables from the environment can not be removed.

Return:

void

Parameter:

Pattern varPattern (in) The name or the search pattern for the context variable(s) to beremoved.


aoSession.removeContext(varPattern);

Java Example:



public class RemoveContext extends AoSessionExampleAbstract {

/**

* The main program.



© 2015/08/19 Version 1.33




*/


try {


// Remove the context variable DRIVER

aoSess.removeContext("DRIVER");


aoSess.close();


// Report the error



}

}

}

See also:

getContext of interface AoSessiongetContextByName of interface AoSessionlistContext of interface AoSessionsetContext of interface AoSessionsetContextString of interface AoSession

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NOT_FOUNDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.odsapi.read.AoSessionTest.testAoSessionContextFilter()test.highqsoft.odsapi.CreateMeasurementSpecTest.testAppendValues()

5.2.27 setContext of interface AoSession

Purpose:

Set/modify a known context variable or add a new context variable to the session.

Note

The variables which are read-only will throw an exception.

Return:

void

Parameter:

NameValue contextVariable (in) The context variable.


© 2015/08/19 Version 1.33



5.2 AoSession 75


aoSession.setContext(contextVariable);

Java Example:






public class SetContext extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


// Set the context variable DEBUGLEVEL to a value of 5

NameValue nv = new NameValue("DEBUGLEVEL", new TS_Value(new TS_Union(),(short) 15));

nv.value.u.stringVal("5");

aoSess.setContext(nv);


aoSess.close();


// Report the error



}

}

}

See also:

getContext of interface AoSessiongetContextByName of interface AoSessionlistContext of interface AoSessionremoveContext of interface AoSessionsetContextString of interface AoSession

Errors:


Tested by:

test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.odsapi.performance.ValueMatrixPerfIT.testReadManyVmCount()test.highqsoft.odsapi.read.AoSessionTest.testAoSessionContextFilter()test.highqsoft.odsapi.xTend.ReplaceLocalColumnTest.testCreateMeaReplace()test.highqsoft.odsapi.CreateMeasurementTestIT.testCreateManyValues()....


© 2015/08/19 Version 1.33




5.2.28 setContextString of interface AoSession

Purpose:

Set/modify a known context variable or add a new context variable to the session. This is aconvenience method for the frequently used string variable type. It uses setContext internally.

Note

Use this method to set the DEBUGLEVEL and the ODS_LOGFILE during runtime. Thevariables which are read-only will throw an exception.

Return:

void

Parameter:

Name varName (in) The name of the context variable.

T_STRING value (in) The value of the context variable.


aoSession.setContextString(varName,value);

Java Example:



public class SetContextString extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {


// Set the context variable DEBUGLEVEL to a value of 5

aoSess.setContextString("DEBUGLEVEL", "5");


aoSess.close();


// Report the error



}

}

}

See also:

getContext of interface AoSessiongetContextByName of interface AoSessionlistContext of interface AoSessionremoveContext of interface AoSessionsetContext of interface AoSession


© 2015/08/19 Version 1.33



5.2 AoSession 77

Errors:


Tested by:

test.highqsoft.avalon.AoFactoryTestIT.tearDown()test.highqsoft.avalon.ApplicationStructureRelationTestIT.testApplicationStructureRelation()test.highqsoft.avalon.DescElemQueryTestIT.testQueryChildren()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.MeasurementTestIT.testManyMeasurement()....

5.2.29 setCurrentInitialRights of interface AoSession

Purpose:

Every new created session instance will set its initial rights to <acl> . This method overridesthe default-methods for applying initial rights. The initial rights are only valid for the currentsession.

Note

This method doesn't work for nested server. The setCurrentInitialRights method or functionwill not be called by the driver.

Return:

void

Parameter:

InitialRightSequence irlEntries (in) The current initial rights.

T_BOOLEAN set (in) Set (1) or remove (0) the current initial rights. The previous initialrights get lost. If the parameter set is 0 (remove) the parameter irlEntries will be ignored.


aoSession.setCurrentInitialRights(irlEntries,set);

Java Example:



import org.asam.ods.InitialRight;

import org.asam.ods.T_LONGLONG;

public class SetCurrentInitialRights extends AoSessionExampleAbstract {


© 2015/08/19 Version 1.33




/**

* The main program.


*/


try {




// Set the initial rights for the usergroups 1 and 2

int right = 1; // READ

T_LONGLONG usergroup1 = new T_LONGLONG(0,1);

T_LONGLONG usergroup2 = new T_LONGLONG(0,2);

T_LONGLONG refAid = new T_LONGLONG(0,0);

InitialRight[] irList = new InitialRight[2];

irList[0] = new InitialRight(right, usergroup1, refAid);

irList[1] = new InitialRight(right, usergroup2, refAid);

aoSess.setCurrentInitialRights(irList, true);





aoSess.close();


// Report the error



}

}

}

Errors:

AO_ACCESS_DENIEDAO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.security.InitialRightsTest.testDeleteCreatedInstances()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()test.highqsoft.odsapi.security.SubTestCheckTest.tearDown()

5.2.30 setLockMode of interface AoSession

Purpose:

Set the new lock mode. The lock mode tells the server which objects to lock for upcomingchanges. Application elements, instance elements or children of elements can be locked.

Note



© 2015/08/19 Version 1.33



5.2 AoSession 79

Return:

void

Parameter:

T_SHORT lockMode (in) The new lock mode. The lock mode constants are de�ned in theinterface LockMode. The interface de�nition language IDL does not allow to set the values ofenumerations thus the constant de�nitions had to be done in an interface.


aoSession.setLockMode(lockMode);

Errors:

AO_ACCESS_DENIEDAO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

5.2.31 setPassword of interface AoSession

Purpose:

Change the password for user de�ned by <username> to <newPassword>. A normal usermust supply his current password <oldPassword>. The super user can change the passwordwithout supplying the current password <oldPassword>. If no username is given the passwordof the user of the current session will be changed. The password is normally encrypted in theattribute of the user instance element. Creating a new user can be done by creating a newinstance, afterwards the password must be set by the super user.

Note

This method doesn't work for nested server, except when the user is a superuser. The setPass-word method / function isn't used for the nested server but an update of the user instance isperformed. The INI-File variable USE_CRYPTED_PASSWORD force the impementationto write the password in MD5 format, the default is NO. This method runs only within antransaction.

Return:

void

Parameter:

T_STRING username (in) The name of the user for which the password will be changed. Ifno username is given the password of the current user will be changed. If the username di�ersfrom the current user the current user must be a super user.


© 2015/08/19 Version 1.33




T_STRING oldPassword (in) The current password of the user. A normal user must supplyhis current password. The super user can change the password without supplying the currentpassword.

T_STRING newPassword (in) The new password of the user.


aoSession.setPassword(username,oldPassword,newPassword);

Java Example:



public class SetPassword extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {




// Set the password for the user hans, with the old password sercet and a

// new password secret123

aoSess.setPassword("hans", "secret", "secret123");




aoSess.close();


// Report the error



}

}

}

Errors:

AO_ACCESS_DENIEDAO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVEAO_WRONG_PASSWORD

Tested by:

test.highqsoft.odsapi.security.AttributeCheckTest.testCheckAttributeGrantRight()test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()


© 2015/08/19 Version 1.33



5.2 AoSession 81

test.highqsoft.odsapi.security.ManyGroupTest.testCreateGroups()test.highqsoft.odsapi.security.SubTestCheckTest.tearDown()....

5.2.32 startTransaction of interface AoSession

Purpose:

Start a transaction on the physical storage system (e.g. database system). Only when atransaction is started it is allowed to create or modify instances or measurement data. Thechanges will become permanent with a commit of the transaction or will be lost with an abortof the transaction. If the session is closed the transaction will be committed automatically. Ifa transaction is already active an exception is thrown.

Note


Return:

void

Parameter:

None.


aoSession.startTransaction();

Java Example:



public class StartTransaction extends AoSessionExampleAbstract {

/**

* The main program.


*/


try {




System.out.println("The transaction is started");





aoSess.close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33




See also:

abortTransaction of interface AoSessioncommitTransaction of interface AoSession

Errors:

AO_ACCESS_DENIEDAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_ALREADY_ACTIVE

Tested by:

test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.bosch.MultiSessionIT.threadCreate.threadCreate()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.ford.FordMesaurementTest.testCreateMeasurementDoubleLc()test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()....

5.3 ApplElemAccess

Package:

org.asam.ods

Description:

The application element access. The ApplElemAccess interface provides query methods to retrieveinstances of application elements. Currently available query methods are:

- query with attribute and value

- query with attribute and values (not)in set

- sorted results

- grouped results including having condition

5.3.1 How to build a query.

There are two methods to perform a query on the ASAM ODS server. The methods aregetInstances of interface ApplElemAccess (p. 113) and getInstancesExt of interface Ap-plElemAccess (p. 116).

Both methods hava a input a structure in which the query is formulated (De�nitions of theQueryStructure structure. (p. 538) and De�nitions of the QueryStructureExt struc-ture. (p. 539)).

The �elds in the both structures with the same name has the same functionallity. All �elds mustbe initialized otherwise the structure can not be transferred from the client to the server and acorba exception will raise.

The following �elds are available in the stuctures and used for the given purpose.


© 2015/08/19 Version 1.33



5.3 ApplElemAccess 83

anuSeq

In this sequence the attributes of the elements which must be reported in the result set arede�ned. You have to de�ne the application element using the Id, the attribute using the nameof the attribute and the Id of the unit in which the attributes must be reported. When youwant the values of the attributes in the default unit (unit of the storage) you can de�ne the Idof the unit with 0. When you use the the QueryStructureExt you can de�ne also an aggregatefunction for the attributes (De�nitions of the AggrFunc enumeration. (p. 553)).

condSeq

In this sequence the conditions can be de�ned. A condition is an attribute de�nition, theoperator and a value. The attribute de�nition is identical with the attribute de�nition in theanuSeq, the application element using the Id, the attribute using the name of the attribute andthe Id of the unit. The operator (De�nitions of the SelOpcode enumeration. (p. 566))tells the server which condition is used. The value is the value where the attribute is comparedwith, the unit of the value is given with the attribute de�nition of the condition. When youuse the the QueryStructureExt you can de�ne how the di�erent conditions are combined byusing the operator (De�nitions of the SelOperator enumeration. (p. 568))between theconditions in the sequence.

orderBy

In this sequence you can de�ne the ordering of the instances in the result set. You have tode�ne the application element using the Id, the attribute using the name of the attribute andthe order direction.

operSeq (QueryStructure)

This �eld is only in the QueryStructure available. Like you can de�ne the how the condi-tions are combined in the condSeq of the QueryStrutureExt, you can do the same in theQueryStructure with this �eld. There are di�enrent examples given in De�nitions of theQueryStructure structure. (p. 538)

relInst (QueryStructure)

This �eld is only in the QueryStructure available. The de�nition of the related instance,which will reduce the result set with only the attributes values of the instances related to thegiven instance. The instance is de�ned by the Id of the application element and the Id of theinstance.

relName (QueryStructure)

This �eld is only in the QueryStructure available. This �eld de�nes which relation must beused for the selection on the relation instance given in the �eld relInst

joinSeq (QueryStructureExt)

This �eld is only in the QueryStructureExt available. A sequence with join de�nitions. Inthis �eld you can de�ne how the attributes in the list of attribute to report and the attributesof the conditions must be joined when they are from di�erent elements. You have to de�nethe type of the join (De�nitions of the JoinType enumeration. (p. 564)), the elementwhere the join starts and where the join ends using the Id of the element, and the name ofthe relation which must be used.


© 2015/08/19 Version 1.33




groupBy (QueryStructureExt)

This �eld is only in the QueryStructureExt available. The sequence of the attributes whichmust be grouped. This sequence is only required when you have used an aggregate functionin the anuSeq. You have to de�ne the application element using the Id, the attribute usingthe name of the attribute.

5.3.2 The results of the query.

The way the results are organized in the result set of the di�erent queries are more or less identical.The attributes are organized in a sequence of the attributes of one element. The values of theattributes are returned in a sequence of values in De�nitions of the TS_ValueSeq structure.(p. 546). The length of the value sequence is identical for each attribute. The values with thesame index in the value sequence belongs to the same instance element. So the result set is like atable where each attribute is a column and each instance is a row.

The big di�erence between the result set is the iterator for the rest of the values.

The method getInstances of interface ApplElemAccess (p. 113) RETURNS a sequence ofDe�nitions of the ElemResultSet structure. (p. 532). The attribute values of each requestedelement are stored in an entry of the sequence. The �eld aid gives the application element Idof the element where the attributes belongs to. The attribute values of an attribute are storedin an entry of the �eld attrValues of type De�nitions of the AttrResultSet structure.(p. 531). The �rst how_many values are stored in the �eld attrValues of type De�nitions of theNameValueSeqUnitId structure. (p. 537) (Note twice the �eld attrValues with di�erent typeand di�erent meaning). The �eld valName is the name of the attribute, the �eld value of typeDe�nitions of the TS_ValueSeq structure. (p. 546) is the sequence of the attribute values.The �ags in the �eld flag of the �eld value tells with the same index wether the value is valid ornot. The �eld rest of type NameValueUnitIdIterator (p. 422) of the �rst �eld attrValues isan iteraotr for the rest of the attribute values.

The method getInstancesExt of interface ApplElemAccess (p. 116) returns a sequence ofthe structure ResultSetExt (see also De�nitions of the ResultSetExt structure. (p. 541)).This sequence will always have the length of 1. This element in the sequence have two �elds

1. �rstElems of type ElemResultSetExtSequence (see also ElemResultSetExtSequence )

2. restElems of type ElemResultSetExtSeqIterator (see also ElemResultSetExtSeqIterator(p. 338))

�rstElems

The firstElems is a sequence of ElemResultSetExt (see also De�nitions of the ElemRe-sultSetExt structure. (p. 532)), the length of the sequence corresponds with the num-ber of di�erent application elements requested in the anuSeq of the QueryStructrueExt(see also De�nitions of the QueryStructureExt structure. (p. 539)). The structureElemResultSetExt has the �elds aid and values. The aid is the Id of the application el-ement, the values, a sequence of the structure NameValueSeqUnitId (see also De�nitionsof the NameValueSeqUnitId structure. (p. 537)) are the values of the attributes. Foreach reported attribute an entry is given in the seqence, the name of the attribute is givenin the �eld valName, in case an aggregate function was requested this function is given aspart of the name of the attribute. The Id of the unit is given in the �eld unitId, this isthe Id of the instance of the application element derived from the base element AoUnit. Thevalues are given in the �eld value with the type TS_ValueSeq (see also De�nitions of theTS_ValueSeq structure. (p. 546)). Each value sequence has the same length, this lengthis maximum how_many the parameter of the method. If no values are found the length of the


© 2015/08/19 Version 1.33




sequence is 0. The values with the same index in the di�erent sequences of the entry in theNameValueSeqUnitIdSequence belongs to the same instance element.

restElems

The restElems is an iterator for the remaining sequence of ElemResultSetExt. This iteratorallows to load the next N values from the ResultSet. The result of the element is the same waystored as at the �eld firstElems, the next N is the length of the sequence of the �eld value

of the NameValueSeqUnitId. The method nextOne is wrong speci�ed and should not be used,use instead the method nextN with n=1. The method getCount return the total number offound element, also the number already returned in firstElems. The method reset set theiterator the the beginning of the ResultSet, this is the beginning of the firstElems.

5.3.3 The number of returned values in the result set.

The methods getInstances of interface ApplElemAccess (p. 113) and getInstancesExt ofinterface ApplElemAccess (p. 116) have a parameter how_many. This parameter de�nes howmany resutls will be returned. The implementation have a protection for network transfer, memoryusage, performance and client memory which will return only a restricted number of values in theresult set. The restricted number of values given in the INI-File variable SQL_MAX_ROWS, the defaultvalue of this variable is 10000.

When the client knows how many values it likes to return the client can specify this number inthe parameter how_many. Depending of the value of how_many the impelementation returns thefollowing maximum number of values.

� how_many <= 0; returns maximum SQL_MAX_ROWS

� how_many < 10000000 returns maximum how_many

� how_many > 10000000 return maximum SQL_MAX_ROWS

5.3.4 Query for Tableview with method getInstances of interface Ap-plElemAccess.

An example how to use the method getInstances of interface ApplElemAccess (p. 113) isgiven below. The example loads the attribute values of all instances of one element and replacethe Id of the related instances with the names of the related instances.

/* @(#) $Id: table_query.java,v 1.13 2017/04/06 13:28:24 adil Exp $

****************************************************************************


****************************************************************************

* HighQSoft GmbH *



****************************************************************************

* *


* HighQSoft GmbH. *

* *





* *

****************************************************************************


© 2015/08/19 Version 1.33




*/

import java.util.Vector;

import org.asam.ods.AIDName;

import org.asam.ods.AIDNameUnitId;

import org.asam.ods.AIDNameValueUnitId;




import org.asam.ods.ApplicationAttribute;


import org.asam.ods.ApplicationRelation;


import org.asam.ods.ElemId;

import org.asam.ods.ElemResultSet;

import org.asam.ods.NameValueSeqUnitId;

import org.asam.ods.QueryStructure;

import org.asam.ods.RelationRange;

import org.asam.ods.Relationship;

import org.asam.ods.SelOpcode;

import org.asam.ods.SelOperator;

import org.asam.ods.SelOrder;

import org.asam.ods.SelValue;




/*

* <TABLE BORDER class="PropertyTable">

* <TR><TH> Property Keyword </TH><TH> Datatype </TH><TH> Default </TH><TH> Desc

ription </TH></TR>

* <TR><TD> ApplicationElementName </TD>

* <TD> String </TD>

* <TD> "Messung". </TD>

* <TD> The name of the application element.<br>

* <em>This value is an application property.</em> </TD></TR>

* </TABLE>

*

*/

public class table_query extends ExamplesHelper {

/* showTableResultSet

*

* Show the names of the element ans the names of the related instances.

*

* param elemRes the names and the ids of the references instances,

* the first attribute result set ist the name, the next

* attribute result set are the Ids.

* This method is complete client performance, no request to the

server.

* param elemResArray The vector with the element result sets of the reference

s elements.

* The order of the results set is identical with the oder

of the references

* attributes in the elemRes. All result set have two attri

butes, the first the

* attribute is the Id, the second attribute is the name.

*/

public static void showTableResultSet (ElemResultSet elemRes, Vector elemResAr

ray) {


// Get the names of the element.


© 2015/08/19 Version 1.33




String names[] = elemRes.attrValues[0].attrValues.value.u.stringVal();

int noInst = names.length;

ElemResultSet relRes;

// Get the list with the Ids

int relIdArr[][] = new int[elemRes.attrValues.length-1][];

for (int j = 0; j < relIdArr.length; j++) {

relIdArr[j] = elemRes.attrValues[j+1].attrValues.value.u.longVal();

}

// i is the index of the rows

for (int i = 0; i < noInst; i++) {

// j is the index of the columns

System.out.print(names[i]);

for (int j = 0; j < relIdArr.length; j++) {

// Get the result set from the vector

relRes = (ElemResultSet) elemResArray.get(j);

// Get the sequence with Ids and the sequences with names.

// This are structure so client internal calls without a network roun

dtrip

int relIds[] = relRes.attrValues[0].attrValues.value.u.longVal();

String relNames[] = relRes.attrValues[1].attrValues.value.u.stringVal

();

// Get the Id of the related instance

int relId = relIdArr[j][i];

if (relId != 0) {

int k;

// Search for the related instance

for (k = 0; k < relIds.length; k++) {

if (relId == relIds[k]) {

System.out.print(", " + relNames[k]);

k = -3;

break;

}

}

if (k >= 0) {

System.out.print(", not found " + k);

}

} else {

// No related instance defined.

System.out.print(", UNDEFINED");

}

}


}

}

/* getRelAttributeName

* This method returns the name of the relation attribute.

* If the relation have the wrong relation range a null will be returned.

* The relation range is important, because the attribute should resolve to on

e

* instance element.

*

* param as the application structure

*

* param aeObj the source application element.

*

* param aeRel the related application element

*

* returns the name of the relation attribute

*/

public static String getRelAttributeName (ApplicationStructure as, Application

Element aeObj, ApplicationElement aeRel) throws AoException {

ApplicationRelation rel[] = as.getRelations(aeObj, aeRel);

// Expect there is only one relation


© 2015/08/19 Version 1.33




String relAttrName = null;

RelationRange relRange = rel[0].getRelationRange();

// Only n:1 relations.

if (relRange.max == 1) {

relAttrName = rel[0].getRelationName();

}

return (relAttrName);

}

/* getRelNames

* Get the Ids and Names of the related instances. A Query is used to ask for

the names, the Ids are the selection criteria

* The Ids are not reduced to a unique list of Ids, the server or database wil

l do this.

*

* param aoSession, the current session. The application structure and applele

meaccess could be paased instead.

*

* param aeRel, the referenced application element

*

* param ids the list with the requested ids.

*/

public static ElemResultSet getRelNames(AoSession aoSession, ApplicationElemen

t aeRel, NameValueSeqUnitId ids) throws AoException {

ElemResultSet elemResRel[] = null;

// Get the application structure, can be optimized


// Get the appl elem access object, can be optimized

ApplElemAccess aea = aoSession.getApplElemAccess();

// Create the query structure for the method getInstances

QueryStructure aoq;

aoq = new QueryStructure();

ApplicationAttribute aaObj;

T_LONGLONG id = new T_LONGLONG();

id.low = 0;

id.high = 0;

System.out.println("Load the names of the instances of " + aeRel.getName())

;

// Report the id and name of the related instances.

aaObj = aeRel.getAttributeByBaseName("id");

aoq.anuSeq = new AIDNameUnitId [2];

aoq.anuSeq[0] = new AIDNameUnitId ();

aoq.anuSeq[0].attr = new AIDName();

aoq.anuSeq[0].attr.aid = aeRel.getId();

aoq.anuSeq[0].attr.aaName = aaObj.getName();

aoq.anuSeq[0].unitId = id;

aaObj = aeRel.getAttributeByBaseName("name");



aoq.anuSeq[1].attr.aid = aeRel.getId();



// There is one condition

// The Id inset of the resultes in the attrResultSet

aaObj = aeRel.getAttributeByBaseName("id");

aoq.condSeq = new SelValue[1];

aoq.condSeq[0] = new SelValue();


© 2015/08/19 Version 1.33




aoq.condSeq[0].attr = new AIDNameValueUnitId();

aoq.condSeq[0].attr.attr = new AIDName();

aoq.condSeq[0].attr.attr.aid = aeRel.getId();

aoq.condSeq[0].attr.attr.aaName = aaObj.getName();

aoq.condSeq[0].attr.unitId = id;

aoq.condSeq[0].attr.values = new TS_Value();

aoq.condSeq[0].attr.values.flag = 15;

aoq.condSeq[0].attr.values.u = new TS_Union();

aoq.condSeq[0].attr.values.u.longVal(0); // Dummy

// The inset

aoq.condSeq[0].oper = SelOpcode.INSET;

aoq.condSeq[0].value = new TS_Value();

aoq.condSeq[0].value.flag = 15;

aoq.condSeq[0].value.u = new TS_Union();

aoq.condSeq[0].value.u.longSeq(ids.value.u.longVal()); // The value of

TS_UnionSeq is identical with the Sequence of a TS_Union

// Initialize the not used fields

aoq.operSeq = new SelOperator[0];

aoq.orderBy = new SelOrder[0];

aoq.relInst = new ElemId();

aoq.relInst.aid = id;

aoq.relInst.iid = id;

aoq.relName = "";

elemResRel= aea.getInstances(aoq, 1000);

// showElemResultSet(elemResRel);

return (elemResRel[0]);

}




System.out.println("\nExample table_query...");




try {



try {



// Get the appl elem access object



QueryStructure aoq;

// The application attribute.


// Result of the request

ElemResultSet elemRes[];

// Query on the application element AoTest


© 2015/08/19 Version 1.33




String aeName = ExamplesConnect.getArgumentValue("ApplicationElementN

ame", "Messung");

ApplicationElement aeObj = as.getElementByName(aeName);

// Get all related elements.

ApplicationElement ae[] = aeObj.getRelatedElementsByRelationship(Rela

tionship.ALL_REL);

int noRel = ae.length;

// Create a list with names and relations.

ApplicationElement aeRels[] = new ApplicationElement[noRel];

String relAttrNames[] = new String[noRel];

int relIndex = 0;

for (int i = 0; i < noRel; i++) {

// Get the name of the reference attribute.

// Only with the correct cardinality will be returned.

relAttrNames[relIndex] = getRelAttributeName(as, aeObj, ae[i]);

if (relAttrNames[relIndex] != null) {

aeRels[relIndex] = ae[i];

relIndex++;

}

}

noRel = relIndex; // Set the number of used relations.


id.low = 0;

id.high = 0;

// ******************************************************************

******************

// Report the name attribute of the element

aoq = new QueryStructure();

// Report the name and for each related element the Id, or relation a

ttribute

aaObj = aeObj.getAttributeByBaseName("name");

aoq.anuSeq = new AIDNameUnitId [1+noRel];



aoq.anuSeq[0].attr.aid = aeObj.getId();



relIndex = 0;

// Add the


relIndex++;

aoq.anuSeq[relIndex] = new AIDNameUnitId ();

aoq.anuSeq[relIndex].attr = new AIDName();

// set Id of element

aoq.anuSeq[relIndex].attr.aid = aeObj.getId();

aoq.anuSeq[relIndex].attr.aaName = relAttrNames[i];

aoq.anuSeq[relIndex].unitId = id;

}

// No Conditions




// Initialize the not used fields

aoq.relInst = new ElemId();


© 2015/08/19 Version 1.33




aoq.relInst.aid = id;

aoq.relInst.iid = id;

aoq.relName = "";

elemRes = aea.getInstances(aoq, 1000);

// showElemResultSet(elemRes);

// Now we have the name and Id's of the related instances.

// Load the ids and names of the related instances.

ElemResultSet elemResRel;

Vector elemResArray = new Vector();

if ((elemRes != null) && (elemRes.length > 0)) {

int noAttr = elemRes[0].attrValues.length;

// The first attribute is the name all the other attributes are re

ference attributes, the order of the

// attributes are identical with the request order.

relIndex = 0;

for (int i = 1; i < noAttr; i++) {

elemResRel = getRelNames(aoSession, aeRels[relIndex], elemRes[0

].attrValues[i].attrValues);

relIndex++;

elemResArray.add(elemResRel);

}

}


System.out.println ("\nElapsed Time (in ms) for the query: " + (Syste

m.currentTimeMillis()-mSeconds));

// Now we have the elemRes, with the instances of the application ele

ment and

// the ids and names of the related instances in elemResArray.

showTableResultSet(elemRes[0], elemResArray);

aea = null;

as = null;


System.err.println("\ntable_query, " +

aoException.toString() + ":" +


}

// Close the active session.

aoSession.close();


System.err.println("\ntable_query, " +



}

System.out.println ("\nTotal elapsed Time (in ms): " + (System.currentTimeM

illis()-mSeconds));


System.exit(0);

}

}

5.3.5 Query for Tableview with method getInstancesExt of interfaceApplElemAccess.

An example how to use the method getInstancesExt of interface ApplElemAccess (p. 116)is given below. The example loads the attribute values of all instances of one element and the


© 2015/08/19 Version 1.33




names of the related instances using joins.

An example how to use the method getInstancesExt of the interface ApplElemAccess is givenbelow.

/* @(#) $Id: table_query_ext.java,v 1.6 2017/04/28 14:29:29 karst Exp $

****************************************************************************


****************************************************************************

* HighQSoft GmbH *



****************************************************************************

* *


* HighQSoft GmbH. *

* *





* *

****************************************************************************

*/



import org.asam.ods.AggrFunc;








import org.asam.ods.JoinDef;

import org.asam.ods.JoinType;

import org.asam.ods.QueryStructureExt;


import org.asam.ods.ResultSetExt;

import org.asam.ods.SelAIDNameUnitId;

import org.asam.ods.SelItem;



import org.asam.ods.SelValueExt;




public class table_query_ext {

public static void showTableResult(ResultSetExt elemRes) {

int noRows;

int noCols;

if (elemRes.firstElems != null) {

noCols=elemRes.firstElems.length;

String vals[][] = new String[noCols][];

short flags[][] = new short[noCols][];

for (int colIndex = 0; colIndex < noCols; colIndex++) {

vals[colIndex] = elemRes.firstElems[colIndex].values[0].value.u.strin

gVal();

flags[colIndex] = elemRes.firstElems[colIndex].values[0].value.flag;

}

if (noCols > 0) {

noRows = vals[0].length;

System.out.println("Number of rows: " + noRows);

for (int rowIndex = 0; rowIndex < noRows; rowIndex++) {

for (int colIndex = 0; colIndex < noCols; colIndex++) {


© 2015/08/19 Version 1.33




if (flags[colIndex][rowIndex] == 15) {

System.out.print(vals[colIndex][rowIndex]+ ", ");

} else {

System.out.print("UNDEFINED, ");

}

}

System.out.println();

}

}

}

}




System.out.println("\nExample table_query_ext...");




try {



try {



// Get the appl elem access object



QueryStructureExt aoq;

// Result of the request

ResultSetExt elemRes[];

// The application attribute.


// Query on the application element AoTest

String aeName = ExamplesConnect.getArgumentValue("ApplicationElementN

ame", "Messung");

ApplicationElement aeObj = as.getElementByName(aeName);

// Get all relations

ApplicationRelation arList[] = aeObj.getAllRelations();

int noRel = arList.length;

// Create a list with names and relations.

ApplicationElement aeList[] = new ApplicationElement[noRel+1];

aeList[0] = aeObj;

JoinDef joinSeq[] = new JoinDef[noRel];

T_LONGLONG aid = aeObj.getId();

T_LONGLONG toAID;

ApplicationElement aeTo;

int relIndex = 0;


// Get the related elements,

// Only with the correct cardinality will be returned.

RelationRange relRange = arList[i].getRelationRange();


© 2015/08/19 Version 1.33




if (relRange.max == 1) {

aeTo = arList[i].getElem2();

toAID = aeTo.getId();

if (toAID.low == aid.low) {

aeList[relIndex+1] = arList[i].getElem1();

toAID = aeList[relIndex+1].getId();

} else {

aeList[relIndex+1] = aeTo;

}

joinSeq[relIndex] = new JoinDef();

joinSeq[relIndex].fromAID = aid;

joinSeq[relIndex].toAID = toAID;

joinSeq[relIndex].refName = arList[i].getRelationName();

if (relRange.min == 0) {

joinSeq[relIndex].joiningType = JoinType.JTOUTER;

} else {

joinSeq[relIndex].joiningType = JoinType.JTDEFAULT;

}

relIndex++;

}

}

noRel = relIndex+1; // Set the number of used elements.


id.low = 0;

id.high = 0;

// Buildup the query structure

aoq = new QueryStructureExt();

// Report the name of the selected instance and the related instances

.

aoq.anuSeq = new SelAIDNameUnitId[noRel];

for (int aeIndex = 0; aeIndex < noRel; aeIndex++) {

aoq.anuSeq[aeIndex] = new SelAIDNameUnitId();

aaObj = aeList[aeIndex].getAttributeByBaseName("name");

aid = aeList[aeIndex].getId();

aoq.anuSeq[aeIndex].attr = new AIDName(aid, aaObj.getName());

aoq.anuSeq[aeIndex].unitId = id;

aoq.anuSeq[aeIndex].aggregate = AggrFunc.NONE;

}

// Set the join sequence

noRel--;

aoq.joinSeq = new JoinDef[noRel];


aoq.joinSeq[i] = joinSeq[i];

}

// Condition name like "*"

aaObj = aeObj.getAttributeByBaseName("name");

aoq.condSeq = new SelItem[1];

aoq.condSeq[0] = new SelItem();

SelValueExt sel = new SelValueExt();

sel.attr = new AIDNameUnitId(new AIDName(aeObj.getId(), aaObj.getName

()), id);

sel.oper = SelOpcode.LIKE;

sel.value = new TS_Value();

sel.value.flag = 15;

sel.value.u = new TS_Union();

sel.value.u.stringVal("*");

aoq.condSeq[0].value(sel);

// No group by

aoq.groupBy = new AIDName[0];

// Order by name


© 2015/08/19 Version 1.33





aoq.orderBy[0] = new SelOrder();

aoq.orderBy[0].attr = new AIDName(aeObj.getId(), aaObj.getName());

aoq.orderBy[0].ascending = true;


System.out.println ("\nElapsed Time (in ms) for the preparation: " +

(System.currentTimeMillis()-mSeconds));

elemRes = aea.getInstancesExt(aoq, 1000);


System.out.println ("\nElapsed Time (in ms) for the Query: " + (Syste

m.currentTimeMillis()-mSeconds));

if (elemRes.length > 0) {

showTableResult(elemRes[0]);

}

aea = null;

as = null;


System.err.println("\ntable_query_ext, " +



}


aoSession.close();


System.err.println("\ntable_query_ext, " +



}

System.out.println ("\nTotal elapsed Time (in ms): " + (System.currentTimeM

illis()-mSeconds));


System.exit(0);

}

}

5.3.6 Report attribute with sequence datatype at method getInstances.

The default behaviour of the method getInstances of interface ApplElemAccess (p. 113)don't return attributes with a sequence datatype (DS_∗). The behaviour of this method can bechanged with the conect or INI-File variable REPORT_SEQUENCE_ATTRIBUTES. When this variableis set to 'YES' the attributes with sequence datatypes are also reported. This variable can be anINI-File variable or used as context variable in the session.

5.3.7 Example for the LIMIT operator paging of the resulst.

There are queries in ASAM ODS which will return an enormious amount of data. When the clientshows these results to the user the view will have to much entries and paging of the results isrequired. Loading the complete result to the client will take lang and requires a lot anf memoryand network transfer for data which the user will never see. For paging of the results a LIMIToperator is required because the client will not load all the results in his own memory and do thepaging locally.


© 2015/08/19 Version 1.33




The LIMIT operator is not speci�ed in the ASAM ODS IDL, because they are not supportedby the database and for the databases where they are de�ned the results of the database LIMIToperator will not mach with the LIMIT operator on ASAM ODS API.

The following code shows how a client side LIMIT operator can work, without loading all the datain the client memory.

The use case is show the id, name, description and measurement_begin and measurement_end ofthe instances of AoMeasurement ordered by the name. To show the result to the user each pagewill have 50 lines.

The client needs the id of all instances in memory and use the id as condition for laoding the dataof the page.

So the �rst query is select the id of the element ordered by name. This query must be done aspreparation. The query for a page use the id in the condition with a INSET to select the instancesof the requested page.

The code given below explains how to create the queries and handle the paging.

The following objects are available:

// The application element of AoMeasurement.

ApplicationElement ae

// The access object to ASAM ODS.

ApplElemAccess aea

The following constant is de�ned:

// The size of a page.

int pageSize = 50;

We use the following helper methods to create and initialize the query structure or parts of thequery structure.

public QueryStructureExt createQueryStructureExt() {

QueryStructureExt aoq = new QueryStructureExt();

aoq.anuSeq = new SelAIDNameUnitId[0];




aoq.joinSeq = new JoinDef[0];

return(aoq);

}

public SelAIDNameUnitId createSelAIDNameUnitId(T_LONGLONG aid, String aaName) {

return (createSelAIDNameUnitId(aid, aaName, AggrFunc.NONE));

}

public SelAIDNameUnitId createSelAIDNameUnitId(T_LONGLONG aid, String aaName, Agg

rFunc aggr) {

SelAIDNameUnitId ret = null;

ret = new SelAIDNameUnitId();

ret.attr = new AIDName(aid, aaName);

ret.unitId = new T_LONGLONG(0, 0);

ret.aggregate = aggr;

return (ret);

}

public SelValueExt createSelValueExt(T_LONGLONG aid, String aaName, SelOpcode ope

r) {

SelValueExt sel = new SelValueExt();

sel.attr = new AIDNameUnitId();

sel.attr.attr = new AIDName();


© 2015/08/19 Version 1.33




sel.attr.attr.aid = aid;

sel.attr.attr.aaName = aaName;

sel.attr.unitId = new T_LONGLONG(0, 0);

sel.oper = oper;

sel.value = new TS_Value();

sel.value.flag = 15;

sel.value.u = new TS_Union();

return (sel);

}

public T_LONGLONG[] getIdSequence(ResultSetExt[] res, T_LONGLONG aid, String aaId

Name) throws AoException {

T_LONGLONG ids[] = null;

if (res != null) {

if (res.length == 1) {

ids = getIdSequence(res[0].firstElems, aid, aaIdName);

}

}

return (ids);

}

public T_LONGLONG[] getIdSequence(ElemResultSetExt[] res, T_LONGLONG aid, String

aaIdName) throws AoException {

T_LONGLONG ids[] = null;

if (res != null) {

int noRes = res.length;

for (int resIndex = 0; resIndex < noRes && ids == null; resIndex++) {

if (res[resIndex].aid.low == aid.low) {

if (res[resIndex].values != null) {

int noAttr = res[resIndex].values.length;

for (int attrIndex = 0; attrIndex < noAttr; attrIndex++) {

if (aaIdName.compareTo(res[resIndex].values[attrIndex].valName)

== 0) {

ids = getIdSequence(res[resIndex].values[attrIndex].value.u)

;

}

}

}

}

}

}

return (ids);

}

public T_LONGLONG[] getIdSequence(TS_UnionSeq u) throws AoException {

int intSeq[] = null;

T_LONGLONG idSeq[] = null;

switch (u.discriminator().value()) {

case DataType._DT_LONG:

intSeq = u.longVal();

int no = intSeq.length;

idSeq = new T_LONGLONG[no];

for (int i = 0; i < no; i++) {

idSeq[i] = new T_LONGLONG(0, intSeq[i]);

}

break;

case DataType._DT_LONGLONG:

intSeq = null;

idSeq = u.longlongVal();

break;

}

return (idSeq);

}

The following code will load the Id values of the element.

// The Id of the application element


© 2015/08/19 Version 1.33




T_LONGLONG aid = ae.getId();

// Get the name of the Id attribute

ApplicationAttribute aaId = ae.getAttributeByBaseName("id");

String aaIdName = aaId.getName();

// Create an empty query.

aoq = createQueryStructureExt();

// Select only the Id so one attribute to select


aoq.anuSeq[0] = createSelAIDNameUnitId(aid, aaIdName);

// Get the name of the Name attribute

ApplicationAttribute aaName = ae.getAttributeByBaseName("name");

String aaNameName = aaName.getName();

// Order on the name.


aoq.orderBy[0] = new SelOrder(new AIDName(aid, aaNameName), true);

// Run the query 1 million of Ids is enough.

ResultSetExt[] res = aea.getInstancesExt(aoq, 1000000);

// Extract the Ids from the eesult set of the query.

T_LONGLONG[] ids = getIdSequence(res, aid, aaIdName);

Now we have the all Ids sorted by the name. With the following methods we can handle thepageing of the Ids.

T_LONGLONG[] getPage(T_LONGLONG[] ids, int pageNo) {

int limitMin = pageNo * pageSize;

int noInst = pageSize;

int limitMax = limitMin + noInst;

if (limitMax > ids.length) {

limitMax = ids.length;

noInst = limitMax - limitMin;

}

T_LONGLONG[] pageIds = new T_LONGLONG[noInst];

for (int j= limitMin; j < limitMax; j++) {

pageIds[j-limitMin] = ids[j];

}

return pageIds;

}

int getNumberOfPages(T_LONGLONG[] ids) {

int noPages = (ids.length / pageSize)+1;

return (noPages);

}

The following query can be used to select the id, name, description, measurement_begin andmeasurement_end of the instances of AoMeasurement ordered by the name for a page. For thepaging the conditon is an INSET of the Id's for the page, we prepare the condition.

QueryStructureExt aoqPage = createQueryStructureExt();

// Select of the based attributes id, name, description, measurement_begin and me

asurement_end

// which is 5 attributes.

aoqPage.anuSeq = new SelAIDNameUnitId[5];

// Set the selected attribute.

aoqPage.anuSeq[0] = createSelAIDNameUnitId(aid, aaIdName);

aoqPage.anuSeq[1] = createSelAIDNameUnitId(aid, aaNameName);

aoqPage.anuSeq[2] = createSelAIDNameUnitId(aid, ae.getAttributeByBaseName("descri

ption").getName());

aoqPage.anuSeq[3] = createSelAIDNameUnitId(aid, ae.getAttributeByBaseName("measur

ement_begin").getName());

aoqPage.anuSeq[4] = createSelAIDNameUnitId(aid, ae.getAttributeByBaseName("measur

ement_end").getName());

// There is one condition

aoqPage.condSeq = new SelItem[1];

aoqPage.condSeq[0] = new SelItem();

// Prepare the select value of the condition.

SelValueExt selValue = createSelValueExt(aid, aaIdName, SelOpcode.INSET);


© 2015/08/19 Version 1.33




The query for the paging is now prepared, the list of the Ids exist and we have methods to get theIds for a certain page from the list of the Ids. With the following code we can load the attributevalues for a certain page.

// Get the number of pages.

int noPages = getNumberOfPages(ids);

// Loop over all the pages, you can also select one of the pages.

for (int page = 0; page < noPages; page++) {

// Get the Ids for this page

T_LONGLONG[] pageIds = getPage(ids, page);

// Set the Ids in the select values of the condition.

selValue.value.u.longlongSeq(pageIds);

// Set the select value in the condition

aoqPage.condSeq[0].value(selValue);

// Perform the query.

ResultSetExt[]resPage = aea.getInstancesExt(aoqPage, pageSize);

// Show the page.

}

With this code snappers you can do the LIMIT operator or paging on the client with only keepingthe array with all Ids and two queries. When you like to sort on any other attribute you haveto change the attribute in orderBy of both queries. When you have a condition to reduce thenumber of instances in the pages you have to add this condition to the �rst query which loads theIds and the same query which loads the attributes will still work without any modi�cation.

5.3.8 Java Examples of ApplElemAccess


package api.methods.applelemaccess;














import api.methods.aosession.AoSessionExampleAbstract;

/** The examples of the methods of ApplElemAccess are all derived from this class */

public class ApplElemAccessExampleAbstract extends AoSessionExampleAbstract {

// The session

protected static AoSession aoSess=null;

protected static ApplicationStructureValue asv = null;

/**

* Get the appl elem access object

* @return the appl elem access.

* @throws AoException any occurring ASAM ODS exception.

*/

protected static ApplElemAccess getApplElemAccess() throws AoException {

if (aoSess == null) {

aoSess = connect();

}

return (aoSess.getApplElemAccess());

}


© 2015/08/19 Version 1.33




/**

* Get the application structure as a value.

* @return the application structure value.


*/

protected static ApplicationStructureValue getApplicationStructureValue() throws AoException {

if (asv == null) {


aoSess = connect();

}

asv = aoSess.getApplicationStructureValue();

}

return (asv);

}

/**

* Get application element Id of the element with the requested name.

* @param aeName the requested name of the element.

* @return the id of the element.


*/

protected static T_LONGLONG getAidByName(String aeName) throws AoException {

T_LONGLONG aid = null;

ApplicationStructureValue asv = getApplicationStructureValue();

for (int aeIndex = 0; aeIndex < asv.applElems.length && aid == null; aeIndex++) {

if (asv.applElems[aeIndex].aeName.compareTo(aeName)==0) {

aid = asv.applElems[aeIndex].aid;

}

}

return aid;

}

/**

* Get application element Id of the first element with the requested base type.

* @param beType the requested base type of the element.

* @return the id of the element.


*/

protected static T_LONGLONG getAidByBaseType(String beType) throws AoException {

T_LONGLONG aid = null;


for (int aeIndex = 0; aeIndex < asv.applElems.length && aid == null; aeIndex++) {

if (asv.applElems[aeIndex].beName.compareToIgnoreCase(beType)==0) {

aid = asv.applElems[aeIndex].aid;

}

}

return aid;

}

/**

* Get application attribute name of the attribute derived from the requested base attribute

* of element with the requested Id.

* @param aid the requested Id of the element.

* @param baName the requested base attribute name.

* @return the name of the attribute.


*/

protected static String getAttributeNameByBaseName(T_LONGLONG aid, String baName) throws AoException {

String aaName = null;


for (int aeIndex = 0; aeIndex < asv.applElems.length && aaName == null; aeIndex++) {

if ((asv.applElems[aeIndex].aid.low == aid.low) &&

(asv.applElems[aeIndex].aid.high == aid.high) ) {

for (int aaIndex = 0; aaIndex < asv.applElems[aeIndex].attributes.length; aaIndex ++) {

if (asv.applElems[aeIndex].attributes[aaIndex].baName!=null) {

if (asv.applElems[aeIndex].attributes[aaIndex].baName.compareToIgnoreCase(baName)==0) {

aaName = asv.applElems[aeIndex].attributes[aaIndex].aaName;


© 2015/08/19 Version 1.33




}

}

}

}

}

return aaName;

}

/**

* Get application relation name of the relation derived from the requested base relation

* of element with the requested Id.


* @param brName the requested base relation name.

* @return the name of the relation.


*/

protected static String getRelationNameByBaseName(T_LONGLONG aid, String brName) throws AoException {

String arName = null;


for (int aeIndex = 0; aeIndex < asv.applRels.length && arName == null; aeIndex++) {

if ((asv.applRels[aeIndex].elem1.low == aid.low) &&

(asv.applRels[aeIndex].elem1.high == aid.high) ) {

if (asv.applRels[aeIndex].brName != null) {

if (asv.applRels[aeIndex].brName.compareToIgnoreCase(brName) == 0) {

arName = asv.applRels[aeIndex].arName;

}

}

}

}

return arName;

}

/**

* Get application relation name of the relation between the two elements, use the

* relation name with the max relation range of 1, which is the relation attribute.

* The first found relation will be take.


* @param aidRel the id of the relation element.

* @return the name of the relation.


*/

protected static String getRelationName(T_LONGLONG aid, T_LONGLONG aidRel) throws AoException {

String arName = null;


for (int aeIndex = 0; aeIndex < asv.applRels.length && arName == null; aeIndex++) {

if ((asv.applRels[aeIndex].elem1.low == aid.low) &&

(asv.applRels[aeIndex].elem1.high == aid.high) ) {

if ((asv.applRels[aeIndex].elem2.low == aidRel.low) &&

(asv.applRels[aeIndex].elem2.high == aidRel.high) ) {

if (asv.applRels[aeIndex].arRelationRange.max==1) {

arName = asv.applRels[aeIndex].arName;

}

}

}

}

return arName;

}

/**

* Create a SelAIDNameUnitId structure to request for the values of the attribute

* with t he given name of the element with the given Id.

* @param aid the Id of the element.

* @param aaName the name of the attribute

* @return he created and initialized SelAIDNameUnitId

*/

protected static SelAIDNameUnitId createSelAIDNameUnitId(T_LONGLONG aid, String aaName) {

SelAIDNameUnitId ret = new SelAIDNameUnitId();


© 2015/08/19 Version 1.33




ret.aggregate = AggrFunc.NONE;

ret.attr = new AIDName(aid, aaName);

ret.unitId = new T_LONGLONG(0,0);

return ret;

}

/**

* Create an empty query structure ext.

* The fields of the query structure ext are all initialized otherwise

* a CORBA exception will be thrown when the structure has uninitialized

* field.

*

* @return the created and initialized query structure ext.

*/

protected static QueryStructureExt createQueryStructureExt() {







return (aoq);

}

/**

* Close the connection to the ODS Server


*/

protected static void close() throws AoException {

if (aoSess != null) {

aoSess.close();

aoSess = null;

}

}

/**

* Get the session.

* @return the session.


*/

protected static AoSession getSession() throws AoException {


aoSess = connect();

}

return(aoSess);

}

/**

* Get the Id's of the instances of the element with the given application element Id.

* @param aid the Id of the application element. Max 20 instances are returned.

* @return the list with the Id's.


*/

protected static T_LONGLONG[] getInstanceIds(T_LONGLONG aid) throws AoException {

ApplElemAccess aea = getApplElemAccess();

// Get the names of the attributes.

String aaIdName = getAttributeNameByBaseName(aid, "id");

QueryStructureExt aoq = createQueryStructureExt();



// Ask the server for the Ids of the element.


// Get the Ids from the result set.

// There is one element and one attribute requested.

// We do not check the fields of the structure and the

// datatype of the result.

T_LONGLONG[] ieIds = res[0].firstElems[0].values[0].value.u.longlongVal();

return (ieIds);


© 2015/08/19 Version 1.33




}

}

5.3.9 deleteInstances of interface ApplElemAccess

Purpose:

Delete instances from an application element. In case of inherited application elements theId of the super type has to be speci�ed.This method can be used to delete several instances of the same application element. Themethod removeInstance of the interface ApplicationElement to remove one instance of anapplication element with the children of the instance element.

Note

See also Transaction handling in ODS API. (p. 15).This method does not delete the children of the instances, this must be done by the client ex-plicit, however when the element is deirved from AoMeasurement the ATHOS implementationwill also delete the children of theinstances which are the instances AoMeasurementQuantity,AoSubMatrix, AoLocalColumn and AoExternalComponent and in case of ASAM ODS 5.3.0also AoFile. The client do not have to delete these children instances explcit, this behavouris not conform the ASAM ODS speci�cation but will improve the performance.

Return:

void

Parameter:

T_LONGLONG aid (in) The application element Id.

S_LONGLONG instIds (in) The sequence of instance Id's.


applElemAccess.deleteInstances(aid,instIds);

Java Example:








public class DeleteInstances extends ApplElemAccessExampleAbstract {

/**

* The main program. Example deletes some instances of the element Log.

* First a query is used to load the Ids of the instances, the first and

* last Id will be used for the example.

*


© 2015/08/19 Version 1.33





*/


try {

String aeName = "Log";

// Get the appl elem access


// Get the Id of the application element.

T_LONGLONG aid = getAidByName(aeName);





// Ask the server for the Ids of the element.









// Take the first and last Id of the list and remove these.

T_LONGLONG[] ieIdsToDelete = new T_LONGLONG[] {ieIds[0], ieIds[ieIds.length-1] };

// Delete the instances, which will work when there are no other

// Instance referencing the instances of this element which will be deleted.

aea.deleteInstances(aid, ieIdsToDelete);



System.out.println("The instances are deleted.");


close();

} catch (AoException ex) {

// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.performance.MeasurementPerfIT.deleteTimeMeasurementAEA()test.highqsoft.odsapi.performance.MeasurementPerfIT.deleteTimeMeasurementAthos()test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()test.highqsoft.odsapi.security.XQueryTest.testDeleteTest()....


© 2015/08/19 Version 1.33




5.3.10 getAttributeRights of interface ApplElemAccess

Purpose:

Retrieve access control list information for the given application attribute <aid>/<attr_-name>.

Note

See Usage of e�ective rights in ODS API. (p. 14)

Return:

ACLSequence aclEntries The access control list entries of the given application attribute.

Parameter:

T_LONGLONG aid (in) The Id of the application element.

T_STRING attrName (in) The name of the attribute.


ACL[] aclEntries = applElemAccess.getAttributeRights(aid,attrName);

Java Example:


import org.asam.ods.ACL;




public class GetAttributeRights extends ApplElemAccessExampleAbstract {

/**

* The main program. Example get the rights of the attribute

* derived from the base name "name" of the element derived from

* the base element with the type "AoTest".


*/


try {

// Get the appl elem access.


// Get the Id of the element

T_LONGLONG aid = getAidByBaseType("AoTest");

String aaIdName = getAttributeNameByBaseName(aid, "name");

ACL[] aclList = aea.getAttributeRights(aid, aaIdName);

if (aclList.length > 0) {

for (ACL acl : aclList) {

System.out.print("Right " + acl.rights);

// We expect there are less then 2 GB usergroups.

System.out.println(" for usegroup with id " + acl.usergroupId.low);

}

} else {

System.out.println("There are no rights defined from the attribute.");

}


close();


© 2015/08/19 Version 1.33





// Report the error



}

}

}

See also:

getRights of interface ApplicationAttribute

Errors:


Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()

5.3.11 getElementInitialRights of interface ApplElemAccess

Purpose:

Retrieve access control list information of the initial rights for the requested application ele-ment <aid>.

Return:

InitialRightSequence aclEntries The access control list entries of the given application elementfor the initial rights.

Parameter:



InitialRight[] aclEntries = applElemAccess.getElementInitialRights(aid);

Java Example:



// Get ApplElemAccess Interface


/* Get the all application elements. */

ApplicationElement aeList[] = as.getElements("*");

for (int aeIndex = 0; aeIndex < aeList.length; aeIndex++) {


© 2015/08/19 Version 1.33




InitialRight [] irSeq; // The Initial rights.

// Id of the application element.

T_LONGLONG aid = aeList[aeIndex].getId();

// Name of the application element

String aeName = aeList[aeIndex].getName();

// Get the access control list, using the ApplElemAccess

// alternative is

// irSeq = ae.getInitialRights();

irSeq = aea.getElementInitialRights(aid);

for (int irIndex = 0; irIndex < irSeq.length; irIndex++) {

System.out.println(

aeName +

irSeq[irIndex].usergroupId.low + ", " +

irSeq[irIndex].refAid.low + ", " +

irSeq[irIndex].rights);

}

}

See also:

getInitialRights of interface ApplicationElement

Errors:


Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.security.InitialRightsTest.testDeleteCreatedInstances()

5.3.12 getElementRights of interface ApplElemAccess

Purpose:

Retrieve access control list information for the requested application element <aid>.

Note


Return:

ACLSequence aclEntries The access control list entries of the given application element.

Parameter:



ACL[] aclEntries = applElemAccess.getElementRights(aid);


© 2015/08/19 Version 1.33




Java Example:






public class GetElementRights extends ApplElemAccessExampleAbstract {

/**

* The main program. Example get the rights of the element derived from

* the base element with the type "AoTest".


*/


try {





ACL[] aclList = aea.getElementRights(aid);






}

} else {

System.out.println("There are no rights defined from the element.");

}


close();


// Report the error



}

}

}

See also:

getRights of interface ApplicationElement

Errors:


Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()


© 2015/08/19 Version 1.33




5.3.13 getInitialRightReference of interface ApplElemAccess

Purpose:

Get all attribute names (references) which are used to retrieve the Initial Rights.

Return:

NameSequence refNameList The names of the references which will be used for the initialrights determination.

Parameter:



Name[] refNameList = applElemAccess.getInitialRightReference(aid);

Java Example:





public class GetInitialRightReference extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how the initial rights references

* of an element are loaded for the element derived from the

* base element with the type "AoMeasurement".

*


*/


try {



// Get the element Id

T_LONGLONG aid = getAidByBaseType("AoMeasurement");

String[] irRefNames = aea.getInitialRightReference(aid);

System.out.println("There are " + irRefNames.length + " initial right references.");

for (String refName : irRefNames) {

System.out.println("Initial right reference: " + refName);

}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEM


© 2015/08/19 Version 1.33




AO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.security.ApplModelCheckTest.testApplElemAccessgetInitialRightReference()

5.3.14 getInstanceInitialRights of interface ApplElemAccess

Purpose:

Retrieve access control list information of the initial rights for the requested instance<aid>/<iid>.

Return:

InitialRightSequence aclEntries The access control list entries of the given instance for theinitial rights.

Parameter:


T_LONGLONG iid (in) The Id of the instance.


InitialRights[] aclEntries = applElemAccess.getInstanceInitialRights(aid,iid);

Java Example:









// Id of the application element.

T_LONGLONG aid = aeList[aeIndex].getId();



// Get the instances of the application element, a query

// for only the Id of the instances using the ApplElemAccess

// interface, would do it also, but the query is harder to

// code and will blowup the example.

InstanceElement ieObj;

InstanceElementIterator iei = aeList[aeIndex].getInstances("*");

if (iei != null) {

do {


© 2015/08/19 Version 1.33




ieObj = iei.nextOne();

if (ieObj != null) {

// Id of the instance,

T_LONGLONG iid = ieObj.getId();

// Get the access control list, using the

// ApplElemAccess interface alternative is

// irSeq = ieObj.getInitialRights();

irSeq = aea.getInstanceInitialRights(aid, iid);

for (int irIndex = 0;

irIndex < irSeq.length;

irIndex++) {

System.out.println(aeName + ", " + iid.low + ", " +




}

// Destroy the instance element, the object is not

// used anymore at the client.

ieObj.destroy();

}

} while (ieObj != null);

// Destroy the instance iterator, the object is not


iei.destroy();

}

} // for all application elements.

Errors:


Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.security.InitialRightsTest.testDeleteCreatedInstances()

5.3.15 getInstanceRights of interface ApplElemAccess

Purpose:

Retrieve access control list information for the requested instance <aid>/<iid>.

Note


Return:

ACLSequence aclEntries The access control list entries of the given instance.

Parameter:


T_LONGLONG iid (in) The Id of the instance.


© 2015/08/19 Version 1.33





ACL[] aclEntries = applElemAccess.getInstanceRights(aid,iid);

Java Example:






public class GetInstanceRights extends ApplElemAccessExampleAbstract {

/**

* The main program. Example get the rights of the instances of the

* element derived from the base element with the type "AoTest".

*

* @param args

* not used.

*/


try {





// Get the Id's of the instance of the AoTest element.

T_LONGLONG[] ieIds = getInstanceIds(aid);

for (T_LONGLONG ieId : ieIds) {

// We expect the Id's are less then 2 Gbyte.

System.out.println("Handle instance with Id " + ieId.low);

ACL[] aclList = aea.getInstanceRights(aid, ieId);



System.out.print("\tRight " + acl.rights);



}

} else {

System.out.println("\tThere are no rights defined from the element.");

}

}


close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()test.highqsoft.odsapi.security.InitialRightsTest.testDeleteCreatedInstances()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()

5.3.16 getInstances of interface ApplElemAccess

Purpose:

Perform the Query.The number of di�erent application elements which are requested are exactly de�ned by thede�nition of the query given in the substructure anuSeq of QueryStructure. The number ofattributes for each application element is also given in the de�nition. The number of matchinginstances (their attributes) is not de�ned by the query and can be a large amount. Thereforeonly one iterator for the attribute values are de�ned.The values of the localcolumn instances is part of the resultset when the following criteria all�t:- Only when the attributes id, generation_parameters, values, �ags are requested (as soon asany other attributes are requested the values are not reported).- The values of the localcolumn must all belong to exactly one instance of AoMeasurement- The result set does not exceed the server memory limitation. An ASAM ODS server has amemory limitation (not the system memory limitation); as soon as the result set breaks thislimitation an exception will be thrown.- No iterator for the rest is required.In case an attribute of blob type is among the requested attributes, the content of the returnstructure will depend on the number of instances that are returned:- In case attributes of only one instance are returned (either because 'how_many' was set to1 or there is only one instance available at the server), the return structure contains the blobitself.-In case attributes of more than one instance are returned, the return structure does notcontain the blobs; instead it contains the headers of the respective blobs.

Note

Use the context or INI-File variable REPORT_SEQUENCE_ATTRIBUTES to get also theattributes with sequence datatypes. Read of the values of the localcolumn instances only forthe same datatype in one call. The generation_parameters and �ags (both with sequencedatatypes) will be reported when the id and values of the localcoumns are also requested.The request of the Id of the localcolumns is always required otherwise the implementationis not able to link the values to an instance of localcolumn and can not load the values ofthat instances and an error of Oracle will occure. The length of an attribute with datatypeDT_BYTESTR is restricted to 20000 bytes, use the method InstanceElement_GetValue toread DT_BYTESTR with more then 20000 bytes.

The parameter how_many overrides the INI-File variable SQL_MAX_ROWS . The value ofhow_many is restricted to 2000000 (hard code). When a value given is bigger then this restriction,SQL_MAX_ROWS will be used.

Return:

ElemResultSetSequence elemResultSet The result set with the requested attribute values.


© 2015/08/19 Version 1.33




Parameter:

QueryStructure aoq (in) The query de�nition.

T_LONG how_many (in) Maximum number of values in each result set. Valid argumentsare:how_many = 0 : report all found values,how_many > 0 : report a maximum number of values.


ElemResultSet[] elemResultSet = applElemAccess.getInstances(aoq,how_many);

Java Example:




import org.asam.ods.AIDNameValueUnitId;



import org.asam.ods.AttrResultSet;

import org.asam.ods.DataType;


import org.asam.ods.ElemResultSet;

import org.asam.ods.QueryStructure;




import org.asam.ods.SelValue;




public class GetInstances extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how the Id and Name of the

* instances of the element derived from AoTest with the name

* starts with an A are requested from the server. The values are sorted

* by the name.

*


*/


try {







String aaNameName = getAttributeNameByBaseName(aid, "name");

QueryStructure aoq = new QueryStructure();

// We ask for the values of two attribute.

// No special unit to report are required.

aoq.anuSeq = new AIDNameUnitId[2];

aoq.anuSeq[0] = new AIDNameUnitId(new AIDName(aid, aaIdName), new T_LONGLONG(0,0));

aoq.anuSeq[1] = new AIDNameUnitId(new AIDName(aid, aaNameName), new T_LONGLONG(0,0));

// The condition is the name start with "A"


aoq.condSeq[0] = new SelValue();


© 2015/08/19 Version 1.33




// Set the attribute in the condition

aoq.condSeq[0].attr = new AIDNameValueUnitId();

aoq.condSeq[0].attr.attr = new AIDName(aid, aaNameName);

// The unitId and the TS_Value are not need but must be initialized.

aoq.condSeq[0].attr.unitId = new T_LONGLONG(0,0);

aoq.condSeq[0].attr.values = new TS_Value();

aoq.condSeq[0].attr.values.u = new TS_Union();

aoq.condSeq[0].attr.values.u.longVal(0);

aoq.condSeq[0].attr.values.flag =0;

// Set the condition

aoq.condSeq[0].oper = SelOpcode.LIKE;

// Set the value

aoq.condSeq[0].value = new TS_Value();

aoq.condSeq[0].value.flag = (short) 15;

aoq.condSeq[0].value.u = new TS_Union();

aoq.condSeq[0].value.u.stringVal("A*"); // Pattern is *

// There is only one condition so we do not need the operSeq,

// but it must be initialized.


// The order sequence.


aoq.orderBy[0] = new SelOrder(new AIDName(aid,aaNameName), true);

// There is no related instance but the fields must be initialized.

aoq.relInst = new ElemId(new T_LONGLONG(0,0), new T_LONGLONG(0,0));

aoq.relName = "";

// Ask the server for the Id and names of the element.

ElemResultSet[] res = aea.getInstances(aoq, 0);

/*

* The results of the query is given in array of values for each attribute.

* The index in the array of the values of the different attributes are the

* values the attributes of an instance.

*/

if (res != null) {

for (ElemResultSet er : res) {

System.out.println("The results of the element with the Id: " + er.aid.low);

// We know, we have asked for the Id and the Name so we load the attribute

// values from the result set. Id and Name are both required attributes so

// we can ignore the flags.

T_LONGLONG[] ieIds=null;

String[] ieNames=null;

for (AttrResultSet ars : er.attrValues) {

if (ars.attrValues.valName.compareTo(aaIdName)==0) {

// Found the Id attribute, read the values.

if (ars.attrValues.value.u.discriminator().value()==DataType._DT_LONGLONG) {

ieIds = ars.attrValues.value.u.longlongVal();

} else {

System.out.println("Unexpected datatype for Id");

}

}

if (ars.attrValues.valName.compareTo(aaNameName)==0) {

// Found the Id attribute, read the values.

if (ars.attrValues.value.u.discriminator().value()==DataType._DT_STRING) {

ieNames = ars.attrValues.value.u.stringVal();

} else {

System.out.println("Unexpected datatype for Name");

}

}

}

if ((ieIds != null) && (ieNames != null)) {

// The Length of the Ids and Names must be identical

if (ieIds.length == ieNames.length) {

for (int i = 0; i < ieIds.length; i++) {

// The values of the elements in the arrays with the same

// index belongs to the same instance element.

System.out.println("Instance with name " + ieNames[i] + " has the Id " + ieIds[i].low);

}

} else {


© 2015/08/19 Version 1.33




System.out.println("Error the length of the results must be identical");

}

} else {

System.out.println("Error at least one of the requested attributes not in the result set.");

}

}

}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testCheckRelLccMeq()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelationApplElemAccess()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesValueQuery()test.highqsoft.avalon.InstanceElementTestCase.queryIds()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()....

5.3.17 getInstancesExt of interface ApplElemAccess

Purpose:

Perform the Query. This method can be used for a more powerful query compared to themethod getInstances of this interface, with join de�nitions and aggregate functions.The number of di�erent application elements which are requested are exactly de�ned by thede�nition of the query given in the �eld anuSeq of the QueryStructureExt. The number ofattributes for each application element is also given in the de�nition. The number of matchinginstances (their attributes) is not de�ned by the query and can be a large amount. Thereforeonly one iterator for the attribute values is de�ned.The return is a sequence of the structure ResultSetExt . This sequence will always have thelength of 1. Thiselement in the structure has two �elds- �rstElems of type ElemResultSetExtSequence- restElems of type ElemResultSetExtSeqIterator�rstElemsThe �rstElems is a sequence of ElemResultSetExt, the length of the sequence correspondswith the number of di�erent application elements requested in the anuSeq of the QueryStruc-trueExt. The structure ElemResultSetExt has the �elds aid and values. The aid is the Id ofthe application element, the values, a sequence of the structure NameValueSeqUnitId are thevalues of the attributes. For each reported attribute an entry is given in the sequence, the


© 2015/08/19 Version 1.33




name of the attribute is given in the �eld valName. The Id of the unit is given in the �eldunitId, this is the Id of the instance of the application element derived from the base elementAoUnit. The values are given in the �eld value with the type TS_ValueSeq. Each valuesequence has the same length, this length is less or equal to maximum how_many (the pa-rameter of the method). If no values are found the length of the sequence is 0. The values withthe same index in the di�erent sequences of the entry in the NameValueSeqUnitIdSequencebelong to the same instance element.restElemsThe restElems is an iterator for the remaining sequence of ElemResultSetExt. This iteratorallows to load the next N values from the ResultSet. The result of the element is stored thesame way as at the �rstElems, the next N is the length of the sequence of the �eld value ofthe NameValueSeqUnitId. The method nextOne is wrong speci�ed and should not be used,use instead the method nextN with n=1. The method getCount returns the total number ofelements found, the number already returned in �rstElems. The method reset set the iteratorthe beginning of the ResultSet, this is the beginning of the �rstElems.The values of the localcolumn instances are part of the resultset when the following criteriaall �t:- Only when the attributes id, generation_parameters, values, �ags are requested, as soon asany other attributes is requested the values are not reported.- The values of the localcolumn must all belong to exactly one instances of AoMeasurement- The server have a limitation of the memory, not the system memory limitation, as soon asthe result set will break the limitation an exception will be thrown.- No iterator for the rest is required.In case an attribute of blob type is among the requested attributes, the content of the returnstructure will depend on the number of instances that are returned:- In case attributes of only one instance are returned (either because 'how_many' was set to1 or there is only one instance available at the server), the return structure contains the blobitself.- In case attributes of more than one instance are returned, the return structure does notcontain the blobs; instead it contains the headers of the respective blobs.The value of valName of query result values shall be the aaName in case AggrFunc='NONE'and shall be constructed for all other AggrFunc values as string concatenation of the AggrFuncvalue followed by a '(' character, followed by the name of attribute (aaName) followed by a')' character.

Note

Read of the values of the localcolumn instances only for the same datatype in one call. Therequest of the Id of the localcolumns is always required otherwise the implementation is notable to link the values to an instance of localcolumn and can not load the values of thatinstances and an error of Oracle will occure. The length of an attribute with datatype DT_-BYTESTR is restricted to 20000 bytes, use the method InstanceElement_GetValue to readDT_BYTESTR with more then 20000 bytes.

The parameter how_many overrides the INI-File variable SQL_MAX_ROWS . The value ofhow_many is restricted to 2000000 (hard code). When a value given is bigger then this restriction,SQL_MAX_ROWS will be used.

Return:

ResultSetExtSequence resultSet The result set with the requested attribute values.

Parameter:

QueryStructureExt aoq (in) The query de�nition.


© 2015/08/19 Version 1.33




T_LONG how_many (in) Maximum number of values in each result set. Valid argumentsare:how_many = 0 : report all found values,how_many > 0 : report a maximum number of values.


ResultSetExt[] resultSet = applElemAccess.getInstancesExt(aoq,how_many);

Java Example:







import org.asam.ods.ElemResultSetExt;


import org.asam.ods.JoinType;

import org.asam.ods.NameValueSeqUnitId;








import org.asam.ods.SelValueExt;




public class GetInstancesExt extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how to use the extended query.

* The name of the Units ad the number of Quantities which use the unit

* are requested with one query. The condition is the Name of the unit

* starting with "k" (case blind) or the factor == 1.0, because comparing

* floating point numbers on an exact value is always risky we compare the

* factor between 0.95 and 1.05. We order the result by the name of the Unit.

* We like also the units which have no quantities so an outer join is required.

* We have to group the counts of the quantities for the name of the unit.

*


*/


try {



// Get the Id of the AoUnit and AoQuantity element

T_LONGLONG aidUnit = getAidByBaseType("AoUnit");

T_LONGLONG aidQty = getAidByBaseType("AoQuantity");


String aaNameName = getAttributeNameByBaseName(aidUnit, "name");

String aaFactorName = getAttributeNameByBaseName(aidUnit, "factor");

String arQtyUnitName = getRelationNameByBaseName(aidQty, "default_unit");


// We ask for the values of two attribute.

// First is the Name of the Unit, second is the count of the

// relational attribute from AoQuantity to AoUnit.



© 2015/08/19 Version 1.33




aoq.anuSeq[0] = new SelAIDNameUnitId();

aoq.anuSeq[0].aggregate= AggrFunc.NONE;

aoq.anuSeq[0].attr = new AIDName(aidUnit, aaNameName);

aoq.anuSeq[0].unitId = new T_LONGLONG(0,0);

// Here we show a relation attribute can also be used as attribute to select,

// It can also be used as a condition attribute.

aoq.anuSeq[1] = new SelAIDNameUnitId();

aoq.anuSeq[1].aggregate = AggrFunc.COUNT;

aoq.anuSeq[1].attr = new AIDName(aidQty, arQtyUnitName);

aoq.anuSeq[1].unitId = new T_LONGLONG(0,0);

// The condition is the name start with "S" or factor between (0.95 and 1.05)

// This are 3 conditions

// 1. unit.name CI_LIKE S* (SelValueExt)

// 2. OR (SelOperator)

// 3. factor between (0.95 and 1.05) (SelValueExt)



// Create the first condition, all field must be initialized.

SelValueExt selName = new SelValueExt();

// The attribute of the condition

selName.attr = new AIDNameUnitId();

selName.attr.attr = new AIDName(aidUnit, aaNameName);

selName.attr.unitId = new T_LONGLONG(0,0); // No special unit

selName.oper = SelOpcode.CI_LIKE;

selName.value = new TS_Value();

selName.value.flag = 15;

selName.value.u = new TS_Union();

selName.value.u.stringVal("k*");

aoq.condSeq[0].value(selName);

// Create the second condition,


aoq.condSeq[1]._operator(SelOperator.OR);

// Create the third condition, all field must be initialized.


SelValueExt selFactor = new SelValueExt();

// The attribute of the condition

selFactor.attr = new AIDNameUnitId();

selFactor.attr.attr = new AIDName(aidUnit, aaFactorName);

selFactor.attr.unitId = new T_LONGLONG(0,0); // No special unit

selFactor.oper = SelOpcode.BETWEEN;

selFactor.value = new TS_Value();

selFactor.value.flag = 15;

selFactor.value.u = new TS_Union();

// Set the value of the condition, BETWEEN has two values

// so a sequence of values must be set.

selFactor.value.u.doubleSeq(new double[] { 0.95, 1.05} );

aoq.condSeq[2].value(selFactor);

// The order sequence.


aoq.orderBy[0] = new SelOrder(new AIDName(aidUnit,aaNameName), true);

// The outer join from AoUnit to AoQuantity


aoq.joinSeq[0] = new JoinDef();

aoq.joinSeq[0].fromAID = aidUnit;

aoq.joinSeq[0].toAID = aidQty;

aoq.joinSeq[0].joiningType = JoinType.JTOUTER;

aoq.joinSeq[0].refName = arQtyUnitName;

// Group the results by the name of the unit.


aoq.groupBy[0] = new AIDName(aidUnit, aaNameName);

// Ask the server for the Id and names of the element.


/*


© 2015/08/19 Version 1.33




* The results of the query is given in array of values for each attribute.

* The index in the array of the values of the different attributes are the

* values the attributes of an instance.

*/

if (res != null) {

String[] unitNames=null;

int[] quantityCounts=null;

for (ResultSetExt er : res) {

if (er.firstElems != null) {

for (ElemResultSetExt ers: er.firstElems) {

System.out.println("The results of the element with the Id: " + ers.aid.low);

if ((ers.aid.low == aidUnit.low) && (ers.aid.high== aidUnit.high)) {

// The element is the unit.

for (NameValueSeqUnitId attrVal : ers.values) {

// Compare the valName with the attribute name.

if (attrVal.valName.compareTo(aaNameName)==0) {

unitNames = attrVal.value.u.stringVal();

}

}

}

if ((ers.aid.low == aidQty.low) && (ers.aid.high== aidQty.high)) {

// The element is the quantity.

for (NameValueSeqUnitId attrVal : ers.values) {

// The Aggregate function is part the valName so search

// that the relation name is in the valName.

if (attrVal.valName.contains(arQtyUnitName)) {

// Count is always integer so get the longVal.

quantityCounts = attrVal.value.u.longVal();

}

}

}

}

}

}

if ((unitNames!=null) && (quantityCounts!=null)) {

if (unitNames.length == quantityCounts.length) {

for (int i = 0; i < unitNames.length; i++) {

System.out.print("Unit " + unitNames[i]);

System.out.println(" is used by " + quantityCounts[i] + " quantities.");

}

} else {

System.out.println("Error length is not identical.");

}

} else {

System.out.println("Error one of the requested attributes is not found.");

}

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.0

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTED


© 2015/08/19 Version 1.33




AO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.DescElemQueryTestIT.testQueryChildren()test.highqsoft.avalon.ExtQueryTestIT.main()test.highqsoft.avalon.ExtQueryTestIT.runNoResultExt()test.highqsoft.avalon.ExtQueryTestIT.runQueryExtAoAny()test.highqsoft.avalon.ExtQueryTestIT.runSimpleQueryExt()....

5.3.18 getODSFile of interface ApplElemAccess

Purpose:

Get the ODSFile interface for an instance of an application element derived from AoFile.This method returns an ODSFile interface.One parameter controls the behavior of this method:The value of the parameter 'elem' (with its components 'aid' and 'iid') uniquely identi�esan instance within the ODS storage. If no such instance exists, or if the instance is notan instance of an application element derived from AoFile, the exceptionAO_INVALID_BASETYPE is thrown.Note that an ODS server may be set up to support the ODS security concepts and that insuch case access to a �le is only allowed if the access rights of the accessing user aresu�cient. If the user does not have at least READ rights for the instance speci�ed by'elem' an exception AO_ACCESS_DENIED will be thrown.

Return:

ODSFile odsFile The ODSFile interface to access the desired �le.

Parameter:

ElemId elem (in) The instance to which the �le belongs, whose access is intended.

Java Example:





import org.asam.ods.ODSFile;





public class GetODSFile extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how to get the ODS File interface for the

* managed files.

*


*/


© 2015/08/19 Version 1.33





try {




T_LONGLONG aid = getAidByBaseType("AoFile");

if (aid != null) {






// Ask the server for the Ids of the element (restricted to 20 instances).










ODSFile odsFile = aea.getODSFile(new ElemId(aid, ieId));

if (odsFile != null) {

System.out.println("We have the ODS File interface.");

// Destroy the ODSFile to cleanup the POA map.

odsFile.destroy();

}

}

} else {

System.out.println("There is no element derived from AoFile.");

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:

AO_BAD_PARAMETERAO_INVALID_BASETYPEAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_ACCESS_DENIED

Tested by:

test.highqsoft.odsapi.ods530.DeleteAoFileTest.testInstanceDeleteFileAbort()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()


© 2015/08/19 Version 1.33




5.3.19 getRelInst of interface ApplElemAccess

Purpose:

Get related instances (Id). This method returns a sequence of related instances.The relation name speci�es the relation given in the ApplStructValue. The aid of the ElemIdand the relName de�nes the unique relation and the target application element.

Return:

S_LONGLONG instIds The list of the Ids of the related instances.

Parameter:

ElemId elem (in) Original instance.

Name relName (in) The relation name.


T_LONGLONG[] instIds = applElemAccess.getRelInst(elem,relName);

Java Example:






public class GetRelInst extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how related instances can be required

* for a N:M Relation. The relation from AoUser to AoUserGroup will be used

* in the example.

*


*/


try {




T_LONGLONG aidUser = getAidByBaseType("AoUser");

String relName = getRelationNameByBaseName(aidUser, "groups");

// Get the Id's of the instance of the AoUser element.

T_LONGLONG[] ieIds = getInstanceIds(aidUser);



System.out.println("Handle instance of User with Id " + ieId.low);

T_LONGLONG[] ieUsergroupIds = aea.getRelInst(new ElemId(aidUser, ieId), relName);

if (ieUsergroupIds.length > 0) {

for (T_LONGLONG ieUsergroupId : ieUsergroupIds) {

System.out.println(" in usegroup with id " + ieUsergroupId.low);

}

} else {

System.out.println("\t is in none usergroups.");

}

}


© 2015/08/19 Version 1.33





close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelationApplElemAccess()test.highqsoft.avalon.MultiSessionTestIT.threadInstancesRelationApplElemAccess.threadInstancesRelationApplElemAccess()test.highqsoft.avalon.ValueMatrixUnitTestIT.threadHandleColumn.threadHandleColumn()test.highqsoft.odsapi.ford.FordTest.testCreateManagementData()test.highqsoft.odsapi.read.InstanceRelationTest.testGetRelationInstances()....

5.3.20 getRelInst of interface ApplElemAccess

Purpose:

Get related instances (Id). This method returns a sequence of related instances.The relation name speci�es the relation given in the ApplStructValue. The aid of the ElemIdand the relName de�nes the unique relation and the target application element.

Return:

S_LONGLONG instIds The list of the Ids of the related instances.

Parameter:

ElemId elem (in) Original instance.

Name relName (in) The relation name.


T_LONGLONG[] instIds = applElemAccess.getRelInst(elem,relName);


© 2015/08/19 Version 1.33




Java Example:






public class GetRelInst extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how related instances can be required


* in the example.

*


*/


try {










System.out.println("Handle instance of User with Id " + ieId.low);

T_LONGLONG[] ieUsergroupIds = aea.getRelInst(new ElemId(aidUser, ieId), relName);

if (ieUsergroupIds.length > 0) {

for (T_LONGLONG ieUsergroupId : ieUsergroupIds) {

System.out.println(" in usegroup with id " + ieUsergroupId.low);

}

} else {

System.out.println("\t is in none usergroups.");

}

}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelationApplElemAccess()test.highqsoft.avalon.MultiSessionTestIT.threadInstancesRelationApplElemAccess.threadInstancesRelationApplElemAccess()test.highqsoft.avalon.ValueMatrixUnitTestIT.threadHandleColumn.threadHandleColumn()test.highqsoft.odsapi.ford.FordTest.testCreateManagementData()test.highqsoft.odsapi.read.InstanceRelationTest.testGetRelationInstances()


© 2015/08/19 Version 1.33




....

5.3.21 getValueMatrix of interface ApplElemAccess

Purpose:

Get the value matrix of a measurement or a submatrix. If the value matrix will be built upwith special submatrix link, use the interface Measurement.By calling this method, the value matrix mode of the returned value matrix will be taken fromthe context variable 'VALUEMATRIX_MODE'. For more information especially on di�erentmodes of the value matrix, see description at the method getValueMatrixInMode() of theinterfaces 'Measurement' and 'SubMatrix'.

Return:

ValueMatrix vm The value matrix

Parameter:

ElemId elem (in) The element id. The aid has to be the application element Id of the AoMea-surement or AoSubmatrix.


ValueMatrix vm = applElemAccess.getValueMatrix(elem);

Java Example:






import org.asam.ods.ValueMatrix;

public class GetValueMatrix extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how to get the valuematrix from an instance

* of the submatrix.

*


*/


try {




T_LONGLONG aidSm = getAidByBaseType("AoSubMatrix");

// Get the Id's of the instance of the AoSubMatrix element.

T_LONGLONG[] ieIds = getInstanceIds(aidSm);




ValueMatrix vm = aea.getValueMatrix(new ElemId(aidSm, ieId));

if (vm != null) {

System.out.println("We have the valuematrix.");

// Destroy the valuematrix to cleanup the POA map.


© 2015/08/19 Version 1.33




vm.destroy();

}

}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_INVALID_BASETYPE

Tested by:

test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()test.highqsoft.odsapi.ods530.ReadVmAUDITest.main()test.highqsoft.odsapi.performance.MeasurementPerfIT.readTimeMeasurementValueMatrix()test.highqsoft.odsapi.performance.MeasurementPerfIT.testCreateMeasurement()test.highqsoft.odsapi.read.ApplElemAccessTest.testGetValueMatrix()....

5.3.22 getValueMatrixInMode of interface ApplElemAccess

Purpose:

Get the value matrix of a measurement or a submatrix. If the value matrix will be built upwith special submatrix link, use the interface Measurement.The behavior of the ASAM ODS server depends on whether the referenced element is asubmatrix or a measurement. For more information on the server behavior see description atthe method getValueMatrixInMode() of the interfaces 'Measurement' and 'SubMatrix'.

Return:

ValueMatrix vm The value matrix.

Parameter:

ElemId elem (in) The element id. The aid has to be the application element Id of the AoMea-surement or AoSubmatrix.

ValueMatrixMode vmMode (in) The requested mode of the value matrix.


ValueMatrix vm = measurement.getValueMatrix();


© 2015/08/19 Version 1.33




Java Example:







import org.asam.ods.ValueMatrixMode;

public class GetValueMatrixInMode extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how to get the valuematrix from an instance

* of the submatrix. Get the valuematrix in the mode STORAGE, teh defualt mode

* of avalon is CALCULATED.

*


*/


try {




T_LONGLONG aidSm = getAidByBaseType("AoSubMatrix");

// Get the Id's of the instance of the AoSubMatrix element.

T_LONGLONG[] ieIds = getInstanceIds(aidSm);




ValueMatrix vm = aea.getValueMatrixInMode(new ElemId(aidSm, ieId), ValueMatrixMode.STORAGE);

if (vm != null) {

System.out.println("We have the valuematrix.");

// Destroy the valuematrix to cleanup the POA map.

vm.destroy();

}

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.2

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_INVALID_BASETYPEAO_INVALID_VALUEMATRIX_STRUCTURE


© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.avalon.ValueMatrixCreateTestIT.testCreateValueMatrixFromSmSelectMea()test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()test.highqsoft.odsapi.ods530.MeasurementFileTest.testCountFile()test.highqsoft.odsapi.performance.ValueMatrixPerfIT.testReadManyVmCount()....

5.3.23 insertInstances of interface ApplElemAccess

Purpose:

Create instance elements of an application element.The application element is speci�ed by the AID of input structure.The attribute names are speci�ed by the name of the input structure.The values of one instance element are speci�ed in the valueseq of the input structure.You can create several instance elements in one call by �lling the valueseq of the input struc-ture.The same index in the valueseq corresponds to the attributes values of one instance element.This method returns a sequence of Id's, the order is related to the order of instance elementspeci�ed in the input structure. In case of inheritance, the method supports only instancesof same subtype per call. The returned Id's are the Id's of the related super type instances.The client must supply all mandatory attributes and references within one single method call;otherwise the object cannot be made persistent by the server in the database without the riskof violating any database constraint.

Note

See also Transaction handling in ODS API. (p. 15) Insert of the based attributes val-ues, �ags and generation_parameters of the AoLocalColumn element will not work with thismethod use updateInstances of interface ApplElemAccess (p. 143). When the attributederived from the base attribute "id" is inserted an AoException is thrown for the databasetranslators. With the INI-File variable IGNORE_INSERT_ID no exception will be thrown.

Return:

ElemIdSequence elemIds List with the Id's of the new created instances.

Parameter:

AIDNameValueSeqUnitIdSequence val (in) The sequence of attributes and their values.


ElemIdSequence elemIds = applElemAccess.insertInstances(val);

Java Example:


import java.text.SimpleDateFormat;

import java.util.Date;



© 2015/08/19 Version 1.33




import org.asam.ods.AIDNameValueSeqUnitId;





import org.asam.ods.TS_UnionSeq;

import org.asam.ods.TS_ValueSeq;


public class InsertInstances extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how instances of a AoLog element

* related to the AoTest element get instances with the related instances

* of AoTest.

*


*/


try {




T_LONGLONG aidTest = getAidByBaseType("AoTest");

T_LONGLONG aidLog = getAidByBaseType("AoLog");

// Get the relation from AoLog to AoTest

String relName = getRelationName(aidLog, aidTest);

// Check the relation is in the model.

if (relName != null) {


T_LONGLONG[] ieIds = getInstanceIds(aidTest);

// We write for each found instance of AoTest an new instance of Log.

// The number of instances (values in the sequence) have no restriction.

int noInst = ieIds.length;

// Prepare the flags of the attribute values.

short[] flags = new short[noInst];


flags[i] = 15; // The attribute value is valid.

}

// We write the name and date of the instances of AoLog, this are the

// mandatory attributes, and also the relation to AoTest

String aaNameName = getAttributeNameByBaseName(aidLog, "name");

String aaDateName = getAttributeNameByBaseName(aidLog, "date");

// So we have to write 3 attributes

// The number of attributes have no restriction

AIDNameValueSeqUnitId[] vals = new AIDNameValueSeqUnitId[3];

// Write the names

vals[0] = new AIDNameValueSeqUnitId();

// Set the element and attribute for which the values are inserted.

vals[0].attr = new AIDName(aidLog, aaNameName);

// There is no special unit.

vals[0].unitId = new T_LONGLONG(0,0);

// Prepare the structure for the values of the attribute.

vals[0].values = new TS_ValueSeq();

vals[0].values.flag = flags;

vals[0].values.u = new TS_UnionSeq();

// Create the name of the instances.

String[] names = new String[noInst];


names[i] = "ExampleName"+i;

}

// Set the names.

vals[0].values.u.stringVal(names);

// Write the Dates




© 2015/08/19 Version 1.33




vals[1].attr = new AIDName(aidLog, aaDateName);







SimpleDateFormat formatter = new SimpleDateFormat(ODS_DATE_FORMAT);

String date = formatter.format(new Date());

// Create the dates of the instances all get the same date.

String[] dates = new String[noInst];


dates[i] = date;

}

// Set the dates.

vals[1].values.u.stringVal(dates);

// Write the relation to AoTest



vals[2].attr = new AIDName(aidLog, relName);







vals[2].values.u.longlongVal(ieIds);

// we have now created the sequence with attribute value sequences.

// The index in the attribute value sequence will come to be the

// attribute values of an instance.

// Write the instances in a transaction

AoSession aoSess = getSession();

try {



// Insert the new instances.

ElemId[] newInsts = aea.insertInstances(vals);




System.out.println("Instance with Id " + newInsts[i].iid.low + " with name " + names[i]

+ " is created");

}


// Report the error

System.err.println("AoException: error code = " + ex.errCode.value()

+ " and reason : " + ex.reason);



}

}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOST


© 2015/08/19 Version 1.33




AO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.CheckNotNullConstraintTest.testChangeLengthNotNullAttr()test.highqsoft.odsapi.ford.FordMesaurementTest.testCreateMeasurementDoubleLc()test.highqsoft.odsapi.ford.FordSeq1Test.testCreateFordElements()test.highqsoft.odsapi.ford.FordSeq2Test.testCreateFordElements()test.highqsoft.odsapi.ford.FordSeq3Test.testCreateFordElements()....

5.3.24 setAttributeRights of interface ApplElemAccess

Purpose:

Set the ACL information on some application element-attribute de�ned by<aid> and<attr_-name>. The <usergroup_id> de�nes the user group the rights should be set for. <rights>de�nes the rights to set or to clear. If the parameter <set> is set to 'set', the rights in<rights> are set all others are cleared. If the parameter <set> is set to 'add', the rightsin <rights> are added to the existing rights. If the parameter <set> is set to 'remove', therights in <rights> are removed from the existing rights. Restriction for the model: only oneapplication element of the type AoUserGroup is allowed.

Note

See also Transaction handling in ODS API. (p. 15)

Return:

void

Parameter:


T_STRING attrName (in) The name of the attribute.

T_LONGLONG usergroupId (in) The user group to set the rights for.

T_LONG rights (in) The new right for the user group.

RightsSet set (in) What to do with the new right.


applElemAccess.setAttributeRights(aid,attrName,usergroupId,rights,set);


© 2015/08/19 Version 1.33




Java Example:





import org.asam.ods.RightsSet;

import org.asam.ods.SecurityRights;


public class SetAttributeRights extends ApplElemAccessExampleAbstract {

/**

* The main program. Example set the rights of the attribute

* derived from the base name "name" of the element derived from

* the base element with the type "AoTest". The first usergroup get

* the GRANT and DELETE right.


*/


try {





T_LONGLONG aidUsg = getAidByBaseType("AoUserGroup");

String aaIdName = getAttributeNameByBaseName(aid, "name");

T_LONGLONG[] userGroupIds = getInstanceIds(aidUsg);

int rights = SecurityRights.SEC_GRANT | SecurityRights.SEC_DELETE;

// Update the instances in a transaction


try {



// Add the right for usergroup

aea.setAttributeRights(aid, aaIdName, userGroupIds[0], rights, RightsSet.ADD_RIGHT);



System.out.println("The right is added.");


// Report the error




}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE


© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.security.InstanceAttributeCheckTest.testCreateElementAttributeSecurity()

5.3.25 setElementInitialRights of interface ApplElemAccess

Purpose:

Set the access control list information for the initial rights on some application element de�nedby <aid>. The <usergroup_id> de�nes the user group the rights should be set for. <rights>de�nes the rights to set or to clear. If the parameter<set> is set to 'set', the rights in<rights>are set all others are cleared. If the parameter <set> is set to 'add', the rights in <rights> areadded to the existing rights. If the parameter <set> is set to 'remove', the rights in <rights>are removed from the existing rights. Restriction for the model: only one application elementof the type AoUserGroup is allowed.

Return:

void

Parameter:


T_LONGLONG usergroupId (in) The user group to set the initial rights for.

T_LONG rights (in) The new initial rights for the user group. The rights constants arede�ned in the interface SecurityRights. The interface de�nition language IDL does not allowto set the values of enumerations thus the constant de�nitions have to be done in an interface.

T_LONGLONG refAid (in) The Id of referencing application element for which the initialrights will be used. If no refAid is set the initial rights will be used for each new instanceelement independent of the application element.

RightsSet set (in) What to do with the new initial rights.


applElemAccess.setElementInitialRights(aid,usergroupId,rights,refAid,set);

Java Example:








public class SetElementInitialRights extends ApplElemAccessExampleAbstract {


© 2015/08/19 Version 1.33




/**

* The main program. Example set the initial rights of the element derived from


* the READ and INSERT right.


*/


try {







int rights = SecurityRights.SEC_READ | SecurityRights.SEC_INSERT;

// A reference application element Id is not used over here because the

// initial rights will be the rights of the own instances.

T_LONGLONG refAid = new T_LONGLONG(0,0);



try {




aea.setElementInitialRights(aid, userGroupIds[0], rights, refAid, RightsSet.ADD_RIGHT);



System.out.println("The initial right is added.");


// Report the error




}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()


© 2015/08/19 Version 1.33




5.3.26 setElementRights of interface ApplElemAccess

Purpose:

Set the ACL information on some application element de�ned by <aid>. The <usergroup_-id> de�nes the user group the rights should be set for. <rights> de�nes the rights to setor to clear. If the parameter <set> is set to 'set', the rights in <rights> are set all othersare cleared. If the parameter <set> is set to 'add', the rights in <rights> are added to theexisting rights. If the parameter <set> is set to 'remove', the rights in <rights> are removedfrom the existing rights. Restriction for the model: only one application element of the typeAoUserGroup is allowed.

Note


Return:

void

Parameter:



T_LONG rights (in) The new rights for the user group. The rights constants are de�ned inthe interface SecurityRights. The interface de�nition language IDL does not allow to set thevalues of enumerations thus the constant de�nitions had to be done in an interface.



applElemAccess.setElementRights(aid,usergroupId,rights,set);

Java Example:








public class SetElementRights extends ApplElemAccessExampleAbstract {

/**

* The main program. Example set the rights of the element derived from


* the GRANT and DELETE right.


*/



© 2015/08/19 Version 1.33




try {







int rights = SecurityRights.SEC_GRANT | SecurityRights.SEC_DELETE;



try {




aea.setElementRights(aid, userGroupIds[0], rights, RightsSet.ADD_RIGHT);





// Report the error




}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.security.RelationSecurityTest.testCreate1_NRelation()

5.3.27 setInitialRightReference of interface ApplElemAccess

Purpose:

Set the �ag <set> in svcattr, if this reference will be used (or not) to retrieve the InitialRights. If more than one reference is set to true, the union (or-function) of all rights are used.

Return:

void

Parameter:



© 2015/08/19 Version 1.33




T_STRING refName (in) The name of the reference.

RightsSet set (in) What to do with the given reference.


applElemAccess.setInitialRightReference(aid,refName,set);

Java Example:







public class SetInitialRightReference extends ApplElemAccessExampleAbstract {

/**

* The main program. Example set the initial right reference from the element derived from AoLog to the element

* derived from AoTest.

*

* @param args

* not used.

*/


try {





T_LONGLONG aidLog = getAidByBaseType("AoLog");

// Get the relation from AoLog to AoTest

String relName = getRelationName(aidLog, aidTest);

// Check the relation is in the model.

if (relName != null) {



try {




aea.setInitialRightReference(aidLog, relName, RightsSet.ADD_RIGHT);



System.out.println("The initial right reference is added.");


// Report the error




}

}


close();


// Report the error



}


© 2015/08/19 Version 1.33




}

}

Errors:


Tested by:

5.3.28 setInstanceInitialRights of interface ApplElemAccess

Purpose:

Set the access control list information for the initial rights on some instance de�ned by theapplication element id <aid> and a sequence of instances de�ned by the id <iid>. The<usergroup_id> de�nes the user group the rights should be set for. <rights> de�nes therights to set or to clear. If the parameter <set> is set to 'set', the rights in <rights> are setall others are cleared. If the parameter <set> is set to 'add', the rights in <rights> are addedto the existing rights. If the parameter <set> is set to 'remove', the rights in <rights> areremoved from the existing rights. Restriction for the model: only one application element ofthe type AoUserGroup is allowed.

Note


Return:

void

Parameter:



T_LONGLONG usergroupId (in) The user group to set the initial rights for.

T_LONG rights (in) The new initial right for the user group.



© 2015/08/19 Version 1.33






applElemAccess.setInstanceInitialRights(aid,instIds,usergroupId,rights,refAid,set);

Errors:


Tested by:

test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()

5.3.29 setInstanceRights of interface ApplElemAccess

Purpose:

Set the ACL information on some instances de�ned by the application element id <aid>and a sequence of instances de�ned by the id <iid>. The <usergroup_id> de�nes the usergroup the rights should be set for. <rights> de�nes the rights to set or to clear. If theparameter <set> is set to 'set', the rights in <rights> are set all others are cleared. If theparameter <set> is set to 'add', the rights in <rights> are added to the existing rights. Ifthe parameter <set> is set to 'remove', the rights in <rights> are removed from the existingrights. Restriction for the model: only one application element of the type AoUserGroup isallowed.

Note


Return:

void

Parameter:




T_LONG rights (in) The new right for the user group.



© 2015/08/19 Version 1.33





applElemAccess.setInstanceRights(aid,instIds,usergroupId,rights,set);

Errors:


Tested by:

test.highqsoft.odsapi.read.ApplElemAccessTest.testGetValueMatrix()test.highqsoft.odsapi.security.ApplElemAccessWriteTest.testCheckReadInsert()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()test.highqsoft.odsapi.security.InstanceConcurrentCheckTest.testConcurrentApplElemAccess()test.highqsoft.odsapi.security.Mantis4842Test.testPrepare()....

5.3.30 setRelInst of interface ApplElemAccess

Purpose:

Add a set of instances as related instances to a given instance.

Note


Return:

void

Parameter:

ElemId elem (in) The instance to add to the given relation.

Name relName (in) The name of relation.

S_LONGLONG instIds (in) Sequence of instance id's.

SetType type (in) The type of the modi�cation, insert, update or remove.


applElemAccess.setRelInst(elem,relName,instIds,type);


© 2015/08/19 Version 1.33




Java Example:





import org.asam.ods.SetType;


public class SetRelInst extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how related instances can be set


* in the example.

*


*/


try {





T_LONGLONG aidUserGrp = getAidByBaseType("AoUserGroup");




if (ieIds.length > 0) {

// Get the Id's of the instance of the AoUserGroup element.

T_LONGLONG[] ieGrpIds = getInstanceIds(aidUserGrp);

try {



// Set the usegroups loaded as related instances to the first instance of user.

aea.setRelInst(new ElemId(aidUser, ieIds[0]), relName, ieGrpIds, SetType.INSERT);


System.out.println("The related instances are added.");


// Report the error




}

}


close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.ford.FordTest.testCreateManagementData()test.highqsoft.odsapi.performance.InstancePerfIT.testCreateN_M_Relation()test.highqsoft.odsapi.read.ReadRelationTest.testGetSetRelInst()test.highqsoft.odsapi.security.ManyGroupTest.testCreateGroups()test.highqsoft.odsapi.CreateInstanceElementTest.testAeCreateInstances()....

5.3.31 updateInstances of interface ApplElemAccess

Purpose:

Update one or more attributes of one or more instance elements. It's necessary that the inputstructure includes also the Id attribute, the Id attribute will be used to select the instanceelements. In case of inherited application elements the super type Id has to be included. Thevalues of one instance element are speci�ed in the valueseq of the input structure. The sameindex in the valueseq corresponds to the attributes values of one instance element.The server will update the values of the localcolumn instances when the following criteria all�t:- Only when the attributes id, generation_parameters, values, �ags are given, as soon as anyother attributes is given an exception is thrown.- The values of the localcolumn must all belong to exactly one instance of AoMeasurement- The amount of given values does not exceed the server memory limitation. An ASAM ODSserver has a memory limitation (not the system memory limitation); as soon as the givenvalues break the limitation an exception will be thrown.

Note

See also Transaction handling in ODS API. (p. 15)Update of the sequence attributes (values, �ags, generation_parameters) of the instances ofAoLocalColumn are supported with direct database access in case SVCVAL_SPS is used.The generated_parameters are written direct to the dataase. The values are written to thedatabase in case the write_mode is database, the �ags are only written to the databasein combination with the values. Updating an single value of �ags use the methods of theValueMatrix, here we will replace all values and �ags of the localcolumn. When the datatypeof the values of the localcolumn is DT_BYTESTR the values are written for each instanceof AoLocalColumn separatly.

Return:

void

Parameter:

AIDNameValueSeqUnitIdSequence val (in) The sequence of attributes and their values. Atleast one of the attribute values sequence must be a sequence with the Id.


applElemAccess.updateInstances(val);

Java Example:



© 2015/08/19 Version 1.33





import org.asam.ods.AIDNameValueSeqUnitId;







public class UpdateInstances extends ApplElemAccessExampleAbstract {

/**

* The main program. Example shows the how an attribute of several

* instances of a AoTest element are updated. The description of the

* instances will be changed. each second attribute will be invalid.

* This example show only how

* one attribute is changed but you can update with the same method

* also more attributes.

*


*/


try {






T_LONGLONG[] ieIds = getInstanceIds(aidTest);

// We write for each found instance of AoTest an new instance of Log.

// The number of instances (values in the sequence) have no restriction.

int noInst = ieIds.length;

// We write the description of the instances of AoTest

String aaIdName = getAttributeNameByBaseName(aidTest, "id");

String aaDescName = getAttributeNameByBaseName(aidTest, "description");

// So we have to write 2 attributes, the Id and description

// The number of attributes have no restriction

AIDNameValueSeqUnitId[] vals = new AIDNameValueSeqUnitId[2];

// Write the names



vals[0].attr = new AIDName(aidTest, aaDescName);


vals[0].unitId = new T_LONGLONG(0, 0);



short[] flags = new short[noInst];


if ((i % 2) == 0) {

flags[i] = 15; // Value is valid.

} else {

flags[i] = 0; // Value in not valid.

}

}



// Create the descriptions of the instances.

String[] descriptions = new String[noInst];


descriptions[i] = "Example description for instance with the Id " + ieIds[i].low;

}

// Set the descriptions.

vals[0].values.u.stringVal(descriptions);

// Write the Ids to AoTest



© 2015/08/19 Version 1.33





vals[1].attr = new AIDName(aidTest, aaIdName);


vals[1].unitId = new T_LONGLONG(0, 0);



// All the Ids are valid

flags = new short[noInst];


flags[i] = 15; // Value is valid.

}



vals[1].values.u.longlongVal(ieIds);

// we have now created the sequence with attribute value sequences.

// The index in the attribute value sequence will come to be the

// attribute values of an instance.



try {



// Update the instances

aea.updateInstances(vals);



System.out.println(noInst + " instances are updated.");


// Report the error




}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.security.InstanceAttributeCheckTest.testCreateElementAttributeSecurity()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()test.highqsoft.odsapi.security.InstanceConcurrentCheckTest.testConcurrentApplElemAccess()test.highqsoft.odsapi.security.Mantis4842Test.testPrepare()test.highqsoft.odsapi.security.SubTestCheckTest.tearDown()....


© 2015/08/19 Version 1.33




5.4 ApplicationAttribute

Package:

org.asam.ods

Description:

The ASAM ODS application attribute interface.

5.4.1 Java Examples of ApplicationAttribute


package api.methods.applicationattribute;







/** The examples of the methods of ApplicationAttribute are all derived from this class */

public class ApplicationAttributeExampleAbstract extends AoSessionExampleAbstract {

// The session

protected static AoSession aoSess = null;

// The application structure

protected static ApplicationStructure as = null;

// The application element

protected static ApplicationElement ae = null;

/**

* Get the application structure

*

* @return the application structure

* @throws AoException

* any occurring ASAM ODS exception.

*/

protected static ApplicationStructure getApplicationStructure() throws AoException {

if (as == null) {


aoSess = connect();

}

as = aoSess.getApplicationStructure();

}

return (as);

}

/**

* Get the application element, this examples use the element derived from AoTest.

*

* @return the application element.



*/

protected static ApplicationElement getApplicationElement() throws AoException {

if (ae == null) {

ApplicationStructure as = getApplicationStructure();

ae = as.getElementsByBaseType("AoTest")[0];


© 2015/08/19 Version 1.33



5.4 ApplicationAttribute 147

}

return ae;

}

/**

* Get the element with a given name.

*

* @param aeName

* the name of the element




*/

protected static ApplicationElement getApplicationElement(String aeName) throws AoException {

if (ae == null) {


ae = as.getElementByName(aeName);

}

return ae;

}

/**

* Get the attribute with the given base name of the application element with the given name.

*

* @param aeName


* @param baName

* the name of the base attribute

* @return the application attribute.



*/

protected static ApplicationAttribute getApplicationAttribute(String aeName, String baName) throws AoException {

if (ae == null) {

ApplicationElement ae = getApplicationElement(aeName);

}

return ae.getAttributeByBaseName(baName);

}

/**

* Get the attribute with the given name of the application element.

*

* @param aaName

* the name of the attribute




*/

protected static ApplicationAttribute getApplicationAttribute(String aaName) throws AoException {

if (ae == null) {

ApplicationElement ae = getApplicationElement();

}

return ae.getAttributeByName(aaName);

}

/**

* Get the 'name' attribute with the given name of the application element.

*




*/

protected static ApplicationAttribute getApplicationAttribute() throws AoException {

if (ae == null) {


}

return ae.getAttributeByBaseName("name");


© 2015/08/19 Version 1.33




}

/**


*



*/



aoSess.close();

aoSess = null;

}

}

/**

* Get the session.

*




*/



aoSess = connect();

}

return (aoSess);

}

}

5.4.2 getApplicationElement of interface ApplicationAttribute

Purpose:

Return the application element to which the attribute belongs.

Return:

ApplicationElement applElem The application element of the attribute.

Parameter:

None.


ApplicationElement applElem = applAttr.getApplicationElement();

Java Example:





public class GetApplicationElement extends ApplicationAttributeExampleAbstract {

/**

* Example to get the application element of an attribute.

* @param args, not used.

*/


© 2015/08/19 Version 1.33





try {

// Get the attribute

ApplicationAttribute aa = getApplicationAttribute();

// Get the application element

ApplicationElement ae = aa.getApplicationElement();

System.out.println("We have the element.");


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.odsapi.security.AAAQueryJoinTest.testReadHierarchy()

5.4.3 getBaseAttribute of interface ApplicationAttribute

Purpose:

Get the base attribute of the application attribute.

Return:

BaseAttribute baseAttr The base attribute of the application attribute. A 'null' is returned ifthe application attribute has no base attribute.

Parameter:

None.


BaseAttribute baseAttr = applAttr.getBaseAttribute();

Java Example:




import org.asam.ods.BaseAttribute;


© 2015/08/19 Version 1.33




public class GetBaseAttribute extends ApplicationAttributeExampleAbstract {

/**

* Example to get the base attribute of an attribute.


*/


try {



// Get the base attribute.

BaseAttribute ba = aa.getBaseAttribute();

if (ba != null) {

System.out.println("The attribute is derived from a base attribute.");

} else {

System.out.println("The attribute is an application attribute.");

}


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.avalon.SecurityTestIT.testIniRights()....

5.4.4 getDataType of interface ApplicationAttribute

Purpose:

Get the data type of the application attribute.

Return:

DataType aaDataType The data type of the application attribute.

Parameter:

None.


DataType aaDataType = applAttr.getDataType();


© 2015/08/19 Version 1.33




Java Example:





public class GetDataType extends ApplicationAttributeExampleAbstract {

/**

* Example to get the datatype of an attribute.


*/


try {



// Get the datatype.

DataType dt = aa.getDataType();

System.out.println("The attribute has a datatype with the value "+dt.value());


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.AoFactoryTestIT.ThreadtestNewSession.run()test.highqsoft.avalon.AoFactoryTestIT.ThreadTestNewFactory.run()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()....

5.4.5 getEnumerationDe�nition of interface ApplicationAttribute

Purpose:

Get the de�nition of the enumeration.

Return:

EnumerationDe�nition enumDef The ASAM ODS enumeration.

Parameter:

None.


© 2015/08/19 Version 1.33





EnumerationDefinition enumDef = aaObj.getEnumerationDefinition();

Java Example:




import org.asam.ods.EnumerationDefinition;

public class GetEnumerationDefinition extends ApplicationAttributeExampleAbstract {

/**

* Example to get the enumeration definition of an attribute. We use the application

* element Quantity with and the attribute derived from the base attribute

* default_datatype, because this attribute has an enumeration. Other

* models will not have the element "Quantity" so an error can occur.

* When the attribute has no enumeration an error will occur.

*

* @param args

* , not used.

*/


try {


ApplicationAttribute aa = getApplicationAttribute("Quantity", "default_datatype");

// Get the enumeration definition.

EnumerationDefinition ed = aa.getEnumerationDefinition();

System.out.println("We have the enumeration.");


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_INVALID_DATATYPE

Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadTestEnumerationDe�nition.threadTestEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.testEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestEnumerationDe�nition.ThreadTestEnumerationDe�nition()test.highqsoft.avalon.EnumerationReadTestIT.testEnumerationRead()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()....

5.4.6 getLength of interface ApplicationAttribute

Purpose:

Get the maximum allowed string length of the value of the application attribute.


© 2015/08/19 Version 1.33




Return:

T_LONG aaLength The maximum allowed string length of the application attribute.

Parameter:

None.


int aaLength = applAttr.getLength();

Java Example:




public class GetLength extends ApplicationAttributeExampleAbstract {

/**

* Example to get the length of an attribute, this only of interest from certain datatypes like DT_STRING or DT_DATE.

*

* @param args

* , not used.

*/


try {



// Get the length.

int len = aa.getLength();

System.out.println("The lengh of the attribute is " + len);


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.odsapi.xatf.XATFCopyIT.compareElement()....


© 2015/08/19 Version 1.33




5.4.7 getName of interface ApplicationAttribute

Purpose:

Get the name of the application attribute.

Return:

Name aaName The name of the application attribute.

Parameter:

None.


String aaName = applAttr.getName();

Java Example:




public class GetName extends ApplicationAttributeExampleAbstract {

/**

* Example to get the name of an attribute.

*

* @param args

* , not used.

*/


try {



// Get the name.

String aaName = aa.getName();

System.out.println("The name of the attribute is " + aaName);


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElementUnique()


© 2015/08/19 Version 1.33




test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()....

5.4.8 getRights of interface ApplicationAttribute

Purpose:

Retrieve access control list information of the given object.

Note


Return:

ACLSequence aclEntries The access control list entries of the given application attribute.

Parameter:

None.


ACL[] aclEntries = applAttr.getRights();

Java Example:





public class GetRights extends ApplicationAttributeExampleAbstract {

/**

* The main program. Example get the rights of the attribute.


*/


try {

// Get the attribute.


ACL[] aclList = aa.getRights();






}

} else {

System.out.println("There are no rights defined from the attribute.");

}


close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33




Errors:


Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()

5.4.9 getUnit of interface ApplicationAttribute

Purpose:

Get the unit Id of the application attribute. The unit Id is only valid for the current server.

Return:

T_LONGLONG aaUnit The unit Id of the application attribute.

Parameter:

None.


T_LONGLONG aaUnit = applAttr.getUnit();

Java Example:





public class GetUnit extends ApplicationAttributeExampleAbstract {

/**

* Example to get Id of the unit of the attribute.

* To get the name of the Unit, search for the element derived from AoUnit and get the

* instance with the given Id.

*

* @param args

* , not used.

*/


try {



// Get the unit.

T_LONGLONG aaUnitId = aa.getUnit();

System.out.println("The Id of the unit of the attribute is " + aaUnitId.low);


// Report the error


© 2015/08/19 Version 1.33






}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.odsapi.read.UnitTest.testGetInstancesAnuSeq()test.highqsoft.odsapi.unitconvert.UnitConvertTest.testAeaInsertInstances()....

5.4.10 hasUnit of interface ApplicationAttribute

Purpose:

Has the attribute an unit. If this �ag is set, all the attributes of the instances derived fromthis attribute will has an unit.

Return:

T_BOOLEAN hasUnit The �ag if the attribute has an unit.

Parameter:

None.


Boolean hasUnit = aaObj.hasUnit();

Java Example:




public class HasUnit extends ApplicationAttributeExampleAbstract {

/**

* Example checks if the attribute has a unit.

*

* @param args

* , not used.

*/



© 2015/08/19 Version 1.33




try {



// Check if the attribute has a unit.

boolean hasUnit = aa.hasUnit();

if (hasUnit) {

System.out.println("The attribute has a unit.");

} else {

System.out.println("The attribute has no unit.");

}


// Report the error



}

}

}

Since

ASAM ODS 5.0

See also:

withUnit of interface ApplicationAttribute

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()

5.4.11 hasValueFlag of interface ApplicationAttribute

Purpose:

Deprecated, not used any more since ASAM ODS 5.2.Has the attribute a value �ag? If this �ag is set, all the attributes of the instances derivedfrom this attribute will have a value �ag. If this �ag is not set the �ag in the TS_Valuestructure can be ignored.

Note

Not yet implemented. Deprecated in ASAM ODS 5.2

Return:

T_BOOLEAN hasValueFlag TRUE if the attribute has a value �ag, selse FALSE.


© 2015/08/19 Version 1.33




Parameter:

None.


Boolean hasValueFlag = aaObj.hasValueFlag();

Since

ASAM ODS 5.0

See also:

withValueFlag of interface ApplicationAttribute

Errors:


Tested by:

5.4.12 isAutogenerated of interface ApplicationAttribute

Purpose:

Get the auto generate �ag of the application attribute.

Return:

T_BOOLEAN isAutogenerated The auto generate �ag of the application attribute.

Parameter:

None.


boolean isAutogenerated = applAttr.IsAutogenerated();

Java Example:




public class IsAutogenerated extends ApplicationAttributeExampleAbstract {

/**

* Example checks if the attribute is autogenerated, the server will set the values at the instances


© 2015/08/19 Version 1.33




* for the autogenerated attributes.

*

* @param args

* , not used.

*/


try {



// Check if the attribute is autogenerated.

boolean isAutogen = aa.isAutogenerated();

if (isAutogen) {

System.out.println("The attribute is an autogenerated attribute.");

} else {

System.out.println("The attribute is not an autogenerated attribute.");

}


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.odsapi.ods530.InstanceElementWriteTest.testUpdateAoTest()test.highqsoft.odsapi.xatf.XATFCopyIT.compareElement()....

5.4.13 isObligatory of interface ApplicationAttribute

Purpose:

Get the obligatory �ag of the application attribute.

Return:

T_BOOLEAN aaIsObligatory The obligatory �ag of the application attribute.

Parameter:

None.


boolean isObligatory = applAttr.isObligatory();


© 2015/08/19 Version 1.33




Java Example:




public class IsObligatory extends ApplicationAttributeExampleAbstract {

/**

* Example checks if the attribute is obligatory, the client needs to set the values

* of an obligatory attribute otherwise an AoException with error code AO_MISSING_VALUE

* will be thrown.

*

* @param args

* , not used.

*/


try {



// Check if the attribute is obligatory.

boolean isObliagtory = aa.isObligatory();

if (isObliagtory) {

System.out.println("The attribute is an obligatory attribute.");

} else {

System.out.println("The attribute is not an obligatory attribute.");

}


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.odsapi.xatf.XATFCopyIT.compareElement()....

5.4.14 isUnique of interface ApplicationAttribute

Purpose:

Get the unique �ag of the application attribute. This method can be used to check whetherthe attributes values of the instances must have unique values.


© 2015/08/19 Version 1.33




Return:

T_BOOLEAN aaIsUnique The unique �ag of the application attribute.

Parameter:

None.


boolean isUnique = applAttr.isUnique();

Java Example:




public class IsUnique extends ApplicationAttributeExampleAbstract {

/**

* Example checks if the attribute is an unique attribute, the client needs to set unique values

* for this attribute at the instances otherwise a AoException with the error code AO_BAD_PARAMETER

* will be thrown.

*

* @param args

* , not used.

*/


try {



// Check if the attribute is unique.

boolean isUnique = aa.isUnique();

if (isUnique) {

System.out.println("The attribute is an unique attribute.");

} else {

System.out.println("The attribute is not an unique attribute.");

}


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()....


© 2015/08/19 Version 1.33




5.4.15 setBaseAttribute of interface ApplicationAttribute

Purpose:

Set the base attribute of the application attribute. This allows the client to declare the ap-plication attribute (new or existing) additional to a base attribute. The application attributewill become the derived attribute of the given base attribute.It is allowed to modify the application attribute outside a transaction but it is recommendedto activate a transaction.The base attribute must be unique within the application element otherwise the exceptionAO_DUPLICATE_BASE_ATTRIBUTE is thrown.For performance and �exibility reasons this set-method should be used before the new appli-cation attribute is committed the �rst time.If this method is called before the �rst commit it will not throw the following exceptions:AO_INVALID_DATATYPEAO_MISSING_VALUEAO_NOT_UNIQUE.After the �rst commit, there may be instances of the application attribute. These instancesmay cause the following problems:AO_INVALID_DATATYPE: The data type of the base attribute is not the same as the datatype of the instantiated attributes.AO_MISSING_VALUE: The obligatory �ag of the base attribute is set but there are one ormore empty values in the instances.AO_NOT_UNIQUE: The unique �ag of the base attribute is set but the values of the in-stances are not unique.The length, the name and the unit of the application attribute are not a�ected by this call.

Note

It is only allowed to modify an atribute of an appliation element when there are no instancestored at the application element. For the transaction handling see section Transactionhandling in ODS API. (p. 15)

Return:

void

Parameter:

BaseAttribute baseAttr (in) The base attribute.


applAttr.setBaseAttribute(baseAttr);

Java Example:








import org.asam.ods.BaseElement;


© 2015/08/19 Version 1.33




public class SetBaseAttribute extends ApplicationAttributeExampleAbstract {

/**

* The main program. Example creates an attribute created_by derived

* from the base attribute ao_created_by at an application element.

* The base attribute ao_last_modified_by is new in ASAM ODS 5.3.0, the

* attribute is an autogenerated and obligatory attribute but the values

* are not to be unique.

* The length will be set to 30 characters.

* You can run this examples once, because the attribute is generated and

* the next invocation will throw an AoException.

*


*/


try {

// Get the session




// Get the element.

ApplicationElement ae = as.getElementByName("StructureLevel");

// Get the base element of the application element

BaseElement be = ae.getBaseElement();

// Start the transaction, modification of the model

// is only allowed in a transaction and the user must

// be a superuser.


try {

// Create the attribute at the element

ApplicationAttribute aa = ae.createAttribute();

// set the name.

aa.setName("created_by");

// Get the base attribute of the base element

BaseAttribute ba = be.getAttributes("ao_created_by")[0];

// Set the base attribute, this will automatically set the

// datatype of the attribute.

aa.setBaseAttribute(ba);

// Set the length

aa.setLength(30);

// Set the autogenerated flag

aa.setIsAutogenerated(true);

// Set the obligatory flag, this will cause an exception

// when there are instances of the element, because the

// existing instances have no value for this attribute.

aa.setIsObligatory(true);

// Set the not unique flag

aa.setIsUnique(false);





// Report the error



}

// Close the session, until the session is closed

// Avalon does not allow any other session to modify the model

close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33




Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_DUPLICATE_BASE_ATTRIBUTEAO_IMPLEMENTATION_PROBLEMAO_INVALID_DATATYPEAO_MISSING_VALUEAO_NOT_IMPLEMENTEDAO_NOT_UNIQUEAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.changemodel.CheckNotNullConstraintTest.testChangeLengthNotNullAttr()test.highqsoft.odsapi.ford.FordElementTest.testCreateFordElement()....

5.4.16 setDataType of interface ApplicationAttribute

Purpose:

Set the data type of the application attribute.It is allowed to modify the application attribute outside a transaction but it is recommendedto activate a transaction.It is not allowed to set the data type of application attributes that represent base attributes.An attempt to set the data type of such an application attribute will result in the exceptionAO_IS_BASE_ATTRIBUTE.For performance and �exibility reasons this set-method should be used before the new appli-cation attribute is committed the �rst time.If this method is called before the �rst commit it will not throw the following exception:AO_INVALID_DATATYPEAfter the �rst commit, there may be instances of the application attribute. These instancesmay cause the following problem:AO_INVALID_DATATYPE: The data type of the base attribute is not the same as the datatype of the instantiated attributes.

Note


Return:

void

Parameter:

DataType aaDataType (in) The data type.


© 2015/08/19 Version 1.33





applAttr.setDataType(aaDataType);

Java Example:

See method createAttribute of interface ApplicationElement (p. 181) and methodsetEnumerationDe�nition of interface ApplicationAttribute (p. 167)

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_BASE_ATTRIBUTEAO_IMPLEMENTATION_PROBLEMAO_INVALID_DATATYPEAO_IS_BASE_ATTRIBUTEAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CheckNotNullConstraintTest.testChangeLengthNotNullAttr()test.highqsoft.odsapi.ford.FordElementTest.testCreateFordElement()....

5.4.17 setEnumerationDe�nition of interface ApplicationAttribute

Purpose:

Set the de�nition of the enumeration. This method modi�es the application model, only thesuper user can use this method.The AoException AO_INVALID_DATATYPE is thrown when the data type of the attributeis not DT_ENUM.

Note

It is only allowed to modify an atribute of an appliation element when there are no instancestored at the application element. For the transaction handling see section Transaction han-dling in ODS API. (p. 15) When the datatype of the attribute is not set (DT_UNKNOWN)this method set automatically the datatype of the attribute to DT_ENUM.

Return:

void

Parameter:

EnumerationDe�nition enumDef (in) The new enumeration de�nition.


© 2015/08/19 Version 1.33





aaObj.setEnumerationDefinition(enumDef);

Java Example:









public class SetEnumerationDefinition extends ApplicationAttributeExampleAbstract {

/**

* The main program. Example set the enumeration definition of an

* attribute. Get the enumeration definition with the name "Company"

* and set this definition at the attribute 'enumVal' of the element

* derived from "AoTest". The datatype of the attribute must be

* DT_ENUM otherwise and exception will be thrown. The attribute 'enumVal'

* will be created in this example.

* When the attribute exist and the datatype is given and the are instances

* at the element you can not change the datatype of the attribute.

* In the test data storage is an attribute with the given name at the

* element and the enumeration exists. When this attribute or the instance

* not exist and AoException will be thrown.

*

*


*/


try {

// Get the session




// Get the enumeration definition

EnumerationDefinition ed = as.getEnumerationDefinition("Company");

// Get the element




// be a superuser.


try {

// Create the attribute


// Set the name

aa.setName("enumVal");

// Set the first the datatype

aa.setDataType(DataType.DT_ENUM);

// Set the enumeration definition

aa.setEnumerationDefinition(ed);



System.out.println("Attribute created and enumeration is set.");



// Report the error



}


© 2015/08/19 Version 1.33






close();


// Report the error



}

}

}

Since

ASAM ODS 5.0

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVEAO_ACCESS_DENIEDAO_INVALID_DATATYPE

Tested by:

test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()

5.4.18 setIsAutogenerated of interface ApplicationAttribute

Purpose:

Set the auto generate �ag of the application attribute.It is allowed to modify the application attribute outside a transaction but it is recommendedto activate a transaction.For performance and �exibility reasons this set-method should be used before the new appli-cation attribute is committed the �rst time.

Note


Return:

void

Parameter:

T_BOOLEAN isAutogenerated (in) The auto generate �ag.


applAttr.setIsAutogenerated(isAutogenerated);


© 2015/08/19 Version 1.33




Java Example:

See method setBaseAttribute of interface ApplicationAttribute (p. 163)

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_BASE_ATTRIBUTEAO_IMPLEMENTATION_PROBLEMAO_IS_BASE_ATTRIBUTEAO_MISSING_VALUEAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.ods530.AoFileCreateTest.createBasedAttributes()test.highqsoft.odsapi.ods530.AoFileCreateTest.testCreateElement()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()test.highqsoft.odsapi.AutogenAttrTest.testCreateAutogenAttr()test.highqsoft.odsapi.AutogenMeaAttrTest.testCreateAutogenMeaAttr()

5.4.19 setIsObligatory of interface ApplicationAttribute

Purpose:

Set the obligatory �ag of the application attribute.It is allowed to modify the application attribute outside a transaction but it is recommendedto activate a transaction.It is not allowed to set the obligatory �ag of application attributesthat represent base attributes. An attempt to set the obligatory �ag of such an applicationattribute will result in the exception AO_IS_BASE_ATTRIBUTE.For performance and �exibility reasons this set-method should be used before the new appli-cation attribute is committed the �rst time.If this method is called before the �rst commit it will not throw the following exception:AO_MISSING_VALUEAfter the �rst commit, there may be instances of the application attribute. These instancesmay cause the following problem:AO_MISSING_VALUE: The obligatory �ag of the base attribute is set but there are one ormore empty values in the instances.

Note


Return:

void

Parameter:

T_BOOLEAN aaIsObligatory (in) The obligatory �ag.


© 2015/08/19 Version 1.33





applAttr.setIsObligatory(aaIsObligatory);

Java Example:


Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_BASE_ATTRIBUTEAO_IMPLEMENTATION_PROBLEMAO_IS_BASE_ATTRIBUTEAO_MISSING_VALUEAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.CheckNotNullConstraintTest.testChangeLengthNotNullAttr()test.highqsoft.odsapi.ods530.AoFileCreateTest.createBasedAttributes()test.highqsoft.odsapi.ods530.AoFileCreateTest.testCreateElement()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()....

5.4.20 setIsUnique of interface ApplicationAttribute

Purpose:

Set the unique �ag of the application attribute.It is allowed to modify the application attribute outside a transaction but it is recommendedto activate a transaction.The server will check if the values of the instance attributes are unique. If this �ag is set andthe values of an attribute are not unique when using the method setValue an exception isthrown. If instances of the application element already exist that contain non-unique valuesand the �ag shall be set this method throws an exception.It is not allowed to set the unique �ag of application attributes that represent base attributes.An attempt to set the unique �ag of such an application attribute will result in the exceptionAO_IS_BASE_ATTRIBUTE.If the unique �ag is set to TRUE the obligatory �ag is also set to TRUE. The previous valuesof both �ags do not matter in this case. Setting the unique �ag to FALSE does not a�ect theobligatory �ag.For performance and �exibility reasons this set-method should be used before the new appli-cation attribute is committed the �rst time.If this method is called before the �rst commit it will not throw the following exception:AO_MISSING_VALUEAO_NOT_UNIQUEAfter the �rst commit, there may be instances of the application attribute. These instancesmay cause the following problem:


© 2015/08/19 Version 1.33




AO_MISSING_VALUE: The obligatory �ag of the base attribute is set but there are one ormore empty values in the instances.AO_NOT_UNIQUE: The unique �ag of the base attribute is set but the values of the in-stances are not unique.

Note

It is only allowed to modify an atribute of an appliation element when there are no instancestored at the application element. The check of the uniqueness of the instance attributesvalues in not implemented.

For the transaction handling see section Transaction handling in ODS API. (p. 15)

Return:

void

Parameter:

T_BOOLEAN aaIsUnique (in) The unique �ag.


applAttr.setIsUnique(aaIsUnique);

Java Example:


Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_BASE_ATTRIBUTEAO_IMPLEMENTATION_PROBLEMAO_IS_BASE_ATTRIBUTEAO_MISSING_VALUEAO_NOT_IMPLEMENTEDAO_NOT_UNIQUEAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.CheckNotNullConstraintTest.testChangeLengthNotNullAttr()test.highqsoft.odsapi.ods530.AoFileCreateTest.createBasedAttributes()test.highqsoft.odsapi.ods530.AoFileCreateTest.testCreateElement()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()....

5.4.21 setLength of interface ApplicationAttribute

Purpose:

Set the maximum allowed length of the application attribute. The maximum value acceptedby the ASAM ODS server for this length information depends on the underlying physical


© 2015/08/19 Version 1.33




storage. For the physical storage speci�ed in chapter 3 the maximum allowed length will bestored in the AFLEN value in SVCATTR, and it is restricted by the maximum length of stringtype database �elds. If a length is speci�ed that exceeds the capabilities of the underlyingphysical storage the server will throw the exception AO_INVALID_LENGTH.It is allowed to modify the application attribute outside a transaction but it is recommendedto activate a transaction.This method is useful for ODS database design tools. Negative length values are not allowed.This method provides only a hint to a database server in the design phase which sizethe data entries may have. The length is only relevant for attribute values with thedata type DT_STRING, DS_STRING, DT_DATE, DS_DATE, all components of DT_-EXTERNALREFERENCE and of DS_EXTERNALREFERENCE, and the header portionof DT_BLOB.For performance and �exibility reasons this set-method should be used before the new appli-cation attribute is committed the �rst time.If this method is called before the �rst commit it will not throw the following exception:AO_HAS_INSTANCESAfter the �rst commit, there may be instances of the application attribute. These instancesmay cause the exception AO_HAS_INSTANCES if the instances of the application attributeare not empty.

Note


Return:

void

Parameter:

T_LONG aaLength (in) The maximum attribute length.


applAttr.setLength(aaLength);

Java Example:


Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_INSTANCESAO_IMPLEMENTATION_PROBLEMAO_INVALID_LENGTHAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()


© 2015/08/19 Version 1.33




test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.changemodel.CheckNotNullConstraintTest.testChangeLengthNotNullAttr()test.highqsoft.odsapi.ford.FordElementTest.testCreateFordElement()....

5.4.22 setName of interface ApplicationAttribute

Purpose:

Set the name of an application attribute.It is allowed to modify the application attribute outside a transaction but it is recommendedto activate a transaction.The name must be unique.For performance and �exibility reasons this set-method should be used before the new appli-cation attribute is committed the �rst time.The name of an application attribute must not exceed the maximum name length of theunderlying physical storage. Current server implementations typically restrict it to 30 char-acters.

Note


Return:

void

Parameter:

Name aaName (in) The application attribute name.


applAttr.setName(aaName);

Java Example:

See method createAttribute of interface ApplicationElement (p. 181) and methodsetBaseAttribute of interface ApplicationAttribute (p. 163) and method setEnu-merationDe�nition of interface ApplicationAttribute (p. 167)

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_DUPLICATE_NAMEAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE


© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CheckNotNullConstraintTest.testChangeLengthNotNullAttr()....

5.4.23 setRights of interface ApplicationAttribute

Purpose:

The given user group the rights should be set for. <rights> de�nes the rights to set or to clear.If the parameter <set> is set to 'set', the rights in <rights> are set all others are cleared. Ifthe parameter <set> is set to 'add', the rights in <rights> are added to the existing rights. Ifthe parameter <set> is set to 'remove', the rights in <rights> are removed from the existingrights.

Return:

void

Parameter:

InstanceElement usergroup (in) The user group for which the rights will be modi�ed.

T_LONG rights (in) The new right for the user group. The rights constants are de�ned inthe interface SecurityRights. The interface de�nition language IDL does not allow to set thevalues of enumerations thus the constant de�nitions had to be done in an interface.



applAttr.setRights(usergroup,rights,set);

Java Example:










public class SetRights extends ApplicationAttributeExampleAbstract {

/**

* The main program. Example add the GRANT-right for the usegroup with the name

* "admin" to the attribute.


© 2015/08/19 Version 1.33





*/


try {

// Get the session



// Get the element of the usergroup.

ApplicationElement aeUsg = as.getElementsByBaseType("AoUserGroup")[0];

// get the instance with the name admin

InstanceElement ieUsg = aeUsg.getInstanceByName("admin");





int rights = SecurityRights.SEC_GRANT;

// Set the right.

aa.setRights(ieUsg, rights, RightsSet.ADD_RIGHT);




ieUsg.destroy();


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.security.AttributeCheckTest.testCheckAttributeGrantRight()test.highqsoft.odsapi.security.InstanceAttributeCheckTest.testCreateElementAttributeSecurity()test.highqsoft.odsapi.security.UserGroupDeleteTest.testCreateUserGroupWithRights()

5.4.24 setUnit of interface ApplicationAttribute

Purpose:

Set the unit Id of an application attribute.It is allowed to modify the application attribute outside a transaction but it is recommendedto activate a transaction.The unit Id is only valid for the current server. If instances of the application attributeexist, the respective values are automatically converted to the new unit. If there is no knownconversion an exception is thrown.The automatic conversion can be avoided if the unit is set to zero. After that the transactionmust be committed. In the next step the new unit may be set in another transaction.


© 2015/08/19 Version 1.33




The automatic conversion is done only for the following data types:DT_BYTEDT_COMPLEXDT_DCOMPLEXDT_DOUBLEDT_FLOATDT_LONGDT_LONGLONGDT_SHORTas well as for the corresponding sequence data types. For complex data types the real andimaginary part are converted separately.If the unit of an attribute is set the unit is constant. If the value of the attribute hasanother unit the value is recalculated to the unit of the application attribute. If there is nounit associated with the application attribute the unit at the attribute value is stored andreported on request at the instance.For performance and �exibility reasons this set-method should be used before the new appli-cation attribute is committed the �rst time.If this method is called before the �rst commit it will not throw the following exceptions:AO_INCOMPATIBLE_UNITSAO_MATH_ERRORAfter the �rst commit, there may be instances of the application attribute. These instancesmay cause the following problems:AO_INCOMPATIBLE_UNITS: No conversion rules is known to convert the unit.AO_MATH_ERROR: Converting the values to the new unit results in data over�ow orunder�ow or a division by zero is detected.

Note

It is only allowed to modify an atribute of an appliation element when there are no instancestored at the application element. No check and modi�cation of the unit ids of the instanceattributes are implemented. For the transaction handling see section Transaction handlingin ODS API. (p. 15)

Return:

void

Parameter:

T_LONGLONG aaUnit (in) The unit Id.


applAttr.setUnit(aaUnit);

Java Example:








public class SetUnit extends ApplicationAttributeExampleAbstract {


© 2015/08/19 Version 1.33




/**

* The main program. Example set the unit 'm' to the attribute with

* the name 'dVal' of the element with the base type AoTest.

* The unit 'm' is the instance with the name 'm' of the application

* element derived from the base element 'AoUnit'.

* In the test data storage is an attribute with the given name at the

* element and the unit 'm' exists. When this attribute or the instance

* not exist and AoException will be thrown.

*


*/


try {

// Get the session




// There is only one element derived from AoUnit.

ApplicationElement aeUnit = as.getElementsByBaseType("AoUnit")[0];

InstanceElement ieUnit = aeUnit.getInstanceByName("m");



// be a superuser.



ApplicationAttribute aa = getApplicationAttribute("dVal");

try {

// Set the unit, use the Id of the instance.

aa.setUnit(ieUnit.getId());





// Report the error



}

// Destroy the instance to cleanup the POA map.

ieUnit.destroy();



close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INCOMPATIBLE_UNITSAO_MATH_ERRORAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_UNKNOWN_UNIT


© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()

5.4.25 withUnit of interface ApplicationAttribute

Purpose:

Speci�es whether the attribute will have an unit or not. A call to the method setUnit() willautomatically set the withUnit �ag to TRUE.

Note

It is only allowed to modify an atribute of an appliation element when there are no instancestored at the application element.

For the transaction handling see section Transaction handling in ODS API. (p. 15)


Return:

void

Parameter:

T_BOOLEAN withUnit (in) TRUE, if the attribute will have an unit, FALSE otherwise.


aaObj.withUnit(TRUE);

Since

ASAM ODS 5.0

See also:

hasUnit of interface ApplicationAttributesetUnit of interface ApplicationAttribute

Errors:


Tested by:


© 2015/08/19 Version 1.33



5.5 ApplicationElement 179

5.4.26 withValueFlag of interface ApplicationAttribute

Purpose:

Deprecated, not used any more since ASAM ODS 5.2.Speci�es whether the attribute has a value �ag or not. If this �ag isn't set the �ag of theTS_Value will be ignored by the server.

Note

It is only allowed to modify an atribute of an appliation element when there are no instancestored at the application element. Not yet implemented. Deprecated in ASAM ODS 5.2

Return:

void

Parameter:

T_BOOLEAN withValueFlag (in) TRUE �ag if the attribute becomes a value �ag, elseFALSE.


aaObj.withValueFlag(TRUE);

Since

ASAM ODS 5.0

See also:

hasValueFalg of interface ApplicationAttribute

Errors:


5.5 ApplicationElement

Package:

org.asam.ods

Description:

The ASAM ODS application element interface.

5.5.1 Java Examples of ApplicationElement



© 2015/08/19 Version 1.33




package api.methods.applicationelement;






/** The examples of the methods of ApplicationElement are all derived from this class */

public class ApplicationElementExampleAbstract extends AoSessionExampleAbstract {

// The session




/**




*/


if (as == null) {


aoSess = connect();

}


}

return (as);

}

/**



* @throws AoException n any occurring ASAM ODS exception.

*/



ApplicationElement ae = as.getElementsByBaseType("AoTest")[0];

return ae;

}

/**



*/



aoSess.close();

aoSess = null;

}

}

/**

* Get the session.



*/



aoSess = connect();

}

return(aoSess);

}

}


© 2015/08/19 Version 1.33




5.5.2 createAttribute of interface ApplicationElement

Purpose:

Create a new application attribute on the server.It is allowed to modify the application element outside a transaction but it is recommendedto activate a transaction.The properties of the new application attribute may be changed via the set-methods of theApplicationAttribute interface.For performance reasons it is recommended to set all required properties of an applicationattribute before it is committed the �rst time. This avoids database cross-checks for eachattribute.The default properties of a new application attribute are:BaseAttribute NULLDataType DT_UNKNOWNIsObligatory 0IsUnique 0Length 0Name "AUTOGEN"Unit NULLIf there are already instances of the application element the values of the existing instancesof the new attribute are set to unde�ned.The exception AO_DUPLICATE_NAME is thrown if there is already another applicationattribute with the name "AUTOGEN".

Note

It is only allowed to create a new attribute, if there are no instances de�ned at the applicationelement. For the transaction handling see section Transaction handling in ODS API.(p. 15)

Return:

ApplicationAttribute applAttr The new application attribute.

Parameter:

None.


ApplicationAttribute applAttr = applElem.createAttribute();

Java Example:






public class CreateAttribute extends ApplicationElementExampleAbstract {

/**

* The main program. Example creates a new attribute call "NewAttribute" at the element. The datatype of the new

* attribute is DT_FLOAT.

*


© 2015/08/19 Version 1.33




* @param args

* not used.

*/


try {





// be a superuser.


try {

// Create the attribute.


// Set the name of the attribute

aa.setName("NewAttribute");

// Set the datatype of the attribute

aa.setDataType(DataType.DT_FLOAT);





// Report the error



}



close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOSTAO_DUPLICATE_NAMEAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CheckNotNullConstraintTest.testChangeLengthNotNullAttr()....

5.5.3 createInstance of interface ApplicationElement

Purpose:

Create an instance of the application element.


© 2015/08/19 Version 1.33




It is allowed to create an instance outside a transaction but it is recommended to activate atransaction.The instance gets permanent when the transaction is committed. All attributes connected tothe application element are automatically created and connected to the instance. The valuesof the attributes can be set by the method setValue of the interface InstanceElement.

Note


Return:

InstanceElement instElem The new instance.

Parameter:

Name ieName (in) The instance name.


InstanceElement instElem = applElem.createInstance(ieName);

Java Example:





public class CreateInstance extends ApplicationElementExampleAbstract {

/**

* The main program. Example creates a new instance call "NewInstance" at the element.

* there are no other attribute set.


*/


try {





// Create the attribute.

InstanceElement ie = ae.createInstance("NewInstance");




close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.booleans.UpdateQueryTest.testCreateQuery()test.highqsoft.odsapi.bosch.MultiSessionIT.threadCreate.threadCreate()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()....

5.5.4 createInstances of interface ApplicationElement

Purpose:

Create a list with instances. The attribute names are given with the name of the sequence.The attribute values are given in the value sequence. The index in the di�erent value sequencesmatch for one instance element. The index in the instance element sequence of the relatedinstances match for the instance with the same index in the value sequence.

Note


Return:

InstanceElementSequence elemList The list with the new created instances.

Parameter:

NameValueSeqUnitSequence attributes (in) The attributes of the new created instances.

ApplicationRelationInstanceElementSeqSequence relatedInstances (in) The list with relatedinstances for di�erent application relations.


ApplicationElement aeObj;

NameValueSeqUnit attributes[];

ApplicationRelationInstanceElement[] relatedInstances;

InstanceElement elemList[] = aeObj.createInstances(attributes, relatedInstances);

Since

ASAM ODS 5.0

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTED


© 2015/08/19 Version 1.33




AO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.CreateInstanceElementTest.testAeCreateInstances()

5.5.5 getAllRelatedElements of interface ApplicationElement

Purpose:

Get a list of all related application elements connected to this application element.

Return:

ApplicationElementSequence applElems The list with the related application elements.

Parameter:

None.


ApplicationElement[] applElems = applElem.getAllRelatedElements();

Java Example:




public class GetAllRelatedElements extends ApplicationElementExampleAbstract {

/**

* The main program. Example shows the how the related elements are loaded.


*/


try {



ApplicationElement[] relElems = ae.getAllRelatedElements();

System.out.println("There are " + relElems.length + " related elements.");


close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEM


© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.odsapi.read.ExtendedQueryTest.testAllAttr()....

5.5.6 getAllRelations of interface ApplicationElement

Purpose:

Get a list of all application relations connected to this application element. The inverserelation of relations connected to other application elements pointing to the given applicationelements are not returned.

Return:

ApplicationRelationSequence applRels The list with the application relations of the applicationelement.

Parameter:

None.


ApplicationRelation[] applRels = applElem.getAllRelations();

Java Example:





public class GetAllRelations extends ApplicationElementExampleAbstract {

/**

* The main program. Example shows the how the relations of an element are loaded.


*/


try {



ApplicationRelation[] rel = ae.getAllRelations();

System.out.println("There are " + rel.length + " relations.");


close();


// Report the error


© 2015/08/19 Version 1.33






}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelationApplElemAccess()....

5.5.7 getApplicationStructure of interface ApplicationElement

Purpose:

Get the application model to which the application element belongs by returning an objectwith the interface ApplicationStructure. The application model provided is the same as thatprovided from the method getApplicationStructure of the Interface AoSession. This methodguarantees that the client software is able to return to the session in case the session objectis not available.

Return:

ApplicationStructure applStruct The application structure to which the application elementbelongs.

Parameter:

None.


ApplicationStructure applStruct = applElem.getApplicationStructure();

Java Example:





public class GetApplicationStructure extends ApplicationElementExampleAbstract {

/**


© 2015/08/19 Version 1.33




* The main program. Example get the application structure of the element


*/


try {



ApplicationStructure as = ae.getApplicationStructure();

System.out.println("We have the application structure");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.odsapi.xatf.XATFCopyIT.ThreadCopyMeasurement.ThreadCopyMeasurement()test.highqsoft.odsapi.RelatedInstances.loadIdBoundaries()....

5.5.8 getAttributeByBaseName of interface ApplicationElement

Purpose:

Get the application attribute of an application element which is inherited from the baseattribute with the given name. The base name of the attribute is case insensitive (the basemodel itself is case insensitive; ID, Id, id are treated as the same items). The calling parametermay not contain wildcard characters.Note: The base model is case blind, e.g. Id, ID and id is all the same base attribute.

Return:

ApplicationAttribute applAttr The application attribute.

Parameter:

Name baName (in) The base attribute name.


ApplicationAttribute applAttr = applElem.getAttributeByBaseName(baName);


© 2015/08/19 Version 1.33




Java Example:





public class GetAttributeByBaseName extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the application attribute derived from the base attribute

* "Id", the base model is case insensitive. All elements have an attribute derived from "Id"


*/


try {



ApplicationAttribute aa = ae.getAttributeByBaseName("iD");

System.out.println("We have the attribute.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationElementTestIT.testExistBaseAttributes()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElementUnique()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()....

5.5.9 getAttributeByName of interface ApplicationElement

Purpose:

Get the application attribute of an application element which has the given name. The nameis case sensitive and may not contain wildcard characters.Note: The application model is (in contrary to the base model) case sensitive, e.g. ID, Id andid are three di�erent items.Note: In the application mnodel ID and Id are di�erent application attributes. It is best notto use such misleading attribute names.


© 2015/08/19 Version 1.33




Return:

ApplicationAttribute applAttr The application attribute.

Parameter:

Name aaName (in) The application attribute name.


ApplicationAttribute applAttr = applElem.getAttributeByName(aaName);

Java Example:





public class GetAttributeByName extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the application attribute with a given name.

* The new created attribute with the name "NewAttribute" is loaded.


*/


try {



ApplicationAttribute aa = ae.getAttributeByName("NewAttribute");

System.out.println("We have the attribute.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadTestEnumerationDe�nition.threadTestEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.testEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestEnumerationDe�nition.ThreadTestEnumerationDe�nition()test.highqsoft.avalon.EnumerationReadTestIT.testEnumerationRead()test.highqsoft.odsapi.booleans.UpdateQueryTest.testCreateQuery()....


© 2015/08/19 Version 1.33




5.5.10 getAttributes of interface ApplicationElement

Purpose:

Get a list of the application attributes of an application element. The reference attributes arenot returned.

Return:

ApplicationAttributeSequence applAttrs The application attributes.

Parameter:

Pattern aaPattern (in) The name or the search pattern for the application attribute name.


ApplicationAttribute[] applAttrs = applElem.getAttributes(aaPattern);

Java Example:





public class GetAttributes extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the application attributes of the element.


*/


try {



// Get the attribute, use * for the pattern.

ApplicationAttribute[] aaList = ae.getAttributes("*");

System.out.println("We have " + aaList.length + " attributes.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.AoFactoryTestIT.ThreadtestNewSession.run()


© 2015/08/19 Version 1.33




test.highqsoft.avalon.AoFactoryTestIT.ThreadTestNewFactory.run()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()....

5.5.11 getBaseElement of interface ApplicationElement

Purpose:

Get the base element of an application element.

Return:

BaseElement baseElem The base element.

Parameter:

None.


BaseElement baseElem = applElem.getBaseElement();

Java Example:





public class GetBaseElement extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the base element of the application element.


*/


try {



BaseElement be = ae.getBaseElement();

System.out.println("We have the base element.");


close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureBase.threadApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureBase()....

5.5.12 getId of interface ApplicationElement

Purpose:

Get the Id of an application element.

Return:

T_LONGLONG aeId The Id of the application element.

Parameter:

None.


T_LONGLONG aeId = applElem.getId();

Java Example:





public class GetId extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the Id of the application element.


*/


try {



T_LONGLONG aid = ae.getId();

if (aid.high == 0) {

System.out.println("The Id of the element is " + aid.low);

} else {

System.out.println("The Id of the element is very high.");

}


close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33




Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureElements.threadApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElementUnique()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.ApplicationStructureTestIT.testGetInstances()....

5.5.13 getInitialRightRelations of interface ApplicationElement

Purpose:

Get all relations which are used to retrieve the instances to create the initial rights of the newcreated instance element. If there is more then one application relation, the initial rights ofeach related instance are 'ored' to the list of the initial rights.

Return:

ApplicationRelationSequence applRels The sequence with the application relations which willbe used to create the initial rights of the new created instance element.

Parameter:

None.


ApplicationRelation[] applRels = applElem.getInitialRightRelations();

Java Example:





public class GetInitialRightRelations extends ApplicationElementExampleAbstract {

/**

* The main program. Example shows the how the initial right relations

* of an element are loaded. The initial right relations are special relations

* to load the rights of a new created instance. Most application models

* will not have any of these relations in the model.

*


*/


try {


© 2015/08/19 Version 1.33






ApplicationRelation[] rel = ae.getInitialRightRelations();

System.out.println("There are " + rel.length + " initial right relations.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.security.InitialRightsTest.testDeleteCreatedInstances()

5.5.14 getInitialRights of interface ApplicationElement

Purpose:

Retrieve access control list information for the initial rights of the given object.

Return:

InitialRightSequence initialRights The access control list entries with the initial rights of thegiven application element.

Parameter:

None.


InitialRight[] initialRights = applElem.getInitialRights();

Java Example:










© 2015/08/19 Version 1.33






// Get the access control list

irSeq = aeList[aeIndex].getRights();

for (int irIndex = 0; irIndex < irSeq.length; irIndex++) {

System.out.println(

aeName +




}

}

See also:

getElementInitialRightRelation of interface ApplElemAccess

Errors:


Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.security.InitialRightsTest.testDeleteCreatedInstances()test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()

5.5.15 getInstanceById of interface ApplicationElement

Purpose:

Get the instance element speci�ed by the given Id. If the Id of the instance is not unique anexception is thrown.

Note

This methods tries �rst to get the instance from the instancews cache, the instance cache willnot be cleared independent from the INI-File variable NO_INSTANCE_CACHE.

Return:

InstanceElement instElem The instance element.

Parameter:

T_LONGLONG ieId (in) The instance element Id.


InstanceElement instElem = applElem.getInstanceById(ieId);


© 2015/08/19 Version 1.33




Java Example:






public class GetInstanceById extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the instance of the application element with

* a given Id.


*/


try {



// We know in our test database there is an instance with the Id 30.

T_LONGLONG ieId = new T_LONGLONG(0, 30);

InstanceElement ie = ae.getInstanceById(ieId);

System.out.println("We have the instance.");


ie.destroy();


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testCheckRelLccMeq()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelationApplElemAccess()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesValueQuery()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesValueQueryExt()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()....

5.5.16 getInstanceByName of interface ApplicationElement

Purpose:

Get the instance element speci�ed by the given name. If the instance name is not unique anexception is thrown.


© 2015/08/19 Version 1.33




This is a convenience method for instance elements with unique names. If there are duplicatenames for instances use the method getInstances instead and specify the requested name aspattern parameter.

Return:

InstanceElement instElem The instance element.

Parameter:

Name ieName (in) The instance element name.


InstanceElement instElem = applElem.getInstanceByName(ieName);

Java Example:





public class GetInstanceByName extends ApplicationElementExampleAbstract {

/**


* a given name.


*/


try {



// We know in our test database there is an instance with the Name "NewInstance".

// In case the name is not unique an exception will be thrown by the server.

InstanceElement ie = ae.getInstanceByName("NewInstance");



ie.destroy();


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_DUPLICATE_NAMEAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE


© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CreateNewInstanceElementTest.testCreateFKInstances()test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()....

5.5.17 getInstances of interface ApplicationElement

Purpose:

Get the instances whose names match with the pattern. The pattern is case sensitive andmay contain wildcard characters.

Note

This method will load the requested instances from the storage into the cache of the imple-mentation. There is no amount restriction of the number of instances. When the amountof instances is high, the implemetation will have problems to cleanup his memory. Thiscan leads to memory problems in the implementation and or reduce the performance of theimplementation. Use the query when a high amount of instances is requested.

Return:

InstanceElementIterator ieIterator The instance elements.

Parameter:

Pattern iePattern (in) The name or the search pattern for the instance element name.


InstanceElementIterator ieIterator = applElem.getInstances(iePattern);

Java Example:




import org.asam.ods.InstanceElementIterator;

public class GetInstances extends ApplicationElementExampleAbstract {

/**


* a given pattern. The instances will be returned to the client in an iterator,

* which is again an interface in ODS API so all access to the iterator will cause

* a network access to the server.


*/


try {



// Ask an iterator for the instances starting with an "N"


© 2015/08/19 Version 1.33




// * is the pattern.

InstanceElementIterator ieIter = ae.getInstances("N*");

System.out.println("We have the iterator for the instance.");

// Destroy the iterator to cleanup the POA map.

ieIter.destroy();


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testCheckRelLccMeq()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()test.highqsoft.avalon.InstanceElementTestIT.testInstancesRelationNames()....

5.5.18 getName of interface ApplicationElement

Purpose:

Get the name of an application element.

Return:

Name aeName The name of the application element.

Parameter:

None.


String aeName = applElem.getName();

Java Example:





© 2015/08/19 Version 1.33




public class GetName extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the Name of the application element.


*/


try {



String name = ae.getName();

System.out.println("The element: " + name);


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureBase.threadApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureElements.threadApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()....

5.5.19 getRelatedElementsByRelationship of interface ApplicationEle-ment

Purpose:

Get related application elements connected via the speci�ed relationship.

Return:

ApplicationElementSequence applElems The related application elements.

Parameter:

Relationship aeRelationship (in) The requested relationship.


ApplicationElement[] applElems = applElem.getRelatedElementsByRelationship(aeRelationship);


© 2015/08/19 Version 1.33




Java Example:





public class GetRelatedElementsByRelationship extends ApplicationElementExampleAbstract {

/**

* The main program. Example shows the how the related elements are loaded.

* The relationship CHILD will be used


*/


try {



ApplicationElement[] relElems = ae.getRelatedElementsByRelationship(Relationship.CHILD);

System.out.println("There are " + relElems.length + " child elements.");


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATIONSHIPAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()....

5.5.20 getRelationsByBaseName of interface ApplicationElement

Purpose:

Return the application relations derived from the base relation with the given relation name.Please note that at most elements only one application relation can be derived from a baserelation. However there are some well de�ned exceptions where this method may return morethen one application relation.


© 2015/08/19 Version 1.33




Return:

ApplicationRelationSequence applRel The application relation sequence; if no relation is foundan empty sequence is returned.

Parameter:

Name baseRelName (in) The name of the base relation.


ApplicationRelation applSeq[] = ae.getRelationaByBaseName("parent_test");

Java Example:





public class GetRelationsByBaseName extends ApplicationElementExampleAbstract {

/**

* The main program. Example shows the how the relations are loaded.

* The base relation relation children is the condition.

* In some models there can be no relation derived from the given

* base relation.

*


*/


try {



ApplicationRelation[] rel = ae.getRelationsByBaseName("children");



close();


// Report the error



}

}

}

Since

ASAM ODS 5.1.1

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()


© 2015/08/19 Version 1.33




test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.ford.FordMesaurementTest.testCreateMeasurementDoubleLc()test.highqsoft.odsapi.ford.FordSeq1Test.testCreateFordElements()....

5.5.21 getRelationsByType of interface ApplicationElement

Purpose:

Get application relations of the requested type connected with this application element. Theinverse relations are not returned.

Return:

ApplicationRelationSequence applRels The application relations.

Parameter:

RelationType aeRelationType (in) The requested relation type.


ApplicationRelation[] applRels = applElem.getRelationsByType(aeRelationType);

Java Example:





import org.asam.ods.RelationType;

public class GetRelationsByType extends ApplicationElementExampleAbstract {

/**

* The main program. Example shows the how the relations are loaded.

* The INFO relations are loaded.


*/


try {



ApplicationRelation[] rel = ae.getRelationsByType(RelationType.INFO);



close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETER


© 2015/08/19 Version 1.33




AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATION_TYPEAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.read.ExtendedQueryTest.testAllAttr()test.highqsoft.odsapi.xatf.BitFieldTest.testCompareMeaBitXatf()test.highqsoft.odsapi.xatf.BooleanTest.testCompareMeaBool()test.highqsoft.odsapi.xatf.XATFCopyIT.instanceElementCopy()test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()....

5.5.22 getRights of interface ApplicationElement

Purpose:


Note


Return:

ACLSequence aclEntries The access control list entries of the given application element.

Parameter:

None.


ACL[] aclEntries = applElem.getRights();

Java Example:





public class GetRights extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the rights of the element.


*/


try {

// Get the element.


ACL[] aclList = ae.getRights();


© 2015/08/19 Version 1.33








}


close();


// Report the error



}

}

}

See also:

getElementRights of interface ApplElemAccess

Errors:


Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.security.CreateInstanceElementRightTest.testCheckElementRights()test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()test.highqsoft.odsapi.security.SubTestCheckTest.tearDown()test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()

5.5.23 getSecurityLevel of interface ApplicationElement

Purpose:

Get the security level of the application element. The security level tells if there is a securitycheck for both application element and instance elements or only for the application attributes,the instance elements or none at all.

Return:

T_LONG secLevel The current security level. The security level constants are de�ned in theinterface SecurityLevel. The interface de�nition language IDL does not allow to set the valuesof enumerations thus the constant de�nitions had to be done in an interface.

Parameter:

None.


SecurityLevel secLevel = applElem.getSecurityLevel();


© 2015/08/19 Version 1.33




Java Example:




public class GetSecurityLevel extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the security level of the element.


*/


try {

// Get the element.


int sl = ae.getSecurityLevel();

String slStr=null;

if (sl == 0) {

slStr = "NONE";

} else {

if ((sl & 1) != 0) {

slStr = "ELEMENT";

}

if ((sl & 2) != 0) {

if (slStr == null) {

slStr = "INSTANCE";

} else {

slStr = slStr+"|INSTANCE";

}

}

if ((sl & 4) != 0) {

if (slStr == null) {

slStr = "ATTRIBUTE";

} else {

slStr = slStr+"|ATTRIBUTE";

}

}

}

System.out.println("The security level is: " + slStr);


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.read.ApplElemAccessTest.testGetValueMatrix()test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()test.highqsoft.odsapi.security.SubTestCheckTest.tearDown()


© 2015/08/19 Version 1.33




test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()

5.5.24 listAllRelatedElements of interface ApplicationElement

Purpose:

Get the names of all related application elements.

Return:

NameSequence applElemNames The names of the related application elements.

Parameter:

None.


Name[] applElemNames = applElem.listAllRelatedElements();

Java Example:




public class ListAllRelatedElements extends ApplicationElementExampleAbstract {

/**

* The main program. Example shows the how the names of the related elements are loaded.


*/


try {



String[] relElemNames = ae.listAllRelatedElements();

for (String aeName : relElemNames) {

System.out.println("Related element: " + aeName);

}


close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()

5.5.25 listAttributes of interface ApplicationElement

Purpose:

Get the application attribute names of the application element. There are no attribute namesreturned in the result list that contain a reference to another application element.

Return:

NameSequence applAttrNames The names of the application attributes.

Parameter:



Name[] applAttrNames = applElem.listAttributes(aaPattern);

Java Example:




public class ListAttributes extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the names of the application attributes of the element.


*/


try {



// Get the names of the attributes, use * for the pattern.

String[] aaNames = ae.listAttributes("*");

for (String aaName : aaNames) {

System.out.println("Attribute: " + aaName);

}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETER


© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesValueQuery()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesValueQueryExt()....

5.5.26 listInstances of interface ApplicationElement

Purpose:

Get the names of the instances whose names match with the pattern. The pattern is casesensitive and may contain wildcard characters.

Return:

NameIterator ieNameIterator The names of the instances.

Parameter:



NameIterator ieNameIterator = applElem.listInstances(aaPattern);

Java Example:





public class ListInstances extends ApplicationElementExampleAbstract {

/**

* The main program. Example get the names of the instance of the application element

* with a given pattern. The names of the instances will be returned to the client in

* an iterator, which is again an interface in ODS API so all access to the iterator

* will cause a network access to the server.


*/


try {



// Ask an iterator for the instances starting with an "N"

// * is the pattern.

NameIterator ieNameIter = ae.listInstances("N*");


© 2015/08/19 Version 1.33




System.out.println("We have the iterator for the names.");

// Destroy the iterator to cleanup the POA map.

ieNameIter.destroy();


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()test.highqsoft.odsapi.read.UnitTest.testGetInstancesAnuSeq()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()test.highqsoft.odsapi.unitconvert.UnitConvertTest.testAeaInsertInstances()test.highqsoft.odsapi.DeleteInstanceElementTest.testApplElemAccessDeleteInstances()

5.5.27 listRelatedElementsByRelationship of interface ApplicationEle-ment

Purpose:

Get the names of related application elements connected via the speci�ed relationship.

Return:

NameSequence applElemNames The names of the related application elements.

Parameter:

Relationship aeRelationship (in) The requested relationship.


Name[] applElemNames = applElem.listRelatedElementsByRelationship(aeRelationship);

Java Example:






© 2015/08/19 Version 1.33




public class ListRelatedElementsByRelationship extends ApplicationElementExampleAbstract {

/**


* The relationship CHILD will be used


*/


try {



String[] relElemNames = ae.listRelatedElementsByRelationship(Relationship.CHILD);

for (String aeName : relElemNames) {

System.out.println("Related element: " + aeName);

}


close();


// Report the error



}

}

}

Errors:


Tested by:


5.5.28 removeAttribute of interface ApplicationElement

Purpose:

Remove an application attribute from an application element. If there are instances of theapplication element the attribute of the existing instances change from application to instanceattributes.It is allowed to modify the application element outside a transaction but it is recommendedto activate a transaction.

Note


Return:

void


© 2015/08/19 Version 1.33




Parameter:

ApplicationAttribute applAttr (in) The application attribute to remove.


applElem.removeAttribute(applAttr);

Java Example:





public class RemoveAttribute extends ApplicationElementExampleAbstract {

/**

* The main program. Example remove the attribute with the name "NewAttribute" from

* the element.


*/


try {





// be a superuser.



ApplicationAttribute aa = ae.getAttributeByName("NewAttribute");

// Remove the attribute.

ae.removeAttribute(aa);





close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_FOUNDAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.AutogenAttrTest.testCreateAutogenAttr()


© 2015/08/19 Version 1.33




5.5.29 removeInstance of interface ApplicationElement

Purpose:

Remove an instance from the application element.It is allowed to remove an instance outside a transaction but it is recommended to activate atransaction.The instance is removed from the server when the transaction is committed. If the recursive�ag is set all children of the instance are also deleted. Removing instances is allowed only ifthere are no references(relations) to this instance. If the recursive �ag is set a reference toone of the children is not allowed and will cause an exception.

Note


Return:

void

Parameter:

T_LONGLONG ieId (in) The instance Id.

T_BOOLEAN recursive (in) The recursive �ag.


applElem.removeInstance(ieId,recursive);

Java Example:






public class RemoveInstance extends ApplicationElementExampleAbstract {

/**

* The main program. Example removes an instance form the application element.


*/


try {



// We know in our test database there is an instance with the Name "NewInstance".

// In case the name is not unique an exception will be thrown by the server.

InstanceElement ie = ae.getInstanceByName("NewInstance");

// Get the session.


// Start the transaction to delete the instance.


// Delete the instance with all his children.

ae.removeInstance(ie.getId(), true);


ie.destroy();


© 2015/08/19 Version 1.33




// Close the transaction.



close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_REFERENCESAO_IMPLEMENTATION_PROBLEMAO_NOT_FOUNDAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.ford.FordElementTest.testCreateFordElement()test.highqsoft.odsapi.ford.FordMesaurementTest.testCreateMeasurementDoubleLc()test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()....

5.5.30 setBaseElement of interface ApplicationElement

Purpose:

Set or modify the base element of the application element.It is allowed to modify the application element outside a transaction but it is recommendedto activate a transaction.The assignment to the current base element is overwritten. If there are instances of theapplication element or references to the application element an exception is thrown.

Note


Return:

void

Parameter:

BaseElement baseElem (in) The base element.


applElem.setBaseElement(baseElem);


© 2015/08/19 Version 1.33




Java Example:








public class SetBaseElement extends ApplicationElementExampleAbstract {

/**

* The main program. Example set the base type of an element to another base type. We search in the storage for the

* element Log, which is derived from AoLog and change the base type to AoAny.

*

* @param args

* not used.

*/


try {

// Get the session




// Get the base element of the type "AoAny"

BaseElement be = bs.getElementByType("AoAny");



// Get the element.

ApplicationElement ae = as.getElementByName("Log");



// be a superuser.


try {

// Set the base type

ae.setBaseElement(be);





// Report the error



}



close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_INSTANCESAO_HAS_REFERENCESAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTED


© 2015/08/19 Version 1.33




AO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()

5.5.31 setInitialRightRelation of interface ApplicationElement

Purpose:

Set for the given application element, which relation will be used to determine the initialrights for the new created instances.

Note


Return:

void

Parameter:

ApplicationRelation applRel (in) The application relation which will be used to determine theinitial rights. The relation range of the application relation must be [1:1] otherwise the servercan not �nd an unique instance element to retrieve the initial rights.

T_BOOLEAN set (in) Set or remove the relation for the initial rights. If this parameter istrue the relation will be set otherwise removed.


applElem.setInitialRightRelation(applRel,set);

See also:

setElementInitialRightRelation of interface ApplElemAccess

Errors:


Tested by:


© 2015/08/19 Version 1.33




5.5.32 setInitialRights of interface ApplicationElement

Purpose:

The given user group the initial rights should be set for. <rights> de�nes the rights to setor to clear. If the parameter <set> is set to 'set', the rights in <rights> are set all othersare cleared. If the parameter <set> is set to 'add', the rights in <rights> are added to theexisting rights. If the parameter <set> is set to 'remove', the rights in <rights> are removedfrom the existing rights.

Return:

void

Parameter:

InstanceElement usergroup (in) The user group for which the initial rights will be modi�ed.

T_LONG rights (in) The new initial rights for the user group. The rights constants arede�ned in the interface SecurityRights. The interface de�nition language IDL does not allowto set the values of enumerations thus the constant de�nitions had to be done in an interface.

T_LONGLONG refAid (in) The Id of referencing application element to which the initialrights will be applied. If no refAid is set the initial rights will be used for each new instanceelement independent of the application element.



applElem.setInitialRights(usergroup,rights,refAid,set);

Java Example:










public class SetInitialRights extends ApplicationElementExampleAbstract {

/**

* The main program. Example add the READ-right for the usegroup with the name

* "admin" to the element as initial right, no reference application element id

* is given.


*/


try {

// Get the session


© 2015/08/19 Version 1.33












// Get the element.


int rights = SecurityRights.SEC_READ;

// Set the initial right.

ae.setInitialRights(ieUsg, rights, new T_LONGLONG(0,0), RightsSet.ADD_RIGHT);

System.out.println("The initial right is added.");



ieUsg.destroy();


close();


// Report the error



}

}

}

See also:

setElementInitialRights of interface ApplElemAccess

Errors:


Tested by:

test.highqsoft.odsapi.security.ApplModelCheckTest.testApplElemAccessgetInitialRightReference()test.highqsoft.odsapi.security.InstanceAttributeCheckTest.testCreateElementAttributeSecurity()test.highqsoft.odsapi.security.InstanceConcurrentCheckTest.testConcurrentApplElemAccess()test.highqsoft.odsapi.security.Mantis5244Test.testCleanupModelPart()test.highqsoft.odsapi.security.SecurityTestCase.setIniRights()

5.5.33 setName of interface ApplicationElement

Purpose:

Set the name of the application element.It is allowed to modify the application element outside a transaction but it is recommendedto activate a transaction.The name of the application element must be unique.The name of an application element must not exceed the maximum name length of theunderlying physical storage. Current server implementations restrict it to 30 characters.


© 2015/08/19 Version 1.33




Note


Return:

void

Parameter:

Name aeName (in) The application element name.


applElem.setName(aeName);

Java Example:

See method createElement of interface ApplicationStructure (p. 252)

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_DUPLICATE_NAMEAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.changemodel.CheckLockTest.testCheckLock()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()....

5.5.34 setRights of interface ApplicationElement

Purpose:

The given user group the rights should be set for. <rights> de�nes the rights to set or to clear.If the parameter <set> is set to 'set', the rights in <rights> are set, all others are cleared. Ifthe parameter <set> is set to 'add', the rights in <rights> are added to the existing rights. Ifthe parameter <set> is set to 'remove', the rights in <rights> are removed from the existingrights.

Note


Return:

void


© 2015/08/19 Version 1.33




Parameter:





applElem.setRights(usergroup,rights,set);

Java Example:









public class SetRights extends ApplicationElementExampleAbstract {

/**

* The main program. Example add the GRANT-right for the usegroup with the name

* "admin" to the element.


*/


try {

// Get the session









// Get the element.


int rights = SecurityRights.SEC_GRANT;

// Set the right.

ae.setRights(ieUsg, rights, RightsSet.ADD_RIGHT);




ieUsg.destroy();


close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33




See also:

setElementRights of interface ApplElemAccess

Errors:


Tested by:

test.highqsoft.odsapi.security.ApplElemAccessWriteTest.testCheckReadInsert()test.highqsoft.odsapi.security.ApplModelCheckTest.testApplElemAccessgetInitialRightReference()test.highqsoft.odsapi.security.AttributeCheckTest.testCheckAttributeGrantRight()test.highqsoft.odsapi.security.CreateInstanceElementRightTest.testCheckElementRights()test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()....

5.5.35 setSecurityLevel of interface ApplicationElement

Purpose:

Set the security level for the given application element. If the security level is added the clientis responsible for the access control list entries of the existing objects.

Note


Return:

void

Parameter:

T_LONG secLevel (in) The new security level. The security level constants are de�ned inthe interface SecurityLevel. The interface de�nition language IDL does not allow to set thevalues of enumerations thus the constant de�nitions had to be done in an interface.

RightsSet set (in) What to do with the new security level.


applElem.setSecurityLevel(secLevel,set);

Java Example:




© 2015/08/19 Version 1.33



5.6 ApplicationRelation 223




public class SetSecurityLevel extends ApplicationElementExampleAbstract {

/**

* The main program. Example remove the ATTRIBUTE security level from the element.


*/


try {

// Get the session




// Get the element.


int secLevel = 4; // ATTRIBUTE

// Set the right.

ae.setSecurityLevel(secLevel, RightsSet.REMOVE_RIGHT);

System.out.println("The security level is removed.");




close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.security.ApplModelCheckTest.testApplElemAccessgetInitialRightReference()test.highqsoft.odsapi.security.AttributeCheckTest.testCheckAttributeGrantRight()test.highqsoft.odsapi.security.CreateInstanceElementRightTest.testCheckElementRights()test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()test.highqsoft.odsapi.security.InitialRightsTest.testDeleteCreatedInstances()....

5.6 ApplicationRelation

Package:

org.asam.ods

Description:


© 2015/08/19 Version 1.33




The ASAM ODS application relation interface.

A relation is the connection between two ASAM ODS elements; it may be navigated in both

directions. The get- and set- methods are de�ned from the �rst element, the getInverse- and

setInverse- methods work from the second element.

A relation is the connection between two ASAM-ODS elements in both directions. There is noinverse relation, the OO-API allows to ask for the inverse name of the relation but it is onlyone relation. The get- and set- methods are de�ned from the �rst element, the getInverse- andsetInverse- methods works from the second element.

E.g.

Element 1

Element 2

Children inverse Parent

Figure 5.1: Example of relation

method getRelationName returns "Children" method getInverseRelationName returns "Parent"

method getElem1 will return 'Element 1' method getElem2 will return 'Element 2'

When we create a relation between two elements the inverse way is also created and when weremove a relation the inverse way is also removed. This is valid for the application structure andthe instance structure.

When a new relation is created take care the correct 'Element 1' and 'Element 2' are given at thecorresponding set function.

5.6.1 The Relation Type

The RelationType is an ASAM ODS de�ned enumeration. There are three types of the relations:

FATHER_CHILD

there is a hierachical relation between two elements. The FATHER_CHILD relation is usedfor the uniqueness of the instance by the ASAM-PATH.

E.g. AoMeasurement and AoMeasurementQuantity.

INFO

there is an informational relation between the two elements.


© 2015/08/19 Version 1.33




E.g. AoMeasurementQuantity and AoQuantity

INHERITANCE

there is an inheritance relation between two elements, the relation is only allowed betweentwo elements of the same basetype.

E.g. AoSubTest and AoSubTest.

5.6.2 The Relationship

The Relationship is an ASAM ODS de�ned enumeration. Beside the type of relation we have alsothe relationships. If we like to ask for the related elements we need the relationship and not therelation type. The following relationships are de�ned:

FATHER

The father element is requested of the relations of the type FATHER_CHILD. The fatherelement is 'element 1' of the relation.

CHILD

The child element is requested of the relations of the type FATHER_CHILD. The childelement is the 'element 2' of the relation.

INFO_TO

The target element is requested of the relations of the type INFO, the target element is the'element 2' of relation.

INFO_FROM

The source element is requested of the relations of the type INFO, the target element is the'element 1' of relation.

INFO_REL

The direction of the informational relation doesn't matter, so all elements connected with aninformational relation are reported.

SUPER

The super element of the inheritance relation is given. The super element is the 'element 1'of the relation.

SUB

The sub element of the inheritance relation is given, the sub element is the 'element 2' of therelation.

ALL_REL

All related elements of all kind (types) of relation are reported.

The method CreateRelation and RemoveRelation of the interface InstanceElement is able to rec-ognize which application element of the instance elements are the 'element 1' or 'element 2' of theapplication relation.


© 2015/08/19 Version 1.33




5.6.3 The Relation Range

The RelationRange is an ASAM ODS de�ned structure. The relation range gives the number ofthe allowed relation from one element to the ohter element of the relation. The following relationranges are de�ned:

� Min is the minimum number of relations. (0 or 1)

� Max is the maximum number of relations (1 or -1 Many).

For the relation range the methods getRelationRange, getInverseRelationRange, setRelationRangeand setInverseRelationRange are introduced.

Using this relation range the obligatory �ag is not longer needed at the relation, so the correspond-ing methods on the interfaces BaseRelation and ApplicationRelation are also not longer needed.If the mininum number of the relation range is 1 then the relation is required.

If there is a base reference the relation type and the relation range of the base reference are usedat the application reference. If there is no base reference the default relation type will be INFOand a relationship INFO_TO. Depending on the datatype of the attribute the relation range isset. A datatype of DT_∗ means a relation range of 0:1. A datatype of DS_∗ means a relationrange of 0:MANY.

The relation range has the following structure:

typedef struct RELATIONRANGE RelationRange;

struct RELATIONRANGE {

T_SHORT min;

T_SHORT max;

};

The �elds means:

min

The minimum number of relations, 0 or 1. If the minimum value is 1 there must be always areference set. The value -2 means not initialised.

max

The maximum number of relation. The value -1 means MANY. There is no speci�ed maximumany amount greater equal minimum is allowed. The value -2 means not initialised.

E.g


© 2015/08/19 Version 1.33




AoQuantityGroup

AoQuantity

Figure 5.2: Example of N:M relation

5.6.4 Modi�cation of the relation type.

It is only allowed to modify a relation type when no base relation is given, otherwise the exceptionAO_HAS_BASE_RELATION is thrown.

It is not allowed to set the relation type FATHER_CHILD, these relation type is reserved for thebase model. The two relationtypes which can be set are INFO or INHERITANCE.

The relationship is set automatic when the relation type is set, the maximum of the relation rangedetermines the relationship between the elements of the relation.

RelationType maximum ofRelationRange

maximum ofinverseRelationRange

Relationship

INFO 1 1 exception,AO_INVALID_RELATION_TYPE

INFO 1 MANY INFO_TOINFO MANY 1 INFO_FROMINFO MANY MANY INFOINHERITANCE 1 1 exception,

AO_INVALID_RELATION_TYPEINHERITANCE 1 MANY SUPERTYPEINHERITANCE MANY 1 SUBTYPEINHERITANCE MANY MANY exception,

AO_INVALID_RELATION_TYPE

The method setRelationType of interface ApplicationRelation (p. 248) allows modi�cationof the relationtype.

5.6.5 The attribute of a relation.

The relations where one of the relations ranges The Relation Range (p. 226) has a max of 1is a so called 1:N relation. The relation is stored in an attribute or database column at the ele-ment where the relation has the max relation range of 1. The relation name can be used as anattribute in the query for the selections or the conditions, for insert and update of the instances


© 2015/08/19 Version 1.33




this attribute can be used also. The usage of this attribute can be very helpful and guarantee highperformance at structures the methods getInstances of interface ApplElemAccess (p. 113),getInstancesExt of interface ApplElemAccess (p. 116), insertInstances of interface Ap-plElemAccess (p. 129) and updateInstances of interface ApplElemAccess (p. 143).

5.6.6 Create an new ApplicationRelation.

The following code snipper shows how a new ApplicationRelation can be created in the applicationmodel. The order of the calls is important, otherwise the implementation is not able to set therelation and inverse relation names correct and writing instances to the relation will given doublerelation tags at the instances in an ATF/XML �le.

ApplicationStructure target; // The target application structure

ApplicationRelation targetAr; // The target application relation.

ApplicationElement targetAe; // The first element of the new relation

ApplicationElement targetAe2; // The second element of the new relation

..............

// Create the relation

targetAr = target.createRelation();

// Set the elements.

targetAr.setElem1(targetAe);

targetAr.setElem2(targetAe2);

// Set the name and inverse name

targetAr.setRelationName(sourceAr.getRelationName());

targetAr.setInverseRelationName(sourceAr.getInverseRelationName());

// Set the relation range and inverse relation range

targetAr.setRelationRange(sourceAr.getRelationRange());

targetAr.setInverseRelationRange(sourceAr.getInverseRelationRange());

// Check if the source has an base relation

BaseRelation br = sourceAr.getBaseRelation();

if (br != null) {

// Get the base relation name

String brName = br.getRelationName();

// Get the base elements

BaseElement targetBe = targetAe.getBaseElement();

BaseElement targetBe2 = targetAe2.getBaseElement();

BaseRelation targetBr=null;

// Search for the base relation in the target base structure

BaseRelation brList[] = targetBe.getAllRelations();

for (int brIndex = 0; brIndex < brList.length && targetBr == null; brIndex++)

{

if (brList[brIndex].getRelationName().compareToIgnoreCase(brName)==0) {

if (targetBe2.getType().compareToIgnoreCase(brList[brIndex].getElem2().g

etType())==0) {

targetBr = brList[brIndex];

}

}

}

// The base relation found in the target

if (targetBr != null) {

// Check if the name of the base relation match.

if (targetBr.getRelationName().compareToIgnoreCase(brName)==0) {

// Write only the base relation when the name of the relation match.

targetAr.setBaseRelation(targetBr);

if ((messenger != null) && (messenger.isLoggable(Level.INFO))) {

String msg = MessageFormat.format(Messages.getString("Info.SetBaseRel

ation"), new Object[] {brName});

messenger.info(msg);

}

}

}

} else {


© 2015/08/19 Version 1.33




// Set the relation type.

targetAr.setRelationType(sourceAr.getRelationType());

}

5.6.7 Java Examples of ApplicationRelation


package api.methods.applicationrelation;







/** The examples of the methods of ApplicationRelation are all derived from this class */

public class ApplicationRelationExampleAbstract extends AoSessionExampleAbstract {

// The session

protected static AoSession aoSess = null;



// The application element


/**


*




*/


if (as == null) {


aoSess = connect();

}


}

return (as);

}

/**


*




*/


if (ae == null) {


ae = as.getElementsByBaseType("AoTest")[0];

}

return ae;

}

/**

* Get the element with a given name.

*

* @param aeName


© 2015/08/19 Version 1.33








*/

protected static ApplicationElement getApplicationElement(String aeName) throws AoException {

if (ae == null) {



}

return ae;

}

/**

* Get the relation with the given base name of the application element with the given name.

*

* @param aeName


* @param brName

* the name of the base relation

* @return the application relation.



*/

protected static ApplicationRelation getApplicationRelation(String aeName, String brName) throws AoException {

if (ae == null) {

ApplicationElement ae = getApplicationElement(aeName);

}

ApplicationRelation[] arList = ae.getRelationsByBaseName(brName);

return arList[0];

}

/**

* Get the 'children' relation with the given name of the application element.

*

* @return the application relation.



*/

protected static ApplicationRelation getApplicationRelation() throws AoException {

if (ae == null) {


}

ApplicationRelation[] arList = ae.getRelationsByBaseName("children");

return arList[0];

}

/**


*



*/



aoSess.close();

aoSess = null;

}

}

/**

* Get the session.

*





© 2015/08/19 Version 1.33




*/



aoSess = connect();

}

return (aoSess);

}

}

5.6.8 getBaseRelation of interface ApplicationRelation

Purpose:

Get the base relation of the application relation.

Return:

BaseRelation baseRel The base relation of the application relation. A 'null' is returned if theapplication relation has no base relation.

Parameter:

None.


BaseRelation baseRel = applRel.getBaseRelation();

Java Example:




import org.asam.ods.BaseRelation;

public class GetBaseRelation extends ApplicationRelationExampleAbstract {

/**

* Example to get the base relation of an relation.


*/


try {

// Get the relation

ApplicationRelation aa = getApplicationRelation();

// Get the base relation.

BaseRelation ba = aa.getBaseRelation();

if (ba != null) {

System.out.println("The relation is derived from a base relation.");

} else {

System.out.println("The relation is an application relation.");

}


// Report the error



}

}

}


© 2015/08/19 Version 1.33




Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()....

5.6.9 getElem1 of interface ApplicationRelation

Purpose:

Get the �rst application element of the application relation.

Return:

ApplicationElement applElem The �rst application element of the application relation.

Parameter:

None.


ApplicationElement applElem = applRel.getElem1();

Java Example:





public class GetElem1 extends ApplicationRelationExampleAbstract {

/**

* Example to get the element of a relation where the

* relation starts.


*/


try {

// Get the relation

ApplicationRelation ar = getApplicationRelation();

// Get the element where the relation starts.

ApplicationElement be = ar.getElem1();



// Report the error


© 2015/08/19 Version 1.33






}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()....

5.6.10 getElem2 of interface ApplicationRelation

Purpose:

Get the second application element of the application relation.

Return:

ApplicationElement applElem The second application element of the application relation.

Parameter:

None.


ApplicationElement applElem = applRel.getElem2();

Java Example:





public class GetElem2 extends ApplicationRelationExampleAbstract {

/**

* Example to get the element of a relation where the

* relation ends.


*/


try {


© 2015/08/19 Version 1.33




// Get the relation


// Get the element where the relation ends.

ApplicationElement ae = ar.getElem2();



// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelationApplElemAccess()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()....

5.6.11 getInverseRelationName of interface ApplicationRelation

Purpose:

Get the inverse name of the application relation. The inverse name of an application relationis the name of the relation seen from the other application element.

Return:

Name arInvName The inverse name of the application relation.

Parameter:

None.


Name arInvName = applRel.getInverseRelationName();

Java Example:




public class GetInverseRelationName extends ApplicationRelationExampleAbstract {


© 2015/08/19 Version 1.33




/**

* Example to get name of the inverse relation.


*/


try {

// Get the relation


// Get the name of the inverse relation

String invArName = ar.getInverseRelationName();

System.out.println("The name of the inverse relation is " + invArName);


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.odsapi.ford.FordTest.testCreateManagementData()test.highqsoft.odsapi.performance.InsertInstancesPerfIT.testInsertInstances()test.highqsoft.odsapi.read.ExtendedQueryTest.testAllAttr()test.highqsoft.odsapi.read.InstanceRelationTest.testGetRelationInstances()....

5.6.12 getInverseRelationRange of interface ApplicationRelation

Purpose:

Get the inverse relation range of the application relation. The range value describes theallowed number of the relations from one element to the other element of the relation. Therelation range is de�ned by a min and a max value.

Return:

RelationRange arRange The inverse relation range of the application relation.

Parameter:

None.


RelationRange arRange = applRel.getInverseRelationRange();

Java Example:



© 2015/08/19 Version 1.33







public class GetInverseRelationRange extends ApplicationRelationExampleAbstract {

/**

* Example to get inverse range of the relation.


*/


try {

// Get the relation


// Get the inverse relation relation.

RelationRange rr = ar.getInverseRelationRange();

// min == 1 means required relation

System.out.print("The inverse range of the relation is: min " + rr.min + " max ");

// max == -1 means Many

if (rr.max == -1) {

System.out.println("Many");

} else {

System.out.println(rr.max);

}


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.odsapi.read.MatrixTest.testCreateRelationBetweenNewAndExistingInstance()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()test.highqsoft.odsapi.AthosTestCase.deleteteInstanceElementWithSubelements()....

5.6.13 getInverseRelationship of interface ApplicationRelation

Purpose:

Get the inverse relationship of the application relation.

Return:

Relationship relationship The inverse relationship of the application relation.


© 2015/08/19 Version 1.33




Parameter:

None.


Relationship relationship = applRel.getInverseRelationship();

Java Example:





public class GetInverseRelationship extends ApplicationRelationExampleAbstract {

/**

* Example to get the inverse relationship of the relation.


*/


try {

// Get the relation

ApplicationRelation br = getApplicationRelation();

// Get the inverse relationship.

Relationship rr = br.getInverseRelationship();

System.out.print("The inverse relationship of the relation is: " + rr.value());


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CreateNewInstanceElementTest.testCreateFKInstances()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFileWithoutValues()....

5.6.14 getRelationName of interface ApplicationRelation

Purpose:

Get the name of the application relation.


© 2015/08/19 Version 1.33




Return:

Name arName The name of the application relation.

Parameter:

None.


String arName = applRel.getRelationName();

Java Example:




public class GetRelationName extends ApplicationRelationExampleAbstract {

/**

* Example to get name of a relation.


*/


try {

// Get the relation

ApplicationRelation br = getApplicationRelation();

// Get the name.


System.out.println("The name of the relation is " + brName);


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.DescElemQueryTestIT.testQueryChildren()test.highqsoft.avalon.ExtQueryTestIT.main()test.highqsoft.avalon.ExtQueryTestIT.testCatalogElements()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelationApplElemAccess()....


© 2015/08/19 Version 1.33




5.6.15 getRelationRange of interface ApplicationRelation

Purpose:

Get the relation range of the application relation. The range value describes the allowednumber of relations from one element to the other element of the relation. The relation rangeis de�ned by a min and a max value.

Return:

RelationRange arRange The relation range of the application relation.

Parameter:

None.


RelationRange arRange = applRel.getRelationRange();

Java Example:





public class GetRelationRange extends ApplicationRelationExampleAbstract {

/**

* Example to get range of the relation.


*/


try {

// Get the relation


// Get the relation range.

RelationRange rr = ar.getRelationRange();


System.out.print("The range of the relation is: min " + rr.min + " max ");


if (rr.max == -1) {


} else {


}


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.performance.InsertInstancesPerfIT.testInsertInstances()test.highqsoft.odsapi.read.ExtendedQueryTest.testAllAttr()....

5.6.16 getRelationship of interface ApplicationRelation

Purpose:

Get the relationship of the application relation.

Return:

Relationship relationship The relationship of the application relation.

Parameter:

None.


Relationship relationship = applRel.getRelationship();

Java Example:





public class GetRelationship extends ApplicationRelationExampleAbstract {

/**

* Example to get relationship of the relation.


*/


try {

// Get the relation


// Get the relationship.

Relationship rr = ar.getRelationship();

System.out.print("The relationship of the relation is: " + rr.value());


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CreateNewInstanceElementTest.testCreateFKInstances()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFileWithoutValues()....

5.6.17 getRelationType of interface ApplicationRelation

Purpose:

Get the relation type of the application relation.

Return:

RelationType arType The relation type of the application relation.

Parameter:

None.


RelationType arType = applRel.getRelationType();

Java Example:





public class GetRelationType extends ApplicationRelationExampleAbstract {

/**

* Example to get type of the relation.


*/


try {

// Get the relation


// Get the relation type.

RelationType rt = ar.getRelationType();

System.out.print("The type of the relation is: " + rt.value());


// Report the error



}

}

}


© 2015/08/19 Version 1.33




Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()

5.6.18 setBaseRelation of interface ApplicationRelation

Purpose:

Set the base relation of the application relation.It is allowed to modify the application relation outside a transaction but it is recommendedto activate a transaction.The relation type and relation range is copied from the base relation. The previous valueswill be lost.

Note

It is only allowed to modify the application relation if there are no instances at both applicationelements.See also Transaction handling in ODS API. (p. 15)

Return:

void

Parameter:

BaseRelation baseRel (in) The base relation.


applRel.setBaseRelation(baseRel);

Java Example:

See method createRelation of interface ApplicationStructure (p. 257)

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATIONAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE


© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.ods530.AoFileCreateTest.testCreateElement()test.highqsoft.odsapi.security.Mantis5244Test.testCleanupModelPart()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()....

5.6.19 setElem1 of interface ApplicationRelation

Purpose:

Set the �rst application element of the application relation.It is allowed to modify the application relation outside a transaction but it is recommendedto activate a transaction.

Note


Return:

void

Parameter:

ApplicationElement applElem (in) The application element.


applRel.setElem1(applElem);

Java Example:


Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_ELEMENTAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.ods530.AoFileCreateTest.testCreateElement()test.highqsoft.odsapi.security.InstanceAttributeCheckTest.testCreateElementAttributeSecurity()....


© 2015/08/19 Version 1.33




5.6.20 setElem2 of interface ApplicationRelation

Purpose:

Set the second application element of the application relation.It is allowed to modify the application relation outside a transaction but it is recommendedto activate a transaction.

Note


Return:

void

Parameter:

ApplicationElement applElem (in) The application element.


applRel.setElem2(applElem);

Java Example:


Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_ELEMENTAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:


5.6.21 setInverseRelationName of interface ApplicationRelation

Purpose:

Set the inverse name of the application relation.It is allowed to modify the application relation outside a transaction but it is recommendedto activate a transaction.


© 2015/08/19 Version 1.33




Note

It is only allowed to modify the application relation if there are no instances at both applicationelements. See also Transaction handling in ODS API. (p. 15)

Return:

void

Parameter:

Name arInvName (in) The inverse application relation name.


applRel.setInverseRelationName(arInvName);

Errors:


Tested by:


5.6.22 setInverseRelationRange of interface ApplicationRelation

Purpose:

Set the inverse relation range of an application relation. The range value describes the allowednumber of relations from one element to the other element of the relation. The relation rangeis de�ned by a min and a max value.It is allowed to modify the application relation outside a transaction but it is recommendedto activate a transaction.It is only allowed to set the relation type if no base relation is de�ned.

Note


Return:

void


© 2015/08/19 Version 1.33




Parameter:

RelationRange arRelationRange (in) The inverse relation range.


applRel.setInverseRelationRange(arRelationRange);

Java Example:


Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_BASE_RELATIONAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATION_RANGEAO_IS_BASE_RELATIONAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:


5.6.23 setRelationName of interface ApplicationRelation

Purpose:

Set the name of an application relation.It is allowed to modify the application relation outside a transaction but it is recommendedto activate a transaction.The name of an application attribute must not exceed the maximum name length of theunderlying physical storage. Current server typically implementations restrict it to 30 char-acters.

Note


Return:

void

Parameter:

Name arName (in) The application relation name.


© 2015/08/19 Version 1.33





applRel.setRelationName(arName);

Java Example:


Errors:


Tested by:


5.6.24 setRelationRange of interface ApplicationRelation

Purpose:

Set the relation range of the application relation. The range value describes the allowednumber of relations from one element to the other element of the relation. The relation rangeis de�ned by a min and a max value.It is allowed to modify the application relation outside a transaction but it is recommendedto activate a transaction.It is only allowed to set the relation type if no base relation is de�ned.

Note


Return:

void

Parameter:

RelationRange arRelationRange (in) The relation range.


applRel.setRelationRange(arRelationRange);


© 2015/08/19 Version 1.33




Java Example:


Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_BASE_RELATIONAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATION_RANGEAO_IS_BASE_RELATIONAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:


5.6.25 setRelationType of interface ApplicationRelation

Purpose:

Set the relation type of the application relation.It is allowed to modify the application relation outside a transaction but it is recommendedto activate a transaction.The relationship is automatically set when the relation type is set. It is only allowed to setthe relation type if no base relation is de�ned.It is only allowed to modify a relation type when no base relation is given, otherwise theexception AO_HAS_BASE_RELATION is thrown.It is not allowed to set the relation type FATHER_CHILD. This relation type is reserved forthe base model. The two relation types which can be set are INFO or INHERITANCE.The relationship is set automatically when the relation type is set, the maximum of the relationrange determines the relationship between the elements of the relation, as is described in thefollowing table:R.Type | max R.Range | max inv. R.Range | Relationship------------+-------------+------------------+-------------INFO | 1 | 1 | exception, AO_INVALID_RELATION_TYPE------------+-------------+------------------+-------------INFO | 1 | MANY | INFO_TO------------+-------------+------------------+-------------INFO | MANY | 1 | INFO_FROM------------+-------------+------------------+-------------INFO | MANY | MANY | INFO------------+-------------+------------------+-------------INHERITANCE | 1 | 1 | exception, AO_INVALID_RELATION_TYPE------------+-------------+------------------+-------------


© 2015/08/19 Version 1.33



5.7 ApplicationStructure 249

INHERITANCE | 1 | MANY | SUPERTYPE------------+-------------+------------------+-------------INHERITANCE | MANY | 1 | SUBTYPE------------+-------------+------------------+-------------INHERITANCE | MANY | MANY | exception, AO_INVALID_RELATION_TYPE

Note


This method is only required to add subclasses to the application model, at the moment Inheritanceis only implemented for reading with is existing in the model.

Return:

void

Parameter:

RelationType arRelationType (in) The relation type.


applRel.setRelationType(arRelationType);

Java Example:


Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_BASE_RELATIONAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATION_TYPEAO_IS_BASE_RELATIONAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()

5.7 ApplicationStructure

Package:

org.asam.ods

Description:

The ASAM ODS application structure interface.


© 2015/08/19 Version 1.33




5.7.1 Java Examples of ApplicationStructure


package api.methods.applicationstructure;





/** The examples of the methods of ApplicationStructure are all derived from this class */

public class ApplicationStructureExampleAbstract extends AoSessionExampleAbstract {

// The session


/**




*/



aoSess = connect();

}

return (aoSess.getApplicationStructure());

}

/**



*/



aoSess.close();

aoSess = null;

}

}

/**

* Get the session.



*/



aoSess = connect();

}

return(aoSess);

}

}

5.7.2 check of interface ApplicationStructure

Purpose:

Check the application model for ASAM ODS conformity. The �rst error found is reported byan exception. The following checks are performed:- Each application element must be derived from a valid base element.- An application attribute is derived from one base attribute. It is not allowed to derive more


© 2015/08/19 Version 1.33




the one application attribute from the same base attribute. It is allowed that applicationattributes are not derived from any base attribute.- All application elements must have at least the mandatory attributes.- All application elements must be identifyable by a unique Asam path. No "�oating" appli-cation elements are allowed.- All relations required by the base model must be present.

Note

This method is not complete implemented.

Return:

void

Parameter:

None.


applStruct.check();

Java Example:




public class Check extends ApplicationStructureExampleAbstract {

/**

* The main program.


*/


try {


try {

as.check();

System.out.println("There is no problem at the application model.");


System.err.println("Found a problem at the application model.");


}


close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOSTAO_DUPLICATE_BASE_ATTRIBUTEAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATION


© 2015/08/19 Version 1.33




AO_MISSING_ATTRIBUTEAO_MISSING_RELATIONAO_MISSING_APPLICATION_ELEMENTAO_NOT_IMPLEMENTEDAO_NO_PATH_TO_ELEMENTAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureCheck()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationStructureCheck.ThreadTestApplicationStructureCheck()test.highqsoft.odsapi.ods530.AoFileCreateTest.testCreateElement()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()

5.7.3 createElement of interface ApplicationStructure

Purpose:

Create a new application element in the application model.It is allowed to modify the application model outside a transaction but it is recommended toactivate a transaction.The information whether or not the new application element is a top level element is takenfrom the speci�ed base element. The Id of the application element is set automatically. Themandatory base attributes are created automatically. Optional attributes have to be createdby the calling program. The application attribute interface methods may be used to modifythe attributes.

Note

It is only allowed to modify the application structure if the involved application elements haveno instances. See also Transaction handling in ODS API. (p. 15)

Return:

ApplicationElement applElem The new application element.

Parameter:

BaseElement baseElem (in) The base element from which the application element is derived.


ApplicationElement applElem = applStruct.createElement(baseElem);

Java Example:









© 2015/08/19 Version 1.33




public class CreateElement extends ApplicationStructureExampleAbstract {

/**

* The main program. Example creates a new element call "NewElement" of the base type "AoAny"

*

* @param args

* not used.

*/


try {

// Get the session




// Get the base element of the type "AoAny"

BaseElement be = bs.getElementByType("AoAny");





// be a superuser.


try {

// Create the element.

ApplicationElement ae = as.createElement(be);

// Set the name of the element

ae.setName("NewElement");





// Report the error



}



close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.changemodel.CheckLockTest.testCheckLock()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()....


© 2015/08/19 Version 1.33




5.7.4 createEnumerationDe�nition of interface ApplicationStructure

Purpose:

Create a new enumeration de�nition. This method modi�es the application model and is onlyallowed for the super user.

Note


Return:

EnumerationDe�nition newEnum The new created enumeration

Parameter:

T_STRING enumName (in) Name of the enumeration


EnumerationDefinition enumDef asObj.createEnumerationDefinition(enumName);

Java Example:





public class CreateEnumerationDefinition extends ApplicationStructureExampleAbstract {

/**

* The main program. Example creates a new enumeration definition with the new "NewEnum" and two item name

* "FirstItem" and "SecondItem"

*

* @param args

* not used.

*/


try {





// be a superuser.


try {

// Create the new enumeration

EnumerationDefinition ed = as.createEnumerationDefinition("NewEnum");

// Add the items.

ed.addItem("FirstItem");

ed.addItem("SecondItem");





// Report the error



}



© 2015/08/19 Version 1.33





close();


// Report the error



}

}

}

Since

ASAM ODS 5.0

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVEAO_ACCESS_DENIED

Tested by:

test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.EnumerationTest.testAddAndSetEnumeration()

5.7.5 createInstanceRelations of interface ApplicationStructure

Purpose:

Create the relation between a list of instances. The number of instances in both list mustbe identical. The application element of the instances in each list must be identical. Theapplication elements must match the application elements of the application relation. Theindex in the list of the instances de�nes related instances.

Note


Return:

void

Parameter:

ApplicationRelation applRel (in) The application relation.

InstanceElementSequence elemList1 (in) The list with the instances of one application elementfor which the relation will be created.

InstanceElementSequence elemList2 (in) The list with the related instances.


© 2015/08/19 Version 1.33





ApplicationStructure as;

InstanceElement elemList1[];

InstanceElement elemList2[];

ApplicationRelation applRel;

as.createInstanceRelations(applRel, elemList1, elemList2);

Since

ASAM ODS 5.0

Errors:


Tested by:

test.highqsoft.odsapi.read.MeasurementIT.testCompareNumberOfValues()test.highqsoft.odsapi.ORMETest.testORMECreate()test.highqsoft.odsapi.WriteInstanceElementTest.testCompareCopied()

5.7.6 createRelation of interface ApplicationStructure

Purpose:

Create a new relation.It is allowed to modify the application model outside a transaction but it is recommended toactivate a transaction.The relation is part of the application model. The application relation interface methods maybe used to modify the relation.The default properties of a new application relation are:BaseRelation NULLElement1 NULLElement2 NULLRange -2, -2Name NULLType INFOWhen element 1 or element 2 is set before the name of the relation is speci�ed, the name ofthe application relation is set to "AUTOGEN".

Note

It is only allowed to modify the application structure if the involved application elements haveno instances. See also Transaction handling in ODS API. (p. 15)

Return:

ApplicationRelation applRel The new application relation.


© 2015/08/19 Version 1.33




Parameter:

None.


ApplicationRelation applRel = applStruct.createRelation();

Java Example:








public class CreateRelation extends ApplicationStructureExampleAbstract {

/**

* The main program. Example create a relation between the "NewElement" and the element derived from AoTest.

*

* @param args

* not used.

*/


try {

// Get the session



ApplicationElement[] aeTest = as.getElementsByBaseType("AoTest");

ApplicationElement ae = as.getElementByName("NewElement");



// be a superuser.


try {

// Create the relation

ApplicationRelation ar = as.createRelation();

// Set the elements of the relation

ar.setElem1(aeTest[0]);

ar.setElem2(ae);

// Set the name and the inverse name.

// The relation name is the name of at elem1.

ar.setRelationName("RelationToNewElement");

ar.setInverseRelationName("RelationToAoTest");

// Set the relation range 1 at AoTest N at NewElement

RelationRange relRange = new RelationRange((short) 0, (short) 1);

ar.setRelationRange(relRange);

RelationRange invRelRange = new RelationRange((short) 0, (short) -1);

ar.setInverseRelationRange(invRelRange);





// Report the error



}



close();


// Report the error


© 2015/08/19 Version 1.33






}

}

}

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:


5.7.7 getElementById of interface ApplicationStructure

Purpose:

Get the application element with the requested Id.

Return:

ApplicationElement applElem The requested application element.

Parameter:

T_LONGLONG aeId (in) The Id of the requested application element.


ApplicationElement applElem = applStruct.getElementById(aeId);

Java Example:






public class GetElementById extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the element with the Id 20, is available in our

* model, can cause an error at your application model.

*


© 2015/08/19 Version 1.33





*/


try {


// Get the element

ApplicationElement ae = as.getElementById(new T_LONGLONG(0,20));



close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureElements.threadApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadTestEnumerationDe�nition.threadTestEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()....

5.7.8 getElementByName of interface ApplicationStructure

Purpose:

Get the application element with the requested name.

Return:

ApplicationElement applElem The requested application element.

Parameter:

Name aeName (in) The name of the requested application element.


ApplicationElement applElem = applStruct.getElementByName(aeName);

Java Example:



© 2015/08/19 Version 1.33







public class GetElementByName extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the element "NewElement"

*


*/


try {


// Get the element




close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureElements.threadApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationStructureElements.ThreadTestApplicationStructureElements()test.highqsoft.odsapi.bosch.MultiSessionIT.threadCreate.threadCreate()test.highqsoft.odsapi.bosch.MultiSessionIT.threadDestroy.threadDestroy()....

5.7.9 getElements of interface ApplicationStructure

Purpose:

Get the application elements whose names match with the pattern. The pattern is casesensitive and may contain wildcard characters.

Return:

ApplicationElementSequence applElems The requested application elements.

Parameter:

Pattern aePattern (in) The name or the search pattern for the requested application elements.


© 2015/08/19 Version 1.33





ApplicationElement[] applElems = applStruct.getElements(aePattern);

Java Example:





public class GetElements extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the all the elements starting the name with "N"

*


*/


try {


// Get the elements the * is the pattern

ApplicationElement[] aeList = as.getElements("N*");

System.out.println("We have the " + aeList.length + " elements.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.AoFactoryTestIT.ThreadtestNewSession.run()test.highqsoft.avalon.AoFactoryTestIT.ThreadTestNewFactory.run()test.highqsoft.avalon.ApplicationElementTestIT.testExistBaseAttributes()test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()....

5.7.10 getElementsByBaseType of interface ApplicationStructure

Purpose:

Get the names of application elements that are derived from the speci�ed base element.


© 2015/08/19 Version 1.33




Return:

ApplicationElementSequence applElems The requested application element names.

Parameter:

BaseType aeType (in) The requested base element type. The base element type can be apattern.


ApplicationElement[] applElems = applStruct.getElementsByBaseType(aeType);

Java Example:





public class GetElementsByBaseType extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the all the elements with the base type "AoMeasurement"

*


*/


try {


// Get the elements with the base type, the base model is case insensitive

ApplicationElement[] aeList = as.getElementsByBaseType("aomeasurement");

System.out.println("We have the " + aeList.length + " elements.");


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_BASETYPEAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureBase.threadApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureTestIT.testGetInstances()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationStructureBase.ThreadTestApplicationStructureBase()test.highqsoft.avalon.DescElemQueryTestIT.testQueryChildren()....


© 2015/08/19 Version 1.33




5.7.11 getEnumerationDe�nition of interface ApplicationStructure

Purpose:

Get the speci�ed enumeration de�nition.

Return:

EnumerationDe�nition enumDef The enumeration de�nition.

Parameter:

T_STRING enumName (in) Name of the requested enumeration.


EnumerationDefinition enumDef = asObj.getEnumerationDefinition(enumName);

Java Example:





public class GetElementEnumerationDefinition extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the enumeration definition with the name "datatype_enum"

*


*/


try {


// Get the element

EnumerationDefinition ed = as.getEnumerationDefinition("datatype_enum");

System.out.println("We have the enumeration definition.");


close();


// Report the error



}

}

}

Since

ASAM ODS 5.0

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadTestEnumerationDe�nition.threadTestEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.testEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestEnumerationDe�nition.ThreadTestEnumerationDe�nition()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.EnumerationTest.testAddAndSetEnumeration()

5.7.12 getInstanceByAsamPath of interface ApplicationStructure

Purpose:

Get the instance element speci�ed by the ASAM path.

Return:

InstanceElement instElem The requested instance element.

Parameter:

Name asamPath (in) The ASAM path of the requested instance element.


InstanceElement instElem = applStruct.getInstanceByAsamPath(asamPath);

Java Example:





public class GetInstanceByAsamPath extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get an instance by the ASAM Path.

*


*/


try {

// We use a predefined ASAM path

String asamPath = "/[Environment]TestModel;1.0/[Unit]SEC;1.0";


// Get the instance

InstanceElement ie = as.getInstanceByAsamPath(asamPath);


// Destroy the instance again otherwise the POA map will grow

// and the performance decrease.

ie.destroy();


close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33




Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_ASAM_PATHAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.JBeamTestIT.testMeasurementJBeam()test.highqsoft.odsapi.read.AsamPathTest.main()test.highqsoft.odsapi.read.AsamPathTest.testAsamPath()test.highqsoft.odsapi.xatf.BitFieldTest.testCompareMeaBitXatf()....

5.7.13 getInstancesById of interface ApplicationStructure

Purpose:

Get the instance elements speci�ed by the sequence of element ids.

Return:

InstanceElementSequence instElems The sequence with the requested instance elements.

Parameter:

ElemIdSequence ieIds (in) The sequence with the element ids.


InstanceElement[] instElems = applStruct.getInstancesById(ieIds);

Java Example:







public class GetInstancesById extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the instances with the id's 20 and 21 of the

* element with the with the Id 23 and the instance with the Id's 4294967300 and

* 4294967301 of the element with the Id 101. This data is available in our test

* database and the example will probably report an error at you data storage.

*


*/



© 2015/08/19 Version 1.33




try {


T_LONGLONG aid1 = new T_LONGLONG(0, 23);

T_LONGLONG aid2 = new T_LONGLONG(0, 101);

ElemId[] ieIds = new ElemId[] {

new ElemId(aid1, new T_LONGLONG(0, 20)),

new ElemId(aid1, new T_LONGLONG(0, 21)),

new ElemId(aid2, new T_LONGLONG(1, 4)), // 1 * 2^32+4

new ElemId(aid2, new T_LONGLONG(1, 5)), // 1 * 2^32+5

};

// Get the instance

InstanceElement[] ieList = as.getInstancesById(ieIds);

System.out.println("We have the " + ieList.length + " instances.");

// Destroy the instance again otherwise the POA map will grow

// and the performance decrease.

for (InstanceElement ie: ieList) {

System.out.println(ie.getName());

ie.destroy();

}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_ASAM_PATHAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.ApplicationStructureTestIT.testGetInstances()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.odsapi.read.AsamPathTest.testAsamPath()test.highqsoft.odsapi.read.LocalColumnTest.testGetElementsById()test.highqsoft.odsapi.read.MeasurementIT.testCompareNumberOfValues()....

5.7.14 getRelations of interface ApplicationStructure

Purpose:

Returns the relations between two application elements.

Return:

ApplicationRelationSequence applRels The relations between the speci�ed application ele-ments.

Parameter:

ApplicationElement applElem1 (in) The �rst application element.


© 2015/08/19 Version 1.33




ApplicationElement applElem2 (in) The second application element.


ApplicationRelation[] applRels = applStruct.getRelations(applElem1, applElem2);

Java Example:






public class GetRelations extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the relations ion between the "NewElement" and the element


*


*/


try {


// Get the elements of AoTest, it is only one

ApplicationElement[] aeTest = as.getElementsByBaseType("AoTest");

// Get the element


// Get the relations.

ApplicationRelation[] arList = as.getRelations(ae, aeTest[0]);

System.out.println("We have " + arList.length + " relations.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.ApplicationStructureRelationTestIT.ThreadGetRelations.ThreadGetRelations()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()....


© 2015/08/19 Version 1.33




5.7.15 getSession of interface ApplicationStructure

Purpose:

Get the current client session in which the application model is created.

Return:

AoSession session The current client session.

Parameter:

None.


AoSession session = applStruct.getSession();

Java Example:





public class GetSession extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the session of the application structure

*


*/


try {


// Get the session.

AoSession aoSess = as.getSession();

System.out.println("We have the session.");


aoSess.close();


// Report the error



}

}

}

Errors:


Tested by:



© 2015/08/19 Version 1.33




5.7.16 getTopLevelElements of interface ApplicationStructure

Purpose:

Get the top level application elements which are inherited from the base element that matchesthe base type. If the given base type is no top level base element an exception is thrown. Atop level application element is an application element without a father.

Return:

ApplicationElementSequence applElems The top level application elements.

Parameter:

BaseType aeType (in) The requested base type. The base element type can be a pattern.


ApplicationElement[] applElems = applStruct.getTopLevelElements(aeType);

Java Example:






public class GetTopLevelElements extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the all the top level elements.

* A top level element is a element with an parent or with the parent element

* derived for AoEnvironment

*


*/


try {

// Get the session



// Get the top level elements the * is the pattern

ApplicationElement[] aeList = as.getTopLevelElements("*");

System.out.println("We have the " + aeList.length + " top level elements.");


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_BASETYPE


© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureElements.threadApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationStructureElements.ThreadTestApplicationStructureElements()test.highqsoft.odsapi.read.AsamPathTest.testAsamPath()test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()....

5.7.17 listElements of interface ApplicationStructure

Purpose:

Get the names of the application elements that match with the pattern. The pattern is casesensitive and may contain wildcard characters.

Return:

NameSequence applElemNames The names of the application elements.

Parameter:

Pattern aePattern (in) The name or the search pattern for the requested base elements.


Name[] applElemNames = applStruct.listElements(aePattern);

Java Example:




public class ListElements extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the all the names of all elements

*


*/


try {


// Get the elements the * is the pattern

String[] aeNames = as.listElements("*");

for (String aeName : aeNames) {

System.out.println("Element: " + aeName);

}


close();


// Report the error


© 2015/08/19 Version 1.33






}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureBase.threadApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureElements.threadApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationStructureBase.ThreadTestApplicationStructureBase()....

5.7.18 listElementsByBaseType of interface ApplicationStructure

Purpose:

Get the names of application elements that are derived from the given base type.

Return:


Parameter:

BaseType aeType (in) The requested base type. The base element type can be a pattern.


Name[] applElemNames = applStruct.listElementsByBaseType(aeType);

Java Example:




public class ListElementsByBaseType extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the names of all the elements

* with the base type "AoMeasurement"

*


*/


© 2015/08/19 Version 1.33





try {


// Get the names of the elements with the base type,

// the base model is case insensitive

String[] aeNames = as.listElementsByBaseType("AOMEASUREMENT");



}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureBase.threadApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationStructureBase.ThreadTestApplicationStructureBase()

5.7.19 listEnumerations of interface ApplicationStructure

Purpose:

Get the list of all enumeration names.

Return:

NameSequence enumNames List with all enumeration names.

Parameter:

None.

Java Example:




public class ListEnumerations extends ApplicationStructureExampleAbstract {

/**


© 2015/08/19 Version 1.33




* The main program. Example get the names of all enumerations

*


*/


try {


// Get the names of the enumerations.

String[] enumNames = as.listEnumerations();

for (String enumName : enumNames) {

System.out.println("Enumeration: " + enumName);

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.0

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadTestEnumerationDe�nition.threadTestEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.testEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestEnumerationDe�nition.ThreadTestEnumerationDe�nition()test.highqsoft.odsapi.EnumerationTest.testAddAndSetEnumeration()

5.7.20 listTopLevelElements of interface ApplicationStructure

Purpose:

Get the names of the top level application elements that are derived from the given base type.If the given base type is not a top level base element an exception is thrown. A top levelapplication element is an application element without a father.

Return:


Parameter:

BaseType aeType (in) The requested base type.


Name[] applElemNames = applStruct.listTopLevelElements(aeType);


© 2015/08/19 Version 1.33




Java Example:




public class ListTopLevelElements extends ApplicationStructureExampleAbstract {

/**

* The main program. Example get the names of all the top level elements.

* A top level element is a element with an parent or with the parent element

* derived for AoEnvironment

*


*/


try {


// Get the names of the top level elements.

String[] aeNames = as.listTopLevelElements("*");



}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureElements.threadApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureElements()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationStructureElements.ThreadTestApplicationStructureElements()

5.7.21 removeElement of interface ApplicationStructure

Purpose:

Remove an application element from the application model.It is allowed to modify the application model outside a transaction but it is recommended toactivate a transaction.- Only allowed if the application element:- has no instances.- has no relations with other application elements.


© 2015/08/19 Version 1.33




Note

It is only allowed to modify the application structure if the application element has no in-stances.

Return:

void

Parameter:

ApplicationElement applElem (in) The application element to be removed.


applStruct.removeElement(applElem);

Java Example:







AoSession session;




// Get application structure.

ApplicationStructure as = session.getApplicationStructure();

// Get base structure.

BaseStructure bs = session.getBaseStructure();

// Get a base element by type.

BaseElement be = bs.getElementByType("AoSubmatrix");

// Create a new application element.

ApplicationElement ae = as.createElement(be);

...

// Remove an application element from application structure.

as.removeElement(ae);

...


session.close();

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_INSTANCESAO_HAS_REFERENCESAO_IMPLEMENTATION_PROBLEMAO_NOT_FOUNDAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()


© 2015/08/19 Version 1.33




5.7.22 removeEnumerationDe�nition of interface ApplicationStructure

Purpose:

Remove the enumeration de�nition. The server checks if the enumeration is still in use byone of the attributes. This method modi�es the application model and is only allowed for thesuper user.

Note


Return:

void

Parameter:

T_STRING enumName (in) Name of the enumeration to remove.


asObj.removeEnumerationDefinition(enumName);

Java Example:




public class RemoveEnumerationDefinition extends ApplicationStructureExampleAbstract {

/**

* The main program. Example removes the enumeration definition with the name "NewEnum".

*


*/


try {





// be a superuser.


// Remove the enumeration

as.removeEnumerationDefinition("NewEnum");





close();


// Report the error



}

}

}

Since

ASAM ODS 5.0


© 2015/08/19 Version 1.33




Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVEAO_ACCESS_DENIED

Tested by:


5.7.23 removeRelation of interface ApplicationStructure

Purpose:

This method removes an application relation from the model.It is allowed to modify the application model outside a transaction but it is recommended toactivate a transaction.The elements of the relation are still part of the application model. If there are instances ofthe relation they are also removed.

Note

It is only allowed to modify the application structure if the involved application elements haveno instances.

Return:

void

Parameter:

ApplicationRelation applRel (in) The application relation to be removed.


applStruct.removeRelation(applRel);

Java Example:





AoSession session;




// Get application structure.

ApplicationStructure as = session.getApplicationStructure();

// Create a new application relation.

ApplicationRelation ar = as.createRelation();


© 2015/08/19 Version 1.33




...

// Remove an application relation from an application structure.

as.removeRelation(ar);

...


session.close();

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_HAS_INSTANCESAO_IMPLEMENTATION_PROBLEMAO_NOT_FOUNDAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()

5.8 BaseAttribute

Package:

org.asam.ods

Description:

The ASAM ODS base attribute interface.

5.8.1 Java Examples of BaseAttribute


package api.methods.baseattribute;






/** The examples of the methods of BaseAttribute are all derived from this class */

public class BaseAttributeExampleAbstract extends AoSessionExampleAbstract {

// The session


/**

* Get the base attribute, the base attribute default_quantity of base element

* with the type AoQuantity is returned.

* @return the base attribute


© 2015/08/19 Version 1.33



5.8 BaseAttribute 279


*/

protected static BaseAttribute getBaseAttribute() throws AoException {


aoSess = connect();

}

BaseElement be = aoSess.getBaseStructure().getElementByType("AoQuantity");

BaseAttribute[] baList = be.getAttributes("default_datatype");

return (baList[0]);

}

/**



*/



aoSess.close();

aoSess = null;

}

}

}

5.8.2 getBaseElement of interface BaseAttribute

Purpose:

Return the base element to which the attribute belongs..

Return:

BaseElement baseElem The base element of the attribute.

Parameter:

None.


BaseElement baseElem = baseAttr.getBaseElement();

Java Example:





public class GetBaseElement extends BaseAttributeExampleAbstract {

/**

* Example to get the base element of a base attribute.


*/


try {


BaseAttribute ba = getBaseAttribute();

// Get the base element


© 2015/08/19 Version 1.33




BaseElement be = ba.getBaseElement();



// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()

5.8.3 getDataType of interface BaseAttribute

Purpose:

Get the data type of the base attribute.

Return:

DataType baDataType The data type of the base attribute.

Parameter:

None.


DataType baDataType = baseAttr.getDataType();

Java Example:





public class GetDataType extends BaseAttributeExampleAbstract {

/**

* Example to get the datatype of a base attribute.


*/


try {



© 2015/08/19 Version 1.33





// Get the datatype.

DataType dt = ba.getDataType();

System.out.println("The attribute has a datatype with the value "+dt.value());


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.AutogenAttrTest.testCreateAutogenAttr()test.highqsoft.odsapi.AutogenMeaAttrTest.testCreateAutogenMeaAttr()

5.8.4 getEnumerationDe�nition of interface BaseAttribute

Purpose:

Get the de�nition of the enumeration of the base attribute.

Return:

EnumerationDe�nition enumDef The ASAM ODS enumeration.

Parameter:

None.


EnumerationDefinition enumDef = aaObj.getEnumerationDefinition();

Java Example:





public class GetEnumerationDefinition extends BaseAttributeExampleAbstract {

/**

* Example to get the enumeration definition of the base attribute.

*

* @param args

* , not used.


© 2015/08/19 Version 1.33




*/


try {



// Get the enumeration definition.

EnumerationDefinition ed = ba.getEnumerationDefinition();

System.out.println("We have the enumeration.");


// Report the error



}

}

}

Since

ASAM ODS 5.1

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_INVALID_DATATYPE

Tested by:

test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()

5.8.5 getName of interface BaseAttribute

Purpose:

Get the name of the base attribute.

Return:

Name baName The name of the base attribute.

Parameter:

None.


String baName = baseAttr.getName();

Java Example:




public class GetName extends BaseAttributeExampleAbstract {


© 2015/08/19 Version 1.33




/**

* Example to get the name of a base attribute.

*

* @param args

* , not used.

*/


try {



// Get the name.

String aaName = ba.getName();

System.out.println("The name of the base attribute is " + aaName);


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureThread()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()....

5.8.6 isObligatory of interface BaseAttribute

Purpose:

Get the obligatory �ag of the base attribute.

Note

This is the Mandatory from the basemodel.

Return:

T_BOOLEAN baIsObligatory The obligatory �ag of the base attribute.

Parameter:

None.


boolean baIsObligatory = baseAttr.isObligatory();


© 2015/08/19 Version 1.33




Java Example:




public class IsObligatory extends BaseAttributeExampleAbstract {

/**

* Example checks if the attribute is obligatory.

*

* @param args

* , not used.

*/


try {



// Check if the attribute is obligatory.

boolean isObliagtory = ba.isObligatory();

if (isObliagtory) {

System.out.println("The base attribute is an obligatory attribute.");

} else {

System.out.println("The base attribute is not an obligatory attribute.");

}


// Report the error



}

}

}

Errors:


Tested by:


5.8.7 isUnique of interface BaseAttribute

Purpose:

Get the unique �ag of the base attribute. All instances with this base attribute must haveunique attribute values if the unique �ag is TRUE.

Return:

T_BOOLEAN baIsUnique The unique �ag of the base attribute.

Parameter:

None.


© 2015/08/19 Version 1.33



5.9 BaseElement 285


boolean baIsUnique = baseAttr.isUnique();

Java Example:




public class IsUnique extends BaseAttributeExampleAbstract {

/**

* Example checks if the attribute is an unique attribute,

* the client needs to set unique values for this attribute

* at the instances otherwise a AoException with the error code

* AO_BAD_PARAMETER will be thrown.

*

* @param args

* , not used.

*/


try {



// Check if the attribute is unique.

boolean isUnique = ba.isUnique();

if (isUnique) {

System.out.println("The base attribute is an unique attribute.");

} else {

System.out.println("The base attribute is not an unique attribute.");

}


// Report the error



}

}

}

Errors:


Tested by:


5.9 BaseElement

Package:

org.asam.ods

Description:

The ASAM ODS base element interface.


© 2015/08/19 Version 1.33




5.9.1 Java Examples of BaseElement


package api.methods.baseelement;






/** The examples of the methods of BaseElement are all derived from this class */

public class BaseElementExampleAbstract extends AoSessionExampleAbstract {

// The session


/**

* Get the base element, the base element of type AoTest is returned.

* @return the base element


*/

protected static BaseElement getBaseElement() throws AoException {


aoSess = connect();

}

return (aoSess.getBaseStructure().getElementByType("AoTest"));

}

/**



*/



aoSess.close();

aoSess = null;

}

}

}

5.9.2 getAllRelations of interface BaseElement

Purpose:

Get all known relations of the base element.

Return:

BaseRelationSequence baseRels All known relations of the base element.

Parameter:

None.


BaseRelation[] baseRels = baseElem.getAllRelations();


© 2015/08/19 Version 1.33



5.9 BaseElement 287

Java Example:





public class GetAllRelations extends BaseElementExampleAbstract {

/**

* The main program. Example get the all base relations of the base element.

*

* @param args

* not used.

*/


try {

BaseElement be= getBaseElement();

// Get the relations

BaseRelation[] brList = be.getAllRelations();

System.out.println("We have " + brList.length + " relations.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.DeleteAoFileTest.testInstanceDeleteFileAbort()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.LargeFileWriteTest.testInstanceCreateLargeFile()....

5.9.3 getAttributes of interface BaseElement

Purpose:

Get attributes of the base element matching with the given pattern.

Return:

BaseAttributeSequence baseAttrs The requested attributes of the base element.


© 2015/08/19 Version 1.33




Parameter:

Pattern baPattern (in) The name or the search pattern for the requested base attributes.


BaseAttribute[] baseAttrs = baseElem.getAttributes(baPattern);

Java Example:





public class GetAttributes extends BaseElementExampleAbstract {

/**

* The main program. Example get the base attributes of the base element.

*

* @param args

* not used.

*/


try {


// Get the attributes, use * as pattern

BaseAttribute[] baList = be.getAttributes("*");

System.out.println("We have " + baList.length + " attributes.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.changemodel.CheckNotNullConstraintTest.testChangeLengthNotNullAttr()....


© 2015/08/19 Version 1.33



5.9 BaseElement 289

5.9.4 getRelatedElementsByRelationship of interface BaseElement

Purpose:

Get the related elements of a base element de�ned by the relationship.

Return:

BaseElementSequence baseElems The related elements of a base element.

Parameter:

Relationship brRelationship (in) The requested relationship.


BaseElement[] baseElems = baseElem.getRelatedElementsByRelationship(brRelationship);

Java Example:





public class GetRelatedElementsByRelationship extends BaseElementExampleAbstract {

/**

* The main program. Example get the related elements of the base element.

*

* @param args

* not used.

*/


try {


// Get the related elements

BaseElement[] beList = be.getRelatedElementsByRelationship(Relationship.CHILD);

System.out.println("We have " + beList.length + " related elements.");


close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33




Tested by:


5.9.5 getRelationsByType of interface BaseElement

Purpose:

Get the base element's relations of the requested relation type.

Return:

BaseRelationSequence baseRels The base element's relations of the requested type.

Parameter:

RelationType brRelationType (in) The requested relation type.


BaseRelation[] baseRels = baseElem.getRelationsByType(brRelationType);

Java Example:






public class GetRelationsByType extends BaseElementExampleAbstract {

/**

* The main program. Example get the type of the base element, the

* type is also used as name of the base element.

*

* @param args

* not used.

*/


try {



BaseRelation[] brList = be.getRelationsByType(RelationType.FATHER_CHILD);



close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33



5.9 BaseElement 291

AO_INVALID_RELATION_TYPEAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureBase.threadApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationStructureBase.ThreadTestApplicationStructureBase()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()

5.9.6 getType of interface BaseElement

Purpose:

Get the type of the base element. The type of the base element is identical with the nameof the base element, e.g. AoTest, AoMeasurement, ..etc. . The data type of BaseType is astring.

Return:

BaseType beType The type of the base element.

Parameter:

None.


BaseType beType = baseElem.getType();

Java Example:




public class GetType extends BaseElementExampleAbstract {

/**

* The main program. Example get the base relations with the type FATHER_CHILD

* of the base element.

*

* @param args

* not used.

*/


try {


// Get the type or name

String beType = be.getType();

System.out.println("The base element has the type: " + beType);


close();


// Report the error



© 2015/08/19 Version 1.33





}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationStructureBase.threadApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationStructureBase()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()....

5.9.7 isTopLevel of interface BaseElement

Purpose:

Get whether or not the base element is a top level element. Top level elements are elementswithout a father.

Return:

T_BOOLEAN beIsTopLevel Boolean whether or not the base element is a top level element.

Parameter:

None.


boolean beIsTopLevel = baseElem.isTopLevel();

Java Example:




public class IsTopLevel extends BaseElementExampleAbstract {

/**

* The main program. Example checks if the base element is a top level element.

*

* @param args

* not used.

*/


try {


© 2015/08/19 Version 1.33



5.9 BaseElement 293



boolean isTopLevel= be.isTopLevel();

if (isTopLevel) {

System.out.println("The base element is a top level element.");

}


close();


// Report the error



}

}

}

Errors:


Tested by:

5.9.8 listAttributes of interface BaseElement

Purpose:

Get all attribute names of the base element matching with the given atrribute name pattern.

Return:

NameSequence baseElemNames The requested attribute names of the base element.

Parameter:

Pattern baPattern (in) The name or the search pattern for the requested base attribute names.


String[] baseElemNames = baseElem.listAttributes(baPattern);

Java Example:




public class ListAttributes extends BaseElementExampleAbstract {

/**

* The main program. Example get the names of the base attributes of the base element.

*


© 2015/08/19 Version 1.33




* @param args

* not used.

*/


try {


// Get the names of the base attributes, use * as pattern

String[] baNames = be.listAttributes("*");

for (String aaName : baNames) {

System.out.println("Base attribute: " + aaName);

}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.read.InstanceElementTest.testAllAttr()

5.9.9 listRelatedElementsByRelationship of interface BaseElement

Purpose:

Get the related element names of the base element de�ned by the relationship.

Return:

BaseTypeSequence baseTypes The related element names of the base element.

Parameter:

Relationship brRelationship (in) The requested relationship.


BaseType[] baseTypes = baseElem.listRelatedElementsByRelationship(brRelationship);

Java Example:



© 2015/08/19 Version 1.33



5.10 BaseRelation 295




public class ListRelatedElementsByRelationship extends BaseElementExampleAbstract {

/**


* The relationship CHILD will be used.


*/


try {

// Get the Base element

BaseElement be = getBaseElement();

String[] relElemNames = be.listRelatedElementsByRelationship(Relationship.CHILD);

for (String beName : relElemNames) {

System.out.println("Related element: " + beName);

}


close();


// Report the error



}

}

}

Errors:


Tested by:


5.10 BaseRelation

Package:

org.asam.ods

Description:

The ASAM ODS base relation interface.

5.10.1 Java Examples of BaseRelation


package api.methods.baserelation;


© 2015/08/19 Version 1.33










/** The examples of the methods of BaseRelation are all derived from this class */

public class BaseRelationExampleAbstract extends AoSessionExampleAbstract {

// The session


/**

* Get the base relation, the first FATHER_CHILD base relation of base element

* with the type AoTest is returned.

* @return the base attribute


*/

protected static BaseRelation getBaseRelation() throws AoException {


aoSess = connect();

}

BaseElement be = aoSess.getBaseStructure().getElementByType("AoTest");

BaseRelation[] brList = be.getRelationsByType(RelationType.FATHER_CHILD);

return (brList[0]);

}

/**



*/



aoSess.close();

aoSess = null;

}

}

}

5.10.2 getElem1 of interface BaseRelation

Purpose:

Get the �rst base element of the base relation.

Return:

BaseElement baseElem The �rst base element of the base relation.

Parameter:

None.


BaseElement baseElem = baseRel.getElem1();

Java Example:



© 2015/08/19 Version 1.33







public class GetElem1 extends BaseRelationExampleAbstract {

/**

* Example to get the base element of a base relation where the

* relation starts.


*/


try {

// Get the relation

BaseRelation br = getBaseRelation();

// Get the base element where the relation starts.

BaseElement be = br.getElem1();



// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()

5.10.3 getElem2 of interface BaseRelation

Purpose:

Get the second base element of the base relation.

Return:

BaseElement baseElem The second base element of the base relation.

Parameter:

None.


BaseElement baseElem = baseRel.getElem2();


© 2015/08/19 Version 1.33




Java Example:





public class GetElem2 extends BaseRelationExampleAbstract {

/**

* Example to get the base element of a base relation where the

* relation ends.


*/


try {

// Get the relation


// Get the base element where the relation ends.

BaseElement be = br.getElem2();



// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadApplicationElement.threadApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.testApplicationElement()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestApplicationElement.ThreadTestApplicationElement()test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.ORMETest.testORMECreate()

5.10.4 getInverseRelationName of interface BaseRelation

Purpose:

Return the inverse name of the base relation.

Return:

Name invRelName The name of the inverse relation.

Parameter:

None.


© 2015/08/19 Version 1.33





String invRelName = brObj.getInverseRelationName();

Java Example:




public class GetInverseRelationName extends BaseRelationExampleAbstract {

/**

* Example to get name of the inverse base relation.


*/


try {

// Get the relation


// Get the name of the inverse base relation

String invBrName = br.getInverseRelationName();

System.out.println("The name of the inverse relation is " + invBrName);


// Report the error



}

}

}

Since

ASAM ODS 5.1

Errors:


Tested by:


5.10.5 getInverseRelationRange of interface BaseRelation

Purpose:

Get the inverse relation range of the base relation.

Return:

RelationRange brRange The inverse relation range of the base relation.


© 2015/08/19 Version 1.33




Parameter:

None.


RelationRange brRange = baseRel.getInverseRelationRange();

Java Example:





public class GetInverseRelationRange extends BaseRelationExampleAbstract {

/**

* Example to get inverse range of the base relation.


*/


try {

// Get the relation


// Get the inverse relation relation.

RelationRange rr = br.getInverseRelationRange();


System.out.print("The inverse range of the relation is: min " + rr.min + " max ");


if (rr.max == -1) {


} else {


}


// Report the error



}

}

}

Errors:


Tested by:


5.10.6 getInverseRelationship of interface BaseRelation

Purpose:

Get the inverse relationship of the base relation.


© 2015/08/19 Version 1.33




Return:

Relationship relationship The inverse relationship of the base relation.

Parameter:

None.


Relationship relationship = baseRel.getInverseRelationship();

Java Example:





public class GetInverseRelationship extends BaseRelationExampleAbstract {

/**

* Example to get the inverse relationship of the base relation.


*/


try {

// Get the relation


// Get the inverse relationship.

Relationship rr = br.getInverseRelationship();

System.out.print("The inverse relationship of the relation is: " + rr.value());


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()

5.10.7 getRelationName of interface BaseRelation

Purpose:

Get the relation name of the base relation.


© 2015/08/19 Version 1.33




Return:

Name brName The relation name of the base relation.

Parameter:

None.


String brName = baseRel.getRelationName();

Java Example:




public class GetRelationName extends BaseRelationExampleAbstract {

/**

* Example to get name of a base relation.


*/


try {

// Get the relation


// Get the name.


System.out.println("The name of the relation is " + brName);


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.ORMETest.testORMECreate()

5.10.8 getRelationRange of interface BaseRelation

Purpose:

Get the relation range of the base relation.


© 2015/08/19 Version 1.33




Return:

RelationRange brRange The relation range of the base relation.

Parameter:

None.


RelationRange brRange = baseRel.getRelationRange();

Java Example:





public class GetRelationRange extends BaseRelationExampleAbstract {

/**

* Example to get range of the base relation.


*/


try {

// Get the relation


// Get the relation range.

RelationRange rr = br.getRelationRange();


System.out.print("The range of the relation is: min " + rr.min + " max ");


if (rr.max == -1) {


} else {


}


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()


© 2015/08/19 Version 1.33




5.10.9 getRelationship of interface BaseRelation

Purpose:

Get the relationship of the base relation.

Return:

Relationship relationship The relationship of the base relation.

Parameter:

None.


Relationship relationship = baseRel.getRelationship();

Java Example:





public class GetRelationship extends BaseRelationExampleAbstract {

/**

* Example to get relationship of the base relation.


*/


try {

// Get the relation


// Get the relationship.

Relationship rr = br.getRelationship();

System.out.print("The relationship of the relation is: " + rr.value());


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationRelationTestIT.testApplicationInverseRelationRange()test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()


© 2015/08/19 Version 1.33




5.10.10 getRelationType of interface BaseRelation

Purpose:

Get the relation type of the base relation.

Return:

RelationType brType The relation type of the base relation.

Parameter:

None.


RelationType brType = baseRel.getRelationType();

Java Example:





public class GetRelationType extends BaseRelationExampleAbstract {

/**

* Example to get type of the base relation.


*/


try {

// Get the relation


// Get the relation type.

RelationType rt = br.getRelationType();

System.out.print("The type of the relation is: " + rt.value());


// Report the error



}

}

}

Errors:


Tested by:



© 2015/08/19 Version 1.33




5.11 BaseStructure

Package:

org.asam.ods

Description:

The ASAM ODS base structure interface.

5.11.1 Java Examples of BaseStructure


package api.methods.basestructure;





/** The examples of the methods of BaseStructure are all derived from this class */

public class BaseStructureExampleAbstract extends AoSessionExampleAbstract {

// The session


/**

* Get the base structure

* @return the base structure


*/

protected static BaseStructure getBaseStructure() throws AoException {


aoSess = connect();

}

return (aoSess.getBaseStructure());

}

/**



*/



aoSess.close();

aoSess = null;

}

}

}

5.11.2 getElementByType of interface BaseStructure

Purpose:

Get the base element that matches the requested type. The type of a base element is identicalwith the base element name.


© 2015/08/19 Version 1.33



5.11 BaseStructure 307

Return:

BaseElement baseElem The requested base element.

Parameter:

BaseType beType (in) The name of the requested base element.


BaseElement baseElem = baseStruct.getElementByType(beType);

Java Example:





public class GetElementByType extends BaseStructureExampleAbstract {

/**

* The main program. Example get the element with the base type AoUnit.

*

* @param args

* not used.

*/


try {

BaseStructure bs = getBaseStructure();

// Get the element

BaseElement be = bs.getElementByType("AoUnit");



close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.ApplElemRemoveTest.testChangeBaseElement()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.changemodel.CheckLockTest.testCheckLock()....


© 2015/08/19 Version 1.33




5.11.3 getElements of interface BaseStructure

Purpose:

Get the base elements that match the pattern. The pattern is case sensitive and may containwildcard characters.

Return:

BaseElementSequence baseElems The requested base elements.

Parameter:

Pattern bePattern (in) The name or the search pattern for the requested base elements.


BaseElement[] baseElems = baseStruct.getElements(bePattern);

Java Example:





public class GetElements extends BaseStructureExampleAbstract {

/**

* The main program. Example get the elements of the base structure

*

* @param args

* not used.

*/


try {


// Get the elements, use pattern *

BaseElement[] beList = bs.getElements("*");

System.out.println("We have " + beList.length + " elements.");


close();


// Report the error



}

}

}

Errors:


Tested by:



© 2015/08/19 Version 1.33




5.11.4 getRelation of interface BaseStructure

Purpose:

Get the base relation between two base elements. The base relation is given from the �rstelement (parameter elem1) to the second element (parameter elem2), the inverse relation isnot returned.

Return:

BaseRelation baseRel The base relation between the two base elements.

Parameter:

BaseElement elem1 (in) The base element from which the relation starts.

BaseElement elem2 (in) The base element to which the relation points.


BaseRelation baseRel = baseStruct.getRelation(elem1,elem2);

Java Example:






public class GetRelation extends BaseStructureExampleAbstract {

/**

* The main program. Example get the base relation between the element AoTest

* and the element AoSubTest of the base model.

*

* @param args

* not used.

*/


try {


BaseElement beElem1 = bs.getElementByType("AoTest");

BaseElement beElem2 = bs.getElementByType("AoSubTest");


BaseRelation br = bs.getRelation(beElem1, beElem2);

System.out.println("We have the relations.");


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETER


© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.ods530.AoFileCreateTest.testCreateElement()test.highqsoft.odsapi.ApplModelCreateTest.testAoException()

5.11.5 getRelations of interface BaseStructure

Purpose:

Get the base relations between two base elements. The base relations are given from the �rstelement (parameter elem1) to the second element (parameter elem2), the inverse relation isnot returned.In case there are no base relations between the two elements the server will throw the exceptionAO_NOT_FOUND

Return:

BaseRelationSequence baseRels The list with base relations between the two elements.

Parameter:

BaseElement elem1 (in) The base element from which the relation starts.

BaseElement elem2 (in) The base element to which the relation points.


BaseRelation[] baseRels = bs.getRelations(elem1, elem2);

Java Example:






public class GetRelations extends BaseStructureExampleAbstract {

/**

* The main program. Example get the base relations between the element AoFile

* and the element AoExternalComponent of the base model.

* This is the only place where the base model has more then one base relation

* between two elements. This in new in ASAM ODS 5.3.0.

*


© 2015/08/19 Version 1.33




* @param args

* not used.

*/


try {


BaseElement beElem1 = bs.getElementByType("AoFile");

BaseElement beElem2 = bs.getElementByType("AoExternalComponent");


BaseRelation[] brList = bs.getRelations(beElem1, beElem2);



close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

See also:

getRelation of interface BaseStructure

Errors:


Tested by:

test.highqsoft.odsapi.ods530.AoFileCreateTest.testCreateElement()test.highqsoft.odsapi.security.Mantis5244Test.testCleanupModelPart()

5.11.6 getTopLevelElements of interface BaseStructure

Purpose:

Get the top level base elements that match the pattern. The pattern is case sensitive andmay contain wildcard characters. A top level base element is a base element without a father.

Return:

BaseElementSequence baseElems The requested top level base elements.

Parameter:

Pattern bePattern (in) The name or the search pattern for the requested top level base ele-ments.


© 2015/08/19 Version 1.33





BaseElement[] baseElems = baseStruct.getTopLevelElements(bePattern);

Java Example:





public class GetTopLevelElements extends BaseStructureExampleAbstract {

/**

* The main program. Example get the top level elements of the base model.

*

* @param args

* not used.

*/


try {



BaseElement[] beList = bs.getTopLevelElements("*");

System.out.println("We have " + beList.length + " elements.");


close();


// Report the error



}

}

}

Errors:


Tested by:


5.11.7 getVersion of interface BaseStructure

Purpose:

Get the version of the base model as string. The version of the base model is the version ofthe ASAM ODS base model.

Return:

T_STRING version The version of the ASAM ODS base model.


© 2015/08/19 Version 1.33




Parameter:

None.


String version = baseStruct.getVersion();

Java Example:




public class GetVersion extends BaseStructureExampleAbstract {

/**

* The main program. Example get the version of the base model.

*

* @param args

* not used.

*/


try {



String bmVersion = bs.getVersion();

System.out.println("The version of the base model is: " + bmVersion);


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.ApplModelBaseVersionTest.testUpdateBaseModelVersion()

5.11.8 listElements of interface BaseStructure

Purpose:

Get the base element names that match the pattern. The pattern is case sensitive and maycontain wildcard characters.

Return:

BaseTypeSequence baseTypes The requested base element names.


© 2015/08/19 Version 1.33




Parameter:

Pattern bePattern (in) The name or the search pattern for the requested base element names.


BaseType[] baseTypes = baseStruct.listElements(bePattern);

Java Example:




public class ListElements extends BaseStructureExampleAbstract {

/**

* The main program. Example get the names of the elements of the base model.

*

* @param args

* not used.

*/


try {


// Get the names of the elements, use pattern *

String[] beNames = bs.listElements("*");

for (String beName : beNames) {

System.out.println("Base element: " + beName);

}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.odsapi.read.ApplicationStructureTest.testBaseTypeAoSubTest()

5.11.9 listTopLevelElements of interface BaseStructure

Purpose:

Get the top level base element names that match the pattern. The pattern is case sensitiveand may contain wildcard characters. A top level base element is a base element without afather.


© 2015/08/19 Version 1.33




Return:

BaseTypeSequence baseTypes The requested top level base element names.

Parameter:

Pattern bePattern (in) The name or the search pattern for the requested top level base elementnames.


BaseType[] baseTypes = baseStruct.listTopLevelElements(bePattern);

Java Example:




public class ListTopLevelElements extends BaseStructureExampleAbstract {

/**

* The main program. Example get the names of the top level elements of

* the base model.

*

* @param args

* not used.

*/


try {


// Get the names of the elements, use pattern *

String[] beNames = bs.listTopLevelElements("*");

for (String beName : beNames) {

System.out.println("Base element: " + beName);

}


close();


// Report the error



}

}

}

Errors:


Tested by:



© 2015/08/19 Version 1.33




5.12 Blob

Package:

org.asam.ods

Description:

The ASAM ODS blob interface.

5.12.1 Java Examples of Blob


package api.methods.blob;








import org.asam.ods.NameValueUnit;


/** The examples of the methods of Blob are all derived from this class */

public class BlobExampleAbstract extends AoSessionExampleAbstract {

// The session


protected static Blob blob=null;

/**

* Get a new blob.

* @return the blob


*/

protected static Blob getNewBlob() throws AoException {


aoSess = connect();

}

blob = aoSess.createBlob();

return (blob);

}

/**

* Get a blob, we how in the testserver there is an element called "BlobElement" and this

* element has an attribute called "BlobAttr". We search for any instance where this attribute has

* a valid value, this blob will be used.

* Search for the instance with the valid attribute is not performance optimized but will work for

* this example.

*

* @return the blob


*/

protected static Blob getBlob() throws AoException {


aoSess = connect();

}


// Get the element

ApplicationElement ae = as.getElementByName("BlobElement");

// Get the iterator for the instances.


© 2015/08/19 Version 1.33



5.12 Blob 317

InstanceElementIterator ieIter = ae.getInstances("*0");

if (ieIter != null) {

InstanceElement ie;

do {

// Get the instance.

ie = ieIter.nextOne();

if (ie != null) {

// Get the value of the attribute

NameValueUnit blobAttrValue = ie.getValue("BlobAttr");

// Check the value is valid.

if (blobAttrValue.value.flag==15) {

// Get the blob

System.out.println("Use instance: " + ie.getName());

blob = blobAttrValue.value.u.blobVal();

}

// Destroy the instance.

ie.destroy();

}

} while ((ie != null) && (blob == null));

// destroy the iterator

ieIter.destroy();

}

return (blob);

}

/**

* Get the session.

* @return the session


*/



aoSess = connect();

}

return (aoSess);

}

/**

* Close the connection to the ODS Server, destroy the blob for the client.


*/


if (blob != null) {

blob.destroy();

}


aoSess.close();

aoSess = null;

}

}

}

5.12.2 append of interface Blob

Purpose:

Append a byte sequence to the binary large object.It is allowed to modify the binary large object outside a transaction but it is recommendedto activate a transaction.

Return:

void


© 2015/08/19 Version 1.33




Parameter:

S_BYTE value (in) The byte sequence.


blob.append(value);

Java Example:




public class Append extends BlobExampleAbstract {

/**

* The main program. Example append values of the blob.

*

* @param args

* not used.

*/


try {

Blob blob = getBlob();

// Append the values.

byte[] bv = new byte[] { (byte) 1, (byte) 2, (byte) 3 };

blob.append(bv);

System.out.println("The values of the blob are append.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.BlobTest.testBlobCompare()

5.12.3 compare of interface Blob

Purpose:

Compares the content of the binary large object. The headers are not compared.

Return:

T_BOOLEAN contentEqual A �ag whether or not the compared blobs are equal.


© 2015/08/19 Version 1.33



5.12 Blob 319

Parameter:

T_BLOB aBlob (in) The blob to compare.


boolean contentEqual = blob.compare(aBlob);

Java Example:




public class Compare extends BlobExampleAbstract {

/**

* The main program. Example compare two blobs, the header are not compared.

* the compare method returns true when the values of the blobs are identical.

*

* @param args

* not used.

*/


try {


Blob newBlob = getNewBlob();

if (blob.compare(newBlob)) {

System.out.println("The blobs are identical.");

} else {

System.out.println("The blobs are different.");

}


close();


// Report the error



}

}

}

Errors:


Tested by:


5.12.4 destroy of interface Blob

Purpose:

Destroy the object on the server. This method is used to tell the server that the blob objectis not used any more by the client. Access to this object after the invokation of the destroy


© 2015/08/19 Version 1.33




method will lead to an exception.

Return:

void

Parameter:

None.


blob.destroy()

Java Example:




public class Destroy extends BlobExampleAbstract {

/**

* The main program. Example show the destroy method of the blob interface.

* The destroy method must be called when the client do not need the blob

* object anymore and the server can free the memory required form the object.

*

* @param args

* not used.

*/


try {


// Destroy the blob object at the client / server interface.

blob.destroy();

System.out.println("The blob is destroyed.");


getSession().close();


// Report the error



}

}

}

Since

ASAM ODS 5.0

Errors:


Tested by:



© 2015/08/19 Version 1.33



5.12 Blob 321

5.12.5 get of interface Blob

Purpose:

Get a part of the binary large object.

Return:

S_BYTE byteStream The requested part of the blob data.

Parameter:

T_LONG o�set (in) The starting position of the data in the blob.

T_LONG length (in) The number of bytes requested from the blob.


S_BYTE byteStream = blob.get(offset,length);

Java Example:




public class Get extends BlobExampleAbstract {

/**

* The main program. Example get values of the blob.

*

* @param args

* not used.

*/


try {


// Get the values, from 0, length 0 means all.

byte[] bv = blob.get(0, 0);

System.out.println("The blob has " + bv.length + " values");


close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.read.AttributeValueTest.testBlobAttributeValues()test.highqsoft.odsapi.xatf.BitFieldTest.testCompareMeaBitXatf()test.highqsoft.odsapi.xatf.BooleanTest.testCompareMeaBool()test.highqsoft.odsapi.xatf.XATFCopyIT.instanceElementCopy()test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()....

5.12.6 getHeader of interface Blob

Purpose:

Get the header of the binary large object.

Return:

T_STRING header The blob header.

Parameter:

None.


String header = blob.getHeader();

Java Example:




public class GetHeader extends BlobExampleAbstract {

/**

* The main program. Example get header of the blob.

*

* @param args

* not used.

*/


try {


// Get the header

String hdr = blob.getHeader();

System.out.println("The header of the blob is " + hdr);


close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOST


© 2015/08/19 Version 1.33



5.12 Blob 323


Tested by:

test.highqsoft.odsapi.xatf.BitFieldTest.testCompareMeaBitXatf()test.highqsoft.odsapi.xatf.BooleanTest.testCompareMeaBool()test.highqsoft.odsapi.xatf.XATFCopyIT.instanceElementCopy()test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()test.highqsoft.odsapi.BlobTest.testBlobCompare()....

5.12.7 getLength of interface Blob

Purpose:

Get the length of the binary large object without loading it.

Return:

T_LONG length The blob length.

Parameter:

None.


int length = blob.getLength();

Java Example:




public class GetLength extends BlobExampleAbstract {

/**

* The main program. Example get the length of the values of the blob.

*

* @param args

* not used.

*/


try {


// Get the length.

int len = blob.getLength();

System.out.println("The blob has " + len + " values");


close();


// Report the error



© 2015/08/19 Version 1.33





}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.xatf.BitFieldTest.testCompareMeaBitXatf()test.highqsoft.odsapi.xatf.BooleanTest.testCompareMeaBool()test.highqsoft.odsapi.xatf.XATFCopyIT.instanceElementCopy()test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()test.highqsoft.odsapi.BlobTest.testBlobCompare()....

5.12.8 set of interface Blob

Purpose:

Clear the binary large object and set the new data.It is allowed to modify the binary large object outside a transaction but it is recommendedto activate a transaction.

Return:

void

Parameter:

S_BYTE value (in) The new blob data.


blob.set(value);

Java Example:




public class Set extends BlobExampleAbstract {

/**

* The main program. Example set values of the blob.

*

* @param args

* not used.

*/



© 2015/08/19 Version 1.33



5.12 Blob 325

try {

Blob blob = getNewBlob();

// Set the values.

byte[] bv = new byte[] { (byte) 1, (byte) 2, (byte) 3 };

blob.set(bv);

System.out.println("The values of the blob are set.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.bosch.MultiSessionIT.threadCreate.threadCreate()test.highqsoft.odsapi.bosch.MultiSessionIT.threadUpdate.threadUpdate()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.createNewInstance()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()....

5.12.9 setHeader of interface Blob

Purpose:

Set the header of a binary large object.It is allowed to modify the binary large object outside a transaction but it is recommendedto activate a transaction.

Return:

void

Parameter:

T_STRING header (in) The blob header.


blob.setHeader(header);

Java Example:



© 2015/08/19 Version 1.33






public class SetHeader extends BlobExampleAbstract {

/**

* The main program. Example set header of the blob.

*

* @param args

* not used.

*/


try {

Blob blob = getNewBlob();

// Set the header.

String hdr = "This is a header";

blob.setHeader(hdr);

System.out.println("The header of the blob are set.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CreateNewInstanceElementTest.testCreateFKInstances()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFileWithoutValues()test.highqsoft.odsapi.ods530.MeasurementFileTest.testCountFile()....

5.13 Column

Package:

org.asam.ods

Description:

The ASAM ODS column interface. It is not inherited from InstanceElement. Via the methodgetColumn of the interface SubMatrix the column is accessed. The column is only used for readaccess. With the creation of instances at the application element of type AoLocalColumn and therelation to the instances of the application element of type AoSubMatrix a local column can becreated. The column name is used for the SMatLink and the column is used to store a formula


© 2015/08/19 Version 1.33



5.13 Column 327

for the calculation of the values of the column. There is no de�nition of the formula language atthe moment.

Note

The name of the column is the name of the instance of the measurement quantity. Due tothe fact ASAM ODS requires the name of the local column must be identical with the nameof the measurement quantity there will be normally no di�erence.

5.13.1 destroy of interface Column

Purpose:

Destroy the object on the server. This method is used to tell the server that object is notused anymore by the client. Access to this object after the destroy method will lead to anexception.

Note

This method have only in�uence when corba is used.

Return:

void

Parameter:

None.


column.destroy()

Since

ASAM ODS 5.0

Errors:


Tested by:

test.highqsoft.avalon.MeasurementTestCase.LoadValuesSubMatrixVM()test.highqsoft.avalon.MeasurementTestIT.testManyMeasurement()test.highqsoft.avalon.MultiSessionTestIT.threadCreateValueMatrix.threadCreateValueMatrix()test.highqsoft.avalon.ValueMatrixCompareTestIT.testCompareValueMatrix()test.highqsoft.avalon.ValueMatrixCreateTestIT.testCreateValueMatrix()....


© 2015/08/19 Version 1.33




5.13.2 getDataType of interface Column

Purpose:

Get the data type of the column.This method always returns the data type of the measurement quantity to which this localcolumn belongs, independent of- the value matrix mode of the value matrices this local column belongs to- the sequence representation of this local column

Note

Loading of the datatype of the localcolumn in case the datatype isn't stored at the measure-ment quantity.

Return:

DataType dataType The data type of the column.

Parameter:

None.


DataType dataType = column.getDataType();

Since

ASAM ODS 5.0

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixUnitTestIT.testCheckUnit()test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()test.highqsoft.odsapi.CreateInstanceTestCase.updateMeasurementInstances()test.highqsoft.odsapi.CreateMeasurementSpecTest.testAppendValues()

5.13.3 getFormula of interface Column

Purpose:

Get the formula of the column.There is currently no speci�cation of formula within ASAM ODS, the method should not beused. It will return an empty string if used.

Note

Formula handling not implemented in ATHOS. No Formula de�nietion in ASAM ODS. Alwaysan empty String will be returned.


© 2015/08/19 Version 1.33



5.13 Column 329

Return:

T_STRING formula The formula of the column as string.

Parameter:

None.


String formula = column.getFormula();

Errors:


Tested by:

5.13.4 getGenerationParameters of interface Column

Purpose:

Get the generation parameters of the Column.If no generation parameters exist, an empty sequence is returned, its type is double, its lengthis 0.When the value matrix to which the column belongs is in CALCULATED mode an emptysequence is returned, its type is double, its length is 0.The data type of the generation parameters for the implicit columns is the data type givenat the corresponding measurement quantity. The data type of the generation parameters forraw data is always T_DOUBLE.

Return:

TS_Union generationParameters The generation parameters.

Parameter:

None.


TS_Union generationParameters = column.getGenerationParameters();

Since

ASAM ODS 5.2

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.read.MeasurementIT.testCompareNumberOfValues()test.highqsoft.odsapi.RawRationalTest.testCreateRawRationalInstancesComplex()

5.13.5 getName of interface Column

Purpose:

Get the name of the column.

Note


Return:

Name columnName The name of the column.

Parameter:

None.


String columnName = column.getName();

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixCompareTestIT.testCompareValueMatrix()test.highqsoft.avalon.ValueMatrixGetTestIT.testValueMatrixGetMeaPoint()test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()test.highqsoft.avalon.ValueMatrixUnitTestIT.testCheckUnit()test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()....

5.13.6 getRawDataType of interface Column

Purpose:

Get the data type of the raw values (which is the value of the attribute derived from the baseattribute 'raw_datatype').If the local column does not contain raw values, the data type of the corresponding measure-ment quantity is returned. Also, if the value matrix mode of the value matrix to which thecolumn belongs is 'CALCULATED', the data type of the measurement quantity returned.


© 2015/08/19 Version 1.33



5.13 Column 331

Return:

DataType rawDataType The data type of the raw values.

Parameter:

None.


DataType rawDataType = column.getRawDataType();

Since

ASAM ODS 5.2

Errors:


Tested by:

5.13.7 getSequenceRepresentation of interface Column

Purpose:

Get the sequence representation of the column.When the value matrix to which the column belongs is in CALCULATED mode thesequence_representation is always explicit.

Return:

T_LONG sequenceRepresentation The sequence representation of the column. This is theinteger value according to the enumeration seq_rep_enum of the base model.

Parameter:

None.


int seq_rep = column.getSequenceRepresenation();

Since

ASAM ODS 5.2

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()test.highqsoft.odsapi.read.MeasurementIT.testCompareNumberOfValues()

5.13.8 getSourceMQ of interface Column

Purpose:

Get the source measurement quantity.

Return:

InstanceElement instElem The source measurement quantity.

Parameter:

None.


InstanceElement instElem = column.getSourceMQ();

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixUnitTestIT.testCheckUnit()test.highqsoft.avalon.ValueMatrixUnitTestIT.threadHandleColumn.threadHandleColumn()test.highqsoft.odsapi.DeleteInstanceElementTest.testApplElemAccessDeleteInstances()

5.13.9 getUnit of interface Column

Purpose:

Get the unit of the column.The method returns the unit of the values according to the current setting. Initially withina session this is the unit as given in the storage. After setUnit() is called for a particularcolumn, the unit as speci�ed by setUnit() will bereturned for this column. Thus the unit returned will be retrieved by the ODS server accordingto the following strategy:1) if a unit has already been set for the paricular column by setUnit(..) before, that unit isreturned, else2) if the related measurement quantity has a unit (i.e. it has a relation derived from the baserelation 'unit' referencing an instance of base type AoUnit), that unit's name is returned, else3) if the related measurement quantity has a relation to a quantity (i.e. its relation derivedfrom the base relation 'quantity' is referencing an instance of base type AoQuantity), and thisquantity has


© 2015/08/19 Version 1.33



5.13 Column 333

a default unit (i.e. it has a relation derived from the base relation 'default_unit' referencingan instance of base type AoUnit), that unit's name is returned, else4) an empty string is returned.

Return:

T_STRING unit The unit of the column.

Parameter:

None.


String unit = column.getUnit();

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixUnitTestIT.testCheckUnit()test.highqsoft.avalon.ValueMatrixUnitTestIT.threadHandleColumn.threadHandleColumn()test.highqsoft.odsapi.read.MeasurementIT.testCompareNumberOfValues()test.highqsoft.odsapi.read.UnitTest.testGetInstancesAnuSeq()test.highqsoft.odsapi.CreateInstanceTestCase.updateMeasurementInstances()

5.13.10 isIndependent of interface Column

Purpose:

Is the column an independent column

Return:

T_BOOLEAN independent The independent �ag of the column.

Parameter:

None.


boolean independent = column.isIndependent();

Errors:



© 2015/08/19 Version 1.33




Tested by:

5.13.11 isScaling of interface Column

Purpose:

Deprecated, solved by NVH Application model.Is the column a scaling column.

Return:

T_BOOLEAN scaling Tells if the column is a scaling column.

Parameter:

None.


boolean scaling = column.isScaling();

Errors:


Tested by:

5.13.12 setFormula of interface Column

Purpose:

Set the formula of the column.It is allowed to modify the column outside a transaction but it is recommended to activate atransaction.As there is currently no speci�cation of a formula within ASAM ODS, the method should notbe used.

Note

Formula handling not implemented in ATHOS. No Formula de�nietion in ASAM ODS.

Method not implemented.

Return:

void


© 2015/08/19 Version 1.33



5.13 Column 335

Parameter:

T_STRING formula (in) The formula.


column.setFormula(formula);

Errors:


Tested by:

5.13.13 setGenerationParameters of interface Column

Purpose:

Set the generation parameters.The data type of the generation parameters for the implicit columns must be the data typegiven at the corresponding measurement quantity. The data type of the generation parametersfor raw data must be always T_DOUBLE.

Return:

void

Parameter:

TS_Union generationParameters (in) The generation parameters.


// Set the generation parameters for an implicit linear column with datatype DT_LONG.

TS_Union generationParameters = new TS_Union();

// The startvalue = 100 the offset = 50.

int[] implLinearValues = new int[] { 100, 50};

generationParameters.longSeq(implLinearValues);

column.setGenerationParameters(generationParameters);

Since

ASAM ODS 5.2

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_BAD_PARAMETERAO_TRANSACTION_NOT_ACTVIE


© 2015/08/19 Version 1.33




Tested by:

5.13.14 setIndependent of interface Column

Purpose:

Set a new value (TRUE or FALSE) to the independent �ag of the column.

Return:

void

Parameter:

T_BOOLEAN independent (in) The new value of the independent �ag.


column.setIndependent(independent);

Errors:


Tested by:

test.highqsoft.odsapi.MixedModeTest.createColumm()test.highqsoft.odsapi.MixedModeTest.createMeaDataVM()test.highqsoft.odsapi.MixedModeTest.testApplElemAccess()

5.13.15 setScaling of interface Column

Purpose:

Deprecated, solved by NVH Application model.Set a new value to the scaling �ag of the column.

Return:

void

Parameter:

T_BOOLEAN scaling (in) The new value of the scaling �ag.


column.setScaling(scaling);


© 2015/08/19 Version 1.33



5.13 Column 337

Errors:


Tested by:

5.13.16 setSequenceRepresentation of interface Column

Purpose:

Set the sequence representation of a new column.

Return:

void

Parameter:

T_LONG sequenceRepresentation (in) The sequence representation. This is the integer valueaccording the enumeration seq_rep_enum of the base model.


// Set the column to imlicit linear.

column.setSequenceRepresenation(2);

Since

ASAM ODS 5.2

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_BAD_PARAMETERAO_TRANSACTION_NOT_ACTVIE

Tested by:

5.13.17 setUnit of interface Column

Purpose:

Set the unit of the column. This is only a temporary unit for getting the values of a column.This unit is not stored in the physical storage; however it remains e�ective unti the end ofthe current session or until the next setUnit() invokation.


© 2015/08/19 Version 1.33




If the value matrix mode of the value matrix to which the column belongs is 'STORAGE',this method has no in�uence on the values returned from the value matrix.If an empty string is provided with this method the unit for subsequent requests of column val-ues is reset to the unit stored in the physical storage (related to the correspondig measurementquantity).If a permanent modi�cation of the unit is desired, the relation at the correspondig measure-ment quantity needs to be changed by the client.

Return:

void

Parameter:

T_STRING unit (in) The physical unit.


column.setUnit(unit);

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixUnitTestIT.testCheckUnit()test.highqsoft.odsapi.read.MeasurementIT.testCompareNumberOfValues()test.highqsoft.odsapi.read.UnitTest.testGetInstancesAnuSeq()

5.14 ElemResultSetExtSeqIterator

Package:

org.asam.ods

Description:

For iteration through the result elements, there is also a new iterator necessary called ElemRe-sultSetExtSeqIterator. Its functionality is still the same as all other iterators and needs thereforeno further explanation.

There is only one di�erence to the other iterations. The iteration is done on the lowest level inthat case on the TS_UnionSeq.

5.14.1 destroy of interface ElemResultSetExtSeqIterator

Purpose:

Destroy the iterator and free the associated memory.


© 2015/08/19 Version 1.33



5.14 ElemResultSetExtSeqIterator 339

Return:

void

Parameter:

None.


ersIter.destroy();

Errors:


Tested by:

5.14.2 getCount of interface ElemResultSetExtSeqIterator

Purpose:

Get the total number of elements accessible by the iterator.

Return:

T_LONG count The number of elements accessible by the iterator.

Parameter:

None.


int cnt = ersIter.getCount();

Errors:


Tested by:


© 2015/08/19 Version 1.33




5.14.3 nextN of interface ElemResultSetExtSeqIterator

Purpose:

Get the next n elements from the sequence.In case there are less elements available than requested, only as many as are available will bereturned; if there is none left an empty list is returned.

Return:

ElemResultSetExtSequence elemResults The next n attribute values from the element resultset sequence.

Parameter:

T_LONG how_many (in) The number of requested elements.


int how_many = 10;

ElemResultSetExt[] elemResults = ersIter.nextN(how_many)

Errors:


Tested by:

5.14.4 nextOne of interface ElemResultSetExtSeqIterator

Purpose:

Get the attributes of the next instance element from the sequence.In case no element is available a NIL object is returned.

Return:

ElemResultSetExt elemResult The attribute values of the next instance element from theelement result set sequence.

Parameter:

None.


ElemResultSetExt elemResult = ersIter.nextOne()

Errors:

AO_CONNECTION_LOST


© 2015/08/19 Version 1.33



5.15 EnumerationDe�nition 341


Tested by:

5.14.5 reset of interface ElemResultSetExtSeqIterator

Purpose:

Reset the intwrnal pointer in the element sequence to the �rst element.

Return:

void

Parameter:

None.


ersIter.reset();

Errors:


5.15 EnumerationDe�nition

Package:

org.asam.ods

Description:

The ASAM ODS enumeration interface.

5.15.1 Java Examples of EnumerationDe�nition


package api.methods.enumerationdefinition;






© 2015/08/19 Version 1.33





/** The examples of the methods of EnumerationDefinition are all derived from this class */

public class EnumerationDefinitionExampleAbstract extends AoSessionExampleAbstract {

// The session



/**




*/


if (as == null) {


aoSess = connect();

}


}

return (as);

}

/**

* Get the enumeration definition, this examples use the enumeration datatype_enum

* @return the enumeration definition.

* @throws AoException n any occurring ASAM ODS exception.

*/

protected static EnumerationDefinition getEnumerationDefinition() throws AoException {


aoSess = connect();

}


EnumerationDefinition ed = as.getEnumerationDefinition("datatype_enum");

return ed;

}

/**



*/



aoSess.close();

aoSess = null;

}

}

/**

* Get the session.



*/



aoSess = connect();

}

return(aoSess);

}

}


© 2015/08/19 Version 1.33




5.15.2 addItem of interface EnumerationDe�nition

Purpose:

Append a new item to the enumeration. This method modi�es the application model and isonly allowed for the super user.The name of an item must not exceed the maximum name length of the underlying physicalstorage. Current server implementations restrict it to 128 characters.

Return:

void

Parameter:

T_STRING itemName (in) The name of the new item.


enumDef.addItem(itemName);

Java Example:

Seemethod createEnumerationDe�nition of interface ApplicationStructure (p. 254)

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVEAO_ACCESS_DENIEDAO_DUPLICATE_NAMEAO_DUPLICATE_VALUE

Tested by:


5.15.3 getIndex of interface EnumerationDe�nition

Purpose:

Get the index of the enumeration de�nition.

Return:

T_LONG enumIndex The index of the enumeration.

Parameter:

None.


© 2015/08/19 Version 1.33





int enumIndex = enumDef.getIndex();

Java Example:




public class GetIndex extends EnumerationDefinitionExampleAbstract {

/**

* The main program. Example get the index of the enumeration.


*/


try {

// Get the enumeration

EnumerationDefinition ed = getEnumerationDefinition();

int index = ed.getIndex();

System.out.println("The index of the enumeration is: " + index);


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.EnumerationTest.testAddAndSetEnumeration()

5.15.4 getItem of interface EnumerationDe�nition

Purpose:

Get the value of an item.

Return:

T_LONG item The number of the item.

Parameter:

T_STRING itemName (in) The name of the item.


© 2015/08/19 Version 1.33





int item = enumDef.getItem(itemName);

Java Example:




public class GetItem extends EnumerationDefinitionExampleAbstract {

/**

* The main program. Example get the number of an item of the enumeration.


*/


try {



int item = ed.getItem("DT_DATE");

System.out.println("The item DT_DATE has a value: " + item);


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_NOT_FOUND

Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadTestEnumerationDe�nition.threadTestEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.testEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestEnumerationDe�nition.ThreadTestEnumerationDe�nition()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CreateNewInstanceElementTest.testCreateFKInstances()....

5.15.5 getItemName of interface EnumerationDe�nition

Purpose:

Get the name of an item.

Return:

T_STRING itemName The name of the item.


© 2015/08/19 Version 1.33




Parameter:

T_LONG item (in) The value of the item.


String itemName = enumDef.getItemName(item);

Java Example:




public class GetItemName extends EnumerationDefinitionExampleAbstract {

/**

* The main program. Example get the name of an enumeration item.


*/


try {



String itemName = ed.getItemName(4);

System.out.println("The name of the item: " + itemName);


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_NOT_FOUND

Tested by:

test.highqsoft.avalon.EnumerationReadTestIT.testEnumerationRead()test.highqsoft.odsapi.EnumerationTest.testAddAndSetEnumeration()test.highqsoft.odsapi.ORMETest.testORMECreate()

5.15.6 getName of interface EnumerationDe�nition

Purpose:

Get the name of the enumeration.


© 2015/08/19 Version 1.33




Return:

T_STRING enumName Name of the enumeration.

Parameter:

None.


String enumName = enumDef.getName();

Java Example:




public class GetName extends EnumerationDefinitionExampleAbstract {

/**

* The main program. Example get the name of the enumeration.


*/


try {



String name = ed.getName();

System.out.println("The enumeration: " + name);


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadTestEnumerationDe�nition.threadTestEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.testEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestEnumerationDe�nition.ThreadTestEnumerationDe�nition()test.highqsoft.avalon.BaseStructureTestIT.testBaseElement()test.highqsoft.avalon.EnumerationReadTestIT.testEnumerationRead()....


© 2015/08/19 Version 1.33




5.15.7 listItemNames of interface EnumerationDe�nition

Purpose:

List the possible names of the enumeration. The sort order of the list is the value of the item.The �rst item has the value zero.

Return:

NameSequence nameList List with all possible names of the enumeration items.

Parameter:

None.


NameSequence nameList = enumDef.listItemNames();

Java Example:




public class ListItemNames extends EnumerationDefinitionExampleAbstract {

/**

* The main program. Example get the names of the items of the enumeration.


*/


try {



// Get the names of the items

String[] itemNames = ed.listItemNames();

for (String itemName : itemNames) {

System.out.println("Item: " + itemName);

}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ApplicationStructureMultiSessionTestIT.threadTestEnumerationDe�nition.threadTestEnumerationDe�nition()


© 2015/08/19 Version 1.33




test.highqsoft.avalon.ApplicationStructureTestIT.testEnumerationDe�nition()test.highqsoft.avalon.ApplicationStructureTestIT.ThreadTestEnumerationDe�nition.ThreadTestEnumerationDe�nition()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CreateNewInstanceElementTest.testCreateFKInstances()....

5.15.8 renameItem of interface EnumerationDe�nition

Purpose:

Rename the item of the enumeration. This method modi�es the application model and isonly allowed for the super user.

Return:

void

Parameter:

T_STRING oldItemName (in) The existing name of the item.

T_STRING newItemName (in) the new name of the item.


enumDef.renameItem(oldItemName, newItemName);

Java Example:





public class RenameItem extends EnumerationDefinitionExampleAbstract {

/**

* The main program. Example rename an item of the enumeration.

* From the enumeration Company, the item AUDI will be renamed

* to "VW-AUDI"


*/


try {




EnumerationDefinition ed = as.getEnumerationDefinition("Company");



// be a superuser.


try {

ed.renameItem("AUDI", "VW-AUDI");





© 2015/08/19 Version 1.33





// Report the error



}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVEAO_NOT_FOUND

Tested by:


5.15.9 setName of interface EnumerationDe�nition

Purpose:

Set the name of the enumeration. This method modi�es the application model and is onlyallowed for the super user.The name of an enumeration de�nition must not exceed the maximum name length of theunderlying physical storage. Current server implementations restrict it to 30 characters.

Return:

void

Parameter:

T_STRING enumName (in) Name of the enumeration.


enumDef.setName(enumName);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORY


© 2015/08/19 Version 1.33



5.16 InstanceElement 351

AO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVEAO_ACCESS_DENIED

Tested by:


5.16 InstanceElement

Package:

org.asam.ods

Description:

The ASAM ODS instance element interface. It is allowed to modify the instances outside atransaction but it is recommended to activate a transaction before the instances are modi�ed.The modi�cations to instances get permanent when the transaction is committed.

5.16.1 Java Examples of InstanceElement


package api.methods.instanceelement;








/** The examples of the methods of InstanceElement are all derived from this class */

public class InstanceElementExampleAbstract extends AoSessionExampleAbstract {

// The session


protected static InstanceElement ie=null;


/**

* Get the application element defined by the name.

* @param aeName the name of the element



*/

protected static ApplicationElement getApplicationElementByName(String aeName) throws AoException {

if (ae == null) {


aoSess = connect();

}


// Get the element


}

return (ae);

}


© 2015/08/19 Version 1.33




/**

* Get the application element defined by the base type.

* @param beType the base type.



*/

protected static ApplicationElement getApplicationElementByBaseType(String beType) throws AoException {

if (ae == null) {


aoSess = connect();

}


// Get the element

ae = as.getElementsByBaseType(beType)[0];

}

return (ae);

}

/**

* Get the application element derived from AoTest



*/


return (getApplicationElementByBaseType("AoTest"));

}

/**

* Get an instance, the instance is one of the instances from the element derived from given base element.

*

* @param beType the base type.

* @return the instance


*/

protected static InstanceElement getInstanceElement(String beType) throws AoException {

// Get the application element.

ApplicationElement ae = getApplicationElementByBaseType(beType);

return (getInstanceElement(ae));

}

/**

* Get an instance, the instance is one of the instances from the given element.

*

* @param ae the application element to load an instance from.



*/

protected static InstanceElement getInstanceElement(ApplicationElement ae) throws AoException {


InstanceElementIterator ieIter = ae.getInstances("*");

if (ieIter.getCount()==0) {

System.err.println("There are no instances.");

}


ieIter.destroy();

return (ie);

}

/**

* Get an instance, the instance is one of the instances from the element derived from AoTest.

*



*/

protected static InstanceElement getInstanceElement() throws AoException {


© 2015/08/19 Version 1.33




return (getInstanceElement("AoTest"));

}

/**

* Get the session.



*/



aoSess = connect();

}

return (aoSess);

}

/**

* Close the connection to the ODS Server, destroy the iterator for the client.


*/


if (ie != null) {

ie.destroy();

}


aoSess.close();

aoSess = null;

}

}

}

5.16.2 addInstanceAttribute of interface InstanceElement

Purpose:

Add an instance attribute to the instance. The instance attribute is built as aName/Value/Unit tuple on the client. This method has to copy the data from the clientto the server. The name of the attribute must be unique.It is allowed to add an instance attribute outside a transaction but it is recommended toactivate a transaction.Note: As the current speci�cation of the physical storage restricts the length of instanceattribute names to maximum of 30 characters, clients must take care not to exceed this limt.

Note

The datatypes of the instances attribute is restricted by the ASAM ODS speci�cation to DT_-BYTE, DT_SHORT, DT_LONG, DT_FLOAT, DT_DOUBLE, DT_STRING and DT_-DATE.

Return:

void

Parameter:

NameValueUnit instAttr (in) The instance attribute to be added.


instElem.addInstanceAttribute(instAttr);


© 2015/08/19 Version 1.33




Java Example:







public class AddInstanceAttribute extends InstanceElementExampleAbstract {

/**

* The main program. Example show the how an instance attribute is added.

* Do not use instance attributes, because they are bad for the performance.

* You can run this example only once, the second time you will get an exception

* because the name of the instance attribut emust be unique.

*

* @param args

* not used.

*/


try {

InstanceElement ie = getInstanceElement();



// Create the instance attribute

NameValueUnit nvu = new NameValueUnit();

nvu.valName = "ExampleInstanceAttribute";

nvu.value = new TS_Value();

nvu.value.u = new TS_Union();

nvu.value.flag = 15;

nvu.value.u.stringVal("Value von ExampleInstanceAttribute");

nvu.unit = "";

// Add the instance attribute

ie.addInstanceAttribute(nvu);



System.out.println("Instance attribute added.");

// Destroy the instance object at the client / server interface.

ie.destroy();




// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CreateNewInstanceElementTest.testCreateFKInstances()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()


© 2015/08/19 Version 1.33




test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFileWithoutValues()test.highqsoft.odsapi.ods530.MeasurementFileTest.testCountFile()....

5.16.3 compare of interface InstanceElement

Purpose:

Compare two instance elements. The Id's of the application elements and the Id's of theinstance elements are compared. The Id's of the application elements will be compare �rst.

Return:

T_LONGLONG di� The di�erence of the Id's. Meaning:di� < 0 ElemId of instance is smaller then instance to compare with.di� == 0 ElemId is identical.di� > 0 ElemId of instance is greater then instance to compare with.

Parameter:

InstanceElement compIeObj (in) The instance element to compare with.


T_LONGLONG diff = ieObj.compare(compIeObj);

Java Example:






public class Compare extends InstanceElementExampleAbstract {

/**

* The main program. Example show the compare method of the instance element interface.

*

* Take care each interaction with the API will cause a network roundtrip.

*

* @param args

* not used.

*/


try {



InstanceElementIterator ieIter = ae.getInstances("*");

InstanceElement ieCmp;

boolean found = false;

do {

ieCmp = ieIter.nextOne();

if (ieCmp != null) {

if (ieCmp.compare(ie).low==0) {

found = true;

}

ieCmp.destroy();

}


© 2015/08/19 Version 1.33




} while ((!found) && (ieCmp != null));

if (found) {

System.out.println("The same instance found.");

} else {

System.out.println("The instance is not found.");

}

// Destroy the iterator object at the client / server interface.

ieIter.destroy();


ie.destroy();




// Report the error



}

}

}

Since

ASAM ODS 5.0

Errors:


Tested by:

test.highqsoft.odsapi.WriteInstanceElementTest.testCompareCopied()

5.16.4 createRelatedInstances of interface InstanceElement

Purpose:

Create a list with new instances which are related to the actual instance element. Theattributes are given with the name of the sequence. The values of the attributes are given inthe value sequence. The index in the di�erent value sequences match for one instance element.The index in the instance element sequence of the related instances match for the instancewith the same index in the value sequence.

Return:

InstanceElementSequence elemList The list with the new created instances.

Parameter:

ApplicationRelation applRel (in) The application relation for witch the related instances willbe created.

NameValueSeqUnitSequence attributes (in) The attributes of the new created instances.


© 2015/08/19 Version 1.33




ApplicationRelationInstanceElementSeqSequence relatedInstances (in) The list with relatedinstances for di�erent application relations.



ApplicationRelation applRel;

NameValueSeqUnit attributes[];

ApplicationjRealtionInstanceElementSeq relatedInstances[]

InstanceElement elemList[] = ieObj.createRelatedInstances(applRel, attributes, relatedInstances);

Java Example:


import java.util.ArrayList;





import org.asam.ods.ApplicationRelationInstanceElementSeq;





import org.asam.ods.NameValueSeqUnit;



public class CreateRelatedInstances extends InstanceElementExampleAbstract {

/**

* The main program. Example shows how instances of a related element are created together

* with the relation to related instances. In this example we take an instance from

* AoParanmeterSet, we create instances of AoParameter and set with the same call the

* relation to AoUnit.

*

* This example will not work on all application model.

*


*/


try {

int noNewInst = 4;

// Get the instance

InstanceElement ie = getInstanceElement("AoParameterSet");

ApplicationElement ae = ie.getApplicationElement();


ApplicationRelation[] arList = ae.getRelationsByBaseName("parameters");

ApplicationElement[] aeList = as.getElementsByBaseType("AoUnit");

if (aeList.length > 0) {

ApplicationRelation ar = arList[0];

ApplicationElement aeParameter = ar.getElem2();

ApplicationElement aeUnit = aeList[0];

ApplicationRelation arUnit= null;

try {

ApplicationRelation[] applRelList = as.getRelations(aeParameter, aeUnit);

if (applRelList.length > 0) {

arUnit = applRelList[0];

}

} catch (AoException ao) {

// Accept exception when there are no relations between the two elements.

}


© 2015/08/19 Version 1.33




if (arUnit != null) {

// Get the attributes of the AoParameter element.

ApplicationAttribute[] aaList = aeParameter.getAttributes("*");

// Create all attributes except the Id

ArrayList<NameValueSeqUnit> attributes = new ArrayList<NameValueSeqUnit>();

for (ApplicationAttribute aa : aaList) {

BaseAttribute ba = aa.getBaseAttribute();

if (ba != null) {

String baName = ba.getName();

if (baName.compareToIgnoreCase("name")==0) {

String[] names = new String[noNewInst];

for (int i = 0; i < noNewInst; i++) {

names[i] = "parameter " +i;

}

NameValueSeqUnit attr= new NameValueSeqUnit();

attr.valName = aa.getName();

attr.value = new TS_ValueSeq();

attr.value.u = new TS_UnionSeq();

attr.value.u.stringVal(names);

attr.value.flag = new short[noNewInst];


// Make all the values valid.

attr.value.flag[i]=15;

}

attr.unit = "";

attributes.add(attr);

}

if (baName.compareToIgnoreCase("version")==0) {

String[] versions = new String[noNewInst];


versions[i] = "V"+i;

}

NameValueSeqUnit attr = new NameValueSeqUnit();




attr.value.u.stringVal(versions);





}

attr.unit = "";


}

if (baName.compareToIgnoreCase("pvalue")==0) {

String[] versions = new String[noNewInst];


versions[i] = "V"+i;

}





attr.value.u.stringVal(versions);





}

attr.unit = "";


}

if (baName.compareToIgnoreCase("parameter_datatype")==0) {

int[] pDts = new int[noNewInst];


pDts[i] = DataType._DT_STRING;


© 2015/08/19 Version 1.33




}





if (aa.getDataType().value() == DataType._DT_ENUM) {

attr.value.u.enumVal(pDts);

} else {

attr.value.u.longVal(pDts);

}





}

attr.unit = "";


}

}

}

// Create the relation to the unit.

// All parameter get the Unit "m".

InstanceElement ieUnit = aeUnit.getInstanceByName("m");

ApplicationRelationInstanceElementSeq[] relatedInstances;

relatedInstances= new ApplicationRelationInstanceElementSeq[1];

relatedInstances[0] = new ApplicationRelationInstanceElementSeq();

relatedInstances[0].applRel = arUnit;

relatedInstances[0].instances = new InstanceElement[noNewInst];


relatedInstances[0].instances[i] = ieUnit;

}



// Create the related instances of AoParameter

ie.createRelatedInstances(ar,

attributes.toArray(new NameValueSeqUnit[attributes.size()]),

relatedInstances);

// commit the transaction


System.out.println("Instances for " + aeParameter.getName() + " created");

} // No relation between AoParameter and AoUnit

} // No application element AoUnit.


close();


// Report the error



}

}

}

Since

ASAM ODS 5.0

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()

5.16.5 createRelation of interface InstanceElement

Purpose:

Create a relation between the current and the given instance. Check if the application elementsof the relation matches the application elements of the instances.It is allowed to modify the instance element outside a transaction but it is recommended toactivate a transaction.

Return:

void

Parameter:

ApplicationRelation relation (in) The application relation.

InstanceElement instElem (in) The instance element.


instElem.createRelation(relation,instElem);

Java Example:









public class CreateRelation extends InstanceElementExampleAbstract {

/**

* The main program. Example shows how an instance will be link to another instance.

* In the TestModel there is a relation between the element derived from AoTest and AoLog.

* We use this relation between these elements and instances of these element.

* This example will not work on any other application model.

*


*


*/


try {

// Get the instance

InstanceElement ie = getInstanceElement("AoTest");



ApplicationElement[] aeList = as.getElementsByBaseType("AoLog");

if (aeList.length > 0) {


© 2015/08/19 Version 1.33




ApplicationElement aeRel = aeList[0];

// Load an instance of the related element

InstanceElement ieRel = null;

InstanceElementIterator ieIter = aeRel.getInstances("*");

ieRel = ieIter.nextOne();

// Iterator is not used anymore

ieIter.destroy();

if (ieRel != null) {

// Search for the relation

ApplicationRelation[] arList = as.getRelations(ae, aeRel);

if (arList.length > 0) {




// set the related instance.

ie.createRelation(arList[0], ieRel);



System.out.println("We have set a related instance.");

} else {

System.out.println("Relation not found between " + ae.getName() + " and " + aeRel.getName());

}

} else {

System.out.println("No element of type AoLog found.");

}

// Cleanup the related instance

ieRel.destroy();

}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATIONAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()test.highqsoft.odsapi.changemodel.CheckFKConstraintTest.testCheckFCKElem1ElemN()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CreateNewInstanceElementTest.testCreateFKInstances()....


© 2015/08/19 Version 1.33




5.16.6 deepCopy of interface InstanceElement

Purpose:

Provides an easy-to-use and e�ective copy mechanism for instance element hierarchies insidethe server (e.g. copy a project with all tests or copy a test with all measurements). Thedeep copy follows only the child references but not the informational references. Example:Copying elements of type AoMeasurement does not include copying the referenced elementsof type AoMeasurementQuantity. The copied instance elements of type AoMeasurement willreference the same measurement quantities as the original. An application that wants tocopy the measurement quantity also must do this (including setting the proper references) byitself e.g. with another call to shallowCopy; deepCopy is not necessary in this case becauseAoMeasurementQuantity has no children.

Note

All the child instances are copied also the measurement quantities, submatrixes and localcol-umn.

Return:

InstanceElement newInstElem The reference to the copied instance element hierarchy.

Parameter:

T_STRING newName (in) The name of the new instance element. If a new version shall becreated this parameter may be NULL to use the same name for the copy. In this case a newversion must be provided.

T_STRING newVersion (in) The version of the new instance element. This parameter maybe NULL if a new name is provided.


InstanceElement newInstElem = instElem.deepCopy(newName,newVersion);

Java Example:






public class DeepCopy extends InstanceElementExampleAbstract {

/**

* The main program. Example shows how a complete instance of measurement is copied.

*


*


*/


try {

// Get the instance


© 2015/08/19 Version 1.33




InstanceElement ie = getInstanceElement("AoMeasurement");




// Copy the instances with a new name and version which is the current date.

InstanceElement ieCopy = ie.deepCopy("ExampleDeepCopy", ""+ new Date());



System.out.println("We have the copy the instance with all the children.");


close();


// Report the error



}

}

}

Since

ASAM ODS 4.1

Errors:


Tested by:

test.highqsoft.odsapi.ods530.TransactionTest.testCreate()test.highqsoft.odsapi.WriteInstanceElementTest.testCompareCopied()

5.16.7 destroy of interface InstanceElement

Purpose:

Destroy the object on the server. This method is used to tell the server that this object isnot used anymore by the client. Access to this object after the destroy method will lead toan exception.

Note


Return:

void

Parameter:

None.


ieObj.destroy()


© 2015/08/19 Version 1.33




Java Example:




public class Destroy extends InstanceElementExampleAbstract {

/**

* The main program. Example show the destroy method of the instance element interface.

* The destroy method must be called when the client do not need the instance


*

* @param args

* not used.

*/


try {



ie.destroy();

System.out.println("The instance is destroyed.");




// Report the error



}

}

}

Since

ASAM ODS 5.0

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testCheckRelLccMeq()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelationApplElemAccess()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesValueQuery()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesValueQueryExt()....

5.16.8 getApplicationElement of interface InstanceElement

Purpose:

Get the application element of the instance element.


© 2015/08/19 Version 1.33




Return:

ApplicationElement applElem The application element from which the instance element isderived.

Parameter:

None.


ApplicationElement applElem = instElem.getApplicationElement();

Java Example:





public class GetApplicationElement extends InstanceElementExampleAbstract {

/**

* The main program. Example get application element of an instance.


*/


try {

// Get the instance




System.out.println("We have the application element.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()test.highqsoft.avalon.InstanceElementTestIT.handleChildrenNoDestroy()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()test.highqsoft.avalon.InstanceElementTestIT.testInstancesRelationNames()....


© 2015/08/19 Version 1.33




5.16.9 getAsamPath of interface InstanceElement

Purpose:

Get the ASAM-Path of the instance element.

Return:

Name asamPath The ASAM path to the instance element.

Parameter:

None.


String asamPath = instElem.getAsamPath();

Java Example:




public class GetAsamPath extends InstanceElementExampleAbstract {

/**

* The main program. Example get the ASAMPath of the instance.


*/


try {

// Get the instance


// Get the ASAMPath

String asamPath = ie.getAsamPath();

System.out.println("The ASAMPath of the instance is " + asamPath);


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testCheckRelLccMeq()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelationApplElemAccess()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()


© 2015/08/19 Version 1.33




test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.JBeamTestIT.testMeasurementJBeam()....

5.16.10 getId of interface InstanceElement

Purpose:

Get the Id of the instance element.

Return:

T_LONGLONG ieId The Id of the instance element.

Parameter:

None.


T_LONGLONG ieId = instElem.getId();

Java Example:





public class GetId extends InstanceElementExampleAbstract {

/**

* The main program. Example get the Id of the instance.


*/


try {



T_LONGLONG iid = ie.getId();

long ieId = ((iid.high<<32)+iid.low);

System.out.println("The Id of the instance is " + ieId);


close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelationApplElemAccess()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.MeasurementTestCase.LoadCompareValues()test.highqsoft.avalon.MeasurementTestCase.LoadCompareValuesExt()....

5.16.11 getInitialRights of interface InstanceElement

Purpose:

Retrieve access control list information for the initial rights of the given object.

Return:

InitialRightSequence initialRights The access control list entries with the initial rights of thegiven instance element.

Parameter:

None.


InitialRight[] initialRights = instElem.getInitialRights();

Java Example:











// Get the instances of the application element, a query

// for only the Id of the instances using the ApplElemAccess

// interface, would do it also, but the query is harder to

// code and will blowup the example.


InstanceElementIterator iei = aeList[aeIndex].getInstances("*");

if (iei != null) {

do {

ieObj = iei.nextOne();

if (ieObj != null) {

// Id of the instance,

T_LONGLONG iid = ieObj.getId();

// Get the access control list

irSeq = ieObj.getInitialRights();

for (int irIndex = 0;


© 2015/08/19 Version 1.33




irIndex < irSeq.length;

irIndex++) {

System.out.println(aeName + ", " + iid.low + ", " +




}

// Destroy the instance element, the object is not


ieObj.destroy();

}

} while (ieObj != null);

// Destroy the instance iterator, the object is not


iei.destroy();

}

} // for all application elements.

See also:

getInstanceInitialRights of interface ApplElemAccess

Errors:


Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.security.InitialRightsTest.testDeleteCreatedInstances()test.highqsoft.odsapi.xatf.XATFCopyIT.testCompareAllInstances()

5.16.12 getName of interface InstanceElement

Purpose:

Get the name of the instance element.

Return:

Name ieName The name of the instance element.

Parameter:

None.


String ieName = instElem.getName();

Java Example:



© 2015/08/19 Version 1.33






public class GetName extends InstanceElementExampleAbstract {

/**

* The main program. Example get the Name of the instance.


*/


try {

// Get the instance


// Get the name

String name = ie.getName();

System.out.println("The instance: " + name);


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testCheckRelLccMeq()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()test.highqsoft.avalon.InstanceElementReadTestIT.testSimpleInstanceReading()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()....

5.16.13 getRelatedInstances of interface InstanceElement

Purpose:

Get the related instances. The application relation and the search name pattern of the relatedinstances specify the instances to retrieve. The name pattern is case sensitive and may containwildcard characters.

Return:

InstanceElementIterator ieIterator The related instances.

Parameter:

ApplicationRelation applRel (in) The application relation.


© 2015/08/19 Version 1.33




Pattern iePattern (in) The name or the search pattern for the related instance names.


InstanceElementIterator ieIterator = instElem.getRelatedInstances(applRel,iePattern);

Java Example:








public class GetRelatedInstances extends InstanceElementExampleAbstract {

/**

* The main program. Example shows how the related instances of an element are loaded.

*


*


*/


try {

// Get the instance







// Get the related instances.

InstanceElementIterator ieIter = ie.getRelatedInstances(arList[0], "*");

System.out.println("We have the related instance.");

// Destroy the iterator, not used anymore at the client

ieIter.destroy();

} else {

System.out.println("Relation not found between.");

}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATIONAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE


© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testCheckRelLccMeq()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.InstanceElementTestIT.testInstancesRelationNames()test.highqsoft.avalon.MeasurementTestCase.LoadCompareValues()....

5.16.14 getRelatedInstancesByRelationship of interface InstanceEle-ment

Purpose:

Get the list of related instances. The relationship and the name pattern of the related instancesspecify the instances to retrieve. The name pattern is case sensitive and may contain wildcardcharacters.

Return:

InstanceElementIterator ieIterator The related instances.

Parameter:

Relationship ieRelationship (in) The requested relationship.



InstanceElementIterator ieIterator = instElem.getRelatedInstancesByRelationship(ieRelationship,iePattern);

Java Example:






public class GetRelatedInstancesByRelationship extends InstanceElementExampleAbstract {

/**

* The main program. Example show how to get the related instances,

* this way is a very performance intensive way loaded the related instances,

* better use the method getInstancesExt of the interface ApplElemAccess.

*

* @param args

* not used.

*/


try {


InstanceElementIterator ieIter = ie.getRelatedInstancesByRelationship(Relationship.CHILD, "*");

System.out.println("There are " + ieIter.getCount() + " child instances.");


ieIter.destroy();


© 2015/08/19 Version 1.33





close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementTestIT.handleChildrenNoDestroy()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()....

5.16.15 getRights of interface InstanceElement

Purpose:


Note


Return:

ACLSequence aclEntries The access control list entries of the given instance element.

Parameter:

None.


ACL[] aclEntries = instElem.getRights();

Java Example:





© 2015/08/19 Version 1.33





public class GetRights extends InstanceElementExampleAbstract {

/**

* The main program. Example get the rights of the instance.


*/


try {



ACL[] aclList = ie.getRights();





}

if (aclList.length == 0) {

System.out.println("There are no rights.");

}


close();


// Report the error



}

}

}

See also:

getInstanceRights of interface ApplElemAccess

Errors:


Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.read.ApplElemAccessTest.testGetValueMatrix()test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()test.highqsoft.odsapi.security.InitialRightsTest.testDeleteCreatedInstances()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()....

5.16.16 getValue of interface InstanceElement

Purpose:

Get the name-value-unit tuple of the given attribute of the instance element. This methodwill not return the value of relation attributes; use the method getRelatedInstances() for thiscase.


© 2015/08/19 Version 1.33




Return:

NameValueUnit nameValueUnit The name-value-unit tuple of the attribute.

Parameter:

Name attrName (in) The name of the requested attribute.


NameValueUnit nameValueUnit = instElem.getValue(attrName);

Java Example:







public class GetValue extends InstanceElementExampleAbstract {

/**

* The main program. Example get the Name of the instance using

* the attribute name of the based attribute name 'Name'.


*/


try {

// Get the instance


// Search for the name of the attribute


ApplicationAttribute aa = ae.getAttributeByBaseName("name");


// Get the name

NameValueUnit nameNVU = ie.getValue(aaName);

System.out.println("The instance: " + nameNVU.value.u.stringVal());

System.out.println("The name attribute is: " + nameNVU.valName);


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesValueQuery()


© 2015/08/19 Version 1.33




test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesValueQueryExt()test.highqsoft.avalon.InstanceElementReadTestIT.testSimpleInstanceReading()test.highqsoft.avalon.JBeamTestIT.testMeasurementJBeam()test.highqsoft.avalon.MultiSessionTestIT.threadInstancesValueQuery.threadInstancesValueQuery()....

5.16.17 getValueByBaseName of interface InstanceElement

Purpose:

Get the attribute's name-value-unit tuple of the attribute inherited from the given base at-tribute of the instance element. The base name is case insensitive and may not containwildcard characters.

Return:

NameValueUnit nameValueUnit The attribute name-value-unit tuple.

Parameter:

Name baseAttrName (in) The base name of the requested attribute.


NameValueUnit nameValueUnit = instElem.getValueByBaseName(baseAttrName);

Java Example:





public class GetValueByBaseName extends InstanceElementExampleAbstract {

/**

* The main program. Example get the Name of the instance using the base attribute name 'Name'.


*/


try {

// Get the instance


// Get the name, the base attribute name is case insenstive.

NameValueUnit nameNVU = ie.getValueByBaseName("name");

System.out.println("The instance: " + nameNVU.value.u.stringVal());

System.out.println("The name attribute is: " + nameNVU.valName);


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETER


© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.JBeamTestIT.testMeasurementJBeam()test.highqsoft.avalon.MeasurementTestCase.LoadCompareValues()test.highqsoft.avalon.MeasurementTestCase.LoadCompareValuesExt()test.highqsoft.avalon.MeasurementTestCase.LoadValuesIterator()....

5.16.18 getValueInUnit of interface InstanceElement

Purpose:

Get the attribute value (name, value and unit) of the given attribute of the instance element.

Return:

NameValueUnit nameValueUnit The attribute value, value converted to the requested unit.

Parameter:

NameUnit attr (in) The name of the requested attribute and the unit of the attribute value.


NameValueUnit nameValueUnit = instElem.getValueInUnit(attr);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_INCOMPATIBLE_UNITSAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.read.UnitTest.testGetInstancesAnuSeq()

5.16.19 getValueSeq of interface InstanceElement

Purpose:

Get the sequence of the values of the application or instance attributes, speci�ed by theirnames. The name sequence can use a pattern (∗) for all attributes of the instance element.This means that application as well as instance attributes will be delivered.


© 2015/08/19 Version 1.33




Return:

NameValueUnitSequence values The sequence of the attribute values.

Parameter:

NameSequence attrNames (in) The names of the attributes to be reported.


String attrNames[];

...

NameValueUnit values[] = ieObj.getValueSeq(attrNames);

Java Example:






public class GetValueSeq extends InstanceElementExampleAbstract {

/**

* The main program. Example get the all attribute values of an instance.


*/


try {

// Get the instance




String[] aaNameList = ae.listAttributes("*");

// Get the values of all attributes

NameValueUnit[] attrValues = ie.getValueSeq(aaNameList);

System.out.println("The instance: has " + attrValues.length + " attribute values");

// Here is a special part of the specification when all attributes

// are required, you can use also a pattern.

attrValues = ie.getValueSeq(new String[] { "*"});

System.out.println("The instance: has " + attrValues.length + " attribute values using pattern");


close();


// Report the error



}

}

}

Since

ASAM ODS 5.0

See also:

getValue of interface InstanceElementsetValue of interface InstanceElementsetValueSeq of interface InstanceElement


© 2015/08/19 Version 1.33




Errors:


Tested by:

test.highqsoft.avalon.SecurityTestIT.testIniRights()test.highqsoft.odsapi.ods530.InstanceElementWriteTest.testUpdateAoTest()test.highqsoft.odsapi.read.InstanceElementTest.testAllAttr()test.highqsoft.odsapi.read.LocalColumnTest.testGetElementsById()test.highqsoft.odsapi.read.UserReadTest.ThreadUserAttributes.run()....

5.16.20 listAttributes of interface InstanceElement

Purpose:

Get the attribute names from the instance element. The attribute name pattern is casesensitive and may contain wildcard characters. It can be distinguished between applicationand instance attributes. The attributes reserved for a relation are not listed.

Return:

NameSequence ieNames The names of the attributes.

Parameter:

Pattern iaPattern (in) The name or the search pattern for the attribute names.

AttrType aType (in) The requested attribute type.


AttrType aType = AttrType.ALL;

Name[] ieNames = instElem.listAttributes(iaPattern, aType);

Java Example:



import org.asam.ods.AttrType;


public class ListAttributes extends InstanceElementExampleAbstract {

/**

* The main program. Example get the names of the attributes of the instance.

*


*/


© 2015/08/19 Version 1.33





try {



String[] iaList = ie.listAttributes("*", AttrType.ALL);

for (String ia : iaList) {

System.out.println("Attribute " + ia);

}

if (iaList.length == 0) {

System.out.println("There are no attributes.");

}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_ATTRIBUTE_TYPEAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.JBeamTestIT.testMeasurementJBeam()test.highqsoft.odsapi.InstanceAttributeTest.testAddInstanceAttribute()

5.16.21 listRelatedInstances of interface InstanceElement

Purpose:

Get the names of the related instances. The application relation and the name of the relatedinstances speci�es the listed names. The pattern is case sensitive and may contain wildcardcharacters.

Return:

NameIterator ieNameIterator The names of the related instances.

Parameter:

ApplicationRelation ieRelation (in) The application relation.



NameIterator ieNameIterator = instElem.listRelatedInstances(ieRelation,iePattern);


© 2015/08/19 Version 1.33




Java Example:








public class ListRelatedInstances extends InstanceElementExampleAbstract {

/**

* The main program. Example shows how the related instances of an element are loaded.

*


*


*/


try {

// Get the instance







// Get the related instances.

NameIterator ieNameIter = ie.listRelatedInstances(arList[0], "*");

System.out.println("We have the names of related instance.");

// Destroy the name iterator, not used anymore at the client

ieNameIter.destroy();

} else {

System.out.println("Relation not found between.");

}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementTestIT.testInstancesRelationNames()test.highqsoft.avalon.MultiSessionTestIT.threadInstancesRelationNames.threadInstancesRelationNames()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CreateNewInstanceElementTest.testCreateFKInstances()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()....


© 2015/08/19 Version 1.33




5.16.22 listRelatedInstancesByRelationship of interface InstanceEle-ment

Purpose:

Get the names of the related instances. The relationship and the name of the related instancesspecify the listed names. The pattern is case sensitive and may contain wildcard characters.

Return:

NameIterator ieNameIterator The names of the related instances.

Parameter:

Relationship ieRelationship (in) The requested relationship.



NameIterator ieNameIterator = instElem.listRelatedInstancesByRelationship(ieRelationship,iePattern);

Java Example:






public class ListRelatedInstancesByRelationship extends InstanceElementExampleAbstract {

/**

* The main program. Example show how to get names of the related instances,

* this way is a very performance intensive way loaded the related instances,

* better use the method getInstancesExt of the interface ApplElemAccess.

*

* @param args

* not used.

*/


try {


NameIterator nameIter = ie.listRelatedInstancesByRelationship(Relationship.CHILD, "*");

System.out.println("There are " + nameIter.getCount() + " child instances.");


nameIter.destroy();


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETER


© 2015/08/19 Version 1.33




AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATIONSHIPAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()

5.16.23 removeInstanceAttribute of interface InstanceElement

Purpose:

Remove an instance attribute.It is allowed to remove the instance attribute outside a transaction but it is recommended toactivate a transaction.The application attributes can't be removed.

Return:

void

Parameter:

Name attrName (in) The name of the attribute to be removed.


instElem.removeInstanceAttribute(attrName);

Errors:


Tested by:

test.highqsoft.odsapi.InstanceAttributeTest.testAddInstanceAttribute()

5.16.24 removeRelation of interface InstanceElement

Purpose:

Remove the relation between the current instance and the given instance. It is necessary tospecify the instance element in case of n:m relations if not all relations shall be deleted.It is allowed to modify the instance element outside a transaction but it is recommended toactivate a transaction.


© 2015/08/19 Version 1.33




Return:

void

Parameter:

ApplicationRelation applRel (in) The relation to be removed.

InstanceElement instElem_nm (in) The instance element for speci�c delete from n:m rela-tions.


instElem.removeRelation(applRel,instElem_nm);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_RELATIONAO_NOT_FOUNDAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.read.ExtendedQueryTest.testAllAttr()test.highqsoft.odsapi.security.SecurityTestCase.cleanUserGroups()test.highqsoft.odsapi.security.SubTestCheckTest.tearDown()test.highqsoft.odsapi.security.XQueryTest.testDeleteTest()test.highqsoft.odsapi.DeleteInstanceElementTest.testApplElemAccessDeleteInstances()....

5.16.25 renameInstanceAttribute of interface InstanceElement

Purpose:

Rename the instance attribute. The application attributes can't be renamed.It is allowed to rename the instance attribute outside a transaction but it is recommended toactivate a transaction.

Return:

void

Parameter:

Name oldName (in) The old instance attribute name.

Name newName (in) The new instance attribute name.


instElem.renameInstanceAttribute(oldName,newName);


© 2015/08/19 Version 1.33




Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_DUPLICATE_NAMEAO_IMPLEMENTATION_PROBLEMAO_NOT_FOUNDAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.InstanceAttributeTest.testAddInstanceAttribute()

5.16.26 setInitialRights of interface InstanceElement

Purpose:

The given user group the initial rights should be set for. <rights> de�nes the rights to setor to clear. If the parameter <set> is set to 'set', the rights in <rights> are set all othersare cleared. If the parameter <set> is set to 'add', the rights in <rights> are added to theexisting rights. If the parameter <set> is set to 'remove', the rights in <rights> are removedfrom the existing rights.

Return:

void

Parameter:

InstanceElement usergroup (in) The user group for which the initial rights will be modi�ed.

T_LONG rights (in) The new initial rights for the user group. The rights constants arede�ned in the interface SecurityRights. The interface de�nition language IDL does not allowto set the values of enumerations thus the constant de�nitions have to be done in the interface.




instElem.setInitialRights(usergroup,rights, refAid,set);

See also:

setInstanceInitialRights of interface ApplElemAccess


© 2015/08/19 Version 1.33




Errors:


Tested by:

test.highqsoft.odsapi.security.CreateInstanceElementRightTest.testCheckElementRights()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()test.highqsoft.odsapi.security.SecurityTestCase.setInstanceInitialRights()test.highqsoft.odsapi.security.UserGroupDeleteTest.testCreateUserGroupWithRights()

5.16.27 setName of interface InstanceElement

Purpose:

Set the name of an instance element.It is allowed to modify the name of the instance element outside a transaction but it isrecommended to activate a transaction.

Return:

void

Parameter:

Name iaName (in) The instance attribute name.


instElem.setName(iaName);

Java Example:




public class SetName extends InstanceElementExampleAbstract {

/**

* The main program. Example set the Name of the instance.


*/


try {

// Get the instance


// Start the transaction for the modification


// Set the name

ie.setName("NewName");



© 2015/08/19 Version 1.33





System.out.println("The name is changed.");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()test.highqsoft.odsapi.CreateMeasurementSpecTest.testAppendValues()test.highqsoft.odsapi.WriteInstanceElementTest.testCompareCopied()

5.16.28 setRights of interface InstanceElement

Purpose:

The given user group the rights should be set for. <rights> de�nes the rights to set or to clear.If the parameter <set> is set to 'set', the rights in <rights> are set, all others are cleared. Ifthe parameter <set> is set to 'add', the rights in <rights> are added to the existing rights. Ifthe parameter <set> is set to 'remove', the rights in <rights> are removed from the existingrights.

Return:

void

Parameter:





instElem.setRights(usergroup,rights,set);


© 2015/08/19 Version 1.33




See also:

setInstanceRights of interface ApplElemAccess

Errors:


Tested by:

test.highqsoft.odsapi.security.E�RightsCheckTest.tearDown()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()test.highqsoft.odsapi.security.InstanceConcurrentCheckTest.testConcurrentApplElemAccess()test.highqsoft.odsapi.security.SecurityTestCase.setInstanceRights()test.highqsoft.odsapi.security.SubTestCheckTest.tearDown()....

5.16.29 setValue of interface InstanceElement

Purpose:

Set the value of an application attribute or of an existing instance attribute. This method willnot create a new instance attribute; for this purpose use the method addInstanceAttribute()of this interface.It is allowed to modify the attribute value outside a transaction but it is recommended toactivate a transaction.The name of the attribute is speci�ed by the name of the NameValueUnit tuple. If theapplication attribute �ag unique is set, the uniqueness of the new value is checked.This method can not be used to set the value of a relation attribute, use the method cre-ateRelation of this interface .

Note


Bug

The name of the attribute is compared caseblind. The attribute is part of the applicationmodelso the attribute name should be compared case sensitive.

Return:

void

Parameter:

NameValueUnit value (in) The value to be set in the instance element.


instElem.setValue(value);


© 2015/08/19 Version 1.33




Java Example:










public class SetValue extends InstanceElementExampleAbstract {

/**

* The main program. Example change the Name of the instance by

* setting the value of the attribute.

*


*/


try {


// Get the instance


// Search for the name of the attribute


ApplicationAttribute aa = ae.getAttributeByBaseName("name");


// Create the name attribute value

NameValueUnit nameNVU = new NameValueUnit();

// Set the attribute name

nameNVU.valName = aaName;

// Set the value

nameNVU.value = new TS_Value();

nameNVU.value.u = new TS_Union();

// The name is a string

nameNVU.value.u.stringVal("ModName");

// The name is defined, so the flag must be set to 15

nameNVU.value.flag = 15;

// The attribute has no unit, but the unit must be initialized

// to transfer by CORBA.

nameNVU.unit = "";


aoSess .startTransaction();

// Change the name by setting the attribute

ie.setValue(nameNVU);

// Commit the transaction.


System.out.println("The name is changed to " + ie.getName());


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_DUPLICATE_VALUEAO_IMPLEMENTATION_PROBLEM


© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.booleans.UpdateQueryTest.testCreateQuery()test.highqsoft.odsapi.bosch.MultiSessionIT.threadCreate.threadCreate()test.highqsoft.odsapi.bosch.MultiSessionIT.threadUpdate.threadUpdate()test.highqsoft.odsapi.changemodel.ApplElemCreateTest.testAddAttribute()....

5.16.30 setValueSeq of interface InstanceElement

Purpose:

Set a sequence of values of application attributes but no instances attributes.It is allowed to modify the values of the attributes outside a transaction but it is recommendedto activate a transaction.The name of the attribute is speci�ed by the name of the NameValueUnit tuple. If theapplication attribute �ag unique is set, the uniqueness of the new value is checked.Note: As the current speci�cation of the physical storage restricts the length of names ofinstance attributes to a maximum of 30 characters, clients must take care to not exceed thislimit if they instance attributes (those that arte not given by the application model) with thismethod call.

Note


Bug

The names of the attributes are compared caseblind. The attributes are part of the applica-tionmodel so the attribute names should be compared case sensitive.

Return:

void

Parameter:

NameValueUnitSequence values (in) The sequence of the values to be set at the instance ele-ment.


instElem.setValueSeq(values);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_DUPLICATE_VALUE


© 2015/08/19 Version 1.33




AO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()test.highqsoft.odsapi.ods530.InstanceElementWriteTest.testUpdateAoTest()test.highqsoft.odsapi.read.ExtendedQueryTest.testAllAttr()test.highqsoft.odsapi.read.ExtQueryExtRefTest.testDeleteExtRef()test.highqsoft.odsapi.security.SubTestCheckTest.tearDown()....

5.16.31 shallowCopy of interface InstanceElement

Purpose:

Provides an easy-to-use and e�ective copy mechanism for instance elements inside the server.The new instance elements gets a copy of all attribute values and informational relations thatare available in the original instance element. The new instance element has the same parentas the original instance element but it does not have references to any children of the originalinstance element.

Return:

InstanceElement newInstElem The reference to the copied instance element.

Parameter:

T_STRING newName (in) The name of the new instance element. If a new version shall becreated this parameter may be NULL to use the same name for the copy. In this case a newversion must be provided.

T_STRING newVersion (in) The version of the new instance element. This parameter maybe NULL if a new name is provided.


InstanceElement newInstElem = instElem.shallowCopy(newName,newVersion);

Java Example:






public class ShallowCopy extends InstanceElementExampleAbstract {

/**


© 2015/08/19 Version 1.33




* The main program. Example shows how a instance is copied.


*/


try {

// Get the instance





// Copy the instances with a new name and version which is the current date.

InstanceElement ieCopy = ie.shallowCopy("ExampleShallowCopy", ""+ new Date());



System.out.println("We have the copy the instance.");


close();


// Report the error



}

}

}

Since

ASAM ODS 4.1

Errors:


Tested by:

test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.ods530.TransactionTest.testCreate()test.highqsoft.odsapi.WriteInstanceElementTest.testCompareCopied()

5.16.32 upcastMeasurement of interface InstanceElement

Purpose:

Cast an instance element to a measurement. There are some object-oriented languages whichdo not allow this cast.

Return:

Measurement measurement The instance of type measurement.

Parameter:

None.


© 2015/08/19 Version 1.33





Measurement measurement = instElem.upcastMeasurement();

Java Example:




import org.asam.ods.Measurement;

public class UpcastMeasurement extends InstanceElementExampleAbstract {

/**

* The main program. Example how to upcast to the Measurement interface


*/


try {

// Get the instance


// Upcast to the Measurement

Measurement meaIe = ie.upcastMeasurement();

System.out.println("We have the measureent.");

// Clean up the measurement.

meaIe.destroy();


close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_INVALID_BASETYPE

Tested by:

5.16.33 upcastODSFile of interface InstanceElement

Purpose:

Upcast the InstanceElement object to the corresponding ODSFile interface for an instance.This method may only be invoked for instances of an application element derived fromthe base element AoFile and returns an ODSFile interface.An exception with the error code AO_INVALID_BASETYPE is thrown when the instanceis not an instance of an application element derived from the base element AoFile.


© 2015/08/19 Version 1.33




Return:

ODSFile odsFile The ODSFile interface to access the desired �le.

Parameter:

None.

Java Example:





public class UpcastODSFile extends InstanceElementExampleAbstract {

/**

* The main program. Example how to upcast to the ODSFile interface


* @since ASAM ODS 5.3.0

*/


try {

// Get the instance

InstanceElement ie = getInstanceElement("AoFile");

// Upcast to the ODSFile

ODSFile fileIe = ie.upcastODSFile();

System.out.println("We have the file.");


fileIe.destroy();


close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:

AO_INVALID_BASETYPEAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:


© 2015/08/19 Version 1.33




5.16.34 upcastSubMatrix of interface InstanceElement

Purpose:

Cast an instance element to a submatrix. There are some object-oriented languages which donot allow this cast.

Return:

SubMatrix subMatrix The instance of type submatrix.

Parameter:

None.


SubMatrix subMatrix = instElem.upcastSubMatrix();

Java Example:




import org.asam.ods.SubMatrix;

public class UpcastSubMatrix extends InstanceElementExampleAbstract {

/**

* The main program. Example how to upcast to the SubMatrix interface


*/


try {

// Get the instance

InstanceElement ie = getInstanceElement("AoSubMatrix");

// Upcast to the SubMatrix

SubMatrix meaIe = ie.upcastSubMatrix();

System.out.println("We have the submatrix.");


meaIe.destroy();


close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_INVALID_BASETYPE


© 2015/08/19 Version 1.33




Tested by:

test.highqsoft.odsapi.performance.MeasurementPerfIT.testCreateMeasurement()test.highqsoft.odsapi.read.MeasurementIT.testCompareNumberOfValues()test.highqsoft.odsapi.ORMETest.testORMECreate()

5.17 InstanceElementIterator

Package:

org.asam.ods

Description:

The ASAM ODS instance element iterator interface.

5.17.1 Java Examples of InstanceElementIterator


package api.methods.instanceelementiterator;







/** The examples of the methods of InstanceElementIterator are all derived from this class */

public class InstanceElementIteratorExampleAbstract extends AoSessionExampleAbstract {

// The session


protected static InstanceElementIterator ieIter=null;

/**

* Get an InstanceElementIterator, the iterator contains all the instances of the element


*

* @return the iterator


*/

protected static InstanceElementIterator getInstanceElementIterator() throws AoException {


aoSess = connect();

}


// Get the element



ieIter = ae.getInstances("*");

return (ieIter);

}

/**

* Get the session.



*/



© 2015/08/19 Version 1.33



5.17 InstanceElementIterator 397


aoSess = connect();

}

return (aoSess);

}

/**



*/


if (ieIter != null) {

ieIter.destroy();

}


aoSess.close();

aoSess = null;

}

}

}

5.17.2 destroy of interface InstanceElementIterator

Purpose:


Return:

void

Parameter:

None.


instElemIterator.destroy();

Java Example:




public class Destroy extends InstanceElementIteratorExampleAbstract {

/**

* The main program. Example show the destroy method of the InstanceElementIterator interface.

* The destroy method must be called when the client do not need the iterator


*

* @param args

* not used.

*/


try {

InstanceElementIterator ieIter = getInstanceElementIterator();



© 2015/08/19 Version 1.33




ieIter.destroy();

System.out.println("The iterator is destroyed.");




// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testCheckRelLccMeq()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()test.highqsoft.avalon.InstanceElementTestIT.testInstancesRelationNames()....

5.17.3 getCount of interface InstanceElementIterator

Purpose:


Return:

T_LONG instanceCount The number of elements accessible by the iterator.

Parameter:

None.


int instanceCount = instElemIterator.getCount();

Java Example:




public class GetCount extends InstanceElementIteratorExampleAbstract {

/**

* The main program. Example show to the number of instances of the iterator.


© 2015/08/19 Version 1.33




*

* @param args

* not used.

*/


try {


// Get the number of instances.

int count = ieIter.getCount();

System.out.println("The iterator has " + count + " instances");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testCheckRelLccMeq()test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()test.highqsoft.avalon.InstanceElementReadTestIT.testSimpleInstanceReading()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()....

5.17.4 nextN of interface InstanceElementIterator

Purpose:


Return:

InstanceElementSequence instElems The next n instance elements from the instance sequence.

Parameter:



InstanceElement[] instElems = instElemIterator.nextN(how_many);


© 2015/08/19 Version 1.33




Java Example:





public class NextN extends InstanceElementIteratorExampleAbstract {

/**

* The main program. Example shows how to get instances from the iterator,

* loading 10 instances in one call.

*

* @param args

* not used.

*/


try {


InstanceElement[] ieList;

do {

// Get the next 10 instances from the iterator, the length of the

// list is the number of instances available.

ieList = ieIter.nextN(10);

System.out.println(ieList.length + " instances loaded");

for (InstanceElement ie: ieList) {

// Destroy the instance, not needed anymore at the client.

ie.destroy();

}

} while (ieList.length > 0);


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementReadTestIT.testSimpleInstanceReading()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()test.highqsoft.odsapi.changemodel.CreateNewInstanceElementTest.testCreateFKInstances()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFileWithoutValues()....


© 2015/08/19 Version 1.33




5.17.5 nextOne of interface InstanceElementIterator

Purpose:

Get the next element from the sequence.In case no element is available a NIL object is returned.

Return:

InstanceElement instElem The next instance element from the instance sequence.

Parameter:

None.


InstanceElement instElem = instElemIterator.nextOne();

Java Example:





public class NextOne extends InstanceElementIteratorExampleAbstract {

/**

* The main program. Example shows how to get the instances from the iterator,

* loading each instance separately.

*

* @param args

* not used.

*/


try {


InstanceElement ie;

do {

// Get the next instance from the iterator.


if (ie != null) {


ie.destroy();

}

} while (ie != null);

System.out.println("All instances got from the iterator.");


close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()test.highqsoft.avalon.InstanceElementReadTestIT.testSimpleInstanceReading()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()test.highqsoft.avalon.InstanceElementTestIT.testInstancesRelationNames()....

5.17.6 reset of interface InstanceElementIterator

Purpose:

Reset the pointer in the element sequence to the �rst element.

Return:

void

Parameter:

None.


instElemIterator.reset();

Java Example:




public class Reset extends InstanceElementIteratorExampleAbstract {

/**

* The main program. Example show how to reset the iterator to the beginning.

*

* @param args

* not used.

*/


try {


// Reset the iterator.

ieIter.reset();

System.out.println("The iterator is reset.");


close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33



5.18 Measurement 403

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementAEATestIT.testInstancesRelations()test.highqsoft.avalon.InstanceElementTestIT.testCheckPosIds()test.highqsoft.avalon.MultiSessionTestIT.threadInstancesRelations.threadInstancesRelations()test.highqsoft.avalon.ValueMatrixUnitTestIT.testCheckUnit()test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()....

5.18 Measurement

Package:

org.asam.ods

Description:

The ASAM ODS measurement interface.The interface Measurement extends the interface In-stanceElement. Thus all methods of the interface InstanceElement do also work here.

Derived:

InstanceElement

5.18.1 Java Examples of Measurement


package api.methods.measurement;





import api.methods.instanceelement.InstanceElementExampleAbstract;

/** The examples of the methods of Measurement are all derived from this class */

public class MeasurementExampleAbstract extends InstanceElementExampleAbstract {

// The session


protected static Measurement mea=null;

/**

* Get an instance of AoMeasurement, the instance is one of the instances

* from the element derived from AoMeasurement.

*

* @return the instance of measurement.


© 2015/08/19 Version 1.33





*/

protected static Measurement getMeasurement() throws AoException {


mea = ie.upcastMeasurement();

ie.destroy();

return (mea);

}

/**

* Get the session.



*/



aoSess = connect();

}

return (aoSess);

}

/**



*/


if (mea != null) {

mea.destroy();

}


aoSess.close();

aoSess = null;

}

}

}

5.18.2 createSMatLink of interface Measurement

Purpose:

Create a submatrix link. The submatrix link is only valid in the current session. When thesession is closed the submatrix link will be destroyed.

Note

Not jet implemented, SMatLink are not well de�ned in ASAM ODS.

Return:

SMatLink smLink The new submatrix link.

Parameter:

None.


SMatLink smLink = measurement.createSMatLink();


© 2015/08/19 Version 1.33




Errors:


Tested by:

5.18.3 getSMatLinks of interface Measurement

Purpose:

Get the list of the submatrix links .

Note


Return:

SMatLinkSequence smLinks The available submatrix links.

Parameter:

None.


SMatLink[] smLinks = measurement.getSMatLinks();

Errors:


Tested by:

5.18.4 getValueMatrix of interface Measurement

Purpose:

Get the value matrix of a measurement.By calling this method, the value matrix mode of the returned value matrix will be taken fromthe context variable 'VALUEMATRIX_MODE'. For more information especially on di�erentmodes of the value matrix, see description at the method getValueMatrixInMode() of thisinterface.


© 2015/08/19 Version 1.33




Return:


Parameter:

None.



Java Example:





public class GetValueMatrix extends MeasurementExampleAbstract {

/**

* The main program. Example get valuematrix from the measurement.


*/


try {

// Get the instance

Measurement ie = getMeasurement();

ValueMatrix vm = ie.getValueMatrix();

vm.destroy();

System.out.println("The valuematrix is loaded.");


close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_INVALID_VALUEMATRIX_STRUCTURE

Tested by:

test.highqsoft.avalon.MeasurementTestIT.testManyMeasurement()test.highqsoft.odsapi.ford.FordMesaurementTest.testCreateMeasurementDoubleLc()test.highqsoft.odsapi.read.MeasurementIT.testCompareNumberOfValues()test.highqsoft.odsapi.read.UnitTest.testGetInstancesAnuSeq()test.highqsoft.odsapi.CreateInstanceTestCase.checkMeasurementInstances()....


© 2015/08/19 Version 1.33




5.18.5 getValueMatrixInMode of interface Measurement

Purpose:

Get the value matrix of a measurement in the requested mode.The server checks the independent column. If there is more than one submatrix at the mea-surement there must be exactly one independent column with the same measurement quantityin each submatrix, otherwise the exception AO_INVALID_VALUEMATRIX_STRUCTUREis thrown.The server throws the exception AO_INVALID_VALUEMATRIX_STRUCTURE when itis unable to create the value matrix due to the data of the measurement- if there are no independent columns- if there are di�erent independent columns- if there are sub matrices with more than one independent local column.The server sorts the values according to the values of the independent localcolumn (in as-cending order). It is up to the server what value is returned when a measurement quantityhas two di�erent values at the same measurement point. The gaps in the value matrix aremarked with appropriate �ags in TS_ValueSeq (�agvalue = 0).In the CALCULATED mode the server returns the calculated values for implicit and rawvalues. The server returns at each measurement point the explicit value as the value for theimplicit channels. The raw values are calculated to the explicit values.In the STORAGE mode the server returns the values of the localcolumn as they are in thephysical storage. Writing values to a value matrix is only allowed when the value matrix isSTROAGE.

Return:


Parameter:




Java Example:






public class GetValueMatrixInMode extends MeasurementExampleAbstract {

/**

* The main program. Example get valuematrix in the calculated mode

* from the measurement.

*


*/


try {

// Get the instance

Measurement ie = getMeasurement();

ValueMatrix vm = ie.getValueMatrixInMode(ValueMatrixMode.CALCULATED);


© 2015/08/19 Version 1.33




vm.destroy();



close();


// Report the error



}

}

}

Since

ASAM ODS 5.2

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_INVALID_VALUEMATRIX_STRUCTURE

Tested by:

test.highqsoft.avalon.MultiSessionTestIT.threadCreateValueMatrix.threadCreateValueMatrix()test.highqsoft.avalon.ValueMatrixCompareTestIT.testCompareValueMatrix()test.highqsoft.avalon.ValueMatrixCreateTestIT.testCreateValueMatrix()test.highqsoft.avalon.ValueMatrixUnitTestIT.testCheckUnit()test.highqsoft.odsapi.ods530.MeasurementFileTest.testCountFile()....

5.18.6 removeSMatLink of interface Measurement

Purpose:

Remove a submatrix link.

Note


Return:

void

Parameter:

SMatLink smLink (in) The sub matrix link to be removed.


measurement.removeSMatLink(smLink);

Errors:

AO_BAD_PARAMETER


© 2015/08/19 Version 1.33



5.19 NameIterator 409

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_FOUNDAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

5.19 NameIterator

Package:

org.asam.ods

Description:

The ASAM ODS name iterator interface.

The NameIterator returns at the nextOne() method a String. The String is not de�ned as a corbainterface but as an corba type. Corba does not support the transport of a NULL-value. Whenafter the last element in the iterator a request is done, an Corba exception will occure.

5.19.1 Java Examples of NameIterator


package api.methods.nameiterator;







/** The examples of the methods of NameIterator are all derived from this class */

public class NameIteratorExampleAbstract extends AoSessionExampleAbstract {

// The session


protected static NameIterator nameIter=null;

/**

* Get an NameIterator, the iterator contains all the names of the

* instances of the element derived from AoTest.

*



*/

protected static NameIterator getNameIterator() throws AoException {


aoSess = connect();

}


// Get the element



© 2015/08/19 Version 1.33





nameIter = ae.listInstances("*");

return (nameIter);

}

/**

* Get the session.



*/



aoSess = connect();

}

return (aoSess);

}

/**



*/


if (nameIter != null) {

nameIter.destroy();

}


aoSess.close();

aoSess = null;

}

}

}

5.19.2 destroy of interface NameIterator

Purpose:


Return:

void

Parameter:

None.


nameIterator.destroy();

Java Example:




public class Destroy extends NameIteratorExampleAbstract {

/**


© 2015/08/19 Version 1.33




* The main program. Example show the destroy method of the NameIterator interface.



*

* @param args

* not used.

*/


try {

NameIterator nameIter = getNameIterator();


nameIter.destroy();





// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.AoSessionTestIT.tearDown()test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()test.highqsoft.avalon.InstanceElementTestIT.testInstancesRelationNames()test.highqsoft.avalon.MultiSessionTestIT.threadInstancesRelationNames.threadInstancesRelationNames()test.highqsoft.odsapi.changemodel.CheckNameLengthTest.testCheckMaxName()....

5.19.3 getCount of interface NameIterator

Purpose:


Return:

T_LONG nameCount The number of elements accessible by the iterator.

Parameter:

None.


int nameCount = nameIterator.getCount();


© 2015/08/19 Version 1.33




Java Example:




public class GetCount extends NameIteratorExampleAbstract {

/**

* The main program. Example show how to get the number names of the iterator.

*

* @param args

* not used.

*/


try {


// Get the number of names.

int count = nameIter.getCount();

System.out.println("The iterator has " + count + " names");


close();


// Report the error



}

}

}

Errors:


Tested by:


5.19.4 nextN of interface NameIterator

Purpose:

Get the next n elements from the name sequence.In case there are less elements available than requested, only as many as are available will bereturned; if there is none left an empty list is returned.

Return:

NameSequence names The next n names from the name sequence.


© 2015/08/19 Version 1.33




Parameter:



String[] names = nameIterator.nextN(how_many);

Java Example:




public class NextN extends NameIteratorExampleAbstract {

/**

* The main program. Example shows how to get names of the instances from the iterator.

*

* @param args

* not used.

*/


try {


String[] nameList;

do {



nameList = nameIter.nextN(10);

System.out.println(nameList.length + " instances names loaded");

for (String ieName: nameList) {


System.out.println("Instance name " + ieName);

}

} while (nameList.length > 0);


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()test.highqsoft.odsapi.read.AoSessionTest.testAoSessionContextFilter()test.highqsoft.odsapi.security.InstanceCheckTest.testAddUserGroup()


© 2015/08/19 Version 1.33




5.19.5 nextOne of interface NameIterator

Purpose:

Get the next element from the name sequence.In case no element is available a CORBA exception will be thrown.

Return:

Name name The next name from the name sequence.

Parameter:

None.


String name = nameIterator.nextOne();

Java Example:




public class NextOne extends NameIteratorExampleAbstract {

/**

* The main program. Example shows how to get names from the iterator.

*

* @param args

* not used.

*/


try {


String name;

int noNames = nameIter.getCount();

for (int i = 0; i < noNames; i++) {

// Get the next instance name from the iterator.

name = nameIter.nextOne();

if (name != null) {

System.out.println("Instance name " + name);

}

}

System.out.println("All names got from the iterator.");


close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33




Tested by:


5.19.6 reset of interface NameIterator

Purpose:

Reset the internal pointer in the element sequence to the �rst element.

Return:

void

Parameter:

None.


nameIterator.reset();

Java Example:




public class Reset extends NameIteratorExampleAbstract {

/**

* The main program. Example show Example show how to reset the iterator to the beginning.

*

* @param args

* not used.

*/


try {



nameIter.reset();



close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOST


© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.avalon.InstanceElementTestIT.testInstancesNames()

5.20 NameValueIterator

Package:

org.asam.ods

Description:

The ASAM ODS name-value iterator interface.

The NameValueIterator returns at the nextOne() method a NameValue. The NameValue is notde�ned as a corba interface but as an corba structure. Corba does not support the transportof a NULL-Structure. When after the last element in the iterator a request is done, an Corbaexception will occure.

5.20.1 Java Examples of NameValueIterator


package api.methods.namevalueiterator;






/** The examples of the methods of NameValueIterator are all derived from this class */

public class NameValueIteratorExampleAbstract extends AoSessionExampleAbstract {

// The session


protected static NameValueIterator nameValueIter=null;

/**

* Get an NameValueIterator, the iterator contains all the context

* variables from the session.

*



*/

protected static NameValueIterator getNameValueIterator() throws AoException {


aoSess = connect();

}


nameValueIter = aoSess.getContext("*");

return (nameValueIter);

}


© 2015/08/19 Version 1.33



5.20 NameValueIterator 417

/**

* Get the session.



*/



aoSess = connect();

}

return (aoSess);

}

/**



*/


if (nameValueIter != null) {

nameValueIter.destroy();

}


aoSess.close();

aoSess = null;

}

}

}

5.20.2 destroy of interface NameValueIterator

Purpose:


Return:

void

Parameter:

None.


nameValueIterator.destroy();

Java Example:




public class Destroy extends NameValueIteratorExampleAbstract {

/**

* The main program. Example show the destroy method of the NameValueIterator interface.



*

* @param args


© 2015/08/19 Version 1.33




* not used.

*/


try {

NameValueIterator nameValueIter = getNameValueIterator();


nameValueIter.destroy();





// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.odsapi.read.AoSessionTest.testAoSessionContextFilter()

5.20.3 getCount of interface NameValueIterator

Purpose:


Return:

T_LONG nvCount The number of elements accessible by the iterator.

Parameter:

None.


int nvCount = nameValueIterator.getCount();

Java Example:




public class GetCount extends NameValueIteratorExampleAbstract {

/**

* The main program. Example show how to get the number names of the iterator.


© 2015/08/19 Version 1.33




*

* @param args

* not used.

*/


try {


// Get the number of context variables.

int count = nameValueIter.getCount();

System.out.println("The iterator has " + count + " cotext variables");


close();


// Report the error



}

}

}

Errors:


Tested by:


5.20.4 nextN of interface NameValueIterator

Purpose:

Get the next n elements from the NameValue sequence.In case there are less elements available than requested, only as many as are available will bereturned; if there is none left an empty list is returned.

Return:

NameValueSequence nameValues The next n NameValue pairs from the NameValue pair se-quence.

Parameter:



NameValue[] nameValues = nameValueIterator.nextN(how_many);

Java Example:




© 2015/08/19 Version 1.33






public class NextN extends NameValueIteratorExampleAbstract {

/**

* The main program. Example shows how to get context variables from the iterator.

*

* @param args

* not used.

*/


try {


NameValue[] nameValueList;

do {



nameValueList = nameValueIter.nextN(10);

System.out.println(nameValueList.length + " context variables loaded");

} while (nameValueList.length > 0);


close();


// Report the error



}

}

}

Errors:


Tested by:


5.20.5 nextOne of interface NameValueIterator

Purpose:

Get the next element from the NameValue sequence.In case no element is available a NIL object is returned.

Return:

NameValue nameValue The next NameValue pair from the NameValue pair sequence.

Parameter:

None.


NameValue nameValue = nameValueIterator.nextOne();


© 2015/08/19 Version 1.33




Java Example:





public class NextOne extends NameValueIteratorExampleAbstract {

/**


*

* @param args

* not used.

*/


try {


NameValue nameValue;

do {


nameValue = nameValueIter.nextOne();

} while (nameValue != null);

System.out.println("All context variables got from the iterator.");


close();


// Report the error



}

}

}

Errors:


Tested by:


5.20.6 reset of interface NameValueIterator

Purpose:


Return:

void

Parameter:

None.


nameValueIterator.reset();


© 2015/08/19 Version 1.33




Java Example:




public class Reset extends NameValueIteratorExampleAbstract {

/**


*

* @param args

* not used.

*/


try {



nameValueIter.reset();



close();


// Report the error



}

}

}

Errors:


5.21 NameValueUnitIdIterator

Package:

org.asam.ods

Description:

The ASAMODS NameValueUnitId iterator interface. This interface is identical with the NameVal-ueUnitIterator, except the unit is given as an Id instead of a string.

The NameValueUnitIdIterator returns at the nextOne() method a NameValueUnitId. TheNameValueUnitId is not de�ned as a corba interface but as an corba structure. Corba doesnot support the transport of a NULL-Structure. When after the last element in the iterator arequest is done, an Corba exception will occure.

5.21.1 destroy of interface NameValueUnitIdIterator

Purpose:



© 2015/08/19 Version 1.33



5.21 NameValueUnitIdIterator 423

Return:

void

Parameter:

None.


nameValueUnitIdIterator.destroy();

Errors:


Tested by:

5.21.2 getCount of interface NameValueUnitIdIterator

Purpose:


Return:

T_LONG nameValueUnitIdCount The number of elements accessible by the iterator.

Parameter:

None.


int nvuIdCount = nameValueUnitIdIterator.getCount();

Errors:


Tested by:


© 2015/08/19 Version 1.33




5.21.3 nextN of interface NameValueUnitIdIterator

Purpose:


Return:

NameValueSeqUnitId nameValueUnitIdSeq The next n name-value-unit tuples from the name-value-unit tuple sequence.

Parameter:



NameValueUnitId[] nameValueUnitIds = nameValueUnitIdIterator.nextN(how_many);

Errors:


Tested by:

5.21.4 nextOne of interface NameValueUnitIdIterator

Purpose:

Get the next element from the sequence.In case no element is available a NIL object is returned.

Return:

NameValueUnitId nameValueUnitId The next name-value-unitId tuple from the name-value-unitId tuple sequence.

Parameter:

None.


NameValueUnitId nameValueUnitId = nameValueUnitIdIterator.nextOne();

Errors:

AO_CONNECTION_LOST


© 2015/08/19 Version 1.33



5.22 NameValueUnitIterator 425


Tested by:

5.21.5 reset of interface NameValueUnitIdIterator

Purpose:


Return:

void

Parameter:

None.


nameValueUnitIdIterator.reset();

Errors:


5.22 NameValueUnitIterator

Package:

org.asam.ods

Description:

The ASAM ODS NameValueUnit iterator interface. This interface is identical with the NameVal-ueUnitIdIterator, except the unit is given as a string instead of an Id.

The NameValueUnitIterator returns at the nextOne() method a NameValueUnit. The NameVal-ueUnit is not de�ned as a corba interface but as an corba structure. Corba does not support thetransport of a NULL-Structure. When after the last element in the iterator a request is done, anCorba exception will occure. A Stackprint is show below:

Caused an ERROR

----------BEGIN server-side stack trace----------

org.omg.CORBA.UNKNOWN: vmcid: SUN minor code: 202 completed: Maybe

at com.sun.corba.se.impl.logging.ORBUtilSystemException.runtimeexception(

ORBUtilSystemException.java:8365)


© 2015/08/19 Version 1.33




at com.sun.corba.se.impl.protocol.CorbaMessageMediatorImpl.convertThrowab

leToSystemException(CorbaMessageMediatorImpl.java:1918)

at com.sun.corba.se.impl.protocol.CorbaMessageMediatorImpl.handleThrowabl

eDuringServerDispatch(CorbaMessageMediatorImpl.java:1868)



at com.sun.corba.se.impl.protocol.CorbaServerRequestDispatcherImpl.dispat

ch(CorbaServerRequestDispatcherImpl.java:258)

at com.sun.corba.se.impl.protocol.CorbaMessageMediatorImpl.handleRequestR

equest(CorbaMessageMediatorImpl.java:1680)

at com.sun.corba.se.impl.protocol.CorbaMessageMediatorImpl.handleRequest(

CorbaMessageMediatorImpl.java:1540)

at com.sun.corba.se.impl.protocol.CorbaMessageMediatorImpl.handleInput(Co

rbaMessageMediatorImpl.java:922)

at com.sun.corba.se.impl.protocol.giopmsgheaders.RequestMessage_1_2.callb

ack(RequestMessage_1_2.java:181)



at com.sun.corba.se.impl.transport.SocketOrChannelConnectionImpl.dispatch

(SocketOrChannelConnectionImpl.java:451)

at com.sun.corba.se.impl.transport.SocketOrChannelConnectionImpl.doWork(S

ocketOrChannelConnectionImpl.java:1187)

at com.sun.corba.se.impl.orbutil.threadpool.ThreadPoolImpl$WorkerThread.r

un(ThreadPoolImpl.java:417)

Caused by: java.lang.NullPointerException

at org.asam.ods.NameValueUnitHelper.write(NameValueUnitHelper.java:87)

at org.asam.ods.NameValueUnitIteratorPOA._invoke(NameValueUnitIteratorPOA

.java:150)


chToServant(CorbaServerRequestDispatcherImpl.java:637)



... 8 more

----------END server-side stack trace----------

org.omg.CORBA.UNKNOWN: ----------BEGIN server-side stack trace----------

org.omg.CORBA.UNKNOWN: vmcid: SUN minor code: 202 completed: Maybe

at com.sun.corba.se.impl.logging.ORBUtilSystemException.runtimeexception(

ORBUtilSystemException.java:8365)

at com.sun.corba.se.impl.protocol.CorbaMessageMediatorImpl.convertThrowab

leToSystemException(CorbaMessageMediatorImpl.java:1918)







at com.sun.corba.se.impl.protocol.CorbaMessageMediatorImpl.handleRequestR

equest(CorbaMessageMediatorImpl.java:1680)



at com.sun.corba.se.impl.protocol.CorbaMessageMediatorImpl.handleInput(Co

rbaMessageMediatorImpl.java:922)

at com.sun.corba.se.impl.protocol.giopmsgheaders.RequestMessage_1_2.callb

ack(RequestMessage_1_2.java:181)



at com.sun.corba.se.impl.transport.SocketOrChannelConnectionImpl.dispatch

(SocketOrChannelConnectionImpl.java:451)

at com.sun.corba.se.impl.transport.SocketOrChannelConnectionImpl.doWork(S

ocketOrChannelConnectionImpl.java:1187)

at com.sun.corba.se.impl.orbutil.threadpool.ThreadPoolImpl$WorkerThread.r

un(ThreadPoolImpl.java:417)

Caused by: java.lang.NullPointerException

at org.asam.ods.NameValueUnitHelper.write(NameValueUnitHelper.java:87)

at org.asam.ods.NameValueUnitIteratorPOA._invoke(NameValueUnitIteratorPOA

.java:150)


© 2015/08/19 Version 1.33





chToServant(CorbaServerRequestDispatcherImpl.java:637)



... 8 more

----------END server-side stack trace---------- vmcid: SUN minor code: 202 comp

leted: Maybe

at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)

at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructo

rAccessorImpl.java:39)

at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingCo

nstructorAccessorImpl.java:27)

at java.lang.reflect.Constructor.newInstance(Constructor.java:494)

at com.sun.corba.se.impl.protocol.giopmsgheaders.MessageBase.getSystemExc

eption(MessageBase.java:902)

at com.sun.corba.se.impl.protocol.giopmsgheaders.ReplyMessage_1_2.getSyst

emException(ReplyMessage_1_2.java:99)

at com.sun.corba.se.impl.protocol.CorbaMessageMediatorImpl.getSystemExcep

tionReply(CorbaMessageMediatorImpl.java:572)

at com.sun.corba.se.impl.protocol.CorbaClientRequestDispatcherImpl.proces

sResponse(CorbaClientRequestDispatcherImpl.java:430)

at com.sun.corba.se.impl.protocol.CorbaClientRequestDispatcherImpl.marsha

lingComplete(CorbaClientRequestDispatcherImpl.java:326)

at com.sun.corba.se.impl.protocol.CorbaClientDelegateImpl.invoke(CorbaCli

entDelegateImpl.java:129)

at org.omg.CORBA.portable.ObjectImpl._invoke(ObjectImpl.java:457)

at org.asam.ods._NameValueUnitIteratorStub.nextOne(_NameValueUnitIterator

Stub.java:150)

at test.highqsoft.avalon.ValueMatrixTest.testValueMatrixGetMeaPoint(Value

MatrixTest.java:1545)

at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)

at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.j

ava:39)

Use the following code to read all elements from the iterator without an corba exception:

NameValueUnitIterator nvuIter = vmObj.getValueMeaPoint(0);

if (nvuIter != null) {

NameValueUnit nvu;

int noPoints = nvuIter.getCount();

for (int i = 0; i < noPoints; i++) {

nvu = nvuIter.nextOne();

//

// TODo

//

}

nvuIter.destroy();

}

5.22.1 Java Examples of NameValueUnitIterator


package api.methods.namevalueunititerator;





import org.asam.ods.NameValueUnitIterator;




© 2015/08/19 Version 1.33





/** The examples of the methods of NameValueIterator are all derived from this class */

public class NameValueUnitIteratorExampleAbstract extends InstanceElementExampleAbstract {

// The session

protected static NameValueUnitIterator nameValueUnitIter=null;

protected static ValueMatrix vm = null;

/**

* Get an NameValueIterator, the iterator contains all the context

* variables from the session.

*



*/

protected static NameValueUnitIterator getNameValueUnitIterator() throws AoException {


aoSess = connect();

}

NameValueUnitIterator nameValueUnitIter=null;



SubMatrix sm = ie.upcastSubMatrix();

vm = sm.getValueMatrix();

nameValueUnitIter = vm.getValueMeaPoint(0);

sm.destroy();

ie.destroy();

return (nameValueUnitIter);

}

/**

* Get the session.



*/



aoSess = connect();

}

return (aoSess);

}

/**



*/


if (nameValueUnitIter != null) {

nameValueUnitIter.destroy();

}

if (vm != null) {

vm.destroy();

}


aoSess.close();

aoSess = null;

}

}

}


© 2015/08/19 Version 1.33




5.22.2 destroy of interface NameValueUnitIterator

Purpose:


Return:

void

Parameter:

None.


nameValueUnitIterator.destroy();

Java Example:




public class Destroy extends NameValueUnitIteratorExampleAbstract {

/**

* The main program. Example show the destroy method of the NameValueUnitIterator interface.



*

* @param args

* not used.

*/


try {

NameValueUnitIterator nameValueUnitIter = getNameValueUnitIterator();


nameValueUnitIter.destroy();





// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixGetTestIT.testValueMatrixGetMeaPoint()


© 2015/08/19 Version 1.33




5.22.3 getCount of interface NameValueUnitIterator

Purpose:


Return:

T_LONG nvuCount The number of elements accessible by the iterator.

Parameter:

None.


int nvuCount = nameValueUnitIterator.getCount();

Java Example:




public class GetCount extends NameValueUnitIteratorExampleAbstract {

/**

* The main program. Example show how to get the number of the iterator.

*

* @param args

* not used.

*/


try {


// Get the number of context variables.

int count = nameValueUnitIter.getCount();

System.out.println("The iterator has " + count + " cotext variables");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixGetTestIT.testValueMatrixGetMeaPoint()test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()


© 2015/08/19 Version 1.33




5.22.4 nextN of interface NameValueUnitIterator

Purpose:

Get the next n elements from the NameValueUnit sequence.In case there are less elements available than requested, only as many as are available will bereturned; if there is none left an empty list is returned.

Return:

NameValueUnitSequence nameValueUnits The next n NameValueUnit tuples from theNameValueUnit tuple sequence.

Parameter:



NameValueUnit[] nameValueUnits = nameValueUnitIterator.nextN(how_many);

Java Example:





public class NextN extends NameValueUnitIteratorExampleAbstract {

/**


*

* @param args

* not used.

*/


try {


NameValueUnit[] nameValueUnitList;

do {



nameValueUnitList = nameValueUnitIter.nextN(10);

System.out.println(nameValueUnitList.length + " context variables loaded");

} while (nameValueUnitList.length > 0);


close();


// Report the error



}

}

}

Errors:



© 2015/08/19 Version 1.33





Tested by:


5.22.5 nextOne of interface NameValueUnitIterator

Purpose:

Get the next element from the NameValueUnit sequence.In case no element is available a NIL object is returned.

Return:

NameValueUnit nameValueUnit The next NameValueUnit tuple from the NameValueUnit tu-ple sequence.

Parameter:

None.


NameValueUnit nameValueUnit = nameValueUnitIterator.nextOne();

Java Example:





public class NextOne extends NameValueUnitIteratorExampleAbstract {

/**


*

* @param args

* not used.

*/


try {


NameValueUnit nameValueUnit;

do {


nameValueUnit = nameValueUnitIter.nextOne();

} while (nameValueUnit != null);

System.out.println("All context variables got from the iterator.");


close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33




Errors:


Tested by:


5.22.6 reset of interface NameValueUnitIterator

Purpose:


Return:

void

Parameter:

None.


nameValueUnitIterator.reset();

Java Example:




public class Reset extends NameValueUnitIteratorExampleAbstract {

/**


*

* @param args

* not used.

*/


try {



nameValueUnitIter.reset();



close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33




Errors:


Tested by:


5.23 NameValueUnitSequenceIterator

Package:

org.asam.ods

Description:

The name value unit sequence iterator. The table iterator as query result.

5.23.1 destroy of interface NameValueUnitSequenceIterator

Purpose:


Return:

void

Parameter:

None.


nameValueUnitSequenceIterator.destroy();

Errors:


Tested by:


© 2015/08/19 Version 1.33



5.23 NameValueUnitSequenceIterator 435

5.23.2 getCount of interface NameValueUnitSequenceIterator

Purpose:


Return:

T_LONG nameValueUnitCount The number of elements accessible by the iterator.

Parameter:

None.


int nameValueUnitCount = nameValueUnitSequenceIterator.getCount();

Errors:


Tested by:

5.23.3 nextN of interface NameValueUnitSequenceIterator

Purpose:


Return:

NameValueSeqUnitSequence nameValueSeqUnits The next n values of the name-value-unitsequence. For each NameValuUnit the next n values are stored in the value sequence.

Parameter:



NameValueSeqUnit[] nameValueSeqUnits = nameValueUnitSequenceIterator.nextN(how_many);

Errors:



© 2015/08/19 Version 1.33




Tested by:

5.23.4 nextOne of interface NameValueUnitSequenceIterator

Purpose:

Get the next element from the iterator.In case no element is available a NIL object is returned.

Return:

NameValueSeqUnit nameValueSeqUnit The next name-value-unit tuple sequence from thename-value-unit tuple.

Parameter:

None.


NameValueSeqUnit nameValueSeqUnit = nameValueUnitSequenceIterator.nextOne();

Errors:


Tested by:

5.23.5 reset of interface NameValueUnitSequenceIterator

Purpose:

Reset the internal pointer in the element iterator to the �rst element.

Return:

void

Parameter:

None.


nameValueUnitSequenceIterator.reset();


© 2015/08/19 Version 1.33



5.24 ODSFile 437

Errors:


5.24 ODSFile

Package:

org.asam.ods

Description:

The interface ODSFile extends the interface InstanceElement. Thus all methods of the interfaceInstanceElement do also work here.

ODSFile allows to create a �le that is under control of the ODS server (a 'managed �le'). ODSFilefurthermore allows read, write, append or remove operations to a managed �le.

General information of the �le can be retrieved from this interface as well. Note, that no randomaccess on a �le is provided; only a sequential read and a write by appending at the end is possible.

Replacing an existing �le by a new one requires �rst to remove the old one and then create thenew one.

Derived:

InstanceElement

Files under control of the ODS server are manged �les uning the ODSFile interface and areinstances of an application element derived from AoFile.

Such �les will only appear in or disappear from the server namespace through explicit serveractions. General purpose clients will not directly have access to them (unless the security mech-anisms of the ODS server system are insu�ciently set up); thus a client application cannot copysuch �le immediately into the server namespace nor can it remove or read such �le directly. Thisresults in a much more secure server environment, as no shared drives or FTP channels need to beprovide to clients. In order to read from or write to such �le, ODS provides a base element AoFileand speci�c OO-API interfaces. Note that the RPC-API does not provide methods to access such�les. Each �le that is under control of the ODS server is represented by exactly one instance ofan application element derived from AoFile. All �les which are represented by an instance of anapplication element derived from AoFile belong to this group.

This section describes the concept of managed �les (i.e. �les that are under control of the ODSserver) and compares it to the server behavior with regard to �les that are out of control of theserver. Note that external references (given by the base attribute 'external_references') generallydo not fall under the concept of managed �les, and external component �les only fall under thisconcept if the �les storing values or value �ags use instances of application elements derived fromAoFile. Legacy data before ODS V5.3.0 do not fall under the concept of managed �les.

Bringing �les into and removing �les from the server namespace Files that are out of control of theODS server will not be maintained by the ODS server. It is up to a client application to providesuch �le as well as to delete such �le. Before deleting it, the client application must make sure that


© 2015/08/19 Version 1.33




there is no reference to that �le remaining within the ODS server database. Otherwise consistencyproblems may arise, as �les that are referenced cannot be found at their referred location.

Files that shall be put under control of the ODS server have to be delivered to the server by theclient using the OO-API. It provides the interfaces ODSFile, ODSReadTransfer, and ODSWrite-Transfer for such purpose. In this case the ODS server decides internally where to store the �les,and clients do not need to have direct access (like FTP, shared drive) to the �le location and mightnot even understand where the �le is located. The �le location will be stored in the instance ofan application element derived from AoFile which represents the �le; the attribute derived from'ao_location' is used for that, and the location is speci�ed as described in section 2.10.6; it willuse the symbol name FILE_ROOT_MANAGED, or (if the latter is not speci�ed) the symbolname FILE_ROOT. If the �le that shall be put under control of the ODS server already resideswithin the server namespace, its current location is provided to the server and the server maysimply move the �le to the location where managed �les reside. Similarly a �le can be taken outof control of the server by providing a location to the server which speci�es where to move the �le.If the �le that shall be put under control of the ODS server is not yet within the server namespacethe client will not copy it in a usual way but will read its content, send it to the ODS serverthrough API methods as stream of bytes, and the server will rebuild it as a �le on server side. Asimilar sequence happens when reading such �le, where the server reads the �le on its side, sendsit as stream of bytes to the client as method return value(s) and the client rebuilds it as �le on itsside.

The usual procedures for managed �les are:

� If a client intends to store a �le in the ODS server namespace it �rst has to create aninstance of an application element derived from AoFile and can get the ODSFile interfacefrom such instance. It can then invoke the method create(), which will cause the ODSserver to create a �le physically at a location of its choice with a �le name of its choice(stored in the application attribute derived from 'ao_location'), and hand over the interfaceODSWriteTransfer to the client. This interface can be used by the client to subsequentlytransfer streams of bytes to the server which will be written to the �le by the server. Atthe end of the transfer the client will ask the server to close the �le. Alternatively it caninvoke the method takeUnderControl(..), specifying a �le within the server namespace. Thiswill cause the ODS server to physically move the �le from its original location to a locationof its choice with a �le name of its choice (stored in the application attribute derived from'ao_location').

� If a client intends to read a �le, it �rst needs to access the corresponding instance of anapplication element derived from AoFile to get the ODSFile interface. It may then invokethe method read() to get the interface ODSReadTransfer, which can be used by the client tosubsequently transfer streams of bytes from the �le at the server and further process themaccording to the client's business logic.

� If a client intends to append further information to a �le that already exists at the ODSserver, it �rst needs to access the corresponding instance of an application element derivedfrom AoFile to get the ODSFile interface. It may invoke the method append() to get theinterface ODSWriteTransfer, which can be used by the client to subsequently transfer streamsof bytes to the server which will be appended by the server to the end of the �le.

� If a client intends to remove a �le from the ODS server namespace, it �rst needs to access thecorresponding instance of an application element derived from AoFile to get the ODSFileinterface. It may then invoke the method remove(), asking the server to remove the �le;note, that the instance is not deleted.

� If a client intends to replace a �le it may do so using the same ODSFile interface object;it must remove the current �le �rst, and may then create a new one. There is no need


© 2015/08/19 Version 1.33



5.24 ODSFile 439

to delete the instance of the application element derived from AoFile nor to destroy theODSFile object after the remove action followed by receiving a new ODSFile interface forthe creation of the �le. Note however that it is not possible to create a �le before removingthe previous one.

� If a client intends to take a �le out of control of the ODS server, it �rst needs to access thecorresponding instance of an application element derived from AoFile to get the ODSFileinterface. It may then invoke the method removeFromControl(..), specifying a �le locationwithin the server namespace. This will cause the ODS server to physically move the �le fromits current location to the speci�ed location; it will no longer be under control of the ODSserver.

� If a client deletes an instance of an application element derived from AoFile, the server willautomatically physically remove the corresponding �le (if any) from the server namespace.

There is one case where the ODS server decides on its own to delete an instance of an applicationelement derived from AoFile and remove the corresponding �le physically from its namespace. Itrequires that this application element has only application relations derived from 'ao_extcomp_-values' or 'ao_extcomp_�ags' (no FATHER relation and no extended application relations). If inthis case the ODS server detects that an instance of that application element is not referenced anymore by any instance of application elements derived from AoExternalComponent, it will decideto delete that instance and to physically remove the corresponding component �le. In all othercases it is the responsibility of client applications to invoke a remove() method if a �le is no longerneeded or to explicitly delete an instance of an application element derived from AoFile if it isno longer needed (which implicitly deletes the corresponding �le from the server). Before deletingthem, the client application (as always) must make sure that there is no reference to such instanceremaining within the ODS server database.

Concurrent access

Files that are out of control of the ODS server are not subject to any rules when concurrent accesshappens. This may lead to problems in cases where more than one client is accessing the same�le.

The access to �les that are under control of the ODS server will be controlled by the ODS server.Especially when several applications try to access the same �le, the ODS server will take care of�le consistency by refusing access in cases where data corruption might occur. This is achievedby having exactly one instance of an application element derived from AoFile for each physical�le. A client which wants to access a �le must request an ODSFile interface object from thatinstance; the ODS server observes the state of the �le access and only allows a client to invokethose methods from its ODSFile object that do not interfere with the current activities of theother ODSFile objects acting on the same �le. The rules for accessing �les concurrently fromseveral client applications are:

� A �le may be read simultaneously by any arbitrary number of clients.

� A �le may be appended by at most one client at a given point in time.

� As long as a �le is opened for reading (i.e. an ODSReadTransfer object for that �le exists)it may not be removed or appended or taken out of server control by the same or anotherclient.

� As long as a �le is opened for creating/appending (i.e. an ODSWriteTransfer object for that�le exists) it may not further be read, removed, appended, or taken out of server control bythe same or another client.


© 2015/08/19 Version 1.33




� It is recommended to perform subsequent write operations to the same �le within a trans-action. This then results in either successfully appending all parts or restoring the previous�le (unmodi�ed).

� As soon as an instance of an application element derived from AoFile is representing a �le(i.e. its attribute derived from 'ao_location' shows a value) no further �le can be creatednor can a �le be taken under server control for this instance before the current �le hassuccessfully been removed or taken out of server control.

Access control mechanisms

Files that are out of control of the ODS server will also be out of access control by the ODS server.It is up to a client application to grant or deny access to such �les. Note that this refers solelyto the physical �les; the instances referencing these �les may be under access control by the ODSserver.

Files that are under control of the ODS server will also be under access control of the ODS serveras access is performed using the ODSFile interface. Access rights to �les are managed accordingto the ODS security concepts as described in section 2.9; the speci�c aspects of �le access aredescribed in the following paragraphs. Note however that the following rules only apply if theODS server is set up to support the ODS security concepts. In case element security and/orinstance security is set, access rights to a �le are identical to the rights a user has for accessingthe instance of the application element derived from AoFile which represents the �le. Attributesecurity is not considered when checking rights to access a �le. The following access rights arerequired to perform �le access operations:

� To perform read operations on a �le requires that the user has READ rights for the instance.These rights are also required for the invocation of the ODSFile methods that return infor-mation on the �le.

� To append bytes at the end of a �le requires that the user has UPDATE rights for theinstance.

� To create a new �le requires that the user has INSERT rights for the instance.

� To remove a �le requires that the user has DELETE rights for the instance.

� To take a �le under server control requires that the user has INSERT rights for the instance.

� To remove a �le from server control requires that the user has DELETE rights for theinstance.

The following example shows how to create an instances of an application element derived fromAoFile, and how to create a �le. The AoSession is available as the variable aoSess and theApplicationElement derived from AoFile is the variable aeFile.



try {

// Create an instance

InstanceElement ieFile = aeFile.createInstance("NewInstance");

// Make of the instance a AoFile

ODSFile odsFile = ieFile.upcastODSFile();

// Create a new file, opne the write transfer

ODSWriteTransfer writeTransfer = odsFile.create();

// Create buffer to write in the file.

byte[] buffer = new String("New instance content of file at " + new Date()).ge

tBytes();

// Put the buffer in the file.

writeTransfer.putOctectSeq(buffer);


© 2015/08/19 Version 1.33



5.24 ODSFile 441

// Close the writetransfer

writeTransfer.close();

// Cleanup

odsFile.destroy();

ieFile.destroy();

try {




System.err.println("AoExcetion: " + ex.errCode.value() + " reason: " + ex.r

eason);


}


System.err.println("AoExcetion: " + ex.errCode.value() + " reason: " + ex.reas

on);


}

The following example shows how to read managed �le. The ApplicationElement derived fromAoFile is the variable aeFile. The name of the instance from which the �le is read is called"ReadExample", this name is unique.

try {

// Get the instance

InstanceElement ieFile = aeFile.getInstancebyName("ReadExample");

// Make of the instance a AoFile

ODSFile odsFile = ieFile.upcastODSFile();

// Get the size to read.

T_LONGLONG size = odsFile.getSize();

// We do not read to large files in this example.

if ((size.high == 0) && (size.low > 0)) {

int fileSize = size.low;

int noRead = 0;

//Open the read transfer.

ODSReadTransfer readTransfer = odsFile.read();

// Create buffer to read.

byte[] buffer = new byte[2048];

while (noRead < fileSize) {

// Read the buffer in the file.

buffer = readTransfer.getOctectSeq(buffer.length);

noRead += buffer.size;

// Do something with the buffer

}

// Close the read Transfer

readTransfer.close();

} else {

System.out.println("File is to big to read");

}

// Cleanup

odsFile.destroy();

ieFile.destroy();


System.err.println("AoExcetion: " + ex.errCode.value() + " reason: " + ex.reas

on);

}

5.24.1 Java Examples of ODSFile


package api.methods.odsfile;




© 2015/08/19 Version 1.33







/** The examples of the methods of ODSFile are all derived from this class */

public class ODSFileExampleAbstract extends InstanceElementExampleAbstract {

// The session

protected static ODSFile of=null;

/**

* Get an instance of AoFile, the instance is one of the instances

* from the element derived from AoFile.

*

* @return the instance of ODSFile.


*/

protected static ODSFile getODSFile() throws AoException {

InstanceElement ie = getInstanceElement("AoFile");

of = ie.upcastODSFile();

ie.destroy();

return (of);

}

/**

* Get the session.



*/



aoSess = connect();

}

return (aoSess);

}

/**



*/


if (of != null) {

of.destroy();

}


aoSess.close();

aoSess = null;

}

}

}

5.24.2 append of interface ODSFile

Purpose:

Get the ODSWriteTransfer interface for the �le, to allow appending further bytes to the �le.This method returns the ODSWriteTransfer interface for the �le represented by this ODSFileobject. That interface allows to write sequentially to the �le, beginning at the end of thecurrently existing �le.Before returning the interface ODSWriteTransfer, the physical �le will be opened for subse-quent write operations.


© 2015/08/19 Version 1.33



5.24 ODSFile 443

In case the current user has no UPDATE right for the instance (resp. for all of its attributesin case of attribute security) from which this ODSFile object was created, the exceptionAO_ACCESS_DENIED will be thrown.In case the physical �le referenced by this ODSFile object cannot be found, the exceptionAO_BAD_OPERATION will be thrown.In case the physical �le referenced by this ODSFile object is currently opened by an ODSRead-Transfer or an ODSWriteTransfer object, the exception AO_FILE_LOCKED will be thrown.In case the �le cannot be opened for writing the exception AO_SYSTEM_PROBLEM willbe thrown.

Return:

ODSWriteTransfer odsWriteTransfer The ODSWriteTransfer interface to append to the �le.

Parameter:

None.


ODSWriteTrasfer odsWriteTransfer = odsFile.append();

Java Example:





import org.asam.ods.ODSWriteTransfer;

public class Append extends ODSFileExampleAbstract {

/**

* The main program. Example method create of odsfile


*/


try {

// Get the odsfile

ODSFile ie = getODSFile();

if (ie.canWrite() && ie.exists()) {



ODSWriteTransfer wt = ie.append();

System.out.println("Write transfer is ready to start for appending.");

wt.close();


} else {

System.out.println("Unable to append file.");

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0


© 2015/08/19 Version 1.33




Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_FILE_LOCKEDAO_ACCESS_DENIEDAO_BAD_OPERATIONAO_SYSTEM_PROBLEM

Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.TransactionTest.testCreate()

5.24.3 canRead of interface ODSFile

Purpose:

Check whether the �le may be opened for reading.This method checks whether the �le represented by this ODSFile object may be opened bythe ODS server for reading access.The method returns a boolean TRUE in case the �le may be opened for reading, and a booleanFALSE in case it cannot be opened for reading or it is already opened for write access (i.e.an ODSWriteTransfer object for this �le exists).In case the physical �le referenced by this ODSFile object cannot be found, false will bereturned.

Return:

T_BOOLEAN canRead Information about whether the �le can be opened for reading

Parameter:

None.


boolean canRead = odsFile.canRead();

Java Example:




public class CanRead extends ODSFileExampleAbstract {

/**

* The main program. Example can read of odsfile


*/



© 2015/08/19 Version 1.33



5.24 ODSFile 445

try {

// Get the odsfile


if (ie.canRead()) {

System.out.println("The file can be read.");

} else {

System.out.println("Unable to read file.");

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:


Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.AoFileInstancesReadTest.testInstanceRead()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.ReadFileTest.testReadFile()test.highqsoft.odsapi.ods530.RemoveFromControlTest.testInstanceTakeUnderControlWithoutMoving()....

5.24.4 canWrite of interface ODSFile

Purpose:

Check whether the �le may be opened for writing.This method checks whether the �le represented by this ODSFile object may be opened bythe ODS server for writing access.The method returns a boolean TRUE in case the user has appropriate rights and the �le canbe opened for writing, and a boolean FALSE in case it is already opened for write access(i.e. an ODSWriteTransfer object for this �le exists) or for read access (i.e. one or moreODSReadTransfer objects for this �le exist).In case ao_location is de�ned and the current user has no UPDATE right for the instancefrom which this ODSFile object was created, a boolean FALSE will be returned.In case ao_location is unde�ned and the current user has no INSERT right for the instancefrom which this ODSFile object was created, a boolean FALSE will be returned.

Return:

T_BOOLEAN canWrite Information about whether the �le can be opened for writing


© 2015/08/19 Version 1.33




Parameter:

None.


boolean canWrite = odsFile.canWrite();

Java Example:




public class CanWrite extends ODSFileExampleAbstract {

/**

* The main program. Example can write of odsfile


*/


try {

// Get the odsfile


if (ie.canWrite()) {

System.out.println("The file can be written.");

} else {

System.out.println("Unable to written file.");

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:


Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()

5.24.5 create of interface ODSFile

Purpose:

Create a new �le on the host of the ODS server and get the ODSWriteTransfer interface forthat �le, to allow storing bytes to the �le.


© 2015/08/19 Version 1.33



5.24 ODSFile 447

This method returns the ODSWriteTransfer interface for the �le represented by this ODSFileobject. That interface allows to write sequentially to the (initially empty) �le.Before returning the interface ODSWriteTransfer, the physical �le will be created on the hostcomputer with the ODS server and opened for subsequent write operations. The �le namewill be decided by the ODS server and set as value of the attribute derived from the baseattribute 'ao_location' of the instance from which this ODSFile object was created.In case the current user has no INSERT right for the instance from which this ODSFile objectwas created, the exception AO_ACCESS_DENIED will be thrown.If the attribute derived from 'ao_location' of the instance from which this ODSFile object wascreated already has a value, the instance potentially already references a �le which was notyet removed, and the server will check whether that former �le still exists. If so the exceptionAO_BAD_OPERATION will be thrown and no new �le will be created.In case the �le cannot be opened for writing the exception AO_SYSTEM_PROBLEM willbe thrown.

Return:

ODSWriteTransfer odsWriteTransfer The ODSWriteTransfer interface to a new �le.

Parameter:

None.


ODSWriteTrasfer odsWriteTransfer = odsFile.create();

Java Example:





import org.asam.ods.ODSWriteTransfer;

public class Create extends ODSFileExampleAbstract {

/**



*/


try {

// Get the odsfile


if (!ie.exists()) {



ODSWriteTransfer wt = ie.create();

System.out.println("Write transfer is ready to start for creating.");

wt.close();


} else {

System.out.println("Unable to create file.");

}


close();


// Report the error



© 2015/08/19 Version 1.33





}

}

}

Since

ASAM ODS 5.3.0

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_ACCESS_DENIEDAO_BAD_OPERATIONAO_SYSTEM_PROBLEM

Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.LargeFileWriteTest.testInstanceCreateLargeFile()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()test.highqsoft.odsapi.ods530.MeasurementFileTest.testCountFile()test.highqsoft.odsapi.ods530.TransactionTest.testCreate()....

5.24.6 exists of interface ODSFile

Purpose:

Check whether the �le physically exists at the ODS server.This method checks whether the �le represented by this ODSFile object truly exists at theexpected location (e.g. on a speci�c drive/directory) within reach of the ODS server.The method returns a boolean TRUE in case the �le exists, and a boolean FALSE in case itdoes not exist.

Return:

T_BOOLEAN exists Information about whether the �le exists.

Parameter:

None.


boolean exist = odsFile.exist();

Java Example:




© 2015/08/19 Version 1.33



5.24 ODSFile 449


public class Exists extends ODSFileExampleAbstract {

/**

* The main program. Example method exists of odsfile


*/


try {

// Get the odsfile


if (ie.exists()) {

System.out.println("The file exist.");

} else {

System.out.println("The file do not exist.");

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:


Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.DeleteAoFileTest.testInstanceDeleteFileAbort()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.RemoveFromControlTest.testInstanceTakeUnderControlWithoutMoving()test.highqsoft.odsapi.ods530.TransactionTest.testCreate()

5.24.7 getDate of interface ODSFile

Purpose:

Get the date of the �le.This method returns the date of the �le represented by this ODSFile object. The returnedstring follows the rules for ODS date and time speci�cation strings.The date returned shall specify the timestamp of the latest change of the �le. It is theinformation the operating system of the host computer provides where the ODS server isinstalled; if there is no date available from the operating system with exactly this meaning,the ODS server shall return the closest information available.In case the physical �le referenced by this ODSFile object cannot be found, the exceptionAO_SYSTEM_PROBLEM will be thrown.


© 2015/08/19 Version 1.33




In case the physical �le referenced by this ODSFile object is currently opened by an ODSWrite-Transfer object of another session, the exception AO_FILE_LOCKED will be thrown.In case there is no �le de�ned by the attribute derived from 'ao_location', the exceptionAO_BAD_OPERATION will be thrown.

Return:

T_DATE date The date of last change of the �le represented by this ODSFile object.

Parameter:

None.


String fileDate = odsFile.getDate();

Java Example:




public class GetDate extends ODSFileExampleAbstract {

/**

* The main program. Example method getDate of odsfile


*/


try {

// Get the odsfile


String date = ie.getDate();

System.out.println("The file have a date from "+date);


close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_BAD_OPERATIONAO_SYSTEM_PROBLEMAO_FILE_LOCKED


© 2015/08/19 Version 1.33



5.24 ODSFile 451

Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesReadTest.testInstanceRead()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.ReadFileTest.testReadFile()

5.24.8 getSize of interface ODSFile

Purpose:

Get the size of the �le.This method returns the size of the �le represented by this ODSFile object.The returned value shall specify the exact �le size in bytes. It is the information the operatingsystem of the host computer provides where the ODS server is installed.In case the physical �le referenced by this ODSFile object cannot be found, the exceptionAO_SYSTEM_PROBLEM will be thrown.In case there is no �le de�ned by the attribute derived from 'ao_location', the exceptionAO_BAD_OPERATION will be thrown.In case the physical �le referenced by this ODSFile object is currently opened by an ODSWrite-Transfer object of another session, the exception AO_FILE_LOCKED will be thrown.

Return:

T_LONGLONG size The size in bytes of the �le represented by this ODSFile object.

Parameter:

None.


T_LONGLONG fileSize = odsFile.getSize();

Java Example:





public class GetSize extends ODSFileExampleAbstract {

/**

* The main program. Example method getSize of odsfile


*/


try {

// Get the odsfile


T_LONGLONG size = ie.getSize();

if ((size.high==0) && (size.low >= 0)) {

System.out.println("The file have a size of "+size.low);

} else {

System.out.println("The file is very big.");

}


close();


© 2015/08/19 Version 1.33





// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_FILE_LOCKEDAO_BAD_OPERATIONAO_SYSTEM_PROBLEM

Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.AoFileInstancesReadTest.testInstanceRead()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.LargeFileWriteTest.testInstanceCreateLargeFile()test.highqsoft.odsapi.ods530.ReadFileTest.testReadFile()....

5.24.9 read of interface ODSFile

Purpose:

Get the ODSReadTransfer interface for the �le.This method returns the ODSReadTransfer interface for the �le represented by this ODSFileobject. That interface allows to read sequentially from the �le, either starting at the verybeginning or at a user-speci�ed byte location within the �le.Before returning the interface ODSReadTransfer, the physical �le will be opened for reading.In case the physical �le referenced by this ODSFile object is currently opened by an ODSWrite-Transfer object, the exception AO_FILE_LOCKED will be thrown.In case there is no �le de�ned by the attribute derived from 'ao_location', the exceptionAO_BAD_OPERATION will be thrown.In case the attribute derived from 'ao_location' is de�ned but the physical �le referencedby this ODSFile object cannot be found or cannot be opened for reading, the exceptionAO_SYSTEM_PROBLEM will be thrown.

Return:

ODSReadTransfer odsReadTransfer The ODSReadTransfer interface to read from the �le.

Parameter:

None.


© 2015/08/19 Version 1.33



5.24 ODSFile 453


ODSReadTransfer odsRead = odsFile.read();

Java Example:




import org.asam.ods.ODSReadTransfer;

public class Read extends ODSFileExampleAbstract {

/**

* The main program. Example method read of odsfile


*/


try {

// Get the odsfile


if (ie.canRead()) {

ODSReadTransfer rt = ie.read();

System.out.println("Read transfer is ready to start.");

rt.close();

} else {

System.out.println("Unable to read file.");

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_FILE_LOCKEDAO_BAD_OPERATIONAO_SYSTEM_PROBLEM

Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.AoFileInstancesReadTest.testInstanceRead()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.ReadFileTest.testReadFile()test.highqsoft.odsapi.ods530.TransactionTest.testCreate()....


© 2015/08/19 Version 1.33




5.24.10 remove of interface ODSFile

Purpose:

Remove a �le from the host computer.This method physically deletes the �le represented by this ODSFile object from the hostcomputer if the user has appropriate rights. The attribute derived from the base attribute'ao_location' of the instance from which this ODSFile object was created will become unde-�ned and ao_size will be set to 0.In case the current user has no DELETE right for the instance from which this ODSFileobject was created, the exception AO_ACCESS_DENIED will be thrown.In case the �le is currently opened for write access (i.e. an ODSWriteTransfer object for this�le exists) or for read access (i.e. one or more ODSReadTransfer objects for this �le exist) anexception AO_FILE_LOCKED will be thrown.In case the physical �le referenced by this ODSFile object does not exist, the method willreturn without any further �le action; it will set the attribute derived from the base attribute'ao_location' to unde�ned and 'ao_size' to 0; it will not throw an exception to signal thenon-existence of the �le.In case the �le cannot be physically deleted from its location, the exception AO_SYSTEM_-PROBLEM will be thrown.

Return:

void

Parameter:

None.


odsFile.remove();

Java Example:





public class Remove extends ODSFileExampleAbstract {

/**



*/


try {

// Get the odsfile


if (ie.canWrite() && !ie.exists()) {



ie.remove();

System.out.println("The file is removed.");


} else {

System.out.println("Unable to remove file.");

}



© 2015/08/19 Version 1.33



5.24 ODSFile 455

close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_FILE_LOCKEDAO_ACCESS_DENIEDAO_SYSTEM_PROBLEM

5.24.11 removeFromControl of interface ODSFile

Purpose:

Take a �le that is currently under control of the ODS server out of control of the server andmove it to a speci�ed location within reach of the server.This method allows to take �les out of control of the ODS server and place them at a speci�edlocation, without the need to stream their bytes through the ODSReadTransfer interface.The parameter 'targetUrl' speci�es the location to which the currently managed �le shall bemoved. This location must be accessible by the server. The server will move the �le fromthe location where managed �les reside to the location given by 'targetUrl'; the �le will nolonger exist at its previous location. The server will set the value of the attribute derivedfrom 'ao_location' to unde�ned and of the attribute derived from 'ao_size' to 0.The string value of 'targetUrl' must comply to the URL speci�cation given in RFC 2396 withthe restriction that ASAM ODS only supports absolute URLs with the access scheme "�le:";otherwise the exception AO_BAD_PARAMETER will be thrown.In case the �le speci�ed by 'targetUrl' already exists the exception AO_BAD_PARAMETERwill be thrown and no action will be performed by this method.In case the �le speci�ed by 'targetUrl' cannot be physically moved to the intended location,the exception AO_SYSTEM_PROBLEM will be thrown and no action will be performed bythis method.In case the �le referenced by this ODSFile object is currently opened for write access (i.e. anODSWriteTransfer object for this �le exists) or for read access (i.e. one or more ODSRead-Transfer objects for this �le exist) an exception AO_FILE_LOCKED will be thrown and noaction will be performed by this method.In case there is no �le de�ned by the attribute derived from 'ao_location', the exceptionAO_BAD_OPERATION will be thrown.

Note

The INI-�le variable KEEP_ORIGINAL_FILE_LOCATION is used in ODSFile. Ifthe variable is set to 'YES', it has the following e�ect: The �le will be removed from ODSserver control, but the location of the �le in the �lesystem will not be changed.


© 2015/08/19 Version 1.33




Return:

void

Parameter:

T_STRING targetUrl (in) Filename URL of the �le where to move the managed �le.


odsFile.removeFromControl("file://export/exp.bin");

Java Example:


import java.io.File;

import java.net.URI;




public class RemoveFromControl extends ODSFileExampleAbstract {

/**

* The main program. Example method remove from control of odsfile


*/


try {

// Get the odsfile


if (ie.exists()) {



File f = new File("c:\\test\\example.txt");

URI url = f.toURI();

ie.removeFromControl(url.toString());

System.out.println("The file is removed from control.");


} else {

System.out.println("File not exists.");

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:



© 2015/08/19 Version 1.33



5.24 ODSFile 457

AO_SESSION_NOT_ACTIVEAO_BAD_PARAMETERAO_FILE_LOCKEDAO_SYSTEM_PROBLEMAO_BAD_OPERATIONAO_BAD_PARAMETER

Tested by:

test.highqsoft.odsapi.ods530.RemoveFromControlTest.testInstanceTakeUnderControlWithoutMoving()

5.24.12 takeUnderControl of interface ODSFile

Purpose:

Put a �le that is already residing within reach of the ODS server under control of the ODSserver.This method allows to put �les under control of the ODS server (make them a 'managed �le')without the need to stream their bytes through the ODSWriteTransfer interface.The parameter 'sourceUrl' speci�es the location of the �le that shall become a managed �le.This location must reference a �le which is accessible by the server. The server will movethe �le to a location where managed �les reside and give it a name of its own choice; the �lewill no longer exist at its previous location. The server will store �le name and location inthe attribute derived from 'ao_location' and store the size of the �le in the attribute derivedfrom 'ao_size'.The string value of 'sourceUrl' must comply to the URL speci�cation given in RFC 2396 withthe restriction that ASAM ODS only supports absolute URLs with the access scheme "�le:",otherwise the exception AO_BAD_PARAMETER will be thrown.In case there is no �le de�ned by the attribute derived from 'ao_location', the exceptionAO_BAD_OPERATION will be thrown.In case the �le cannot be physically moved from its original location to a server-location wheremanaged �les reside, the exception AO_SYSTEM_PROBLEM will be thrown (e.g. if the�le speci�ed by 'sourceUrl' does not exist, or if it cannot be physically moved, etc.).

Note

The INI-�le variable KEEP_ORIGINAL_FILE_LOCATION is used in ODSFile. Ifthe variable is set to 'YES', it has the following e�ect: The passed �lename (sourceUrl) willbe taken under control of ODS server, the �le is not moved to ODS server location. Whenthe instance of the ODSFile is deleted, the �le from the sourceUrl will be delated also.

Return:

void

Parameter:

T_STRING sourceUrl (in) Filename URL of the �le to take under control as a managed �le.


odsFile.takeUnderControl("file://import/imp.bin");


© 2015/08/19 Version 1.33




Java Example:


import java.io.File;

import java.net.URI;




public class TakeUnderControl extends ODSFileExampleAbstract {

/**

* The main program. Example method take under control of odsfile


*/


try {

// Get the odsfile


if (!ie.exists()) {



File f = new File("c:\\test\\example.txt");

URI url = f.toURI();

ie.takeUnderControl(url.toString());

System.out.println("The file is under control.");


} else {

System.out.println("Unable to take file under control file already exists.");

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.3.0

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_BAD_PARAMETERAO_BAD_OPERATIONAO_SYSTEM_PROBLEM

Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.RemoveFromControlTest.testInstanceTakeUnderControlWithoutMoving()


© 2015/08/19 Version 1.33



5.25 ODSReadTransfer 459

5.25 ODSReadTransfer

Package:

org.asam.ods

Description:

The interface which supports a read transfer (from the ODS server to a client) of the content ofa �le that is under control of the ODS server.

5.25.1 close of interface ODSReadTransfer

Purpose:

Close this ODSReadTransfer interface.This method closes the �le on the host computer's �le system and destroys this ODSRead-Transfer object.

Return:

void

Parameter:

None.


odsReadTransfer.close();

Since

ASAM ODS 5.3.0

Errors:


Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.AoFileInstancesReadTest.testInstanceRead()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.ReadFileTest.testReadFile()test.highqsoft.odsapi.ods530.TransactionTest.testCreate()....

5.25.2 getOctetSeq of interface ODSReadTransfer

Purpose:

Read a sequence of bytes from the �le.


© 2015/08/19 Version 1.33




This method reads the �le by the ODS server referenced by this ODSReadTransfer and returnsa sequence of bytes from that �le.The parameter 'maxOctets' controls the return behavior of the ODS server. If the �le containsmore bytes than are given by 'maxOctets', only 'maxOctets' bytes will be returned by the�rst method invocation. A subsequent method invocation will return the next 'maxOctets'bytes from the �le, etc., until the complete �le contents has been returned. Further methodinvocations return an empty sequence.If 'maxOctets' is given with a value greater than the �le size or equal to the constantREADALL(-1), there is no restriction on the number of bytes, and the complete �le con-tents will be returned with only one method invocation.Note that only a sequential reading, starting at the �rst byte of the �le, is supported by thisinterface. If previous parts of the �le need to be accessed again, the current ODSReadTransferobject must be closed and a new one must be instantiated.In case the parameter 'maxOctets' is negative other then the constant READALL the excep-tion AO_BAD_PARAMETER is thrown.In case there is any problem reading the �le, the exception AO_SYSTEM_PROBLEM isthrown.

Return:

S_BYTE �leBytes The next (at most 'maxOctets') bytes in the �le.

Parameter:

T_LONG maxOctets (in) The maximum number of bytes to be returned by one method call.


byte[] buffer = odsReadTransfer.read(ODSREadTransfer.READALL);

Since

ASAM ODS 5.3.0

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_SYSTEM_PROBLEMAO_BAD_PARAMETER

Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesReadTest.testInstanceRead()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.ReadFileTest.testReadFile()test.highqsoft.odsapi.ods530.TransactionTest.testCreate()

5.25.3 getPosition of interface ODSReadTransfer

Purpose:

Retrieve the current position of the internal read pointer in the �le.


© 2015/08/19 Version 1.33



5.25 ODSReadTransfer 461

This method returns the current byte position of the �le pointer. The start of the �le corre-sponds to a position of 0.

Return:

T_LONGLONG �lePosition The current position of the internal read pointer in the �le.

Parameter:

None.


T_LONGLONG filePosition = odsReadTransfer.getPosition();

Since

ASAM ODS 5.3.0

Errors:


Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesReadTest.testInstanceRead()

5.25.4 skipOctets of interface ODSReadTransfer

Purpose:

Skip a number of bytes while reading the �le.This method moves the internal read pointer in the �le a number of bytes ahead, starting atits current position; it will not return those bytes. The parameter 'numOctets' speci�es thenumber of bytes to skip.The method returns the true number of bytes that were skipped. This may di�er from'numOctets' e.g. if the end of the �le was reached. If the internal read pointer has reachedthe end of the �le any further method invocations will return a value of 0 for 'numSkipped'.This method may be invoked several times and may be arbitrarily combined with getOctet-Seq().Note that only a sequential reading, starting at the �rst byte of the �le, is supported by thisinterface. If previous parts of the �le need to be accessed again, the current ODSReadTransferobject must be closed and a new one must be instantiated.If 'numOctets' is given with a value less than 0, the method will throw the exception AO_-BAD_PARAMETER and will not perform any �le access nor change the internal read pointer.

Return:

T_LONGLONG numberSkipped the real number of bytes skipped in the �le.

Parameter:

T_LONGLONG numOctets (in) The number of bytes to be skipped.


© 2015/08/19 Version 1.33





T_LONGLONG skipped = odsReadTransfer.skipOctets(new T_LONGLONG(0, 100));

Java Example:

T_LONGLONG numSkipped = odsReadTransfer.skipOctets(numOctets);

Since

ASAM ODS 5.3.0

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_BAD_PARAMETER

5.26 ODSWriteTransfer

Package:

org.asam.ods

Description:

The interface which supports a write transfer (from a client to the ODS server) of the content ofa �le that is under control of the ODS server.

5.26.1 close of interface ODSWriteTransfer

Purpose:

Close this ODSWriteTransfer interface.This method closes the �le on the ODS server's �le system; thereby any data to be writtento the �le and still residing in the ODS server cache will be �ushed to the �le.The method �nally destroys this ODSWriteTransfer object and also the correspondingCORBA object. Access to such objects after having invoked this close method will leadto a CORBA exception.In case the �le creation and/or write operations have been performed within a transaction,this method will not yet save the operations' results permanently at the physical �le locationbut keep them in an intermediate storage until the transaction is committed. The �le willbe locked for any access through ODSReadTransfer or ODSWriteTransfer within any othersession until the end of the transaction.Any subsequent read transfers or write transfers within the same transaction are allowed, andwill work on the latest version of the �le. In case the transaction is committed without apreceding close operation the ODSWriteTransfer will be closed automatically by the server.In case the �le creation and/or write operations have been performed outside a transaction,this method will make all changes permanent.

Return:

void


© 2015/08/19 Version 1.33



5.26 ODSWriteTransfer 463

Parameter:

None.


odsWriteTransfer.close();

Since

ASAM ODS 5.3.0

Errors:


Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.LargeFileWriteTest.testInstanceCreateLargeFile()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()test.highqsoft.odsapi.ods530.MeasurementFileTest.testCountFile()....

5.26.2 getPosition of interface ODSWriteTransfer

Purpose:

Retrieve the current position of the internal write pointer in the �le.This method returns the current byte position of the write pointer. The start of the �lecorresponds to a position of 0.

Return:

T_LONGLONG �lePosition The current position of the write pointer in the �le.

Parameter:

None.


T_LONGLONG filePosition = odsWriteTransfer.getPosition();

Since

ASAM ODS 5.3.0

Errors:



© 2015/08/19 Version 1.33




Tested by:

5.26.3 putOctectSeq of interface ODSWriteTransfer

Purpose:

Write a sequence of bytes to the �le.This method writes a sequence of bytes to the �le represented by this ODSWriteTransfer onthe host computer.The parameter 'bu�er' contains the byte sequence that is to be written to the �le. Thecontents of 'bu�er' will be appended at the end of the �le (which may also be the very startof the �le in case the �le was newly created), and subsequent method invocations will addtheir bytes at the then actual end of the �le.Note that only a sequential writing is supported by this interface. If previous parts of the �leneed to be changed, the �le must be removed and a new one must be created.In case the current location of the �le runs out of memory or any other operating systemproblem occurs the ODS server will return the exception AO_SYSTEM_PROBLEM. In thiscase the results of the actual putOctetSeq() invocation will be undone (no byte of 'bu�er' isadded to the �le) and the �le may be closed without containing 'bu�er' at its end.

Return:

void

Parameter:

S_BYTE bu�er (in) The bu�er containing the sequence of bytes that shall be written to the�le.


odsWriteTransfer.putOctetSeq(new byte[] { 1, 2, });

Since

ASAM ODS 5.3.0

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_NO_MEMORYAO_SYSTEM_PROBLEM

Tested by:

test.highqsoft.odsapi.ods530.AoFileInstancesCreateTest.testCheckCanWrite()test.highqsoft.odsapi.ods530.ExcludeReadWriteTest.testMultiReadTest()test.highqsoft.odsapi.ods530.LargeFileWriteTest.testInstanceCreateLargeFile()test.highqsoft.odsapi.ods530.MeasurementFileTest.createMeasurementFile()test.highqsoft.odsapi.ods530.MeasurementFileTest.testCountFile()....


© 2015/08/19 Version 1.33



5.27 Query 465

5.27 Query

Package:

org.asam.ods

Description:

The ASAM ODS interface Query.

Note

This interface is not implemented, becasue the de�nition of the ASAM ODS query languageis not completed yet.

5.27.1 executeQuery of interface Query

Purpose:

Execute query in asynchronous mode.

Note


Return:

void

Parameter:

NameValueSequence params (in) Sequence of parameter names and values. The followingparameter should be passed:Name: "QueryResultType";Type: ResultType.Comment: Speci�es what kind of result is expected by the client, this parameter is requiredif the parameters isn't given at the method prepareQuery or the method createQuery of theinterface QueryEvaluator.Default value: INSTELEM_ITERATOR_AS_RESULTName: "Synchronous";Type: T_BOOLEANComment: In case of "true" guarantees synchronous execution.Default value: "false"


query.executeQuery(params);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_QUERY_PROCESSING_ERRORAO_QUERY_INVALID_RESULTTYPE


© 2015/08/19 Version 1.33




Tested by:

5.27.2 getInstances of interface Query

Purpose:

Get the query result. This method should only be called after the query has been executed.It returns an iterator on the instances that were found by the query.

Note


Return:

InstanceElementIterator result The result of the query as an instance element iterator.

Parameter:

None.


InstanceElementIterator result = query.getInstances();

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_QUERY_PROCESSING_ERRORAO_QUERY_TIMEOUT_EXCEEDEDAO_QUERY_INCOMPLETEAO_QUERY_INVALID_RESULTTYPE

Tested by:

5.27.3 getQueryEvaluator of interface Query

Purpose:

Get the QueryEvaluator object which is responsible for this query.

Note


Return:

QueryEvaluator queryEvl The QueryEvaluator object which is responsible for this query.


© 2015/08/19 Version 1.33



5.27 Query 467

Parameter:

None.


QueryEvaluator queryEvl = query.getQueryEvaluator();

Errors:


Tested by:

5.27.4 getStatus of interface Query

Purpose:

Return query status.Returns INCOMPLETE if the query is still executing.Returns COMPLETE if the query �nished execution or if the query execution stopped becauseof an error or because the timeout was exceeded.

Note


Return:

QueryStatus status The status of the query.

Parameter:

None.


QueryStatus status = query.getStatus();

Errors:


Tested by:


© 2015/08/19 Version 1.33




5.27.5 getTable of interface Query

Purpose:

Get the query result. This method should only be called after the query has been executed.It returns the result as a structure.

Note


Return:

NameValueSeqUnitSequence result The result of the query as a name value sequence unitsequence. Each name value sequence unit tuple is one column of the table. The name valuesequence unit sequence is the table. The result structure can be very huge.

Parameter:

None.


NameValueSeqUnit[] result = query.getTable();

Errors:


Tested by:

5.27.6 getTableRows of interface Query

Purpose:

Get the query result. This method should only be called after the query has been executed.It returns an iterator on the name value unit sequence.

Note


Return:

NameValueUnitSequenceIterator result The result of the query as a name value unit sequenceiterator. Each name value unit tuple is one cell of the table. The name value unit sequenceis one row of the table.


© 2015/08/19 Version 1.33



5.27 Query 469

Parameter:

None.


NameValueUnitSequenceIterator result = query.getTableRows();

Errors:


Tested by:

5.27.7 prepareQuery of interface Query

Purpose:

Do the query pre-processing (optimization, etc.) Call can be omitted by the client. In thiscase the functionality is executed on the call of executeQuery.

Note


Return:

void

Parameter:

NameValueSequence params (in) Sequence of parameter names and values. The followingparameters should be passed:Name: "QueryResultType";Type: ResultType.Comment: Speci�es what kind of result is expected by the client, this parameter is required ifthe parameters isn't given at the method createQuery of the interface QueryEvaluator.Default value: INSTELEM_ITERATOR_AS_RESULT


query.prepareQuery(params);

Errors:

AO_BAD_PARAMETER


© 2015/08/19 Version 1.33




AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_QUERY_PROCESSING_ERRORAO_QUERY_INVALID_RESULTTYPE

5.28 QueryEvaluator

Package:

org.asam.ods

Description:

The ASAM ODS query evaluator interface allows to perform queries in synchronous mode and tocreate Query objects for asynchronous execution.

Note

This interface is not implemented, becasue the de�nition of the ASAM ODS query languageis not completed yet.

5.28.1 createQuery of interface QueryEvaluator

Purpose:

Create a query object to execute it in asynchronous mode.

Note


Return:

Query queryObj The query object.

Parameter:

T_STRING queryStr (in) The query string

NameValueSequence params (in) Sequence of parameter names and values. The followingparameters should be passed:Name: "QueryResultType";Type: ResultType.Comment: Speci�es what kind of result is expected by the client.Default value: INSTELEM_ITERATOR_AS_RESULTName: "MaxDuration";Type: T_LONGComment: Can be used to restrict the processing time. The time is given in milliseconds,Default value: 0 (no restriction)


© 2015/08/19 Version 1.33



5.28 QueryEvaluator 471


Query queryObj = queryEvaluator.createQuery(queryStr,params);

Errors:

AO_QUERY_TYPE_INVALIDAO_QUERY_INVALIDAO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

5.28.2 getInstances of interface QueryEvaluator

Purpose:

Evaluate a query in synchronous mode.

Note


Return:

InstanceElementIterator result The result of the query as an instance element iterator.

Parameter:

T_STRING queryStr (in) The query string.

NameValueSequence params (in) Sequence of parameter names and values. The followingparameters should be passed:Name: "MaxDuration";Type: T_LONGComment: Can be used to restrict the processing time. The time is given in milliseconds,Default value: 0 (no restriction)


InstanceElementIterator result = queryEvaluator.getInstances(queryStr,params);

Errors:

AO_QUERY_TYPE_INVALIDAO_QUERY_INVALIDAO_QUERY_PROCESSING_ERRORAO_QUERY_TIMEOUT_EXCEEDEDAO_BAD_PARAMETER


© 2015/08/19 Version 1.33





Tested by:

5.28.3 getTable of interface QueryEvaluator

Purpose:


Note


Return:

NameValueSeqUnitSequence result The result of the query as a name value sequence unitsequence. Each name value sequence unit tuple is one column of the table. The name valuesequence unit sequence is the table. The result structure can be very huge.

Parameter:




NameValueSeqUnit[] result = queryEvaluator.getTable(queryStr,params);

Errors:

AO_QUERY_TYPE_INVALIDAO_QUERY_INVALIDAO_QUERY_PROCESSING_ERRORAO_QUERY_TIMEOUT_EXCEEDEDAO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:


© 2015/08/19 Version 1.33



5.29 SMatLink 473

5.28.4 getTableRows of interface QueryEvaluator

Purpose:


Note


Return:

NameValueUnitSequenceIterator result The result of the query as a name value unit sequenceiterator. Each name value unit tuple is one cell of the table. The name value unit sequenceis one row of the table.

Parameter:




NameValueUnitSequenceIterator result = queryEvaluator.getTableRows(queryStr,params);

Errors:

AO_QUERY_TYPE_INVALIDAO_QUERY_INVALIDAO_QUERY_PROCESSING_ERRORAO_QUERY_TIMEOUT_EXCEEDEDAO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

5.29 SMatLink

Package:

org.asam.ods

Description:

The ASAM ODS submatrix link interface.


© 2015/08/19 Version 1.33




Note

This interface is not implemented, becasue the de�nition submatrix links are not completedyet.

5.29.1 getLinkType of interface SMatLink

Purpose:

Get the link or build type.

Note


Return:

BuildUpFunction linkType The link type.

Parameter:

None.


BuildUpFunction linkType = sMatLink.getLinkType();

Errors:


Tested by:

5.29.2 getOrdinalNumber of interface SMatLink

Purpose:

Get the ordinal or sequence number

Note


Return:

T_LONG ordinalNumber The sequence number.

Parameter:

None.


© 2015/08/19 Version 1.33



5.29 SMatLink 475


int ordinalNumber = sMatLink.getOrdinalNumber();

Errors:


Tested by:

5.29.3 getSMat1 of interface SMatLink

Purpose:

Get the �rst submatrix of the link.

Note


Return:

SubMatrix subMatrix The �rst submatrix of the link.

Parameter:

None.


SubMatrix subMatrix = sMatLink.getSMat1();

Errors:


Tested by:

5.29.4 getSMat1Columns of interface SMatLink

Purpose:

Get the bind columns of the �rst submatrix used in the link (e.g. Time).


© 2015/08/19 Version 1.33




Note


Return:

ColumnSequence columns The columns of the �rst submatrix.

Parameter:

None.


Column[] columns = sMatLink.getSMat1Columns();

Errors:


Tested by:

5.29.5 getSMat2 of interface SMatLink

Purpose:

Get the second submatrix of the link.

Note


Return:

SubMatrix subMatrix The second submatrix of the link.

Parameter:

None.


SubMatrix subMatrix = sMatLink.getSMat2();

Errors:


Tested by:


© 2015/08/19 Version 1.33



5.29 SMatLink 477

5.29.6 getSMat2Columns of interface SMatLink

Purpose:

Get the bind columns of the second submatrix used in the link (e.g. Time).

Note


Return:

ColumnSequence columns The columns of the second submatrix.

Parameter:

None.


Column[] columns = sMatLink.getSMat2Columns();

Errors:


Tested by:

5.29.7 setLinkType of interface SMatLink

Purpose:

Set the build or link type.

Note


Return:

void

Parameter:

BuildUpFunction linkType (in) The requested build-up function.


sMatLink.setLinkType(linkType);


© 2015/08/19 Version 1.33




Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_BUILDUP_FUNCTIONAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

5.29.8 setOrdinalNumber of interface SMatLink

Purpose:

Set the ordinal or sequence number.

Note


Return:

void

Parameter:

T_LONG ordinalNumber (in) The sequence number.


sMatLink.setOrdinalNumber(ordinalNumber);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_ORDINALNUMBERAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

5.29.9 setSMat1 of interface SMatLink

Purpose:

Set the �rst submatrix of the link.


© 2015/08/19 Version 1.33



5.29 SMatLink 479

Note


Return:

void

Parameter:

SubMatrix subMat1 (in) The �rst sub matrix of the sub matrix link.


sMatLink.setSMat1(subMatrix);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_SUBMATRIXAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

5.29.10 setSMat1Columns of interface SMatLink

Purpose:

Set the bind columns of the �rst submatrix used in the link (e.g. Time).

Note


Return:

void

Parameter:

ColumnSequence columns (in) The column sequence of the sub matrix.


sMatLink.setSMat1Columns(columns);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_COLUMNAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE


© 2015/08/19 Version 1.33




Tested by:

5.29.11 setSMat2 of interface SMatLink

Purpose:

Set the second submatrix of the link.

Note


Return:

void

Parameter:

SubMatrix subMat2 (in) The second sub matrix of the sub matrix link.


sMatLink.setSMat2(subMatrix);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_INVALID_SUBMATRIXAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

5.29.12 setSMat2Columns of interface SMatLink

Purpose:

Set the bind columns of the second submatrix used in the link (e.g. Time). If there is morethan one column bound the column sequence must be identical with the column sequence ofthe �rst submatrix.

Note


Return:

void


© 2015/08/19 Version 1.33



5.30 SubMatrix 481

Parameter:

ColumnSequence columns (in) The column sequence of the sub matrix.


sMatLink.setSMat2Columns(columns);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_INVALID_COLUMNAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

5.30 SubMatrix

Package:

org.asam.ods

Description:

The ASAM ODS submatrix interface. The instances of the submatrix can be accessed via themethod getRelatedInstances of the interface Measurement. The interface SubMatrix extends theinterface InstanceElement. Thus all methods of the interface InstanceElement do also work here.

Derived:

InstanceElement

5.30.1 Java Examples of SubMatrix


package api.methods.submatrix;






/** The examples of the methods of SubMatrix are all derived from this class */

public class SubMatrixExampleAbstract extends InstanceElementExampleAbstract {

// The session


protected static SubMatrix sm=null;

/**

* Get an instance of AoSubMatrix, the instance is one of the instances

* from the element derived from AoSubMatrix.


© 2015/08/19 Version 1.33




*

* @return the instance of SubMatrix.


*/

protected static SubMatrix getSubMatrix() throws AoException {


sm = ie.upcastSubMatrix();

ie.destroy();

return (sm);

}

/**

* Get the session.



*/



aoSess = connect();

}

return (aoSess);

}

/**



*/


if (sm != null) {

sm.destroy();

}


aoSess.close();

aoSess = null;

}

}

}

5.30.2 getColumns of interface SubMatrix

Purpose:

Get the columns of the submatrix. The column is not inherited from the InstanceElementinterface. This is the only way to get a column. The columns are used in the SMatLinkinterface to build the value matrix. The pattern is case sensitive and may contain wildcardcharacters.

Return:

ColumnSequence columns The columns of the submatrix.

Parameter:

Pattern colPattern (in) The name or the search pattern for the column names.


Column[] columns = subMatrix.getColumns(colPattern);


© 2015/08/19 Version 1.33



5.30 SubMatrix 483

Java Example:



import org.asam.ods.Column;


public class GetColumns extends SubMatrixExampleAbstract {

/**

* The main program. Example get columns from the submatrix.

*


*/


try {

// Get the submatrix

SubMatrix ie = getSubMatrix();

Column[] cols = ie.getColumns("*");

System.out.println("The submatrix has " + cols.length + " columns");

// Destroy the columns.

for (Column col: cols) {

col.destroy();

}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixCreateTestIT.testCreateValueMatrixFromMeaSm()test.highqsoft.avalon.ValueMatrixUnitTestIT.testCheckUnit()test.highqsoft.odsapi.DeleteInstanceElementTest.testApplElemAccessDeleteInstances()

5.30.3 getValueMatrix of interface SubMatrix

Purpose:

Get a value matrix of the submatrix.By calling this method, the value matrix mode of the returned value matrix will be taken fromthe context variable 'VALUEMATRIX_MODE'. For more information especially on di�erentmodes of the value matrix, see description at the method getValueMatrixInMode() of thisinterface.


© 2015/08/19 Version 1.33




Return:

ValueMatrix valueMatrix The value matrix.

Parameter:

None.


ValueMatrix valueMatrix = subMatrix.getValueMatrix();

Java Example:





public class GetValueMatrix extends SubMatrixExampleAbstract {

/**

* The main program. Example get valuematrix from the submatrix.


*/


try {



ValueMatrix vm = ie.getValueMatrix();

vm.destroy();



close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_SMATLINKAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.ValueMatrixGetTestIT.testValueMatrixGetMeaPoint()test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()test.highqsoft.odsapi.ford.FordMesaurementTest.testCreateMeasurementDoubleLc()test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()test.highqsoft.odsapi.performance.MeasurementPerfIT.testCreateMeasurement()....


© 2015/08/19 Version 1.33



5.30 SubMatrix 485

5.30.4 getValueMatrixInMode of interface SubMatrix

Purpose:

Get the value matrix of the submatrix in the requested mode.The server doesn't check any independent columns. The local columns of the value matrixare exactly the local columns of this submatrix. The �ags in the TS_ValueSeq are the �agsof the local columns. If no �ags are given there are no �ags available in the physical storage,and the client has to consider the global_�ag.If the requested mode is 'CALCULATED' the server returns the calculated values for implicitand raw values. Implicit local columns will be expanded to a sequence of explicit values byusing the generation parameters. Local columns storing raw values will be re-calculated usingthe raw values together with the generation parameters .In the STORAGE mode the server handles the values of the localcolumn as they are in thephysical storage. Writing values to a value matrix is only allowed if the value matrix is in theSTORAGE mode. The values are exactly from this submatrix. The raw / implicit values arereturned.

Return:


Parameter:




Java Example:






public class GetValueMatrixInMode extends SubMatrixExampleAbstract {

/**

* The main program. Example get valuematrix in the calculated mode

* from the submatrix.

*


*/


try {



ValueMatrix vm = ie.getValueMatrixInMode(ValueMatrixMode.CALCULATED);

vm.destroy();



close();


// Report the error



}

}

}


© 2015/08/19 Version 1.33




Since

ASAM ODS 5.2

Errors:


Tested by:

test.highqsoft.avalon.MeasurementTestCase.LoadValuesSubMatrixVM()test.highqsoft.avalon.MeasurementTestIT.testManyMeasurement()test.highqsoft.avalon.ValueMatrixCompareTestIT.testCompareValueMatrix()test.highqsoft.avalon.ValueMatrixCreateTestIT.testCreateValueMatrixFromMeaSm()test.highqsoft.avalon.ValueMatrixCreateTestIT.testCreateValueMatrixFromSmSelectMea()....

5.30.5 listColumns of interface SubMatrix

Purpose:

Get the names of the columns of the submatrix. The name sequence is identical with the namesof the related instances. The pattern is case sensitive and may contain wildcard characters.

Return:

NameSequence columnNames The column names of the submatrix.

Parameter:



Name[] columnNames = subMatrix.listColumns(colPattern);

Java Example:




public class ListColumns extends SubMatrixExampleAbstract {

/**

* The main program. Example get names of the columns from the submatrix.

*


*/


try {




© 2015/08/19 Version 1.33



5.31 ValueMatrix 487

String[] colNames = ie.listColumns("*");

System.out.println("The submatrix has " + colNames.length + " columns");

for (String colName : colNames) {

System.out.println("Column with name " + colName);

}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixCreateTestIT.testCreateValueMatrixFromMeaSm()test.highqsoft.avalon.ValueMatrixCreateTestIT.testCreateValueMatrixFromSmSelectMea()test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()

5.31 ValueMatrix

Package:

org.asam.ods

Description:

The ASAM ODS value matrix interface. Value matrix is an interface used by Measurement andSubMatrix to handle vectors of values.

It is only possible to set the values at a ValueMatrix, if the ValueMatrix is created from a submatrixinstance element. If the valuematrix is created from a measurement instance element it is notallowed to set the values.

The following example shows how a valuematrix is create from a measurement with two subma-trixes.

SubMatrix 1

Time QuantityA0.1 xxx10.2 xxx20.3 xxx30.4 xxx4

SubMatrix 2


© 2015/08/19 Version 1.33




Time QuantityB0.22 yyy10.24 yyy20.26 yyy30.28 yyy40.30 yyy50.32 yyy6

Both submatrixes have the same independent column Time.

ValueMatrix

Time QuantityA QuantityB0.1 xxx10.2 xxx20.22 yyy10.24 yyy20.26 yyy30.28 yyy40.30 xxx3 yyy50.32 yyy60.4 xxx4

The server checks the independent column, if there is more than one submatrix at the measurementthere must be exactly one independent column with the same measurement quantity in eachsubmatrix,otherwise th exception AO_INVALID_VALUEMATRIX_STRUCTURE is thrown.

The server throws the exception AO_INVALID_VALUEMATRIX_STRUCTURE when it is unable to createthe valuematrix due to the data of the measurement

� if there are no independent column

� if there are di�erent independent columns

� if there are submatrices with more than one independent column.

The server orders the values according to the values of the independent localcolumn. (in ascendingorder) It is up to the server what value is returned when a measurement quantity has two di�erentvalues at the same independent point. The gaps are marked with Flags in TS_ValueSeq (�agvalue= 0).

The access to valuematrix is quite di�erent during reading, writing, changing and deleting:

Reading:

� Data is requested from a concrete measurement; the submatrix from which this data istaken will not be named.

� Several measurement quantities may be read at once (if needed).

� The required local columns will be selected by a selection criterion.

Writing (adding of new quantities or new local columns to the measurement):

� Several local columns will be written in parallel.

� The local columns can be stored as new or added to existing submatrices.

� Appending/adding one or more 'measured points' (rows) at a given position in a subma-trix.

� The submatrix to which the data should be stored, has to be known.


© 2015/08/19 Version 1.33




Changing (of existing quantities and existing local columns):

� The values themselves and also the �ags of the values, such as visualization and validity,can be changed.

� It will be changed point-wise (one or more 'measured points' (rows) out of a submatrix).

� Typically, one local column (resp. measurement quantity) will be changed at a time.

� Only the measurement will be named; the submatrix is internally known.

� A selection criterion can be given.

� Changed data can be stored as a new version of the quantity; old data may be kept.

Deleting:

� A complete submatrix may be deleted.

� One or more 'measured points' (rows) may be deleted from a submatrix.

There are three methods to set or get the values of a ValueMatrix.

Note


1. setValue or getValue, the following picture illustrate the area of the valuematrix which can be�lled.

XXXX

XXXX

CBANTVt

Figure 5.3: get/setValue

2. setValueVector or getValueVector, the following picture illustrate the area of the valuematrixwhich can be �lled.


© 2015/08/19 Version 1.33




X

X

X

X

X

CBANTVt

Figure 5.4: get/setValueVector

3. setMeaPoint or getMeaPoint, the following picture illustrate the area of the valuematrix whichcan be �lled.

XXXXXXX

CBANTVt

Figure 5.5: get/setMeaPoint

Note

Names of the instances of AoMeasurementQuantity. The methods listColumns and get-Columns of the interface ValuesMatrix have a parameter Pattern. With names of the instancesof AoMeasurementQuantiy (Eg "sin(x\500).(2-sin(x\10000))") the client have to escape thenames otherwise the server will not be able to �nd the correct column.

An example how to use the ValueMatrix interface is given below.

/* @(#) $Id: UsingValueMatrix.java,v 1.13 2017/04/28 14:29:28 karst Exp $

****************************************************************************


****************************************************************************

* HighQSoft GmbH *



****************************************************************************


© 2015/08/19 Version 1.33




* *


* HighQSoft GmbH. *

* *





* *

****************************************************************************

*/















import org.asam.ods.SetType;





public class UsingValueMatrix extends ExamplesHelper {

static String columnPattern = "*";

private static void usingValueMatrixPoints(ValueMatrix vm) throws AoException

{

System.out.println("usingValueMatrixPoints");

int noValues = vm.getRowCount();

int block=65536;

Column[] cols = vm.getColumns(columnPattern);

TS_ValueSeq val;

int maxCols = 100;

if (columnPattern.compareTo("*") == 0) {

maxCols = 5;

}

/* Show all values of the first 5 columns */

for (int valIndex = 0; valIndex < noValues; valIndex+=block)

{

for (int colIndex = 0; (colIndex < cols.length) && (colIndex < maxCols);

colIndex++) {

val = vm.getValueVector(cols[colIndex], valIndex, block);

System.out.println("Values of column " + cols[colIndex].getName());

System.out.println(ts_valueSeqToString(val));

}

}

try {

// Get the iterator to the values of the first row.

NameValueUnitIterator nvuIter = vm.getValueMeaPoint(0);

if (nvuIter != null) {

int nValues = nvuIter.getCount();

System.out.println("Number of values in row = " + nValues);

// Any values in the row ?

if (nValues > 0) {


© 2015/08/19 Version 1.33




// Load a row in one step.

NameValueUnit[] row = nvuIter.nextN(nValues);

// Print all values in the row.

for (int i=0; i<nValues && i < 100; i++) {

System.out.println(" " + nameValueUnitToString(row[i]));

}

} else {

System.err.println("No measurement values found!");

}

// Destroy name-value-unit iterator.

nvuIter.destroy();

} else {

System.err.println("No value iterator available!");

}


System.err.println("\nUsingValueMatrix, " + aoException.toString() + ":"

+

"minorCode " + aoException.minorCode +


}

// Read all values at once of the first column.

val = vm.getValueVector(cols[0], 0, 0);

System.out.println("Values of column " + cols[0].getName());

System.out.println(ts_valueSeqToString(val));

}

private static void showValueMatrixPoints(ValueMatrix vm, int point, int count

) throws AoException

{

try {

System.out.println("showValueMatrixPoints");

// Get the iterator to the values of the .


NameValueSeqUnit[] nvu = vm.getValue(cols, point, count);


for (int i=0; i<nvu.length && i < 100; i++) {

System.out.println(" " + nameValueSeqUnitToString(nvu[i]));

}



+



}

}

public static Column[] removeIndepCols(Column[] cols, String[] indepCols) thro

ws AoException {

int resultLength = cols.length-indepCols.length; // Length of result arra

y

Column[] notIndep = new Column[resultLength]; // Result array

int wIndex=0; // WriteIndex in result

array

boolean found;

for (int colIndex = 0; colIndex < cols.length; colIndex++) {

String colName = cols[colIndex].getName();

found = false;

for (int i = 0; i < indepCols.length; i++) {

if (colName.compareTo(indepCols[i]) == 0) {

found = true;


© 2015/08/19 Version 1.33




System.out.println("Found independent column: " + colName);

}

}

if ((!found) && (wIndex < resultLength)) {

notIndep[wIndex++] = cols[colIndex];

}

}

return(notIndep);

}

public static void modifyValueMatrixPoints(AoSession aos, ValueMatrix vm, int

point) {

try {

System.out.println("modifyValueMatrixPoints");



String[] indepCols = vm.listIndependentColumns("*");

Column[] modCols = removeIndepCols(cols, indepCols);

NameValueSeqUnit[] nvu = vm.getValue(modCols, point, 10);




}

// Modify the value

for (int i=0; i<nvu.length; i++) {

DataType dt = nvu[i].value.u.discriminator();

switch (dt.value()) {

case DataType._DT_DOUBLE:

{

double[] f;

f = nvu[i].value.u.doubleVal();

for (int k = 0; k < f.length; k++) {

f[k] = f[k] + 0.5;

}

break;

}

case DataType._DT_FLOAT:

{

float[] f;

f = nvu[i].value.u.floatVal();


f[k] = f[k] + (float)0.5;

}

break;

}


{

int[] f;

f = nvu[i].value.u.longVal();


f[k] = f[k] + 5;

}

break;

}

case DataType._DT_STRING:

{

String[] f;

f = nvu[i].value.u.stringVal();


f[k] = "String_"+k;

}

break;

}

case DataType._DT_DATE:

{

String[] f;

f = nvu[i].value.u.dateVal();



© 2015/08/19 Version 1.33




f[k] = getOdsDate(null);

}

break;

}

default:

System.out.println("Not implemented datatype: " + dt.value());

break;

}

}

System.out.println("modifyValueMatrixPoints new values");



}

aos.startTransaction();

try {

vm.setValue(SetType.UPDATE, point, nvu);

aos.commitTransaction();


aos.abortTransaction();

System.err.println("\nUsingValueMatrix, " + aoException.toString() +

":" +



}



+



}

}

public static void insertValueMatrixPoints(AoSession aos, ValueMatrix vm, int

point) {

try {

System.out.println("insertValueMatrixPoints");



String[] indepCols = vm.listIndependentColumns("*");

Column[] insCols = removeIndepCols(cols, indepCols);

NameValueSeqUnit[] nvu = vm.getValue(insCols, point, 3);




}

// Modify the value

for (int i=0; i<nvu.length; i++) {

DataType dt = nvu[i].value.u.discriminator();

switch (dt.value()) {

case DataType._DT_DOUBLE:

{

double[] f;

f = nvu[i].value.u.doubleVal();


f[k] = f[k] + 0.5;

}

break;

}

case DataType._DT_FLOAT:

{

float[] f;

f = nvu[i].value.u.floatVal();


f[k] = f[k] + (float)0.5;

}

break;

}


© 2015/08/19 Version 1.33





{

int[] f;

f = nvu[i].value.u.longVal();


f[k] = f[k] + 5;

}

break;

}

case DataType._DT_STRING:

{

String[] f;

f = nvu[i].value.u.stringVal();


f[k] = "String_"+k;

}

break;

}

case DataType._DT_DATE:

{

String[] f;

f = nvu[i].value.u.dateVal();


f[k] = getOdsDate(null);

}

break;

}

default:

System.out.println("Not implemented datatype: " + dt.value());

break;

}

}

System.out.println("insertValueMatrixPoints new values");



}

aos.startTransaction();

try {

vm.setValue(SetType.INSERT, point, nvu);

aos.commitTransaction();


aos.abortTransaction();


":" +



}



+



}

}




System.out.println("\nExample UsingValueMatrix...");

System.out.println("--------------------------------");



try {


© 2015/08/19 Version 1.33




// Establish a session to the service (without session options).


try {



// Get all application elements of type Measurement.

ApplicationElement[] aeMea = as.getElementsByBaseType("AoMeasurement"

);

// At least one measurement object found ?

if (aeMea != null && aeMea.length > 0) {

String ieIdStr = ExamplesConnect.getArgumentValue("InstanceId", "1

");

columnPattern = ExamplesConnect.getArgumentValue("ColumnNamePatter

n", "*");

Integer ieIdLow = new Integer(ieIdStr);

T_LONGLONG ieId;

ieId = new T_LONGLONG();

ieId.high = 0;

ieId.low = ieIdLow.intValue();

// Get the instances of the first measurement type.

InstanceElement ieObj = aeMea[0].getInstanceById(ieId);

Measurement mea = ieObj.upcastMeasurement();

if (mea != null) {

// Show the measurement instance name.

System.out.println("Name of " + aeMea[0].getName() + " instance

= " + mea.getName());

try {

// Get the value matrix of the measurement.

ValueMatrix vm = mea.getValueMatrix();

// Measurement values available ?

if (vm != null) {

usingValueMatrixPoints(vm);

showValueMatrixPoints(vm, 2, 5);

} else {

System.err.println("No measurement value matrix found!");

}


System.err.println("\nUsingValueMatrix, " + aoException.toSt

ring() + ":" +



}

InstanceElement ieSm = null;

InstanceElementIterator ieSmIter = ieObj.getRelatedInstancesByR

elationship(Relationship.CHILD, "*");

do {

ieSm = ieSmIter.nextOne();

if (ieSm != null) {

// The instance can be an AoSubMAtrix or an AoMeasurement

Quantiy

ApplicationElement aeSm = ieSm.getApplicationElement();

BaseElement beSm = aeSm.getBaseElement();

if (beSm.getType().compareToIgnoreCase("AoSubMatrix") ==


© 2015/08/19 Version 1.33




0) {

SubMatrix sm = ieSm.upcastSubMatrix();

ValueMatrix vm = sm.getValueMatrix();


modifyValueMatrixPoints(aoSession, vm, 15);


insertValueMatrixPoints(aoSession, vm, 3);


}

ieSm.destroy();

}

} while (ieSm != null);

ieSmIter.destroy();

} else {

System.err.println("No measurements found!");

}

} else {

System.err.println("No measurement types found!");

}



":" +

" minorCode " + aoException.minorCode +


}


aoSession.close();



+


}



)-mSeconds));


System.exit(0);

}

}

5.31.1 The mode of the ValueMatrix.

The ValueMatrix can be used in two di�erent modes, CALCULLATED and STORAGE.

The �rst mode CALCULATED (default in Athos) will return and expected the values of the Value-Matrix in CALCULATED mode, which means the values are recalculated according the sequencerepresenation stored at the instance of the localcolumn. When in this case the sequence repre-senation or generation parameters are requested from teh Column the sequence represenation isalways EXPLICIT and the generation parameters are not given. The client can use the values asthey come.

The second mode is STORAGE the values are returned as they are stored in the storage. Theclient have to take care for the sequence representation and the generation paramerers. Theseare also returned at the Column. The client have to do the recalculation of values to the realvalues according the sequence represention. This mode can reduce the data transfer between the


© 2015/08/19 Version 1.33




client and the server but make the client mor complex. Writing the values to the ValueMatrixthe STORAGE mode allows write operation also in ValueMatrix generation from an Instance ofAoMeasurement with more then on SubMatrix (Not implemented at the moment).

5.31.2 Java Examples of ValueMatrix


package api.methods.valuematrix;







/** The examples of the methods of ValueMatrix are all derived from this class */

public class ValueMatrixExampleAbstract extends InstanceElementExampleAbstract {

// The session


protected static ValueMatrix vm=null;

/**

* Get an instance of AoSubMatrix, the instance is one of the instances

* from the element derived from AoSubMatrix.

*

* @return the valueMatrix.


*/

protected static ValueMatrix getValueMatrix() throws AoException {


SubMatrix sm = ie.upcastSubMatrix();

vm = sm.getValueMatrix();

sm.destroy();

ie.destroy();

return (vm);

}

/**

* Get the session.



*/



aoSess = connect();

}

return (aoSess);

}

/**



*/


if (vm != null) {

vm.destroy();

}


aoSess.close();

aoSess = null;

}


© 2015/08/19 Version 1.33




}

}

5.31.3 addColumn of interface ValueMatrix

Purpose:

Add a column to the value matrix. It is only allowed to create a value vector if the valuematrix is created from a submatrix.It is allowed to add a column outside a transaction but it is recommended to activate atransaction.The data is made permanent on transaction commit. Until the transaction is committed oruntil the access to the measurement point of the value matrix it is allowed to have di�erentnumber of values in the di�erent value vectors. After the new column is added, it is possibleto set the values of the column.

Note

See also Transaction handling in ODS API. (p. 15). The name of the column is the nameof the instance of the measurement quantity. Due to the fact ASAM ODS requires the nameof the local column must be identical with the name of the measurement quantity there willbe normally no di�erence.

Return:

Column column The new column.

Parameter:

NameUnit newColumn (in) The name and unit of the column to add.


valueMatrix.addColumn(newColumn);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_NAMEAO_INVALID_SET_TYPEAO_IS_MEASUREMENT_MATRIXAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_TRANSACTION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.performance.MeasurementPerfIT.testCreateMeasurement()test.highqsoft.odsapi.SpecialNamedFileTest.testCreateMeaSpecNamedFile()


© 2015/08/19 Version 1.33




5.31.4 addColumnScaledBy of interface ValueMatrix

Purpose:

Deprecated, solved by NVH Application model.Add a column to the value matrix. It is only allowed to create a value vector if the valuematrix is created from a submatrix. The column will be scaled by the given scaling column.It is allowed to add a column outside a transaction but it is recommended to activate atransaction.The data is made permanent on transaction commit. Until the transaction is committed oruntil the access to the measurement point of the value matrix it is allowed to have di�erentnumber of values in the di�erent value vectors. After the new column is added, it is possibleto set the values of the column.

Note

Not yet implemented, the method is depricated.

Return:

Column column The new column.

Parameter:

NameUnit newColumn (in) The name and unit of the column to add.

Column scalingColumn (in) The scaling column.


Column column = valueMatrix.addColumnScaledBy(newColumn,scalingColumn);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_NAMEAO_INVALID_SET_TYPEAO_IS_MEASUREMENT_MATRIXAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_NO_SCALING_COLUMNAO_TRANSACTION_NOT_ACTIVE

Tested by:

5.31.5 destroy of interface ValueMatrix

Purpose:

Destroy the object on the server. The method is used to tell the server that this object is notused any more by the client. Access to this object after the invokation of the destroy methodwill lead to an exception.


© 2015/08/19 Version 1.33




Note


Return:

void

Parameter:

None.


vmObj.destroy()

Java Example:




public class Destroy extends ValueMatrixExampleAbstract {

/**

* The main program. Example show the destroy method of the valuematrix interface.

* The destroy method must be called when the client do not need the instance


*

* @param args

* not used.

*/


try {

ValueMatrix vm = getValueMatrix();


vm.destroy();

System.out.println("The valuematrix is destroyed.");




// Report the error



}

}

}

Since

ASAM ODS 5.0

Errors:



© 2015/08/19 Version 1.33




Tested by:


5.31.6 getColumnCount of interface ValueMatrix

Purpose:

Get the column count of the value matrix.

Return:

T_LONG columnCount The number of columns of the value matrix.

Parameter:

None.


int columnCount = valueMatrix.getColumnCount();

Java Example:




public class GetColumnCount extends ValueMatrixExampleAbstract {

/**

* The main program. Example get number of columns from the valueMatrix.

*


*/


try {

// Get the valueMatrix


int colCount = vm.getColumnCount();

System.out.println("The valueMatrix has " + colCount + " columns");


close();


// Report the error



}

}

}

Errors:

AO_CONNECTION_LOST


© 2015/08/19 Version 1.33





Tested by:

test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()test.highqsoft.odsapi.performance.ValueMatrixPerfIT.testReadManyVmCount()test.highqsoft.odsapi.CreateInstanceTestCase.checkMeasurementInstances()test.highqsoft.odsapi.CreateMeasurementTest.testAddColumn()

5.31.7 getColumns of interface ValueMatrix

Purpose:

Get the columns of the value matrix no matter whether the column is dependent or indepen-dent. The pattern is case sensitive and may contain wildcard characters.

Note

The name of the column is the name of the instance of the measurement quantity and thepattern must match this names.. Due to the fact ASAM ODS requires the name of the localcolumn must be identical with the name of the measurement quantity there will be normallyno di�erence.

Return:

ColumnSequence columns The columns of the value matrix, no matter whether the column isdependent, independent or scaling

Parameter:



Column[] columns = valueMatrix.getColumns(colPattern);

Java Example:





public class GetColumns extends ValueMatrixExampleAbstract {

/**

* The main program. Example get columns from the valueMatrix.

*


*/


try {


© 2015/08/19 Version 1.33




// Get the valuematrix


Column[] cols = vm.getColumns("*");

System.out.println("The ValueMatrix has " + cols.length + " columns");



col.destroy();

}


close();


// Report the error



}

}

}

Errors:


Tested by:


5.31.8 getColumnsScaledBy of interface ValueMatrix

Purpose:

Deprecated, solved by NVH Application model.Get the columns which are scaled by the given column.

Note


Return:

ColumnSequence columns The columns which are scaled by the given input column.

Parameter:



Column[] columns = valueMatrix.getColumnsScaledBy(scalingColumn);


© 2015/08/19 Version 1.33




Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_NO_SCALING_COLUMN

Tested by:

5.31.9 getIndependentColumns of interface ValueMatrix

Purpose:

Get the independent columns of the submatrices used to compose the value matrix. Theindependent column of the value matrix is the union of the independent columns of thesesubmatrices.

Note

The name of the column is the name of the instance of the measurement quantity and thepattern must match this names.. Due to the fact ASAM ODS requires the name of the localcolumn must be identical with the name of the measurement quantity there will be normallyno di�erence.

Return:

ColumnSequence columns The independent column of the value matrix.

Parameter:

Pattern colPattern (in) The name or the search pattern for the independent column name.


Column[] columns = valueMatrix.getIndependentColumns(colPattern);

Java Example:





public class GetIndependentColumns extends ValueMatrixExampleAbstract {

/**

* The main program. Example get independent columns from the valueMatrix.

*


*/


try {


© 2015/08/19 Version 1.33






Column[] cols = vm.getIndependentColumns("*");

System.out.println("The ValueMatrix has " + cols.length + " independent columns");



col.destroy();

}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.MeasurementTestCase.LoadValuesSubMatrixVM()test.highqsoft.avalon.MeasurementTestIT.testManyMeasurement()test.highqsoft.avalon.ValueMatrixCreateTestIT.testCreateValueMatrixFromMeaSm()test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()test.highqsoft.odsapi.read.MeasurementIT.testCompareNumberOfValues()....

5.31.10 getMode of interface ValueMatrix

Purpose:

Get the current mode of the value matrix.

Return:

ValueMatrixMode valueMatrixMode The mode of the value matrix

Parameter:

None.


ValueMatrixMode valueMatrixMode = vm.getMode();

Java Example:



© 2015/08/19 Version 1.33







public class GetMode extends ValueMatrixExampleAbstract {

/**

* The main program. Example get the mode of the valueMatrix.

*


*/


try {



ValueMatrixMode mode = vm.getMode();

if (mode.value()==ValueMatrixMode._CALCULATED) {

System.out.println("The ValueMatrix is in CALCULATED mode");

} else {

if (mode.value()==ValueMatrixMode._STORAGE) {

System.out.println("The ValueMatrix is in STORAGE mode");

} else {

System.out.println("The ValueMatrix is in UNKNOWN mode");

}

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.2

Errors:


Tested by:

test.highqsoft.odsapi.read.MeasurementIT.testCompareNumberOfValues()

5.31.11 getRowCount of interface ValueMatrix

Purpose:

Get the row count of the value matrix.

Return:

T_LONG rowCount The number of rows of the value matrix.


© 2015/08/19 Version 1.33




Parameter:

None.


int rowCount = valueMatrix.getRowCount();

Java Example:




public class GetRowCount extends ValueMatrixExampleAbstract {

/**

* The main program. Example get number of values from the valueMatrix.

*


*/


try {



int rowCount = vm.getRowCount();

System.out.println("The valueMatrix has " + rowCount + " values");


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.MeasurementTestCase.LoadValuesSubMatrixVM()test.highqsoft.avalon.MeasurementTestIT.testManyMeasurement()test.highqsoft.avalon.ValueMatrixCompareTestIT.testCompareValueMatrix()test.highqsoft.avalon.ValueMatrixGetTestIT.testValueMatrixGetMeaPoint()test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()....

5.31.12 getScalingColumns of interface ValueMatrix

Purpose:

Deprecated, solved by NVH Application model.Get the scaling column of the value matrix.


© 2015/08/19 Version 1.33




Return:

ColumnSequence columns The scaling columns of the value matrix.

Parameter:

Pattern colPattern (in) The name or the search pattern for the scaling column name.


Column[] columns = valueMatrix.getScalingColumns(colPattern);

Errors:


Tested by:

5.31.13 getValue of interface ValueMatrix

Purpose:

Get the values of di�erent columns of the value matrix.The server behavior depends on the mode of the value matrix.Value matrix mode 'CALCULATED':In case 'sequence_representation' of the corresponding local column is one of the entries'raw_linear', raw_polynomial', 'raw_linear_external', 'raw_polynomial_external', 'raw_-linear_calibrated', or 'raw_linear_calibrated_external', the server will �rst calculate thephysical values from raw values and generation parameters, before it returns them to therequesting client.Value matrix mode 'STORAGE':In case 'sequence_representation' of the corresponding local column is one of the entries'raw_linear', raw_polynomial', 'raw_linear_external', 'raw_polynomial_external', 'raw_-linear_calibrated', or 'raw_linear_calibrated_external', the server will return the raw valuesof the local column.

Note


Return:

NameValueSeqUnitSequence values The values of the di�erent columns. The name of thereturn structure corresponds with the name of the column. The unit corresponds with the unitof the column. The order of the results might not match the order in the requesting sequence.

Parameter:

ColumnSequence columns (in) The requested columns.


© 2015/08/19 Version 1.33




T_LONG startPoint (in) The starting point in the column.

T_LONG count (in) The number of points to be retrieved. 0 means until end of column.


Column columns[] = vmObj.getColumns("*");

int startPoint = 0;

int count = 100;

NameValueSeqUnit values[] = vmObj.getValue(columns, startPoint, count);

Java Example:






public class GetValue extends ValueMatrixExampleAbstract {

/**

* The main program. Example get the values of the columns from the valueMatrix.

* The value vector is the vector with the values of the column.

*


*/


try {





if (cols.length > 0) {

// Load all values point = 0) from the begin (start = 1)

NameValueSeqUnit[] valSeq = vm.getValue(cols, 1, 0);

for (int i = 0; i < valSeq.length; i++) {

System.out.println("The column " + valSeq[i].valName + " has " + valSeq[i].value.flag.length + " values");

}

}



col.destroy();

}


close();


// Report the error



}

}

}

Since

ASAM ODS 5.0

See also:

getValueVector of interface ValueMatrixgetValueMeaPoint of interface ValueMatrix


© 2015/08/19 Version 1.33




Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixCompareTestIT.testCompareValueMatrix()test.highqsoft.avalon.ValueMatrixGetTestIT.testValueMatrixGetMeaPoint()test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.ford.FordMesaurementTest.testCreateMeasurementDoubleLc()....

5.31.14 getValueMeaPoint of interface ValueMatrix

Purpose:

Get a measurement point of the value matrix. The parameter meaPoint speci�es the row ofthe matrix. The iterator allows to access all elements in the row.The server behavior depends on the mode of the value matrix.Value matrix mode 'CALCULATED':In case 'sequence_representation' of the corresponding local column is one of the entries'raw_linear', raw_polynomial', 'raw_linear_external', 'raw_polynomial_external', 'raw_-linear_calibrated', or 'raw_linear_calibrated_external', the server will �rst calculate thephysical values from raw values and generation parameters, before it returns them to therequesting client.Value matrix mode 'STORAGE':In case 'sequence_representation' of the corresponding local column is one of the entries'raw_linear', raw_polynomial', 'raw_linear_external', 'raw_polynomial_external', 'raw_-linear_calibrated', or 'raw_linear_calibrated_external', the server will return the raw valuesof the local column.

Return:

NameValueUnitIterator valueMeaPoint The requested measurement point.

Parameter:

T_LONG meaPoint (in) The measurement point.


NameValueUnitIterator valueMeaPoint = valueMatrix.getValueMeaPoint(meaPoint);

Errors:



© 2015/08/19 Version 1.33




Tested by:


5.31.15 getValueVector of interface ValueMatrix

Purpose:

Get the values or a part of values of the column from the value matrix. The parametercolumn speci�es from which column the values will be returned. The startPoint and countspecify the part of the vector. A startPoint = 0 and count = rowCount will return the entirevector. When startPoint >= rowCount an exception is thrown. If startPoint + count >rowCount only the remaining values of the vector are returned and no exception is thrown.Use the getName and getUnit method of the interface column for the name and the unit ofthe column. The name and the value are not stored at each element of the vector. The returntype TS_ValueSeq is not a sequence of TS_Value but a special structure.The server behavior depends on the mode of the value matrix.Value matrix mode 'CALCULATED':In case 'sequence_representation' of the corresponding local column is one of the entries'raw_linear', raw_polynomial', 'raw_linear_external', 'raw_polynomial_external', 'raw_-linear_calibrated', or 'raw_linear_calibrated_external', the server will �rst calculate thephysical values from raw values and generation parameters, before it returns them to therequesting client.Value matrix mode 'STORAGE':In case 'sequence_representation' of the corresponding local column is one of the entries'raw_linear', raw_polynomial', 'raw_linear_external', 'raw_polynomial_external', 'raw_-linear_calibrated', or 'raw_linear_calibrated_external', the server will return the raw valuesof the local column.

Return:

TS_ValueSeq valueVector The requested column values of the value matrix.

Parameter:

Column col (in) The column to retrieve the values from.

T_LONG startPoint (in) The starting point in the column.

T_LONG count (in) The number of points to be retrieved. 0 means until end of column.


TS_Value[] valueVector = valueMatrix.getValueVector(col,startPoint,count);

Java Example:






© 2015/08/19 Version 1.33





public class GetValueVector extends ValueMatrixExampleAbstract {

/**

* The main program. Example get the values vector of a column from the valueMatrix.

* The value vector is the vector with the values of the column.

*


*/


try {





if (cols.length > 0) {

// Load all values (point = 0) from the begin (start = 1)

TS_ValueSeq valSeq = vm.getValueVector(cols[0], 1, 0);

System.out.println("The vector has " + valSeq.flag.length + " values");

}



col.destroy();

}


close();


// Report the error



}

}

}

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_COLUMNAO_INVLAID_COUNTAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.avalon.MeasurementTestCase.LoadValuesSubMatrixVM()test.highqsoft.avalon.MeasurementTestIT.testManyMeasurement()test.highqsoft.avalon.ValueMatrixCompareTestIT.testCompareValueMatrix()test.highqsoft.avalon.ValueMatrixGetTestIT.testValueMatrixGetMeaPoint()test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()....

5.31.16 listColumns of interface ValueMatrix

Purpose:

Get the names of the columns of the value matrix no matter whether the column is dependentor independent. The pattern is case sensitive and may contain wildcard characters.


© 2015/08/19 Version 1.33




Return:

NameSequence columnNames The column names of the value matrix, no matter whether thecolumn is dependent, independent or scaled by another one.

Parameter:



Name[] columnNames = valueMatrix.listColumns(colPattern);

Java Example:




public class ListColumns extends ValueMatrixExampleAbstract {

/**

* The main program. Example get names of the columns from the valueMatrix.

*


*/


try {



String[] colNames = vm.listColumns("*");

System.out.println("The valueMatrix has " + colNames.length + " columns");



}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixCreateTestIT.testCreateValueMatrixFromSmSelectMea()test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()test.highqsoft.odsapi.ods530.CreateMeasurementTest.testCreateMeasurement()test.highqsoft.odsapi.performance.ValueMatrixPerfIT.testReadManyVmCount()test.highqsoft.odsapi.CreateMeasurementSpecTest.testAppendValues()


© 2015/08/19 Version 1.33




5.31.17 listColumnsScaledBy of interface ValueMatrix

Purpose:

Deprecated, solved by NVH Application model.List the names of the columns, which are scaled by the given column.

Note


Return:

NameSequence columnNames The names of the columns which are scaled by the given inputcolumn.

Parameter:



Name[] columnNames = valueMatrix.listColumnsScaledBy(scalingColumn);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVEAO_NO_SCALING_COLUMN

Tested by:

5.31.18 listIndependentColumns of interface ValueMatrix

Purpose:

Get the names of the independent columns of the value matrix. The independent columnsare the columns used to build the value matrix.

Return:

NameSequence columnNames The names of the independent columns of the value matrix.

Parameter:

Pattern colPattern (in) The name or the search pattern for the independent column names.


Name[] columnNames = valueMatrix.listIndependentColumns(colPattern);


© 2015/08/19 Version 1.33




Java Example:




public class ListIndependentColumns extends ValueMatrixExampleAbstract {

/**

* The main program. Example get names of independent columns from the valueMatrix.

*


*/


try {



String[] colNames = vm.listIndependentColumns("*");

System.out.println("The valueMatrix has " + colNames.length + " independent columns");



}


close();


// Report the error



}

}

}

Errors:


Tested by:

test.highqsoft.avalon.ValueMatrixTestIT.testApplElemAccessValueMatrix()test.highqsoft.avalon.ValueMatrixUnitTestIT.testCheckUnit()

5.31.19 listScalingColumns of interface ValueMatrix

Purpose:

Deprecated, solved by NVH Application model.Get the names of the scaling columns of the value matrix.

Return:

NameSequence columnNames The names of the scaling columns of the value matrix.

Parameter:

Pattern colPattern (in) The name or the search pattern for the scaling column name.


© 2015/08/19 Version 1.33





Name[] columnNames = valueMatrix.listScalingColumns(colPattern);

Errors:


Tested by:

5.31.20 removeValueMeaPoint of interface ValueMatrix

Purpose:

Remove the values of multiple columns at a given measurement point or remove the numberof points of the given columns beginning at meapoint. If the count is 0 all points until theend of the columns are removed.

Note

Only for valuematrix of a submatrix. Only when all column of the valuematrix are given.The transaction must be activated, but there is no transaction control. The modi�cation ofthe values is directly stored in the data storage. The name of the column is the name of theinstance of the measurement quantity and the names must match these names. Due to thefact ASAM ODS requires the name of the local column must be identical with the name ofthe measurement quantity there will be normally no di�erence.

Return:

void

Parameter:

NameSequence columnNames (in) The columns from which the measurement points are to beremoved.

T_LONG meaPoint (in) The measurement point to be removed.

T_LONG count (in) The number of points to be removed from each column beginning atmeapoint.


valueMatrix.removeValueMeaPoint(columnNames,meaPoint,count);

Errors:

AO_BAD_PARAMETER


© 2015/08/19 Version 1.33




AO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_COUNTAO_NOT_FOUNDAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

5.31.21 removeValueVector of interface ValueMatrix

Purpose:

Remove the values from a single column. Beginning at startPoint the number of valuesspeci�ed in count are removed. If count is 0 all values from the startPoint until the end ofthe column are removed.

Note

Not yet implemented. See also Transaction handling in ODS API. (p. 15)

Return:

void

Parameter:

Column col (in) The column from which the values are to be removed.

T_LONG startPoint (in) The starting point for the value removal.

T_LONG count (in) The number of points to be removed from the column.


valueMatrix.removeValueVector(col,startPoint,count);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_COLUMNAO_INVALID_COUNTAO_NOT_FOUNDAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:


© 2015/08/19 Version 1.33




5.31.22 setValue of interface ValueMatrix

Purpose:

Create or modify a number of value vectors in a value matrix.It is allowed to modify the values of the value matrix outside a transaction but it is recom-mended to activate a transaction.The data is made permanent on transaction commit. Until the transaction is committed oruntil the access to the measurement point of the value matrix it is allowed to have di�erentnumbers of values in the di�erent value vectors.The names of the parameter values are the names of the columns. The values are the newvalues of the column. (setValueMeaPoint allows only one point, the TS_ValueSeq allowsmore then one point) There is a sequence of name value pairs (setValueVector allows only onecolumn), so a block of values can be modi�ed.The meaning of the parameter setType is:INSERT Insert the values from startPoint, the current available values from startPoint aremoved to the end of the new inserted values.APPEND The value of startPoint is ignored, the values are appended at the end of the currentvalues.UPDATE Update or modify the values from startPoint, the current values are overwritten.If the number of values is greater than the number of values in the vector, the measurementpoint is automatically appended.REMOVE Remove the number of values from each column, starting with startPoint. Thename of the column is given as the name of the NameValueseqUnit, the number of values toremove is given in the number of the values in the value.When a client creates a ValueMatrix based on AoMeasurement this methods behaves asfollows:The server checks the sub matrices and creates all necessary instances of AoSubmatrix, AoLo-calColumn and AoMeasurementQuantity. The values of the name attribute of AoSubmatrixmust be generated by the server. The value will be equal to the value of the attribute ID(converted to DT_STRING). Missing instances of AoMeasurementQuantity will be createdby the server, too.The mandatory attributes will get the following default values:Name supplied by clientDatatype copied from AoQuantity.default_datatypeTypesize copied from AoQuantity.default_typesizeInterpolation no interpolationRank copied from AoQuantity.default_rankDimension copied from AoQuantity.default_dimensionThe server takes the value of the channel (supplied by client) and looks up the correspondinginstance in AoQuantity using the attribute default_meq_name.The ValueMatrix interface handles the values but not the raw values, to modify the raw valuesthe instances of localcolumn must be created, the base attribute sequence_representation,raw_datatype and the generation_parameter must be created before the values are modi�ed.The values must have the data type identical with the raw_datatype, any other data typewill cause an AO_INVALID_DATATYPE exception.

Note

The transaction must be activated. See also Transaction handling in ODS API. (p. 15).The name of the column is the name of the instance of the measurement quantity and thenames of the parameter value must match these names. Due to the fact ASAM ODS requiresthe name of the local column must be identical with the name of the measurement quantitythere will be normally no di�erence.


© 2015/08/19 Version 1.33




Return:

void

Parameter:

SetType set (in) The set type.

T_LONG startPoint (in) The measurement point.

NameValueSeqUnitSequence value (in) The values to be inserted.


valueMatrix.setValue(set,startPoint,value);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_COLUMNAO_INVALID_SET_TYPEAO_INVALID_DATATYPEAO_IS_MEASUREMENT_MATRIXAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.performance.MeasurementPerfIT.testCreateMeasurement()test.highqsoft.odsapi.valuematrixwrite.CheckRemoveTest.testCreateMeasurementRemovePart()test.highqsoft.odsapi.CreateInstanceTestCase.updateMeasurementInstances()test.highqsoft.odsapi.XCompMeasurementTest.testAppendInstancesValueMatrix()

5.31.23 setValueMeaPoint of interface ValueMatrix

Purpose:

Create or modify a single measurement point in multiple columns of a value matrix.The sequence of name values speci�es the names of the columns with the new values.The meaning of the parameter 'set' is:INSERT Insert the values at meaPoint, the current values at meaPoint are moved to the endof the new inserted values.APPEND The value of meaPoint is ignored, the values are appended at the end of the currentvalues.UPDATE Update or modify the values at meaPoint, the current values are overwritten. IfmeaPoint is bigger than the number of values in the vector, the measurement point is auto-matically appended.The names of the columns have to exist.When a client creates a ValueMatrix based on AoMeasurement this method behaves as follows:The server checks the sub matrices and creates all necessary instances of AoSubmatrix, AoLo-calColumn and AoMeasurementQuantity. The values of the name attribute of AoSubmatrix


© 2015/08/19 Version 1.33




must be generated by the server. The value will be equal to the value of the attribute ID(converted to DT_STRING). Missing instances of AoMeasurementQuantity will be createdby the server, too.The mandatory attributes will get the following default values:Name supplied by clientDatatype copied from AoQuantity.default_datatypeTypesize copied from AoQuantity.default_typesizeInterpolation no interpolationRank copied from AoQuantity.default_rankDimension copied from AoQuantity.default_dimensionThe server takes the value of the channel (supplied by client) and looks up the correspondinginstance in AoQuantity using the attribute default_meq_name.

Note

Not yet implemented. See also Transaction handling in ODS API. (p. 15) The name ofthe column is the name of the instance of the measurement quantity and the names of theparameter value must match these names. Due to the fact ASAM ODS requires the name ofthe local column must be identical with the name of the measurement quantity there will benormally no di�erence.

Return:

void

Parameter:

SetType set (in) The SetType.

T_LONG meaPoint (in) The measurement point.

NameValueSequence value (in) The values to be inserted.


valueMatrix.setValueMeaPoint(set,meaPoint,value);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_IS_MEASUREMENT_MATRIXAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:


© 2015/08/19 Version 1.33




5.31.24 setValueVector of interface ValueMatrix

Purpose:

Create or modify a value vector in a value matrix.It is allowed to modify the values of the value matrix outside a transaction but it is recom-mended to activate a transaction.The data is made permanent on transaction commit. Until the transaction is committed oruntil the access to the measurement point of the value matrix, it is allowed to have di�erentnumber of values in the di�erent value vectors.The meaning of the parameter setType is:INSERT Insert the values from startPoint, the current available values from startPoint aremoved to the end of the new inserted values.APPEND The value of startPoint is ignored, the values are appended at the end of the currentvalues.UPDATE Update or modify the values from startPoint, the current values are overwritten. Ifthe number of values in the parameter values is too big the values are automatically appended.When a client creates a ValueMatrix based on AoMeasurement this methodsbehaves as follows:The server checks the sub matrices and creates all necessary instances of AoSubmatrix, AoLo-calColumn and AoMeasurementQuantity. The values of the name attribute of AoSubmatrixmust be generated by the server. The value will be equal to the value of the attribute ID(converted to DT_STRING). Missing instances of AoMeasurementQuantity will be createdby the server,too.The mandatory attributes will get the following default values:Name supplied by clientDatatype copied from AoQuantity.default_datatypeTypesize copied from AoQuantity.default_typesizeInterpolation no interpolationRank copied from AoQuantity.default_rankDimension copied from AoQuantity.default_dimensionThe server takes the value of the channel (supplied by client) and looks up the correspondinginstance in AoQuantity using the attribute default_meq_name.

Note

See alsoTransaction handling in ODS API. (p. 15). The number of rows at the SubMatrixwill not be updated when the number of rows of the columns increase. Use the methodsetValue of this interface for the append of the values of the columns.

Return:

void

Parameter:

Column col (in) The column whose values are to be set.

SetType set (in) The set type.

T_LONG startPoint (in) The starting point for the new values.

TS_ValueSeq value (in) The values to be inserted.


© 2015/08/19 Version 1.33





valueMatrix.setValueVector(col,set,startPoint,value);

Errors:

AO_BAD_PARAMETERAO_CONNECTION_LOSTAO_IMPLEMENTATION_PROBLEMAO_INVALID_COLUMNAO_INVALID_SET_TYPEAO_IS_MEASUREMENT_MATRIXAO_NOT_IMPLEMENTEDAO_NO_MEMORYAO_SESSION_NOT_ACTIVE

Tested by:

test.highqsoft.odsapi.booleans.BooleanTest.testChangeMeaBool()test.highqsoft.odsapi.XCompMeasurementTest.testAppendInstancesValueMatrix()


© 2015/08/19 Version 1.33



Chapter 6

ASAM ODS Structures

6.1 De�nitions of the ACL structure.

The ACL Structure

The access control list entry.

rights

is of datatype: T_LONG

The access rights of the requested object.

usergroupId

is of datatype: T_LONGLONG

The usergroup Id.

6.2 De�nitions of the AIDName structure.

The AIDName Structure

AID - Name pair.

aaName

is of datatype: Name

The application attribute name.

aid


The Id of the application element.

526 ASAM ODS Structures

6.3 De�nitions of the AIDNameUnitId structure.

The AIDNameUnitId Structure

AID - Name - UnitId tuple.

attr

is of datatype: AIDName

The attribute of the application element (aid, name).

unitId


The unit of the attribute. The unitId is the Id of the instance element with the basetypeAoUnit.

6.4 De�nitions of the AIDNameValueSeqUnitId structure.

The AIDNameValueSeqUnitId Structure

AID - Name - Value - UnitId quartet. Multiple values for one attribute.

attr



unitId


The unit of the attribute or the column. The unitId is the Id of instance element with thebasetype AoUnit.

values

is of datatype: TS_ValueSeq

The column values with value �ags.

6.5 De�nitions of the AIDNameValueUnitId structure.

The AIDNameValueUnitId Structure

AID - Name - Value - UnitId quartet.


© 2015/08/19 Version 1.33



6.6 De�nitions of the ApplAttr structure. 527

attr



unitId


The unit of the attribute or the column. The unitId is the Id of the instance element withthe basetype AoUnit.

values

is of datatype: TS_Value

The attribute values with value �ags.

6.6 De�nitions of the ApplAttr structure.

The ApplAttr Structure

The application attribute information (metadata) de�nition. The same information is avail-able at the interface ApplicationAttribute

aaName


The application attribute name. The same name is returned by the method getName() of theApplicationAttribute interface.

baName


The name of the base attribute, empty string ("") if the application attribute is not de-rived from a base attribute. The same name is returned by the method getName() of theBaseAttribute interface. The base attribute is given by the method getBaseAttribute() of theinterface ApplicationAttribute.

dType

is of datatype: DataType

The attribute data type. The same data type is given by the method getDataType of theinterface ApplicationAttribute.


© 2015/08/19 Version 1.33




isObligatory

is of datatype: T_BOOLEAN

The indicator for mandatory attributes, the notNull indicator is set at the column of the tablein the physical storage. The same boolean is returned by the method isObligatory() of theinterface ApplicationAttribute.

isUnique


The indicator for unique attributes. The same boolean is returned by the method isUnique()of the interface ApplicationAttribute.

length


The maximum possible length of values. The same length is returned by the methodgetLength() of the interface ApplicationAttribute.

unitId


Id of the unit if global de�ned. The same Id is returned by the method getUnit() of theinterface ApplicationAttribute.

6.7 De�nitions of the ApplElem structure.

The ApplElem Structure

The application element de�nition. The same information is available at the interface Appli-cationElement.

aeName


The application element name. The name is also returned by the method getName() of theinterface ApplicationElement.

aid


The application element id. The id is also returned by the method getId() of the interfaceApplicationElement.


© 2015/08/19 Version 1.33



6.8 De�nitions of the ApplicationRelationInstanceElementSeq structure. 529

attributes

is of datatype: ApplAttrSequence

The attributes of an application element. The attributes are returned by the method getAt-tributes() of the interface ApplicationElement. There are no relations included in the thissequence.

beName


The base element name, all application elements have a basic element. The same nameis returned by the methods getType() of the BaseElement interface. The base element isreturned by the method getBaseElement() of the interface ApplicationElement.

6.8 De�nitions of the ApplicationRelationInstanceEle-

mentSeq structure.

The ApplicationRelationInstanceElementSeq Structure

The application relation with the instances to create the relation with new instances.

applRel

is of datatype: ApplicationRelation

The application relation.

instances

is of datatype: InstanceElementSequence

The list with instances. The application element of the instances in the list must match oneof the application elements of the application relation. All instances of the list must have thesame application element.

6.9 De�nitions of the ApplicationStructureValue structure.

The ApplicationStructureValue Structure

Application structure values. All values of the entire application structure are stored in thisstructure and transfered to the Client on request.

applElems

is of datatype: ApplElemSequence

The list of application elements.


© 2015/08/19 Version 1.33




applRels

is of datatype: ApplRelSequence

The list of relations in the application structure. The list of ApplRel's contains distinct entriesfor relations and their inverses. The �eld invName contains the inverse relation.Both relations, the normal and the inverse relation are given in the sequence.

6.10 De�nitions of the ApplRel structure.

The ApplRel Structure

The application relation info structure. The same information is available at the interfaceApplicationRelation.A relation is the connection between two ASAM ODS elements; it may be navigated in bothdirections. The get- and set- methods are de�ned from the �rst element, the getInverse- andsetInverse- methods work from the second element.

arName


The relation name. The name is returned by the method getName() of the interface Appli-cationRelation.

arRelationRange

is of datatype: RelationRange

The range of the relation. Range of the relation is not stored in the physical storage. Therelation range is returned by the method getRelationRange() of the interface ApplicationRe-lation.

arRelationType

is of datatype: RelationType

The type of the relation. Type of the relation is not stored in the physical storage. The relationtype is returned by the method getRelationType() of the interface ApplicationRelation.

brName


Name of the base relation from the elem1 to the elem2. The base relation is also not storedin the physical storage.

elem1



© 2015/08/19 Version 1.33



6.11 De�nitions of the AttrResultSet structure. 531

The source application element Id. The given Id is the Id of the application element returnedby the method getElem1() of the interface ApplicationRelation.

elem2


The target application element Id. The given Id is the Id of the application element returnedby the method getElem2() of the interface ApplicationRelation.

invBrName


Name of the inverse base relation from the elem2 to the elem1. The base relation is also notstored in the physical storage.

invName


Name of the inverse relation. The name is returned by the method getInverseName() ofthe interface ApplicationRelation. The invName is not available in the physical storage forrelation databases.

invRelationRange

is of datatype: RelationRange

The inverse range of the relation. Range of the relation is not stored in the physical stor-age. The inverse relation range is returned by the method getInverseRelationRange() of theinterface ApplicationRelation.

6.11 De�nitions of the AttrResultSet structure.

The AttrResultSet Structure

The results for one attribute. The result set for all attributes are given in the sequence of theresult set.

attrValues

is of datatype: NameValueSeqUnitId

The attribute result set of one element. All values have the same attribute (AIDName) andthe same unit (UnitId). Only the �rst part of the possible attribute values are available inthis result set. The size of the part depends on the parameter 'how_many' of the method'getInstances' of the interface 'ApplElemAccess'.


© 2015/08/19 Version 1.33




rest

is of datatype: NameValueUnitIdIterator

The rest of the results. The iterator provides access to the consecutive NameValueSeqUnitId-packages of the result set.

6.12 De�nitions of the ElemId structure.

The ElemId Structure

Instance element Id. The unique description of an instance element.

aid



iid


The Id of the instance element.

6.13 De�nitions of the ElemResultSet structure.

The ElemResultSet Structure

The result set for one element. The result set for all elements are given in the sequence of theresult set.

aid



attrValues

is of datatype: AttrResultSetSequence

The selected attributes of the element. The number of values in each AttrResultSet areidentical, the attributes of one element have always the position in the AttrResultSet.

6.14 De�nitions of the ElemResultSetExt structure.

The ElemResultSetExt Structure

Restult set of one application element.


© 2015/08/19 Version 1.33



6.15 De�nitions of the EnumerationAttributeStructure structure. 533

aid


The application element Id.

values

is of datatype: NameValueSeqUnitIdSequence

The attribute values of the instances of the given application element.

6.15 De�nitions of the EnumerationAttributeStructure

structure.

The EnumerationAttributeStructure Structure

The structure with the attribute and the name of the enumeration.

aaName

is of datatype: T_STRING

The name of the attribute

aid


The application element Id.

enumName


The name of the enumeration

6.16 De�nitions of the EnumerationItemStructure structure.

The EnumerationItemStructure Structure

The structure with the items of the enumeration.

index


The index of the enumeration item.


© 2015/08/19 Version 1.33




itemName


The name of the item.

6.17 De�nitions of the EnumerationStructure structure.

The EnumerationStructure Structure

The structure with the enumeration and its items.

enumName


The name of the enumeration.

items

is of datatype: EnumerationItemStructureSequence

The items of the enumeration.

6.18 De�nitions of the InitialRight structure.

The InitialRight Structure

An initial right.

refAid


The referencing application element.

rights


The initial access rights of the requested object.

usergroupId


The usergroup Id of the Initial right list.


© 2015/08/19 Version 1.33



6.19 De�nitions of the JoinDef structure. 535

6.19 De�nitions of the JoinDef structure.

The JoinDef Structure

Basically, joins can only be realized between application elements that are linked via a ref-erence de�ned in the model. From the de�nition of attributes or application elements, thereferences for the joins are determined. It is also taken into account that the application ele-ments involved are not linked directly. However, there must be an unambiguous path betweenthe application elements. The path may also include n:m relations. The unambiguousnessof relations between two application elements no longer exists if more than one referencehas been de�ned between the application elements. In this case, these references must havenames and must be indicated explicitly in the request.For this purpose, the request structureprovides a sequence of relation de�nitions (JoinDefSequence). The sequence in which theapplication elements are addressed in the request also determines the sequence in which thereferences between application elements are searched. Thus, for every new application ele-ment, the server begins with the �rst application element addressed in the request and triesto �nd a relation from there. If no reference to the �rst application element can be found, thesearch continues with the application element that comes next in the request. Furthermore,the explicit relation de�nitions (JoinDefSequence) enable an OUTER join, i.e. the result alsoincludes those records for which the join could not be established.

fromAID


The application element Id of the source element.

joiningType

is of datatype: JoinType

The type of the join: inner or outer join on destination AID.

refName


Name of the application relation that relates the elements which are to join.

toAID


The application element ID of the target element.

6.20 De�nitions of the NameUnit structure.

The NameUnit Structure

The ASAM ODS name-unit tuple structure.


© 2015/08/19 Version 1.33




unit


Attribute unit as string.

valName


Attribute name or measured quantity name.

6.21 De�nitions of the NameValue structure.

The NameValue Structure

The ASAM ODS name-value pair structure.

valName



value


Attribute value or column value (vector).

6.22 De�nitions of the NameValueSeqUnit structure.

The NameValueSeqUnit Structure

The ASAM ODS name-value-unit tuple structure with a sequence of values.

unit


Column unit as string.

valName


Column name or measured quantity name.

value


Column value (vector).


© 2015/08/19 Version 1.33



6.23 De�nitions of the NameValueSeqUnitId structure. 537

6.23 De�nitions of the NameValueSeqUnitId structure.

The NameValueSeqUnitId Structure

The ASAM ODS name-value-unitId tuple structure with a sequence of values.

unitId


Column unit as Id.

valName


Column name or measured quantity name.

value


Column value (vector).

6.24 De�nitions of the NameValueUnit structure.

The NameValueUnit Structure

The ASAM ODS name-value-unit tuple structure. This structure is identical with theNameValueUnitId, except the unit is given as a string instead of an Id.

unit


Attribute or column unit as string.

valName



value




© 2015/08/19 Version 1.33




6.25 De�nitions of the NameValueUnitId structure.

The NameValueUnitId Structure

The ASAM ODS NameValueUnitId tuple structure. This structure is identical with theNameValueUnit, except the unit is given as an Id instead of a string.

unitId


Id of attribute or column unit.

valName



value



6.26 De�nitions of the QueryStructure structure.

The QueryStructure Structure

The query structure.How to build a query.A query is a search condition for instances. The instances are speci�ed by the values of theattributes. The search condition represents an attribute value condition. This means theattribute value speci�es the selection of the instance or instance attribute. An attribute isspeci�ed by the application element and the name of the attribute (AIDName). The conditionsare de�ned in the enumeration SelOPCode. The values are given in the TS_Value or TS_-Union structure. If we like an Unit indepedent condition we need to de�ne the Unit at theattribute, use AIDNameUnitId instead of AIDName, the server has to convert the value tothe proper attribute value. The attribute search condition can be combined by operationsde�ned in the enumeration SelOperator. A query can be built with a sequence SelValue andSelOperator.How to read/write the query:e.g. SelValue1 AND SelValue2selValueSeq = SelValue1, SelValue2selOPeratorSeq = ANDe.g. (SelValue1 AND SelValue2) OR SelValue3selValueSeq = SelValue1, SelValue2, SelValue3selOPeratorSeq = OPEN, AND, CLOSE, ORe.g. NOT(SelValue1 AND SelValue2) OR SelValue3selValueSeq = SelValue1, SelValue2, SelValue3selOPeratorSeq = NOT, OPEN, AND, CLOSE, ORe.g. NOT(SelValue1) AND SelValue2 OR SelValue3


© 2015/08/19 Version 1.33



6.27 De�nitions of the QueryStructureExt structure. 539

selValueSeq = SelValue1, SelValue2, SelValue3selOPeratorSeq = NOT, AND, ORThere is no selection about the N:M relations.There are no aggregate functions (MAX, MIN, COUNT etc.) de�ned so we need no "groupby" and "having" Clause. All the parts de�ned in the "having"-clause can be de�ned in theselect part.

anuSeq

is of datatype: AIDNameUnitIdSequence

The sequence of attributes to be reported. A pattern is accepted for the attribute name.

condSeq

is of datatype: SelValueSequence

The query condition sequence.

operSeq

is of datatype: SelOperatorSequence

The query condition operator sequence.

orderBy

is of datatype: SelOrderSequence

The order by sequence. The order of the result set.

relInst

is of datatype: ElemId

The related instance. (aid == 0 && iid == 0) means no related instance speci�ed.

relName


Name of the relation.

6.27 De�nitions of the QueryStructureExt structure.

The QueryStructureExt Structure

The extended query structure.


© 2015/08/19 Version 1.33




anuSeq

is of datatype: SelAIDNameUnitIdSequence

The sequence of attributes to be reported. A pattern is accepted for the attribute name.

condSeq

is of datatype: SelItemSequence

The query condition sequence.

groupBy

is of datatype: AIDNameSequence

De�nes the grouping attributes for a request, necessary if aggregate functions are de�ned inthe SelAIDNameUnitIdSequence.

joinSeq

is of datatype: JoinDefSequence

De�nes the join between the application elements.

orderBy

is of datatype: SelOrderSequence

The order by sequence. The order of the result set.

6.28 De�nitions of the RelationRange structure.

The RelationRange Structure

The ASAM ODS relation range structure.

max

is of datatype: T_SHORT

The maximum number in the range. -1 means MANY without a speci�ed maximum number.

min


The minimum number in the range.


© 2015/08/19 Version 1.33



6.29 De�nitions of the ResultSetExt structure. 541

6.29 De�nitions of the ResultSetExt structure.

The ResultSetExt Structure

The Result set of the extended query. The iterator is for instance oriented access.

�rstElems

is of datatype: ElemResultSetExtSequence

The sequence of the �rst how_many result elements.

restElems

is of datatype: ElemResultSetExtSeqIterator

The iterator, which allows to iterate over the result values, the attributes of one instance eachiteration.

6.30 De�nitions of the SelAIDNameUnitId structure.

The SelAIDNameUnitId Structure

Its quite the same sequence as in the QueryStructure of GetInstances with one exception. Ithas one new attribute called function, which is of the type AggrFunc. Thereby it is possibleto de�ne aggregate functions on attribute level, without the need to parse the attribute namefor a known aggregate function name. The default value of that attribute function is NONE,it symbolizes that no aggregate function should be applied on that attribute. If an aggregatefunction is used, it is also required to de�ne a GroupSequence. It is also de�ned that a ∗ asattribute name, delivers all attributes of an element.

aggregate

is of datatype: AggrFunc

The aggregate function.

attr



unitId


The unit of the attribute. The unitId is the Id of the instance element with the basetypeAoUnit.


© 2015/08/19 Version 1.33




6.31 De�nitions of the SelOrder structure.

The SelOrder Structure

Order criteria.

ascending


ascending order, FALSE means descending.

attr


Attribute speci�cation.

6.32 De�nitions of the SelQuery structure.

The SelQuery type

attr


Attribute to select for the nested query

condSeq

is of datatype: SelItemSequence

The conditions of the nested query.

6.33 De�nitions of the SelQueryItem structure.

The SelQueryItem type

attr


The attribute of the condition.

nestedQery

is of datatype: SelQuery


© 2015/08/19 Version 1.33



6.34 De�nitions of the SelValue structure. 543

The nested query as condition.

oper

is of datatype: SelOpcode

The condition

6.34 De�nitions of the SelValue structure.

The SelValue Structure

Structure for name value query or attribute search conditions.

attr

is of datatype: AIDNameValueUnitId

The attribute speci�cation with unit of the value.

oper


The compare operator between the attribute and value.

value


Value for the condition.

6.35 De�nitions of the SelValueExt structure.

The SelValueExt Structure

The attribute selection structure.

attr

is of datatype: AIDNameUnitId

The attribute speci�cation with unit Id.

oper


The compare operator between the attribute and value.


© 2015/08/19 Version 1.33




value


Value for the condition.

6.36 De�nitions of the T_COMPLEX structure.

The T_COMPLEX Structure

The ASAM ODS complex data structure. This type is represented in the datatype enumera-tion by DT_COMPLEX.

i

is of datatype: T_FLOAT

The imaginary part of the complex number.

r

is of datatype: T_FLOAT

The real part of the complex number.

6.37 De�nitions of the T_DCOMPLEX structure.

The T_DCOMPLEX Structure

The ASAM ODS double-precision complex data structure. This type is represented in thedatatype enumeration by DT_DCOMPLEX.

i

is of datatype: T_DOUBLE

The imaginary part of the double precision complex number.

r

is of datatype: T_DOUBLE

The real part of the double precision complex number.

6.38 De�nitions of the T_ExternalReference structure.

The T_ExternalReference Structure

The description of a reference object, the reference object can be an internal ASAM ODSobject or an external object. This type is represented in the datatype enumeration by DT_-EXTERNALREFERENCE.


© 2015/08/19 Version 1.33



6.39 De�nitions of the T_LONGLONG structure. 545

description


Description of the external reference.

location


Location of the external reference. (asam path or URL)

mimeType


MIME-type of the external object.

6.39 De�nitions of the T_LONGLONG structure.

The T_LONGLONG Structure

The ASAM ODS 64 bit integer structure. This type is represented in the datatype enumera-tion by DT_LONGLONG.

high


The most signi�cant 32 bits of the 64 bit value.

low


The least signi�cant 32 bits of the 64 bit value.

6.40 De�nitions of the TS_Value structure.

The TS_Value Structure

The ASAM ODS value structure. There is one �ag for each value. If the union (u) containsa sequence, the �ag is valid for all values in that sequence.Meaning of �ags:AO_VF_VALID(0x01) The value is valid.AO_VF_VISIBLE(0x02) The value has to bevisualized.AO_VF_UNMODIFIED(0x04) The value has not been


© 2015/08/19 Version 1.33




modi�ed.AO_VF_DEFINED(0x08) The value is de�ned. Ifthe value in a value matrixis not available this bitis not set.The normal value of the �ag is 15.

�ag


The value �ags.

u

is of datatype: TS_Union

The value union for values of all known datatypes.

6.41 De�nitions of the TS_ValueSeq structure.

The TS_ValueSeq Structure

A structure with sequences of a certain type. Using this union instead of sequence <TS_-Value> gives much better performance.

�ag

is of datatype: S_SHORT

See TS_Value �ag.

u

is of datatype: TS_UnionSeq

The value union for values of all known datatypes.


© 2015/08/19 Version 1.33



Chapter 7

ASAM ODS Unions

7.1 De�nitions of the SelItem union.

The SelItem Union

De�nes the sequence of selection attributes with their logical operators. The Idea is to havethe logical operators and the selection values in one sequence. Therefore no implicit rules arenecessary how logical operators have to be interpreted to the corresponding selection value.Attribute: SelType

operator

Datatype: SelOperatorCaseName: SEL_OPERATOR_TYPE

value

Datatype: SelValueExtCaseName: SEL_VALUE_TYPE

7.2 De�nitions of the TS_Union union.

The TS_Union Union

The union de�nition for all datatypes. Attribute: DataType

blobVal

Datatype: T_BLOBCaseName: DT_BLOB

booleanSeq

Datatype: S_BOOLEANCaseName: DS_BOOLEAN

booleanVal

Datatype: T_BOOLEANCaseName: DT_BOOLEAN

548 ASAM ODS Unions

byteSeq

Datatype: S_BYTECaseName: DS_BYTE

bytestrSeq

Datatype: S_BYTESTRCaseName: DS_BYTESTR

bytestrVal

Datatype: T_BYTESTRCaseName: DT_BYTESTR

byteVal

Datatype: T_BYTECaseName: DT_BYTE

complexSeq

Datatype: S_COMPLEXCaseName: DS_COMPLEX

complexVal

Datatype: T_COMPLEXCaseName: DT_COMPLEX

dateSeq

Datatype: S_DATECaseName: DS_DATE

dateVal

Datatype: T_DATECaseName: DT_DATE

dcomplexSeq

Datatype: S_DCOMPLEXCaseName: DS_DCOMPLEX

dcomplexVal

Datatype: T_DCOMPLEXCaseName: DT_DCOMPLEX

doubleSeq

Datatype: S_DOUBLECaseName: DS_DOUBLE

doubleVal

Datatype: T_DOUBLECaseName: DT_DOUBLE


© 2015/08/19 Version 1.33



7.2 De�nitions of the TS_Union union. 549

enumSeq

Datatype: S_LONGCaseName: DS_ENUM

enumVal

Datatype: T_LONGCaseName: DT_ENUM

extRefSeq

Datatype: S_ExternalReferenceCaseName: DS_EXTERNALREFERENCE

extRefVal

Datatype: T_ExternalReferenceCaseName: DT_EXTERNALREFERENCE

�oatSeq

Datatype: S_FLOATCaseName: DS_FLOAT

�oatVal

Datatype: T_FLOATCaseName: DT_FLOAT

longlongSeq

Datatype: S_LONGLONGCaseName: DS_LONGLONG

longlongVal

Datatype: T_LONGLONGCaseName: DT_LONGLONG

longSeq

Datatype: S_LONGCaseName: DS_LONG

longVal

Datatype: T_LONGCaseName: DT_LONG

shortSeq

Datatype: S_SHORTCaseName: DS_SHORT

shortVal

Datatype: T_SHORTCaseName: DT_SHORT


© 2015/08/19 Version 1.33



550 ASAM ODS Unions

stringSeq

Datatype: S_STRINGCaseName: DS_STRING

stringVal

Datatype: T_STRINGCaseName: DT_STRING

7.3 De�nitions of the TS_UnionSeq union.

The TS_UnionSeq Union

De�ne a union with sequences of a certain type. Using this union instead of sequence <TS_-Union> gives much better performance. Attribute: DataType

blobVal

Datatype: S_BLOBCaseName: DT_BLOB

booleanSeq

Datatype: SS_BOOLEANCaseName: DS_BOOLEAN

booleanVal

Datatype: S_BOOLEANCaseName: DT_BOOLEAN

byteSeq

Datatype: SS_BYTECaseName: DS_BYTE

bytestrSeq

Datatype: SS_BYTESTRCaseName: DS_BYTESTR

bytestrVal

Datatype: S_BYTESTRCaseName: DT_BYTESTR

byteVal

Datatype: S_BYTECaseName: DT_BYTE

complexSeq

Datatype: SS_COMPLEXCaseName: DS_COMPLEX


© 2015/08/19 Version 1.33



7.3 De�nitions of the TS_UnionSeq union. 551

complexVal

Datatype: S_COMPLEXCaseName: DT_COMPLEX

dateSeq

Datatype: SS_DATECaseName: DS_DATE

dateVal

Datatype: S_DATECaseName: DT_DATE

dcomplexSeq

Datatype: SS_DCOMPLEXCaseName: DS_DCOMPLEX

dcomplexVal

Datatype: S_DCOMPLEXCaseName: DT_DCOMPLEX

doubleSeq

Datatype: SS_DOUBLECaseName: DS_DOUBLE

doubleVal

Datatype: S_DOUBLECaseName: DT_DOUBLE

enumSeq

Datatype: SS_LONGCaseName: DS_ENUM

enumVal

Datatype: S_LONGCaseName: DT_ENUM

extRefSeq

Datatype: SS_ExternalReferenceCaseName: DS_EXTERNALREFERENCE

extRefVal

Datatype: S_ExternalReferenceCaseName: DT_EXTERNALREFERENCE

�oatSeq

Datatype: SS_FLOATCaseName: DS_FLOAT


© 2015/08/19 Version 1.33



552 ASAM ODS Unions

�oatVal

Datatype: S_FLOATCaseName: DT_FLOAT

longlongSeq

Datatype: SS_LONGLONGCaseName: DS_LONGLONG

longlongVal

Datatype: S_LONGLONGCaseName: DT_LONGLONG

longSeq

Datatype: SS_LONGCaseName: DS_LONG

longVal

Datatype: S_LONGCaseName: DT_LONG

shortSeq

Datatype: SS_SHORTCaseName: DS_SHORT

shortVal

Datatype: S_SHORTCaseName: DT_SHORT

stringSeq

Datatype: SS_STRINGCaseName: DS_STRING

stringVal

Datatype: S_STRINGCaseName: DT_STRING


© 2015/08/19 Version 1.33



Chapter 8

ASAM ODS Enumerations

8.1 De�nitions of the AggrFunc enumeration.

The AggrFunc Enumeration

The supported aggregate functions of the GetInstancesExt.

NONE 0

No aggregate function is used for attribute.

COUNT 1

Count

DCOUNT 2

Distinct count

MIN 3

Min; only for numerical values

MAX 4

Max; only for numerical values

AVG 5

Average; only for numerical values

STDDEV 6

Standard deviation; only for numerical values

554 ASAM ODS Enumerations

SUM 7

Sum; only for numerical values

DISTINCT 8

Distinct

POINT 9

The index of the values, only used by the attribute values of element AoLocalColumn

8.2 De�nitions of the AttrType enumeration.

The AttrType Enumeration

The ASAM ODS attribute type codes.

APPLATTR_ONLY 0

Report only application attributes.

INSTATTR_ONLY 1

Report only instance attributes.

ALL 2

All attributes.

8.3 De�nitions of the BuildUpFunction enumeration.

The BuildUpFunction Enumeration

The ASAM ODS build-up function codes for measurement views.

BUP_JOIN 0

Join the columns

BUP_MERGE 1

Merge the columns

BUP_SORT 2

Sort the columns


© 2015/08/19 Version 1.33



8.4 De�nitions of the DataType enumeration. 555

8.4 De�nitions of the DataType enumeration.

The DataType Enumeration

The ASAM ODS data types.DT_xxx Basic data types.DS_xxx Sequence of basic data type.|||+- T == Type, S == Sequences.+-- D == Datatype.

DT_UNKNOWN 0

Unknown datatype.

DT_STRING 1

String.

DT_SHORT 2

Short value (16 bit).

DT_FLOAT 3

Float value (32 bit).

DT_BOOLEAN 4

Boolean value.

DT_BYTE 5

Byte value (8 bit).

DT_LONG 6

Long value (32 bit).

DT_DOUBLE 7

Double precision �oat value (64 bit).

DT_LONGLONG 8

LongLong value (64 bit).


© 2015/08/19 Version 1.33




DT_ID 9

LongLong value (64 bit). Not used. DT_LONGLONG is used instead.

DT_DATE 10

Date. Meaning: YYYYMMDDhhmmsslllcccnnn....- YYYY = year, required.- MM = month, optional.- DD = day, optional.- hh = hour, optional.- mm = minute, optional.- ss = second, optional.- lll = millisec, optional, not supported by Oracle timestamp.- ccc = microse, optional, not supported by Oracle timestamp.- nnn = nanosec, optional, not supported by Oracle timestamp.

DT_BYTESTR 11

Bytestream.

DT_BLOB 12

Blob.

DT_COMPLEX 13

Complex value (32 bit each part).

DT_DCOMPLEX 14

Complex value (64 bit each part).

DS_STRING 15

String sequence.

DS_SHORT 16

Short sequence.

DS_FLOAT 17

Float sequence.

DS_BOOLEAN 18

Boolean sequene.


© 2015/08/19 Version 1.33



8.4 De�nitions of the DataType enumeration. 557

DS_BYTE 19

Byte sequence.

DS_LONG 20

Long sequence.

DS_DOUBLE 21

Double sequence.

DS_LONGLONG 22

Longlong sequence.

DS_COMPLEX 23

Complex sequence.

DS_DCOMPLEX 24

Double complex sequence.

DS_ID 25

LongLong sequence. Not used. DS_LONGLONG is used instead.

DS_DATE 26

Date sequence.

DS_BYTESTR 27

Bytestream sequence.

DT_EXTERNALREFERENCE 28

External reference.

DS_EXTERNALREFERENCE 29

Sequence of external reference.

DT_ENUM 30

The enumeration datatype.

DS_ENUM 31

The enumeration sequence datatype.


© 2015/08/19 Version 1.33




8.5 De�nitions of the ErrorCode enumeration.

The ErrorCode Enumeration

The ASAM ODS error codes.

AO_UNKNOWN_ERROR 0

Use the zero as unknown error to avoid confusing error messages if no error code has beenset.

AO_ACCESS_DENIED 1

The ODS server denied the access.

AO_BAD_OPERATION 2

A method was called which is not possible for the current state.

AO_BAD_PARAMETER 3

A parameter of wrong type or value was passed to the method. The minorCode tells whichparameter (1, 2, 3 or 4) is bad. If more than one parameter is bad, only the �rst one isreported.

AO_CONNECT_FAILED 4

The connect to a server failed. This error may occur if the server is down or currentlyunreachable.

AO_CONNECT_REFUSED 5

The connection was refused by the server. This error may occur if the presented authenticationinformation is either incorrect or incomplete. This error shall not occur if the server does notaccept any more sessions due to overload problems. See AO_SESSION_LIMIT_REACHEDfor this case.

AO_CONNECTION_LOST 6

Due to a hardware or network software problem the connection to the server was lost.

AO_DUPLICATE_BASE_ATTRIBUTE 7

Any application element may have only one base attribute of a certain type. This means itmay have only one attribute of base attribute type, that is only one NAME, only one ID, onlyone VERSION and so on.

AO_DUPLICATE_NAME 8

The implicit or explicit speci�ed name is already in use but the name is required to be unique.


© 2015/08/19 Version 1.33



8.5 De�nitions of the ErrorCode enumeration. 559

AO_DUPLICATE_VALUE 9

The attribute is marked unique in the application model. Thus duplicate values are notallowed.

AO_HAS_INSTANCES 10

The operation is not allowed for elements that have instances.

AO_HAS_REFERENCES 11

The requested operation is not permitted because the target element has references.

AO_IMPLEMENTATION_PROBLEM 12

This error is reserved for the reporting of implementation speci�c problems that are notproperly handled by the standard error de�nitions. An application should not crash if thiserror occurs but there is no way to react to this error other than reporting and ignoringit. The intend of this error is not to leave implementation speci�c errors unreported.

AO_INCOMPATIBLE_UNITS 13

The units are incompatible. No conversion rule is known.

AO_INVALID_ASAM_PATH 14

The speci�ed Asam path is invalid.

AO_INVALID_ATTRIBUTE_TYPE 15

The requested attribute type is invalid.

AO_INVALID_BASE_ELEMENT 16

The base element is invalid in this context. If this is an element of type measurement, anotherelement of this type may already exist.

AO_INVALID_BASETYPE 17

The speci�ed base type is invalid. The following basetypes are allowed:AoAnyAoAttributeMapAoEnvironmentAoFileAoLocalColumnAoLogAoMeasurementAoMeasurementQuantityAoNameMapAoParameter


© 2015/08/19 Version 1.33




AoParameterSetAoPhysicalDimensionAoQuantityAoQuantityGroupAoSubmatrixAoSubTestAoTestAoTestDeviceAoTestEquipmentAoTestEquipmentPartAoTestSequenceAoTestSequencePartAoUnitAoUnitGroupAoUnitUnderTestAoUnitUnderTestPartAoUserAoUserGroup

AO_INVALID_BUILDUP_FUNCTION 18

The speci�ed build-up function is invalid.

AO_INVALID_COLUMN 19

The speci�ed column is invalid.

AO_INVALID_COUNT 20

The speci�ed number of points is invalid (probably negative).

AO_INVALID_DATATYPE 21

The datatype is not allowed in the given context or it con�icts with an existing datatypede�nition.This error may also occur in non-typesave language bindings. To avoid this error in alllanguage bindings it is recommended to use always the de�nitions of the enumeration"DataType".

AO_INVALID_ELEMENT 22

The element is invalid in this context.

AO_INVALID_LENGTH 23

The given length is invalid. Negative length values are not allowed.

AO_INVALID_ORDINALNUMBER 24

The ordinal number is either already used or less than zero.


© 2015/08/19 Version 1.33




AO_INVALID_RELATION 25

The relation is invalid. The related elements and the base relation do not �t.

AO_INVALID_RELATION_RANGE 26

The speci�ed relation range is invalid.

AO_INVALID_RELATION_TYPE 27

This error may occur only in non-typesave language bindings. To avoid this error in alllanguage bindings it is recommended to use always the de�nitions of the enumeration "Rela-tionType".

AO_INVALID_RELATIONSHIP 28

This error may occur only in non-typesave language bindings. To avoid this error in alllanguage bindings it is recommended to use always the de�nitions of the enumeration "Rela-tionship".

AO_INVALID_SET_TYPE 29

The speci�ed set-type is invalid.

AO_INVALID_SMATLINK 30

The submatrix link is invalid. Either submatrix 1 or 2 is not speci�ed or the ordinal numberis missing when there is more than one SMatLink.

AO_INVALID_SUBMATRIX 31

The speci�ed submatrix is invalid.

AO_IS_BASE_ATTRIBUTE 32

The application attribute is already of a base attribute type. It can not be changed. If thisis required, the application attribute has to be removed from its application element andre-created. This error may occur if an application attribute derived from a base attributea. shall be overwritten by another baseattribute type.b. shall receive another datatype.c. shall receive another unique-�ag.d. shall receive another obligatory-�ag.

AO_IS_BASE_RELATION 33

Properties of base relations may not be changed.


© 2015/08/19 Version 1.33




AO_IS_MEASUREMENT_MATRIX 34

The matrix is a complex, generated matrix from a measurement not just a simple submatrix.It is only allowed to modify submatrices but not the composed measurement matrices.

AO_MATH_ERROR 35

A computation error occurred. This can be an over�ow, an under�ow or a division by zero.

AO_MISSING_APPLICATION_ELEMENT 36

A required application element is missing.

AO_MISSING_ATTRIBUTE 37

A required (obligatory) attribute is missing.

AO_MISSING_RELATION 38

A required relation is missing.

AO_MISSING_VALUE 39

An obligatory value is missing.

AO_NO_MEMORY 40

No more volatile memory available.

AO_NO_PATH_TO_ELEMENT 41

A free-�oating element was detected. No navigation path leads to this element.

AO_NOT_FOUND 42

The requested element was not found. This error occurs only in remove or rename operationsif the subject of the operation is not found. All get- and list-methods return an empty list ifthe requested item is not found.

AO_NOT_IMPLEMENTED 43

The requested method is not yet implemented. This error is not allowed to occur in a certi�edimplementation. It is intended to allow partial operational tests. during the developmentprocess.

AO_NOT_UNIQUE 44

This error occurs if the instances of a property are required to be unique.


© 2015/08/19 Version 1.33




AO_OPEN_MODE_NOT_SUPPORTED 45

The requested open mode is not supported. Valid open modes are "read" and "write". Any-thing else is rejected with this error and no session is created.

AO_SESSION_LIMIT_REACHED 46

The server does not accept any new connections. This error may occur if the server reachedthe session limit for a distinct user or the total number of sessions allowed.

AO_SESSION_NOT_ACTIVE 47

The session is no longer active. This error occurs if an attempt is made to call a method of aclosed session. This error shall not be confused with the error AO_CONNECTION_LOST.

AO_TRANSACTION_ALREADY_ACTIVE 48

There may be only one active transaction at one time. If this error occurs there is already anactive transaction. That transaction remains active in case of this error.

AO_TRANSACTION_NOT_ACTIVE 49

Write operation have to be done always in the context of a transaction. This error occurs ifno transaction is active during a write operation.

AO_HAS_BASE_RELATION 50

Base relation found. It is not allowed to modify the relationtype, -range or -ship of anapplication relation derived from a base relation.

AO_HAS_BASE_ATTRIBUTE 51

Base attribute found. It is not allowed to modify the datatype, unique- or obligatory �ag .

AO_UNKNOWN_UNIT 52

The unit is unknown.

AO_NO_SCALING_COLUMN 53

The column is no scaling column.

AO_QUERY_TYPE_INVALID 54

The server does not support the speci�ed query language type.

AO_QUERY_INVALID 55

Some error in the query string or some inconsistency between the return type of the querystring and the result type speci�ed by parameter "QueryResultType".


© 2015/08/19 Version 1.33




AO_QUERY_PROCESSING_ERROR 56

Some error occured during the execution of the query.

AO_QUERY_TIMEOUT_EXCEEDED 57

It was not possible to execute the query within the time limit set by parameter "MaxDura-tion".

AO_QUERY_INCOMPLETE 58

The execution of the query was not yet completed.

AO_QUERY_INVALID_RESULTTYPE 59

The requested result type of the query does no match with the previous de�nition of the resulttype.

AO_INVALID_VALUEMATRIX_STRUCTURE 60

The server is unable to create the valuematrix due to the data of the measurement- if there is no independent column- if there are di�erent independent columns- if there are submatrices with more than one independentcolumn.- ..

AO_FILE_LOCKED 61

The kind of access to a managed �le that was requested cannot be granted, as the �le iscurrently in use by another read or write transfer through the OO-API.

AO_SYSTEM_PROBLEM 62

The ODS server detected a problem while accessing operating system ressources (e.g. thespeci�ed �le does not exist, the drive is currently not available, ...).

8.6 De�nitions of the JoinType enumeration.

The JoinType Enumeration

The type of the join.

JTDEFAULT 0

Force inner join.

JTOUTER 1

Force outer join on destination AID.


© 2015/08/19 Version 1.33



8.7 De�nitions of the QueryStatus enumeration. 565

8.7 De�nitions of the QueryStatus enumeration.

The QueryStatus Enumeration

Status of the query execution.

COMPLETE 0

The execution is ready.

INCOMPLETE 1

The execution is still running.

8.8 De�nitions of the Relationship enumeration.

The Relationship Enumeration

The ASAM ODS relationships.

FATHER 0

Father.

CHILD 1

Child.

INFO_TO 2

Directed informational relationship.

INFO_FROM 3

Directed informational relationship.

INFO_REL 4

Informational relationship (no direction)

SUPERTYPE 5

Inheritance relationship: supertype.

SUBTYPE 6

Inheritance relationship: subtype.

ALL_REL 7

Any of the relationships above.


© 2015/08/19 Version 1.33




8.9 De�nitions of the RelationType enumeration.

The RelationType Enumeration

The ASAM ODS relation types.

FATHER_CHILD 0

Father-child relation.

INFO 1

Info relation.

INHERITANCE 2

Inheritance relation.

8.10 De�nitions of the RightsSet enumeration.

The RightsSet Enumeration

The ASAM ODS types for setting access rights.

SET_RIGHT 0

Set the given rights, overwrite the existing rights.

ADD_RIGHT 1

Add the given rights to the existing rights.

REMOVE_RIGHT 2

Remove the given rights form the existing rights.

8.11 De�nitions of the SelOpcode enumeration.

The SelOpcode Enumeration

The selection operators. SelOpcode gives query instructions like "equal", "greater" etc. Sofar, these arguments were case sensitive. There was a demand to add these arguments alsofor case insensitive comparison operations. Therefore, the SelOpcodes for case insensitivitywere added. These arguments have the pre�x CI_.

EQ 0

Equal


© 2015/08/19 Version 1.33



8.11 De�nitions of the SelOpcode enumeration. 567

NEQ 1

Not equal

LT 2

Less then

GT 3

Greater then

LTE 4

Less then equal

GTE 5

Greater then equal

INSET 6

In set, value can be a sequence.

NOTINSET 7

Not in set, value can be a sequence.

LIKE 8

like, use pattern matching, see Pattern for the wildcard de�nitions.

CI_EQ 9

Equal. case insensitive for DT_STRING.

CI_NEQ 10

Not equal. case insensitive for DT_STRING.

CI_LT 11

Less then. case insensitive for DT_STRING.

CI_GT 12

Greater then. case insensitive for DT_STRING.


© 2015/08/19 Version 1.33




CI_LTE 13

Less then equal. case insensitive for DT_STRING.

CI_GTE 14

Greater then equal. case insensitive for DT_STRING.

CI_INSET 15

In set, value can be a sequence. case insensitive for DT_STRING.

CI_NOTINSET 16

Not in set, value can be a sequence. case insensitive for DT_STRING.

CI_LIKE 17

like, use pattern matching, see Pattern for the wildcard de�nitions. case insensitive for DT_-STRING.

IS_NULL 18

Value is NULL

IS_NOT_NULL 19

Value is not NULL

NOTLIKE 20

Not LIKE

CI_NOTLIKE 21

Not LIKE, case insensitive for DT_STRING.

BETWEEN 22

Between; selects all instances where the value of 'attr' lies between the �rst two values givenin 'value' (with 'attr', 'value' being elements of the SelValue structure; 'value' must be of datatype S_∗).

8.12 De�nitions of the SelOperator enumeration.

The SelOperator Enumeration

Operator, bracket open and close.


© 2015/08/19 Version 1.33



8.13 De�nitions of the SelType enumeration. 569

AND 0

AND the two conditions.

OR 1

OR the two conditions.

NOT 2

Negate the next condition.

OPEN 3

Open brackets.

CLOSE 4

Close brackets

8.13 De�nitions of the SelType enumeration.

The SelType Enumeration

The selection type.

SEL_VALUE_TYPE 0

Selection value.

SEL_OPERATOR_TYPE 1

Selection logical operator.

8.14 De�nitions of the SetType enumeration.

The SetType Enumeration

The ASAM ODS types for setting values.

APPEND 0

Append data to the value matrix.

INSERT 1

Insert data into the value matrix.

UPDATE 2

Modify existing data of the value matrix.

REMOVE 3

Remove the given information.


© 2015/08/19 Version 1.33




8.15 De�nitions of the SeverityFlag enumeration.

The SeverityFlag Enumeration

The ASAM ODS error severity �ags.

SUCCESS 0

Ok.

INFORMATION 1

Information.

WARNING 2

Warning.

ERROR 3

Error.

8.16 De�nitions of the ValueMatrixMode enumeration.

The ValueMatrixMode Enumeration

The mode of the value matrix.

CALCULATED 0

The value matrix returns the calculated values.The values of explicit columns are returned as they are stored in the physical storage.The values of implicit columns are expanded and returned explicitly.The values of raw columns are calculated according to the corresponding algorithm (using thecalculation algorithms given by the values of the application attributes derived from the baseattributes 'sequence_representation' and 'generation_parameters') and the resulting physicalvalues are returned.Writing to the value matrix is not allowed in this mode.

STORAGE 1

The value matrix returns the values given in the physical storage.The values of explicit columns are returned as they are stored in the physical storage.The values of implicit columns are expanded and returned explicitly.The values of raw columns are returned as they are stored (without using the calculationalgorithms given by the values of the application attributes derived from the base attributes'sequence_representation' and 'generation_parameters').Writing to value matrix is allowed in this mode.


© 2015/08/19 Version 1.33



Chapter 9

ASAM ODS Constants

9.1 De�nitions of the LockMode constant.

The LockMode Constant

The lock mode of the server. The lock mode tells the way the server will lock the objects assoon as a modi�cation of the server will be done.

LOCK_INSTANCEELEMENT

is of datatype T_SHORT with value 0

Lock the instance element. (Default LockMode)

LOCK_APPLICATIONELEMENT


Lock the application element, all instances of the application element are locked.

LOCK_CHILDREN


Lock the children of the locked object. This mode can be combined with one of the uppertwo modi.

9.2 De�nitions of the ODSReadTransfer constant.

The ODSReadTransfer Interface

The interface which supports a read transfer (from the ODS server to a client) of the contentof a �le that is under control of the ODS server.

READALL

is of datatype T_LONG with value -1

572 ASAM ODS Constants

Read all bytes of the �le.

9.3 De�nitions of the QueryConstants constant.

The QueryConstants Constant

The ASAM ODS query constants.

MaxDurationDEFAULT

is of datatype T_LONG with value 0

Default value of max duration parameter of the query (no limitations).

MaxDuration

is of datatype T_STRING with value "MaxDuration"

The ASAM ODS max duration parameter of the query.

QueryResultType

is of datatype T_STRING with value "QueryResultType"

The ASAM ODS query result type parameter.

QueryResultTypeDEFAULT

is of datatype T_LONG with value ResultType::INSTELEM_ITERATOR_AS_RESULT

Default value of the ASAM ODS query result type parameter.

9.4 De�nitions of the ResultType constant.

The ResultType Constant

The ASAM ODS query result types.

INSTELEM_ITERATOR_AS_RESULT


Iterator of instance elements as result of the query (the default).

TABLE_ITERATOR_AS_RESULT



© 2015/08/19 Version 1.33



9.5 De�nitions of the SecurityLevel constant. 573

Iterator for table access as result type of the query.

TABLE_AS_RESULT


Table as result type of the query.

9.5 De�nitions of the SecurityLevel constant.

The SecurityLevel Constant

The security level of an application element.

NO_SECURITY


No security de�ned.

ELEMENT_SECURITY


Security scaled for the application element.

INSTANCE_SECURITY


Security scaled for instance elements.

ATTRIBUTE_SECURITY


Security scaled for appliation attributes.

9.6 De�nitions of the SecurityRights constant.

The SecurityRights Constant

The bits of the security rights.

SEC_READ



© 2015/08/19 Version 1.33



574 ASAM ODS Constants

Read access is allowed.

SEC_UPDATE


Update access to an existing object is allowed.

SEC_INSERT


Creating new instances is allowed.

SEC_DELETE


Delete of the object is allowed.

SEC_GRANT


Access rights may be passed on.


© 2015/08/19 Version 1.33



Chapter 10

ASAM ODS Types

10.1 De�nition of the CORBA types.

The CORBA types are part of the Corba speci�cation and used by the ASAM ODS. There areno other Corba datatypes used by ASAM ODS.

string

The corba string.

boolean

The corba boolean.

octet

The corba 8 bit signed integer.

short


long


�oat

The corba 32 bit IEEE-Floating point number.

double

The corba 64 bit IEEE-Floating point number.

576 ASAM ODS Types

10.2 De�nitions of the Scalar type.

The Scalar type

BaseType

is of datatype T_STRING

The base types of the elements, these base types are the names of the base elements in thebase model.

Name


A NUL-Terminated string representing a name of an entity.

Pattern


Wildcard character for one character is '?'. Wildcard character for more the one character is'∗'. The Wildcard charachter used as escape character is '\'.

T_BLOB

is of datatype Blob

The blob type de�nition. There is a special interface available for the access to valriables ofthis type. This type is represented in the datatype enumeration by DT_BLOB.

T_BOOLEAN

is of datatype boolean

The boolean type with the values false or true. This type is represented in the datatypeenumeration by DT_BOOLEAN.

T_BYTE

is of datatype octet

A 1 Byte signed interger number. This type is represented in the datatype enumeration byDT_BYTE.


© 2015/08/19 Version 1.33



10.2 De�nitions of the Scalar type. 577

T_DATE


A NUL-terminated string with �xed date-format information. This type is represented in thedatatype enumeration by DT_DATE.

T_DOUBLE

is of datatype double

A 8 Byte �oating point number. This type is represented in the datatype enumeration byDT_DOUBLE.

T_FLOAT

is of datatype �oat

A 4 Byte �oating point number. This type is represented in the datatype enumeration byDT_FLOAT.

T_LONG

is of datatype long

A 4 Byte signed interger number. This type is represented in the datatype enumeration byDT_LONG.

T_SHORT

is of datatype short

A 2 Byte signed interger number. This type is represented in the datatype enumeration byDT_SHORT.

T_STRING

is of datatype string

A NUL-Terminated string. This type is represented in the datatype enumeration by DT_-STRING.


© 2015/08/19 Version 1.33



578 ASAM ODS Types

10.3 De�nitions of the Sequence type.

The Sequence type

ACLSequence

is of datatype ACL

The sequence of access control list entries for a requested object.

AIDNameSequence

is of datatype AIDName

Sequence of AID - Name pairs.

AIDNameUnitIdSequence

is of datatype AIDNameUnitId

Sequence of AID - Name - UnitId tuple.

AIDNameValueSeqUnitIdSequence

is of datatype AIDNameValueSeqUnitId

Sequence of AID - Name - UnitId tuple.

ApplAttrSequence

is of datatype ApplAttr

Sequence of ApplAttr.

ApplElemSequence

is of datatype ApplElem

Application element de�nition sequence. The application elements are given with the methodgetElements() at the interface ApplicationStructure.

ApplicationAttributeSequence

is of datatype ApplicationAttribute


© 2015/08/19 Version 1.33



10.3 De�nitions of the Sequence type. 579

Seqeucne of ApplicationAttribute objects.

ApplicationElementSequence

is of datatype ApplicationElement

Sequence of ApplicationElement objects.

ApplicationRelationInstanceElementSeqSequence

is of datatype ApplicationRelationInstanceElementSeq

Sequence of the application relation with corresponding instances.

ApplicationRelationSequence

is of datatype ApplicationRelation

Sequence of ApplicationRelation objects.

ApplRelSequence

is of datatype ApplRel

Application relation sequence. The application relations are given with the method getRela-tions() at the interface ApplicationStructure.

AttrResultSetSequence

is of datatype AttrResultSet

Sequence of the attribute result sets.

BaseAttributeSequence

is of datatype BaseAttribute

Sequence of BaseAttribute objects.

BaseElementSequence

is of datatype BaseElement


© 2015/08/19 Version 1.33



580 ASAM ODS Types

Sequence of BaseElement objects.

BaseRelationSequence

is of datatype BaseRelation

Sequence of BaseRelation objects.

BaseTypeSequence

is of datatype BaseType

Sequence of BaseType.

ColumnSequence

is of datatype Column

Sequence of Column objects.

ElemIdSequence

is of datatype ElemId

Sequence of element Id's.

ElemResultSetExtSequence

is of datatype ElemResultSetExt

Sequence of ElemResultSetExt

ElemResultSetSequence

is of datatype ElemResultSet

Sequence of the element result sets.

EnumerationAttributeStructureSequence

is of datatype EnumerationAttributeStructure

Sequence of the attribute and enuemration correlation.


© 2015/08/19 Version 1.33




EnumerationItemStructureSequence

is of datatype EnumerationItemStructure

Sequence with the enumeration items.

EnumerationStructureSequence

is of datatype EnumerationStructure

Sequence of the enumerations.

InitialRightSequence

is of datatype InitialRight

The sequence of the initial rights.

InstanceElementSequence

is of datatype InstanceElement

Sequence of InstanceElement objects.

JoinDefSequence

is of datatype JoinDef

Sequence of the join de�nitions.

NameSequence

is of datatype Name

Sequence of Name.

NameValueSequence

is of datatype NameValue

Sequence of NameValue-pairs.

NameValueSeqUnitIdSequence

is of datatype NameValueSeqUnitId


© 2015/08/19 Version 1.33



582 ASAM ODS Types

Sequence of NameValueSeqUnitId-triple.

NameValueSeqUnitSequence

is of datatype NameValueSeqUnit

Sequence of NameValueSeqUnit-triple.

NameValueUnitSequence

is of datatype NameValueUnit

Sequence of NameValueUnit-triple.

ResultSetExtSequence

is of datatype ResultSetExt

The sequence of result set of the extende query, for each application element a result set.

S_BLOB

is of datatype T_BLOB

Sequence of blob objects. This type is represented in the datatype enumeration by DS_BLOB.

S_BOOLEAN

is of datatype T_BOOLEAN

Sequence of boolean values. This type is represented in the datatype enumeration by DS_-BOOLEAN.

S_BYTE

is of datatype T_BYTE

Sequence of byte values. This type is represented in the datatype enumeration by DS_BYTE.

S_BYTESTR

is of datatype T_BYTESTR


© 2015/08/19 Version 1.33




Sequence of byte value sequences. This type is represented in the datatype enumeration byDS_BYTESTR.

S_COMPLEX

is of datatype T_COMPLEX

Sequence of �oat complex values. This type is represented in the datatype enumeration byDS_COMPLEX.

S_DATE

is of datatype T_DATE

Sequence of date values. This type is represented in the datatype enumeration by DS_DATE.

S_DCOMPLEX

is of datatype T_DCOMPLEX

Sequence of double complex values. This type is represented in the datatype enumeration byDS_DCOMPLEX.

S_DOUBLE

is of datatype T_DOUBLE

Sequence of double values. This type is represented in the datatype enumeration by DS_-DOUBLE.

S_ExternalReference

is of datatype T_ExternalReference

Sequence of external references. This type is represented in the datatype enumeration byDS_EXTERNALREFERENCE.

S_FLOAT

is of datatype T_FLOAT

Sequence of �oat values. This type is represented in the datatype enumeration by DS_-FLOAT.


© 2015/08/19 Version 1.33



584 ASAM ODS Types

S_LONG

is of datatype T_LONG

Sequence of long values. This type is represented in the datatype enumeration by DS_LONG.

S_LONGLONG

is of datatype T_LONGLONG

Sequence of LongLong values. This type is represented in the datatype enumeration by DS_-LONGLONG.

S_SHORT

is of datatype T_SHORT

Sequence of short values. This type is represented in the datatype enumeration by DS_-SHORT.

S_STRING


Sequence of string values. This type is represented in the datatype enumeration by DS_-STRING.

SelAIDNameUnitIdSequence

is of datatype SelAIDNameUnitId

Sequence of selected attributes.

SelItemSequence

is of datatype SelItem

The sequence of selection items.

SelOperatorSequence

is of datatype SelOperator

Sequence of select operator.


© 2015/08/19 Version 1.33




SelOrderSequence

is of datatype SelOrder

The sequence of order criteria. The �rst criteria is the importance criteria.

SelValueSequence

is of datatype SelValue

Sequence of attribute search conditions.

SMatLinkSequence

is of datatype SMatLink

Sequence of SMatLink objects.

SS_BOOLEAN

is of datatype S_BOOLEAN

Sequence of boolean sequence.

SS_BYTE

is of datatype S_BYTE

Sequence of octet sequence.

SS_BYTESTR

is of datatype S_BYTESTR

Sequence of bytestream sequence.

SS_COMPLEX

is of datatype S_COMPLEX

Sequence of �oat complex sequence.


© 2015/08/19 Version 1.33



586 ASAM ODS Types

SS_DATE

is of datatype S_DATE

Sequence of date sequence.

SS_DCOMPLEX

is of datatype S_DCOMPLEX

Sequence of double complex sequence.

SS_DOUBLE

is of datatype S_DOUBLE

Sequence of double sequence.

SS_ExternalReference

is of datatype S_ExternalReference

Sequence of external reference sequence.

SS_FLOAT

is of datatype S_FLOAT

Sequence of �oat sequence.

SS_LONG

is of datatype S_LONG

Sequence of long sequence.

SS_LONGLONG

is of datatype S_LONGLONG

Sequence of longlong sequence.


© 2015/08/19 Version 1.33




SS_SHORT

is of datatype S_SHORT

Sequence of short sequence.

SS_STRING

is of datatype S_STRING

Sequence of sting sequence.

SubMatrixSequence

is of datatype SubMatrix

Sequence of SubMatrix objects.

T_BYTESTR

is of datatype T_BYTE

Sequence of byte values. This type is represented in the datatype enumeration by DT_-BYTESTR.


© 2015/08/19 Version 1.33



Chapter 11

ASAM ODS Exceptions

11.1 AoException

The ASAM ODS API knows only one kind of exception the AoException. The di�erent errors aregiven the �eld errCode of the exception, the explanation of the errors are given in De�nitionsof the ErrorCode enumeration. (p. 558). The severity of the exception is given in the �eldsevFlag, the explation of the severity �ag is given inDe�nitions of the SeverityFlag enumer-ation. (p. 570). The minor code is an integer and given in the �eld minorCode. The minorCodeis the Athos error code, for a detail description of the error look at the technical reference sheet.The reason of the error is given in the �eld reason. The reason is the error code as a text andthe description and parameter of the error from Athos.

ErrorCode errCode

The code of the detected error.

SeverityFlag sevFlag

The severity of the error.

T_LONG minorCode

The minor code for a more detailed error analysis.

T_STRING reason

The reason of the error.

Chapter 12

ASAM ODS Interface Short

Reference

Interface: AoFactory

� T_STRING getDescription ();

� T_STRING getInterfaceVersion ();

� T_STRING getName ();

� T_STRING getType ();

� AoSession newSession (T_STRING auth);

� AoSession newSessionNameValue (NameValueSequence auth);

Interface: AoSession

� void abortTransaction ();

� void close ();

� void commitTransaction ();

� Blob createBlob ();

� AoSession createCoSession ();

� QueryEvaluator createQueryEvaluator ();

� void �ush ();

� ApplElemAccess getApplElemAccess ();

� ApplicationStructure getApplicationStructure ();

� ApplicationStructureValue getApplicationStructureValue ();

� BaseStructure getBaseStructure ();

� NameValueIterator getContext (Pattern varPattern);

592 ASAM ODS Interface Short Reference

� NameValue getContextByName (Name varName);

� T_STRING getDescription ();

� EnumerationAttributeStructureSequence getEnumerationAttributes ();

� EnumerationStructureSequence getEnumerationStructure ();

� T_LONG getId ();

� T_SHORT getLockMode ();

� Name getName ();

� T_STRING getType ();

� InstanceElement getUser ();

� NameIterator listContext (Pattern varPattern);

� void removeContext (Pattern varPattern);

� void setContext (NameValue contextVariable);

� void setContextString (Name varName, T_STRING value);

� void setCurrentInitialRights (InitialRightSequence irlEntries, T_BOOLEAN set);

� void setLockMode (T_SHORT lockMode);

� void setPassword (T_STRING username, T_STRING oldPassword, T_STRING newPass-word);

� void startTransaction ();

Interface: ApplElemAccess

� void deleteInstances (T_LONGLONG aid, S_LONGLONG instIds);

� ACLSequence getAttributeRights (T_LONGLONG aid, T_STRING attrName);

� InitialRightSequence getElementInitialRights (T_LONGLONG aid);

� ACLSequence getElementRights (T_LONGLONG aid);

� NameSequence getInitialRightReference (T_LONGLONG aid);

� InitialRightSequence getInstanceInitialRights (T_LONGLONG aid, T_LONGLONG iid);

� ACLSequence getInstanceRights (T_LONGLONG aid, T_LONGLONG iid);

� ElemResultSetSequence getInstances (QueryStructure aoq, T_LONG how_many);

� ResultSetExtSequence getInstancesExt (QueryStructureExt aoq, T_LONG how_many);

� ODSFile getODSFile (ElemId elem);

� S_LONGLONG getRelInst (ElemId elem, Name relName);

� S_LONGLONG getRelInst (ElemId elem, Name relName);

� ValueMatrix getValueMatrix (ElemId elem);

� ValueMatrix getValueMatrixInMode (ElemId elem, ValueMatrixMode vmMode);


© 2015/08/19 Version 1.33



593

� ElemIdSequence insertInstances (AIDNameValueSeqUnitIdSequence val);

� void setAttributeRights (T_LONGLONG aid, T_STRING attrName, T_LONGLONGusergroupId, T_LONG rights, RightsSet set);

� void setElementInitialRights (T_LONGLONG aid, T_LONGLONG usergroupId, T_-LONG rights, T_LONGLONG refAid, RightsSet set);

� void setElementRights (T_LONGLONG aid, T_LONGLONG usergroupId, T_LONGrights, RightsSet set);

� void setInitialRightReference (T_LONGLONG aid, T_STRING refName, RightsSet set);

� void setInstanceInitialRights (T_LONGLONG aid, S_LONGLONG instIds, T_-LONGLONG usergroupId, T_LONG rights, T_LONGLONG refAid, RightsSet set);

� void setInstanceRights (T_LONGLONG aid, S_LONGLONG instIds, T_LONGLONGusergroupId, T_LONG rights, RightsSet set);

� void setRelInst (ElemId elem, Name relName, S_LONGLONG instIds, SetType type);

� void updateInstances (AIDNameValueSeqUnitIdSequence val);

Interface: ApplicationAttribute

� ApplicationElement getApplicationElement ();

� BaseAttribute getBaseAttribute ();

� DataType getDataType ();

� EnumerationDe�nition getEnumerationDe�nition ();

� T_LONG getLength ();


� ACLSequence getRights ();

� T_LONGLONG getUnit ();

� T_BOOLEAN hasUnit ();

� T_BOOLEAN hasValueFlag ();

� T_BOOLEAN isAutogenerated ();

� T_BOOLEAN isObligatory ();

� T_BOOLEAN isUnique ();

� void setBaseAttribute (BaseAttribute baseAttr);

� void setDataType (DataType aaDataType);

� void setEnumerationDe�nition (EnumerationDe�nition enumDef);

� void setIsAutogenerated (T_BOOLEAN isAutogenerated);

� void setIsObligatory (T_BOOLEAN aaIsObligatory);

� void setIsUnique (T_BOOLEAN aaIsUnique);


© 2015/08/19 Version 1.33




� void setLength (T_LONG aaLength);

� void setName (Name aaName);

� void setRights (InstanceElement usergroup, T_LONG rights, RightsSet set);

� void setUnit (T_LONGLONG aaUnit);

� void withUnit (T_BOOLEAN withUnit);

� void withValueFlag (T_BOOLEAN withValueFlag);

Interface: ApplicationElement

� ApplicationAttribute createAttribute ();

� InstanceElement createInstance (Name ieName);

� InstanceElementSequence createInstances (NameValueSeqUnitSequence attributes, Applica-tionRelationInstanceElementSeqSequence relatedInstances);

� ApplicationElementSequence getAllRelatedElements ();

� ApplicationRelationSequence getAllRelations ();

� ApplicationStructure getApplicationStructure ();

� ApplicationAttribute getAttributeByBaseName (Name baName);

� ApplicationAttribute getAttributeByName (Name aaName);

� ApplicationAttributeSequence getAttributes (Pattern aaPattern);

� BaseElement getBaseElement ();

� T_LONGLONG getId ();

� ApplicationRelationSequence getInitialRightRelations ();

� InitialRightSequence getInitialRights ();

� InstanceElement getInstanceById (T_LONGLONG ieId);

� InstanceElement getInstanceByName (Name ieName);

� InstanceElementIterator getInstances (Pattern iePattern);


� ApplicationElementSequence getRelatedElementsByRelationship (Relationship aeRelation-ship);

� ApplicationRelationSequence getRelationsByBaseName (Name baseRelName);

� ApplicationRelationSequence getRelationsByType (RelationType aeRelationType);


� T_LONG getSecurityLevel ();

� NameSequence listAllRelatedElements ();

� NameSequence listAttributes (Pattern aaPattern);


© 2015/08/19 Version 1.33



595

� NameIterator listInstances (Pattern aaPattern);

� NameSequence listRelatedElementsByRelationship (Relationship aeRelationship);

� void removeAttribute (ApplicationAttribute applAttr);

� void removeInstance (T_LONGLONG ieId, T_BOOLEAN recursive);

� void setBaseElement (BaseElement baseElem);

� void setInitialRightRelation (ApplicationRelation applRel, T_BOOLEAN set);

� void setInitialRights (InstanceElement usergroup, T_LONG rights, T_LONGLONG refAid,RightsSet set);

� void setName (Name aeName);


� void setSecurityLevel (T_LONG secLevel, RightsSet set);

Interface: ApplicationRelation

� BaseRelation getBaseRelation ();

� ApplicationElement getElem1 ();

� ApplicationElement getElem2 ();

� Name getInverseRelationName ();

� RelationRange getInverseRelationRange ();

� Relationship getInverseRelationship ();

� Name getRelationName ();

� RelationRange getRelationRange ();

� Relationship getRelationship ();

� RelationType getRelationType ();

� void setBaseRelation (BaseRelation baseRel);

� void setElem1 (ApplicationElement applElem);

� void setElem2 (ApplicationElement applElem);

� void setInverseRelationName (Name arInvName);

� void setInverseRelationRange (RelationRange arRelationRange);

� void setRelationName (Name arName);

� void setRelationRange (RelationRange arRelationRange);

� void setRelationType (RelationType arRelationType);

Interface: ApplicationStructure

� void check ();


© 2015/08/19 Version 1.33




� ApplicationElement createElement (BaseElement baseElem);

� EnumerationDe�nition createEnumerationDe�nition (T_STRING enumName);

� void createInstanceRelations (ApplicationRelation applRel, InstanceElementSequence elem-List1, InstanceElementSequence elemList2);

� ApplicationRelation createRelation ();

� ApplicationElement getElementById (T_LONGLONG aeId);

� ApplicationElement getElementByName (Name aeName);

� ApplicationElementSequence getElements (Pattern aePattern);

� ApplicationElementSequence getElementsByBaseType (BaseType aeType);

� EnumerationDe�nition getEnumerationDe�nition (T_STRING enumName);

� InstanceElement getInstanceByAsamPath (Name asamPath);

� InstanceElementSequence getInstancesById (ElemIdSequence ieIds);

� ApplicationRelationSequence getRelations (ApplicationElement applElem1, ApplicationEle-ment applElem2);

� AoSession getSession ();

� ApplicationElementSequence getTopLevelElements (BaseType aeType);

� NameSequence listElements (Pattern aePattern);

� NameSequence listElementsByBaseType (BaseType aeType);

� NameSequence listEnumerations ();

� NameSequence listTopLevelElements (BaseType aeType);

� void removeElement (ApplicationElement applElem);

� void removeEnumerationDe�nition (T_STRING enumName);

� void removeRelation (ApplicationRelation applRel);

Interface: BaseAttribute

� BaseElement getBaseElement ();


� EnumerationDe�nition getEnumerationDe�nition ();


� T_BOOLEAN isObligatory ();

� T_BOOLEAN isUnique ();

Interface: BaseElement

� BaseRelationSequence getAllRelations ();


© 2015/08/19 Version 1.33



597

� BaseAttributeSequence getAttributes (Pattern baPattern);

� BaseElementSequence getRelatedElementsByRelationship (Relationship brRelationship);

� BaseRelationSequence getRelationsByType (RelationType brRelationType);

� BaseType getType ();

� T_BOOLEAN isTopLevel ();

� NameSequence listAttributes (Pattern baPattern);

� BaseTypeSequence listRelatedElementsByRelationship (Relationship brRelationship);

Interface: BaseRelation

� BaseElement getElem1 ();

� BaseElement getElem2 ();

� Name getInverseRelationName ();

� RelationRange getInverseRelationRange ();

� Relationship getInverseRelationship ();

� Name getRelationName ();

� RelationRange getRelationRange ();

� Relationship getRelationship ();

� RelationType getRelationType ();

Interface: BaseStructure

� BaseElement getElementByType (BaseType beType);

� BaseElementSequence getElements (Pattern bePattern);

� BaseRelation getRelation (BaseElement elem1, BaseElement elem2);

� BaseRelationSequence getRelations (BaseElement elem1, BaseElement elem2);

� BaseElementSequence getTopLevelElements (Pattern bePattern);

� T_STRING getVersion ();

� BaseTypeSequence listElements (Pattern bePattern);

� BaseTypeSequence listTopLevelElements (Pattern bePattern);

Interface: Blob

� void append (S_BYTE value);

� T_BOOLEAN compare (T_BLOB aBlob);

� void destroy ();

� S_BYTE get (T_LONG o�set, T_LONG length);


© 2015/08/19 Version 1.33




� T_STRING getHeader ();

� T_LONG getLength ();

� void set (S_BYTE value);

� void setHeader (T_STRING header);

Interface: Column



� T_STRING getFormula ();

� TS_Union getGenerationParameters ();


� DataType getRawDataType ();

� T_LONG getSequenceRepresentation ();

� InstanceElement getSourceMQ ();

� T_STRING getUnit ();

� T_BOOLEAN isIndependent ();

� T_BOOLEAN isScaling ();

� void setFormula (T_STRING formula);

� void setGenerationParameters (TS_Union generationParameters);

� void setIndependent (T_BOOLEAN independent);

� void setScaling (T_BOOLEAN scaling);

� void setSequenceRepresentation (T_LONG sequenceRepresentation);

� void setUnit (T_STRING unit);

Interface: ElemResultSetExtSeqIterator


� T_LONG getCount ();

� ElemResultSetExtSequence nextN (T_LONG how_many);

� ElemResultSetExt nextOne ();

� void reset ();

Interface: EnumerationDe�nition

� void addItem (T_STRING itemName);

� T_LONG getIndex ();


© 2015/08/19 Version 1.33



599

� T_LONG getItem (T_STRING itemName);

� T_STRING getItemName (T_LONG item);

� T_STRING getName ();

� NameSequence listItemNames ();

� void renameItem (T_STRING oldItemName, T_STRING newItemName);

� void setName (T_STRING enumName);

Interface: InstanceElement

� void addInstanceAttribute (NameValueUnit instAttr);

� T_LONGLONG compare (InstanceElement compIeObj);

� InstanceElementSequence createRelatedInstances (ApplicationRelation applRel, NameVal-ueSeqUnitSequence attributes, ApplicationRelationInstanceElementSeqSequence relatedIn-stances);

� void createRelation (ApplicationRelation relation, InstanceElement instElem);

� InstanceElement deepCopy (T_STRING newName, T_STRING newVersion);


� ApplicationElement getApplicationElement ();

� Name getAsamPath ();

� T_LONGLONG getId ();

� InitialRightSequence getInitialRights ();


� InstanceElementIterator getRelatedInstances (ApplicationRelation applRel, Pattern iePat-tern);

� InstanceElementIterator getRelatedInstancesByRelationship (Relationship ieRelationship,Pattern iePattern);


� NameValueUnit getValue (Name attrName);

� NameValueUnit getValueByBaseName (Name baseAttrName);

� NameValueUnit getValueInUnit (NameUnit attr);

� NameValueUnitSequence getValueSeq (NameSequence attrNames);

� NameSequence listAttributes (Pattern iaPattern, AttrType aType);

� NameIterator listRelatedInstances (ApplicationRelation ieRelation, Pattern iePattern);

� NameIterator listRelatedInstancesByRelationship (Relationship ieRelationship, PatterniePattern);

� void removeInstanceAttribute (Name attrName);


© 2015/08/19 Version 1.33




� void removeRelation (ApplicationRelation applRel, InstanceElement instElem_nm);

� void renameInstanceAttribute (Name oldName, Name newName);

� void setInitialRights (InstanceElement usergroup, T_LONG rights, T_LONGLONG refAid,RightsSet set);

� void setName (Name iaName);


� void setValue (NameValueUnit value);

� void setValueSeq (NameValueUnitSequence values);

� InstanceElement shallowCopy (T_STRING newName, T_STRING newVersion);

� Measurement upcastMeasurement ();

� ODSFile upcastODSFile ();

� SubMatrix upcastSubMatrix ();

Interface: InstanceElementIterator



� InstanceElementSequence nextN (T_LONG how_many);

� InstanceElement nextOne ();

� void reset ();

Interface: Measurement

� SMatLink createSMatLink ();

� SMatLinkSequence getSMatLinks ();

� ValueMatrix getValueMatrix ();

� ValueMatrix getValueMatrixInMode (ValueMatrixMode vmMode);

� void removeSMatLink (SMatLink smLink);

Interface: NameIterator



� NameSequence nextN (T_LONG how_many);

� Name nextOne ();

� void reset ();

Interface: NameValueIterator


© 2015/08/19 Version 1.33



601



� NameValueSequence nextN (T_LONG how_many);

� NameValue nextOne ();

� void reset ();

Interface: NameValueUnitIdIterator



� NameValueSeqUnitId nextN (T_LONG how_many);

� NameValueUnitId nextOne ();

� void reset ();

Interface: NameValueUnitIterator



� NameValueUnitSequence nextN (T_LONG how_many);

� NameValueUnit nextOne ();

� void reset ();

Interface: NameValueUnitSequenceIterator



� NameValueSeqUnitSequence nextN (T_LONG how_many);

� NameValueSeqUnit nextOne ();

� void reset ();

Interface: ODSFile

� ODSWriteTransfer append ();

� T_BOOLEAN canRead ();

� T_BOOLEAN canWrite ();

� ODSWriteTransfer create ();

� T_BOOLEAN exists ();

� T_DATE getDate ();


© 2015/08/19 Version 1.33




� T_LONGLONG getSize ();

� ODSReadTransfer read ();

� void remove ();

� void removeFromControl (T_STRING targetUrl);

� void takeUnderControl (T_STRING sourceUrl);

Interface: ODSReadTransfer

� void close ();

� S_BYTE getOctetSeq (T_LONG maxOctets);

� T_LONGLONG getPosition ();

� T_LONGLONG skipOctets (T_LONGLONG numOctets);

Interface: ODSWriteTransfer

� void close ();

� T_LONGLONG getPosition ();

� void putOctectSeq (S_BYTE bu�er);

Interface: Query

� void executeQuery (NameValueSequence params);

� InstanceElementIterator getInstances ();

� QueryEvaluator getQueryEvaluator ();

� QueryStatus getStatus ();

� NameValueSeqUnitSequence getTable ();

� NameValueUnitSequenceIterator getTableRows ();

� void prepareQuery (NameValueSequence params);

Interface: QueryEvaluator

� Query createQuery (T_STRING queryStr, NameValueSequence params);

� InstanceElementIterator getInstances (T_STRING queryStr, NameValueSequence params);

� NameValueSeqUnitSequence getTable (T_STRING queryStr, NameValueSequence params);

� NameValueUnitSequenceIterator getTableRows (T_STRING queryStr, NameValueSequenceparams);

Interface: SMatLink

� BuildUpFunction getLinkType ();


© 2015/08/19 Version 1.33



603

� T_LONG getOrdinalNumber ();

� SubMatrix getSMat1 ();

� ColumnSequence getSMat1Columns ();

� SubMatrix getSMat2 ();

� ColumnSequence getSMat2Columns ();

� void setLinkType (BuildUpFunction linkType);

� void setOrdinalNumber (T_LONG ordinalNumber);

� void setSMat1 (SubMatrix subMat1);

� void setSMat1Columns (ColumnSequence columns);

� void setSMat2 (SubMatrix subMat2);

� void setSMat2Columns (ColumnSequence columns);

Interface: SubMatrix

� ColumnSequence getColumns (Pattern colPattern);

� ValueMatrix getValueMatrix ();

� ValueMatrix getValueMatrixInMode (ValueMatrixMode vmMode);

� NameSequence listColumns (Pattern colPattern);

Interface: ValueMatrix

� Column addColumn (NameUnit newColumn);

� Column addColumnScaledBy (NameUnit newColumn, Column scalingColumn);


� T_LONG getColumnCount ();

� ColumnSequence getColumns (Pattern colPattern);

� ColumnSequence getColumnsScaledBy (Column scalingColumn);

� ColumnSequence getIndependentColumns (Pattern colPattern);

� ValueMatrixMode getMode ();

� T_LONG getRowCount ();

� ColumnSequence getScalingColumns (Pattern colPattern);

� NameValueSeqUnitSequence getValue (ColumnSequence columns, T_LONG startPoint,T_LONG count);

� NameValueUnitIterator getValueMeaPoint (T_LONG meaPoint);

� TS_ValueSeq getValueVector (Column col, T_LONG startPoint, T_LONG count);

� NameSequence listColumns (Pattern colPattern);


© 2015/08/19 Version 1.33




� NameSequence listColumnsScaledBy (Column scalingColumn);

� NameSequence listIndependentColumns (Pattern colPattern);

� NameSequence listScalingColumns (Pattern colPattern);

� void removeValueMeaPoint (NameSequence columnNames, T_LONG meaPoint, T_LONGcount);

� void removeValueVector (Column col, T_LONG startPoint, T_LONG count);

� void setValue (SetType set, T_LONG startPoint, NameValueSeqUnitSequence value);

� void setValueMeaPoint (SetType set, T_LONG meaPoint, NameValueSequence value);

� void setValueVector (Column col, SetType set, T_LONG startPoint, TS_ValueSeq value);


© 2015/08/19 Version 1.33



Index

abortTransactionAoSession, 48

ACL, 525ACLSequence, 578ADD_RIGHT, 566addColumn

ValueMatrix, 499addColumnScaledBy

ValueMatrix, 499addInstanceAttribute

InstanceElement, 353addItem

EnumerationDe�nition, 342AggrFunc, 553AIDName, 525AIDNameSequence, 578AIDNameUnitId, 526AIDNameUnitIdSequence, 578AIDNameValueSeqUnitId, 526AIDNameValueSeqUnitIdSequence, 578AIDNameValueUnitId, 526ALL, 554ALL_REL, 565AND, 568AO_ACCESS_DENIED, 558AO_BAD_OPERATION, 558AO_BAD_PARAMETER, 558AO_CONNECT_FAILED, 558AO_CONNECT_REFUSED, 558AO_CONNECTION_LOST, 558AO_DUPLICATE_BASE_ATTRIBUTE, 558AO_DUPLICATE_NAME, 558AO_DUPLICATE_VALUE, 559AO_FILE_LOCKED, 564AO_HAS_BASE_ATTRIBUTE, 563AO_HAS_BASE_RELATION, 563AO_HAS_INSTANCES, 559AO_HAS_REFERENCES, 559AO_IMPLEMENTATION_PROBLEM, 559AO_INCOMPATIBLE_UNITS, 559AO_INVALID_ASAM_PATH, 559AO_INVALID_ATTRIBUTE_TYPE, 559AO_INVALID_BASE_ELEMENT, 559AO_INVALID_BASETYPE, 559AO_INVALID_BUILDUP_FUNCTION, 560

AO_INVALID_COLUMN, 560AO_INVALID_COUNT, 560AO_INVALID_DATATYPE, 560AO_INVALID_ELEMENT, 560AO_INVALID_LENGTH, 560AO_INVALID_ORDINALNUMBER, 560AO_INVALID_RELATION, 561AO_INVALID_RELATION_RANGE, 561AO_INVALID_RELATION_TYPE, 561AO_INVALID_RELATIONSHIP, 561AO_INVALID_SET_TYPE, 561AO_INVALID_SMATLINK, 561AO_INVALID_SUBMATRIX, 561AO_INVALID_VALUEMATRIX_-

STRUCTURE, 564AO_IS_BASE_ATTRIBUTE, 561AO_IS_BASE_RELATION, 561AO_IS_MEASUREMENT_MATRIX, 561AO_MATH_ERROR, 562AO_MISSING_APPLICATION_ELEMENT,

562AO_MISSING_ATTRIBUTE, 562AO_MISSING_RELATION, 562AO_MISSING_VALUE, 562AO_NO_MEMORY, 562AO_NO_PATH_TO_ELEMENT, 562AO_NO_SCALING_COLUMN, 563AO_NOT_FOUND, 562AO_NOT_IMPLEMENTED, 562AO_NOT_UNIQUE, 562AO_OPEN_MODE_NOT_SUPPORTED,

563AO_QUERY_INCOMPLETE, 564AO_QUERY_INVALID, 563AO_QUERY_INVALID_RESULTTYPE, 564AO_QUERY_PROCESSING_ERROR, 564AO_QUERY_TIMEOUT_EXCEEDED, 564AO_QUERY_TYPE_INVALID, 563AO_SESSION_LIMIT_REACHED, 563AO_SESSION_NOT_ACTIVE, 563AO_SYSTEM_PROBLEM, 564AO_TRANSACTION_ALREADY_ACTIVE,

563AO_TRANSACTION_NOT_ACTIVE, 563AO_UNKNOWN_ERROR, 558

606 INDEX

AO_UNKNOWN_UNIT, 563AoException, 20, 589AoFactory, 29

getDescription, 35getInterfaceVersion, 36getName, 37getType, 38newSession, 39newSessionNameValue, 41

AoFactory, 21, 29AoFactory.getDescription, 35AoFactory.getInterfaceVersion, 36AoFactory.getName, 37AoFactory.getType, 38AoFactory.newSession, 39AoFactory.newSessionNameValue, 41AoFile, 437AoLocalColumn, 27, 28AoService, 24

listServices, 25newFactory, 25

AoService, 21, 24AoService.listServices, 25AoService.newFactory, 25AoServiceFactory, 24

newService, 24AoServiceFactory, 21, 24AoServiceFactory.newService, 24AoSession, 43

abortTransaction, 48close, 49commitTransaction, 50createBlob, 52createCoSession, 53createQueryEvaluator, 55�ush, 55getApplElemAccess, 56getApplicationStructure, 57getApplicationStructureValue, 58getBaseStructure, 59getContext, 60getContextByName, 62getDescription, 63getEnumerationAttributes, 64getEnumerationStructure, 65getId, 67getLockMode, 67getName, 68getType, 69getUser, 70listContext, 71removeContext, 73setContext, 74setContextString, 75

setCurrentInitialRights, 77setLockMode, 78setPassword, 79startTransaction, 81

AoSession, 43AoSession.abortTransaction, 48AoSession.close, 49AoSession.commitTransaction, 51AoSession.createBlob, 52AoSession.createCoSession, 53AoSession.createQueryEvaluator, 55AoSession.�ush, 55AoSession.getApplElemAccess, 56AoSession.getApplicationStructure, 57AoSession.getApplicationStructureValue, 58AoSession.getBaseStructure, 59AoSession.getContext, 60AoSession.getContextByName, 62AoSession.getDescription, 63AoSession.getEnumerationAttributes, 64AoSession.getEnumerationStructure, 65AoSession.getId, 67AoSession.getLockMode, 68AoSession.getName, 68AoSession.getType, 69AoSession.getUser, 70AoSession.listContext, 72AoSession.removeContext, 73AoSession.setContext, 74AoSession.setContextString, 76AoSession.setCurrentInitialRights, 77AoSession.setLockMode, 78AoSession.setPassword, 79AoSession.startTransaction, 81APPEND, 569append

Blob, 317ODSFile, 442

ApplAttr, 527APPLATTR_ONLY, 554ApplAttrSequence, 578ApplElem, 528ApplElemAccess, 82

deleteInstances, 103getAttributeRights, 104getElementInitialRights, 106getElementRights, 107getInitialRightReference, 108getInstanceInitialRights, 110getInstanceRights, 111getInstances, 113getInstancesExt, 116getODSFile, 121getRelInst, 122, 124


© 2015/08/19 Version 1.33



INDEX 607

getValueMatrix, 126getValueMatrixInMode, 127insertInstances, 129setAttributeRights, 132setElementInitialRights, 134setElementRights, 135setInitialRightReference, 137setInstanceInitialRights, 139setInstanceRights, 140setRelInst, 141updateInstances, 143

ApplElemAccess, 82ApplElemAccess.deleteInstances, 103ApplElemAccess.getAttributeRights, 105ApplElemAccess.getElementInitialRights, 106ApplElemAccess.getElementRights, 107ApplElemAccess.getInitialRightReference, 109ApplElemAccess.getInstanceInitialRights, 110ApplElemAccess.getInstanceRights, 111ApplElemAccess.getInstances, 113ApplElemAccess.getInstancesExt, 116ApplElemAccess.getODSFile, 121ApplElemAccess.getRelInst, 123, 124ApplElemAccess.getValueMatrix, 126ApplElemAccess.getValueMatrixInMode, 127ApplElemAccess.insertInstances, 129ApplElemAccess.setAttributeRights, 132ApplElemAccess.setElementInitialRights, 134ApplElemAccess.setElementRights, 136ApplElemAccess.setInitialRightReference, 137ApplElemAccess.setInstanceInitialRights, 139ApplElemAccess.setInstanceRights, 140ApplElemAccess.setRelInst, 141ApplElemAccess.updateInstances, 143ApplElemSequence, 578ApplicationAttribute, 146

getApplicationElement, 148getBaseAttribute, 149getDataType, 150getEnumerationDe�nition, 151getLength, 152getName, 153getRights, 155getUnit, 156hasUnit, 157hasValueFlag, 158isAutogenerated, 159isObligatory, 160isUnique, 161setBaseAttribute, 162setDataType, 165setEnumerationDe�nition, 166setIsAutogenerated, 168setIsObligatory, 169

setIsUnique, 170setLength, 171setName, 173setRights, 174setUnit, 175withUnit, 178withValueFlag, 178

ApplicationAttribute, 146ApplicationAttribute.getApplicationElement,

148ApplicationAttribute.getBaseAttribute, 149ApplicationAttribute.getDataType, 150ApplicationAttribute.getEnumerationDe�nition,

151ApplicationAttribute.getLength, 152ApplicationAttribute.getName, 154ApplicationAttribute.getRights, 155ApplicationAttribute.getUnit, 156ApplicationAttribute.hasUnit, 157ApplicationAttribute.hasValueFlag, 158ApplicationAttribute.isAutogenerated, 159ApplicationAttribute.isObligatory, 160ApplicationAttribute.isUnique, 161ApplicationAttribute.setBaseAttribute, 163ApplicationAttribute.setDataType, 165ApplicationAttribute.setEnumerationDe�nition,

166ApplicationAttribute.setIsAutogenerated, 168ApplicationAttribute.setIsObligatory, 169ApplicationAttribute.setIsUnique, 170ApplicationAttribute.setLength, 171ApplicationAttribute.setName, 173ApplicationAttribute.setRights, 174ApplicationAttribute.setUnit, 175ApplicationAttribute.withUnit, 178ApplicationAttribute.withValueFlag, 179ApplicationAttributeSequence, 578ApplicationElement, 179

createAttribute, 180createInstance, 182createInstances, 184getAllRelatedElements, 185getAllRelations, 186getApplicationStructure, 187getAttributeByBaseName, 188getAttributeByName, 189getAttributes, 190getBaseElement, 192getId, 193getInitialRightRelations, 194getInitialRights, 195getInstanceById, 196getInstanceByName, 197getInstances, 199


© 2015/08/19 Version 1.33



608 INDEX

getName, 200getRelatedElementsByRelationship, 201getRelationsByBaseName, 202getRelationsByType, 204getRights, 205getSecurityLevel, 206listAllRelatedElements, 208listAttributes, 209listInstances, 210listRelatedElementsByRelationship, 211removeAttribute, 212removeInstance, 214setBaseElement, 215setInitialRightRelation, 217setInitialRights, 217setName, 219setRights, 220setSecurityLevel, 222

ApplicationElement, 179ApplicationElement.createAttribute, 181ApplicationElement.createInstance, 182ApplicationElement.createInstances, 184ApplicationElement.getAllRelatedElements,

185ApplicationElement.getAllRelations, 186ApplicationElement.getApplicationStructure,

187ApplicationElement.getAttributeByBaseName,

188ApplicationElement.getAttributeByName, 189ApplicationElement.getAttributes, 191ApplicationElement.getBaseElement, 192ApplicationElement.getId, 193ApplicationElement.getInitialRightRelations,

194ApplicationElement.getInitialRights, 195ApplicationElement.getInstanceById, 196ApplicationElement.getInstanceByName, 197ApplicationElement.getInstances, 199ApplicationElement.getName, 200ApplicationElement.getRelatedElementsByRelationship,

201ApplicationElement.getRelationsByBaseName,

202ApplicationElement.getRelationsByType, 204ApplicationElement.getRights, 205ApplicationElement.getSecurityLevel, 206ApplicationElement.listAllRelatedElements,

208ApplicationElement.listAttributes, 209ApplicationElement.listInstances, 210ApplicationElement.listRelatedElementsByRelationship,

211ApplicationElement.removeAttribute, 212

ApplicationElement.removeInstance, 214ApplicationElement.setBaseElement, 215ApplicationElement.setInitialRightRelation,

217ApplicationElement.setInitialRights, 218ApplicationElement.setName, 219ApplicationElement.setRights, 220ApplicationElement.setSecurityLevel, 222ApplicationElementSequence, 579ApplicationRelation, 223

create, 228getBaseRelation, 231getElem1, 232getElem2, 233getInverseRelationName, 234getInverseRelationRange, 235getInverseRelationship, 236getRelationName, 237getRelationRange, 238getRelationship, 240getRelationType, 241setBaseRelation, 242setElem1, 243setElem2, 243setInverseRelationName, 244setInverseRelationRange, 245setRelationName, 246setRelationRange, 247setRelationType, 248

ApplicationRelation, 223ApplicationRelation.getBaseRelation, 231ApplicationRelation.getElem1, 232ApplicationRelation.getElem2, 233ApplicationRelation.getInverseRelationName,

234ApplicationRelation.getInverseRelationRange,

235ApplicationRelation.getInverseRelationship,

236ApplicationRelation.getRelationName, 237ApplicationRelation.getRelationRange, 239ApplicationRelation.getRelationship, 240ApplicationRelation.getRelationType, 241ApplicationRelation.setBaseRelation, 242ApplicationRelation.setElem1, 243ApplicationRelation.setElem2, 244ApplicationRelation.setInverseRelationName,

244ApplicationRelation.setInverseRelationRange,

245ApplicationRelation.setRelationName, 246ApplicationRelation.setRelationRange, 247ApplicationRelation.setRelationType, 248ApplicationRelationInstanceElementSeq, 529


© 2015/08/19 Version 1.33



INDEX 609

ApplicationRelationInstanceElementSeqSequence,579

ApplicationRelationSequence, 579ApplicationStructure, 249

check, 250createElement, 252createEnumerationDe�nition, 253createInstanceRelations, 255createRelation, 256getElementById, 258getElementByName, 259getElements, 260getElementsByBaseType, 261getEnumerationDe�nition, 262getInstanceByAsamPath, 264getInstancesById, 265getRelations, 266getSession, 267getTopLevelElements, 268listElements, 270listElementsByBaseType, 271listEnumerations, 272listTopLevelElements, 273removeElement, 274removeEnumerationDe�nition, 275removeRelation, 277

ApplicationStructure, 249ApplicationStructure.check, 250ApplicationStructure.createElement, 252ApplicationStructure.createEnumerationDe�nition,

254ApplicationStructure.createInstanceRelations,

255ApplicationStructure.createRelation, 256ApplicationStructure.getElementById, 258ApplicationStructure.getElementByName, 259ApplicationStructure.getElements, 260ApplicationStructure.getElementsByBaseType,

261ApplicationStructure.getEnumerationDe�nition,

263ApplicationStructure.getInstanceByAsamPath,

264ApplicationStructure.getInstancesById, 265ApplicationStructure.getRelations, 266ApplicationStructure.getSession, 268ApplicationStructure.getTopLevelElements,

269ApplicationStructure.listElements, 270ApplicationStructure.listElementsByBaseType,

271ApplicationStructure.listEnumerations, 272ApplicationStructure.listTopLevelElements,

273

ApplicationStructure.removeElement, 274ApplicationStructure.removeEnumerationDe�nition,

276ApplicationStructure.removeRelation, 277ApplicationStructureValue, 529ApplRel, 530ApplRelSequence, 579ASAM ODS Exceptions, 589ASAM ODS Types, 575AsamOdsConstants, 571AsamOdsEnumerations, 553AsamOdsStructures, 525AsamOdsUnions, 547ATF File, 22ATF/CLA, 22ATF/XML, 22AttrResultSet, 531AttrResultSetSequence, 579AttrType, 554auth, 34AVG, 553

BaseAttribute, 278getBaseElement, 279getDataType, 280getEnumerationDe�nition, 281getName, 282isObligatory, 283isUnique, 284

BaseAttribute, 278BaseAttribute.getBaseElement, 279BaseAttribute.getDataType, 280BaseAttribute.getEnumerationDe�nition, 281BaseAttribute.getName, 282BaseAttribute.isObligatory, 283BaseAttribute.isUnique, 284BaseAttributeSequence, 579BaseElement, 285

getAllRelations, 286getAttributes, 287getRelatedElementsByRelationship, 288getRelationsByType, 290getType, 291isTopLevel, 292listAttributes, 293listRelatedElementsByRelationship, 294

BaseElement, 285BaseElement.getAllRelations, 286BaseElement.getAttributes, 287BaseElement.getRelatedElementsByRelationship,

289BaseElement.getRelationsByType, 290BaseElement.getType, 291BaseElement.isTopLevel, 292


© 2015/08/19 Version 1.33



610 INDEX

BaseElement.listAttributes, 293BaseElement.listRelatedElementsByRelationship,

294BaseElementSequence, 579BaseRelation, 295

getElem1, 296getElem2, 297getInverseRelationName, 298getInverseRelationRange, 299getInverseRelationship, 300getRelationName, 301getRelationRange, 302getRelationship, 303getRelationType, 304

BaseRelation, 295BaseRelation.getElem1, 296BaseRelation.getElem2, 297BaseRelation.getInverseRelationName, 298BaseRelation.getInverseRelationRange, 299BaseRelation.getInverseRelationship, 300BaseRelation.getRelationName, 301BaseRelation.getRelationRange, 302BaseRelation.getRelationship, 304BaseRelation.getRelationType, 305BaseRelationSequence, 580BaseStructure, 306

getElementByType, 306getElements, 307getRelation, 308getRelations, 310getTopLevelElements, 311getVersion, 312listElements, 313listTopLevelElements, 314

BaseStructure, 306BaseStructure.getElementByType, 306BaseStructure.getElements, 308BaseStructure.getRelation, 309BaseStructure.getRelations, 310BaseStructure.getTopLevelElements, 311BaseStructure.getVersion, 312BaseStructure.listElements, 313BaseStructure.listTopLevelElements, 314BaseType, 576BaseTypeSequence, 580BETWEEN, 568Blob, 316

append, 317compare, 318destroy, 319get, 320getHeader, 322getLength, 323set, 324

setHeader, 325Blob, 316Blob.append, 317Blob.compare, 318Blob.destroy, 319Blob.get, 321Blob.getHeader, 322Blob.getLength, 323Blob.set, 324Blob.setHeader, 325boolean, 575BuildUpFunction, 554BUP_JOIN, 554BUP_MERGE, 554BUP_SORT, 554

CALCULATED, 497, 570canRead

ODSFile, 444canWrite

ODSFile, 445check

ApplicationStructure, 250CHILD, 565CI_EQ, 567CI_GT, 567CI_GTE, 568CI_INSET, 568CI_LIKE, 568CI_LT, 567CI_LTE, 567CI_NEQ, 567CI_NOTINSET, 568CI_NOTLIKE, 568CLOSE, 569close

AoSession, 49ODSReadTransfer, 459ODSWriteTransfer, 462

Column, 326destroy, 327getDataType, 327getFormula, 328getGenerationParameters, 329getName, 330getRawDataType, 330getSequenceRepresentation, 331getSourceMQ, 332getUnit, 332isIndependent, 333isScaling, 334setFormula, 334setGenerationParameters, 335setIndependent, 336


© 2015/08/19 Version 1.33



INDEX 611

setScaling, 336setSequenceRepresentation, 337setUnit, 337

Column, 326Column.destroy, 327Column.getDataType, 328Column.getFormula, 328Column.getGenerationParameters, 329Column.getName, 330Column.getRawDataType, 330Column.getSequenceRepresentation, 331Column.getSourceMQ, 332Column.getUnit, 332Column.isIndependent, 333Column.isScaling, 334Column.setFormula, 334Column.setGenerationParameters, 335Column.setIndependent, 336Column.setScaling, 336Column.setSequenceRepresentation, 337Column.setUnit, 337ColumnSequence, 580commitTransaction

AoSession, 50compare

Blob, 318InstanceElement, 355

COMPLETE, 565CORBA-Naming Service, 21COUNT, 553create

ApplicationRelation, 228ODSFile, 446

create relation, 228createAttribute

ApplicationElement, 180createBlob

AoSession, 52createCoSession

AoSession, 53createElement

ApplicationStructure, 252createEnumerationDe�nition

ApplicationStructure, 253createInstance

ApplicationElement, 182createInstanceRelations

ApplicationStructure, 255createInstances

ApplicationElement, 184createQuery

QueryEvaluator, 470createQueryEvaluator

AoSession, 55

createRelatedInstancesInstanceElement, 356

CreateRelation, 228createRelation

ApplicationStructure, 256InstanceElement, 360

createSMatLinkMeasurement, 404

DataType, 555DCOUNT, 553DEBUGLEVEL, 14deepCopy

InstanceElement, 361deleteInstances

ApplElemAccess, 103destroy

Blob, 319Column, 327ElemResultSetExtSeqIterator, 338InstanceElement, 363InstanceElementIterator, 397NameIterator, 410NameValueIterator, 417NameValueUnitIdIterator, 422NameValueUnitIterator, 428NameValueUnitSequenceIterator, 434ValueMatrix, 500

destroy, 4DISTINCT, 554double, 575DS_BOOLEAN, 556DS_BYTE, 556DS_BYTESTR, 557DS_COMPLEX, 557DS_DATE, 557DS_DCOMPLEX, 557DS_DOUBLE, 557DS_ENUM, 557DS_EXTERNALREFERENCE, 557DS_FLOAT, 556DS_ID, 557DS_LONG, 557DS_LONGLONG, 557DS_SHORT, 556DS_STRING, 556DT_BLOB, 556DT_BOOLEAN, 555DT_BYTE, 555DT_BYTESTR, 556DT_COMPLEX, 28, 556DT_DATE, 28, 556DT_DCOMPLEX, 28, 556DT_DOUBLE, 555


© 2015/08/19 Version 1.33



612 INDEX

DT_ENUM, 557DT_EXTERNALREFERENCE, 557DT_FLOAT, 555DT_ID, 555DT_LONG, 555DT_LONGLONG, 27, 555DT_SHORT, 555DT_STRING, 555DT_UNKNOWN, 555

EFFRIGHTS, 15ElemId, 532ElemIdSequence, 580ElemResultSet, 532ElemResultSetExt, 532ElemResultSetExtSeqIterator, 338

destroy, 338getCount, 339nextN, 339nextOne, 340reset, 341

ElemResultSetExtSeqIterator, 338ElemResultSetExtSeqIterator.destroy, 338ElemResultSetExtSeqIterator.getCount, 339ElemResultSetExtSeqIterator.nextN, 340ElemResultSetExtSeqIterator.nextOne, 340ElemResultSetExtSeqIterator.reset, 341ElemResultSetExtSequence, 580ElemResultSetSequence, 580EnumerationAttributeStructure, 533EnumerationAttributeStructureSequence, 580EnumerationDe�nition, 341

addItem, 342getIndex, 343getItem, 344getItemName, 345getName, 346listItemNames, 347renameItem, 349setName, 350

EnumerationDe�nition, 341EnumerationDe�nition.addItem, 343EnumerationDe�nition.getIndex, 343EnumerationDe�nition.getItem, 344EnumerationDe�nition.getItemName, 345EnumerationDe�nition.getName, 346EnumerationDe�nition.listItemNames, 348EnumerationDe�nition.renameItem, 349EnumerationDe�nition.setName, 350EnumerationItemStructure, 533EnumerationItemStructureSequence, 581EnumerationStructure, 534EnumerationStructureSequence, 581EQ, 566

ERROR, 570ErrorCode, 558examples, 20executeQuery

Query, 465exists

ODSFile, 448

FATHER, 565FATHER_CHILD, 566�oat, 575�ush

AoSession, 55FOR_USER, 34

getBlob, 320

getAllRelatedElementsApplicationElement, 185

getAllRelationsApplicationElement, 186BaseElement, 286

getApplElemAccessAoSession, 56

getApplicationElementApplicationAttribute, 148InstanceElement, 364

getApplicationStructureAoSession, 57ApplicationElement, 187

getApplicationStructureValueAoSession, 58

getAsamPathInstanceElement, 365

getAttributeByBaseNameApplicationElement, 188

getAttributeByNameApplicationElement, 189

getAttributeRightsApplElemAccess, 104

getAttributesApplicationElement, 190BaseElement, 287

getBaseAttributeApplicationAttribute, 149

getBaseElementApplicationElement, 192BaseAttribute, 279

getBaseRelationApplicationRelation, 231

getBaseStructureAoSession, 59

getColumnCountValueMatrix, 502


© 2015/08/19 Version 1.33



INDEX 613

getColumnsSubMatrix, 482ValueMatrix, 503

getColumnsScaledByValueMatrix, 504

getContextAoSession, 60

getContextByNameAoSession, 62

getCountElemResultSetExtSeqIterator, 339InstanceElementIterator, 398NameIterator, 411NameValueIterator, 418NameValueUnitIdIterator, 423NameValueUnitIterator, 429NameValueUnitSequenceIterator, 434

getDataTypeApplicationAttribute, 150BaseAttribute, 280Column, 327

getDateODSFile, 449

getDescriptionAoFactory, 35AoSession, 63

getElem1ApplicationRelation, 232BaseRelation, 296

getElem2ApplicationRelation, 233BaseRelation, 297

getElementByIdApplicationStructure, 258

getElementByNameApplicationStructure, 259

getElementByTypeBaseStructure, 306

getElementInitialRightsApplElemAccess, 106

getElementRightsApplElemAccess, 107

getElementsApplicationStructure, 260BaseStructure, 307

getElementsByBaseTypeApplicationStructure, 261

getEnumerationAttributesAoSession, 64

getEnumerationDe�nitionApplicationAttribute, 151ApplicationStructure, 262BaseAttribute, 281

getEnumerationStructure

AoSession, 65getFormula

Column, 328getGenerationParameters

Column, 329getHeader

Blob, 322getId

AoSession, 67ApplicationElement, 193InstanceElement, 367

getIndependentColumnsValueMatrix, 505

getIndexEnumerationDe�nition, 343

getInitialRightReferenceApplElemAccess, 108

getInitialRightRelationsApplicationElement, 194

getInitialRightsApplicationElement, 195InstanceElement, 368

getInstanceByAsamPathApplicationStructure, 264

getInstanceByIdApplicationElement, 196

getInstanceByNameApplicationElement, 197

getInstanceInitialRightsApplElemAccess, 110

getInstanceRightsApplElemAccess, 111

getInstancesApplElemAccess, 113ApplicationElement, 199Query, 466QueryEvaluator, 471

getInstancesByIdApplicationStructure, 265

getInstancesExtApplElemAccess, 116

getInterfaceVersionAoFactory, 36

getInverseRelationNameApplicationRelation, 234BaseRelation, 298

getInverseRelationRangeApplicationRelation, 235BaseRelation, 299

getInverseRelationshipApplicationRelation, 236BaseRelation, 300

getItemEnumerationDe�nition, 344


© 2015/08/19 Version 1.33



614 INDEX

getItemNameEnumerationDe�nition, 345

getLengthApplicationAttribute, 152Blob, 323

getLinkTypeSMatLink, 474

getLockModeAoSession, 67

getModeValueMatrix, 506

getNameAoFactory, 37AoSession, 68ApplicationAttribute, 153ApplicationElement, 200BaseAttribute, 282Column, 330EnumerationDe�nition, 346InstanceElement, 369

getOctetSeqODSReadTransfer, 459

getODSFileApplElemAccess, 121

getOrdinalNumberSMatLink, 474

getPositionODSReadTransfer, 460ODSWriteTransfer, 463

getQueryEvaluatorQuery, 466

getRawDataTypeColumn, 330

getRelatedElementsByRelationshipApplicationElement, 201BaseElement, 288

getRelatedInstancesInstanceElement, 370

getRelatedInstancesByRelationshipInstanceElement, 372

getRelationBaseStructure, 308

getRelationNameApplicationRelation, 237BaseRelation, 301

getRelationRangeApplicationRelation, 238BaseRelation, 302

getRelationsApplicationStructure, 266BaseStructure, 310

getRelationsByBaseNameApplicationElement, 202

getRelationsByType

ApplicationElement, 204BaseElement, 290

getRelationshipApplicationRelation, 240BaseRelation, 303

getRelationTypeApplicationRelation, 241BaseRelation, 304

getRelInstApplElemAccess, 122, 124

getRightsApplicationAttribute, 155ApplicationElement, 205InstanceElement, 373

getRowCountValueMatrix, 507

getScalingColumnsValueMatrix, 508

getSecurityLevelApplicationElement, 206

getSequenceRepresentationColumn, 331

getSessionApplicationStructure, 267

getSizeODSFile, 451

getSMat1SMatLink, 475

getSMat1ColumnsSMatLink, 475

getSMat2SMatLink, 476

getSMat2ColumnsSMatLink, 476

getSMatLinksMeasurement, 405

getSourceMQColumn, 332

getStatusQuery, 467

getTableQuery, 467QueryEvaluator, 472

getTableRowsQuery, 468QueryEvaluator, 472

getTopLevelElementsApplicationStructure, 268BaseStructure, 311

getTypeAoFactory, 38AoSession, 69BaseElement, 291

getUnit


© 2015/08/19 Version 1.33



INDEX 615

ApplicationAttribute, 156Column, 332

getUserAoSession, 70

getValueInstanceElement, 374ValueMatrix, 509

getValueByBaseNameInstanceElement, 376

getValueInUnitInstanceElement, 377

getValueMatrixApplElemAccess, 126Measurement, 405SubMatrix, 483

getValueMatrixInModeApplElemAccess, 127Measurement, 406SubMatrix, 484

getValueMeaPointValueMatrix, 511

getValueSeqInstanceElement, 377

getValueVectorValueMatrix, 512

getVersionBaseStructure, 312

GT, 567GTE, 567

hasUnitApplicationAttribute, 157

hasValueFlagApplicationAttribute, 158

INCOMPLETE, 565INFO, 566INFO_FROM, 565INFO_REL, 565INFO_TO, 565INFORMATION, 570INHERITANCE, 566InitialRight, 534InitialRightSequence, 581INSERT, 569insertInstances

ApplElemAccess, 129INSET, 96, 567instance attributes, 27InstanceElement, 351

addInstanceAttribute, 353compare, 355createRelatedInstances, 356createRelation, 360

deepCopy, 361destroy, 363getApplicationElement, 364getAsamPath, 365getId, 367getInitialRights, 368getName, 369getRelatedInstances, 370getRelatedInstancesByRelationship, 372getRights, 373getValue, 374getValueByBaseName, 376getValueInUnit, 377getValueSeq, 377listAttributes, 379listRelatedInstances, 380listRelatedInstancesByRelationship, 381removeInstanceAttribute, 383removeRelation, 383renameInstanceAttribute, 384setInitialRights, 385setName, 386setRights, 387setValue, 388setValueSeq, 390shallowCopy, 391upcastMeasurement, 392upcastODSFile, 393upcastSubMatrix, 394

InstanceElement, 351InstanceElement.addInstanceAttribute, 353InstanceElement.compare, 355InstanceElement.createRelatedInstances, 356InstanceElement.createRelation, 360InstanceElement.deepCopy, 362InstanceElement.destroy, 363InstanceElement.getApplicationElement, 364InstanceElement.getAsamPath, 366InstanceElement.getId, 367InstanceElement.getInitialRights, 368InstanceElement.getName, 369InstanceElement.getRelatedInstances, 370InstanceElement.getRelatedInstancesByRelationship,

372InstanceElement.getRights, 373InstanceElement.getValue, 374InstanceElement.getValueByBaseName, 376InstanceElement.getValueInUnit, 377InstanceElement.getValueSeq, 377InstanceElement.listAttributes, 379InstanceElement.listRelatedInstances, 380InstanceElement.listRelatedInstancesByRelationship,

382InstanceElement.removeInstanceAttribute, 383


© 2015/08/19 Version 1.33



616 INDEX

InstanceElement.removeRelation, 383InstanceElement.renameInstanceAttribute, 384InstanceElement.setInitialRights, 385InstanceElement.setName, 386InstanceElement.setRights, 387InstanceElement.setValue, 388InstanceElement.setValueSeq, 390InstanceElement.shallowCopy, 391InstanceElement.upcastMeasurement, 392InstanceElement.upcastODSFile, 393InstanceElement.upcastSubMatrix, 395InstanceElementIterator, 396


InstanceElementIterator, 396InstanceElementIterator.destroy, 397InstanceElementIterator.getCount, 398InstanceElementIterator.nextN, 399InstanceElementIterator.nextOne, 401InstanceElementIterator.reset, 402InstanceElementSequence, 581INSTATTR_ONLY, 554IS_NOT_NULL, 568IS_NULL, 568isAutogenerated

ApplicationAttribute, 159isIndependent

Column, 333isObligatory

ApplicationAttribute, 160BaseAttribute, 283

isScalingColumn, 334

isTopLevelBaseElement, 292

isUniqueApplicationAttribute, 161BaseAttribute, 284

JoinDef, 535JoinDefSequence, 581JoinType, 564JTDEFAULT, 564JTOUTER, 564

LIKE, 567LIMIT, 95listAllRelatedElements

ApplicationElement, 208listAttributes

ApplicationElement, 209

BaseElement, 293InstanceElement, 379

listColumnsSubMatrix, 486ValueMatrix, 513

listColumnsScaledByValueMatrix, 514

listContextAoSession, 71

listElementsApplicationStructure, 270BaseStructure, 313

listElementsByBaseTypeApplicationStructure, 271

listEnumerationsApplicationStructure, 272

listIndependentColumnsValueMatrix, 515

listInstancesApplicationElement, 210

listItemNamesEnumerationDe�nition, 347

listRelatedElementsByRelationshipApplicationElement, 211BaseElement, 294

listRelatedInstancesInstanceElement, 380

listRelatedInstancesByRelationshipInstanceElement, 381

listScalingColumnsValueMatrix, 516

listServicesAoService, 25

listTopLevelElementsApplicationStructure, 273BaseStructure, 314

LockMode, 571logging, 14long, 575LT, 567LTE, 567

MAX, 553Measurement, 403

createSMatLink, 404getSMatLinks, 405getValueMatrix, 405getValueMatrixInMode, 406removeSMatLink, 408

Measurement, 403Measurement.createSMatLink, 404Measurement.getSMatLinks, 405Measurement.getValueMatrix, 405Measurement.getValueMatrixInMode, 407


© 2015/08/19 Version 1.33



INDEX 617

Measurement.removeSMatLink, 408MIN, 553

N:M relation, 27Name, 576NameIterator, 409


NameIterator, 409NameIterator.destroy, 410NameIterator.getCount, 411NameIterator.nextN, 412NameIterator.nextOne, 414NameIterator.reset, 415NameSequence, 581NameUnit, 535NameValue, 536NameValueIterator, 416


NameValueIterator, 416NameValueIterator.destroy, 417NameValueIterator.getCount, 418NameValueIterator.nextN, 419NameValueIterator.nextOne, 420NameValueIterator.reset, 421NameValueSequence, 581NameValueSeqUnit, 536NameValueSeqUnitId, 537NameValueSeqUnitIdSequence, 581NameValueSeqUnitSequence, 582NameValueUnit, 537NameValueUnitId, 538NameValueUnitIdIterator, 422


NameValueUnitIdIterator, 422NameValueUnitIdIterator.destroy, 422NameValueUnitIdIterator.getCount, 423NameValueUnitIdIterator.nextN, 424NameValueUnitIdIterator.nextOne, 424NameValueUnitIdIterator.reset, 425NameValueUnitIterator, 425

destroy, 428getCount, 429

nextN, 430nextOne, 432reset, 433

NameValueUnitIterator, 425NameValueUnitIterator.destroy, 429NameValueUnitIterator.getCount, 430NameValueUnitIterator.nextN, 431NameValueUnitIterator.nextOne, 432NameValueUnitIterator.reset, 433NameValueUnitSequence, 582NameValueUnitSequenceIterator, 434


NameValueUnitSequenceIterator, 434NameValueUnitSequenceIterator.destroy, 434NameValueUnitSequenceIterator.getCount, 435NameValueUnitSequenceIterator.nextN, 435NameValueUnitSequenceIterator.nextOne, 436NameValueUnitSequenceIterator.reset, 436NEQ, 567newFactory

AoService, 25newService

AoServiceFactory, 24newSession

AoFactory, 39newSession, 34newSessionNameValue

AoFactory, 41nextN

ElemResultSetExtSeqIterator, 339InstanceElementIterator, 399NameIterator, 412NameValueIterator, 419NameValueUnitIdIterator, 423NameValueUnitIterator, 430NameValueUnitSequenceIterator, 435

nextOneElemResultSetExtSeqIterator, 340InstanceElementIterator, 400NameIterator, 413NameValueIterator, 420NameValueUnitIdIterator, 424NameValueUnitIterator, 432NameValueUnitSequenceIterator, 436

NONE, 553NOT, 569NOTINSET, 567NOTLIKE, 568

octet, 575


© 2015/08/19 Version 1.33



618 INDEX

ODS_LOGFILE, 14ODSFile, 437

append, 442canRead, 444canWrite, 445create, 446exists, 448getDate, 449getSize, 451read, 452remove, 453removeFromControl, 455takeUnderControl, 457

ODSFile, 437ODSFile.append, 442ODSFile.canRead, 444ODSFile.canWrite, 445ODSFile.create, 446ODSFile.exists, 448ODSFile.getDate, 449ODSFile.getSize, 451ODSFile.read, 452ODSFile.remove, 454ODSFile.removeFromControl, 455ODSFile.takeUnderControl, 457ODSReadTransfer, 459

close, 459getOctetSeq, 459getPosition, 460skipOctets, 461

ODSReadTransfer, 459, 571ODSReadTransfer.close, 459ODSReadTransfer.getOctetSeq, 459ODSReadTransfer.getPosition, 460ODSReadTransfer.skipOctets, 461ODSWriteTransfer, 462

close, 462getPosition, 463putOctectSeq, 464

ODSWriteTransfer, 462ODSWriteTransfer.close, 462ODSWriteTransfer.getPosition, 463ODSWriteTransfer.putOctectSeq, 464OPEN, 569OR, 569

paging, 95Parameter, 19Pattern, 576POA, 4POINT, 554portable object adapter, 4prepareQuery

Query, 469

putOctectSeqODSWriteTransfer, 464

Query, 465executeQuery, 465getInstances, 466getQueryEvaluator, 466getStatus, 467getTable, 467getTableRows, 468prepareQuery, 469

Query, 465Query.executeQuery, 465Query.getInstances, 466Query.getQueryEvaluator, 466Query.getStatus, 467Query.getTable, 468Query.getTableRows, 468Query.prepareQuery, 469QueryConstants, 572QueryEvaluator, 470

createQuery, 470getInstances, 471getTable, 472getTableRows, 472

QueryEvaluator, 470QueryEvaluator.createQuery, 470QueryEvaluator.getInstances, 471QueryEvaluator.getTable, 472QueryEvaluator.getTableRows, 473QueryStatus, 565QueryStructure, 538QueryStructureExt, 539

readODSFile, 452

relation, 27relation attribute, 227relation create, 228RelationRange, 226, 540Relationship, 225, 565RelationType, 224, 566REMOVE, 569remove

ODSFile, 453REMOVE_RIGHT, 566removeAttribute

ApplicationElement, 212removeContext

AoSession, 73removeElement

ApplicationStructure, 274removeEnumerationDe�nition

ApplicationStructure, 275


© 2015/08/19 Version 1.33



INDEX 619

removeFromControlODSFile, 455

removeInstanceApplicationElement, 214

removeInstanceAttributeInstanceElement, 383

removeRelationApplicationStructure, 277InstanceElement, 383

removeSMatLinkMeasurement, 408

removeValueMeaPointValueMatrix, 517

removeValueVectorValueMatrix, 518

renameInstanceAttributeInstanceElement, 384

renameItemEnumerationDe�nition, 349

REOPEN_ALWAYS, 15reset

ElemResultSetExtSeqIterator, 341InstanceElementIterator, 402NameIterator, 415NameValueIterator, 421NameValueUnitIdIterator, 425NameValueUnitIterator, 433NameValueUnitSequenceIterator, 436

ResultSetExt, 541ResultSetExtSequence, 582ResultType, 572Return, 19RightsSet, 566

S_BLOB, 582S_BOOLEAN, 582S_BYTE, 582S_BYTESTR, 582S_COMPLEX, 583S_DATE, 583S_DCOMPLEX, 583S_DOUBLE, 583S_ExternalReference, 583S_FLOAT, 583S_LONG, 583S_LONGLONG, 584S_SHORT, 584S_STRING, 584Scalar, 576security, 14SecurityLevel, 573SecurityRights, 573SEL_OPERATOR_TYPE, 569SEL_VALUE_TYPE, 569

SelAIDNameUnitId, 541SelAIDNameUnitIdSequence, 584SelItem, 547SelItemSequence, 584SelOpcode, 566SelOperator, 568SelOperatorSequence, 584SelOrder, 542SelOrderSequence, 585SelQuery, 542SelQueryItem, 542SelType, 569SelValue, 543SelValueExt, 543SelValueSequence, 585Sequence, 578SESSIONID, 47set

Blob, 324SET_RIGHT, 566setAttributeRights

ApplElemAccess, 132setBaseAttribute

ApplicationAttribute, 162setBaseElement

ApplicationElement, 215setBaseRelation

ApplicationRelation, 242setContext

AoSession, 74setContextString

AoSession, 75setCurrentInitialRights

AoSession, 77setDataType

ApplicationAttribute, 165setElem1

ApplicationRelation, 243setElem2

ApplicationRelation, 243setElementInitialRights

ApplElemAccess, 134setElementRights

ApplElemAccess, 135setEnumerationDe�nition

ApplicationAttribute, 166setFormula

Column, 334setGenerationParameters

Column, 335setHeader

Blob, 325setIndependent

Column, 336


© 2015/08/19 Version 1.33



620 INDEX

setInitialRightReferenceApplElemAccess, 137

setInitialRightRelationApplicationElement, 217

setInitialRightsApplicationElement, 217InstanceElement, 385

setInstanceInitialRightsApplElemAccess, 139

setInstanceRightsApplElemAccess, 140

setInverseRelationNameApplicationRelation, 244

setInverseRelationRangeApplicationRelation, 245

setIsAutogeneratedApplicationAttribute, 168

setIsObligatoryApplicationAttribute, 169

setIsUniqueApplicationAttribute, 170

setLengthApplicationAttribute, 171

setLinkTypeSMatLink, 477

setLockModeAoSession, 78

setNameApplicationAttribute, 173ApplicationElement, 219EnumerationDe�nition, 350InstanceElement, 386

setOrdinalNumberSMatLink, 478

setPasswordAoSession, 79

setRelationNameApplicationRelation, 246

setRelationRangeApplicationRelation, 247

setRelationTypeApplicationRelation, 248

setRelInstApplElemAccess, 141

setRightsApplicationAttribute, 174ApplicationElement, 220InstanceElement, 387

setScalingColumn, 336

setSecurityLevelApplicationElement, 222

setSequenceRepresentationColumn, 337

setSMat1SMatLink, 478

setSMat1ColumnsSMatLink, 479

setSMat2SMatLink, 480

setSMat2ColumnsSMatLink, 480

SetType, 569setUnit

ApplicationAttribute, 175Column, 337

setValueInstanceElement, 388ValueMatrix, 518

setValueMeaPointValueMatrix, 520

setValueSeqInstanceElement, 390

setValueVectorValueMatrix, 521

SeverityFlag, 570shallowCopy

InstanceElement, 391short, 575skipOctets

ODSReadTransfer, 461SMatLink, 473

getLinkType, 474getOrdinalNumber, 474getSMat1, 475getSMat1Columns, 475getSMat2, 476getSMat2Columns, 476setLinkType, 477setOrdinalNumber, 478setSMat1, 478setSMat1Columns, 479setSMat2, 480setSMat2Columns, 480

SMatLink, 473SMatLink.getLinkType, 474SMatLink.getOrdinalNumber, 474SMatLink.getSMat1, 475SMatLink.getSMat1Columns, 475SMatLink.getSMat2, 476SMatLink.getSMat2Columns, 477SMatLink.setLinkType, 477SMatLink.setOrdinalNumber, 478SMatLink.setSMat1, 478SMatLink.setSMat1Columns, 479SMatLink.setSMat2, 480SMatLink.setSMat2Columns, 480SMatLinkSequence, 585


© 2015/08/19 Version 1.33



INDEX 621

SS_BOOLEAN, 585SS_BYTE, 585SS_BYTESTR, 585SS_COMPLEX, 585SS_DATE, 585SS_DCOMPLEX, 586SS_DOUBLE, 586SS_ExternalReference, 586SS_FLOAT, 586SS_LONG, 586SS_LONGLONG, 586SS_SHORT, 586SS_STRING, 587startTransaction

AoSession, 81STDDEV, 553STORAGE, 497, 570string, 575SubMatrix, 481

getColumns, 482getValueMatrix, 483getValueMatrixInMode, 484listColumns, 486

SubMatrix, 481SubMatrix.getColumns, 482SubMatrix.getValueMatrix, 483SubMatrix.getValueMatrixInMode, 485SubMatrix.listColumns, 486SubMatrixSequence, 587SUBTYPE, 565SUCCESS, 570SUM, 553SUPERTYPE, 565superuser_�ag, 15

T_BLOB, 576T_BOOLEAN, 576T_BYTE, 576T_BYTESTR, 587T_COMPLEX, 544T_DATE, 577T_DCOMPLEX, 544T_DOUBLE, 577T_ExternalReference, 544T_FLOAT, 577T_LONG, 577T_LONGLONG, 545T_SHORT, 577T_STRING, 577takeUnderControl

ODSFile, 457TS_Union, 547TS_UnionSeq, 550TS_Value, 545

TS_ValueSeq, 546

upcastMeasurementInstanceElement, 392

upcastODSFileInstanceElement, 393

upcastSubMatrixInstanceElement, 394

UPDATE, 569updateInstances

ApplElemAccess, 143

ValueMatrix, 487addColumn, 499addColumnScaledBy, 499destroy, 500getColumnCount, 502getColumns, 503getColumnsScaledBy, 504getIndependentColumns, 505getMode, 506getRowCount, 507getScalingColumns, 508getValue, 509getValueMeaPoint, 511getValueVector, 512listColumns, 513listColumnsScaledBy, 514listIndependentColumns, 515listScalingColumns, 516removeValueMeaPoint, 517removeValueVector, 518setValue, 518setValueMeaPoint, 520setValueVector, 521

ValueMatrix, 487ValueMatrix.addColumn, 499ValueMatrix.addColumnScaledBy, 500ValueMatrix.destroy, 500ValueMatrix.getColumnCount, 502ValueMatrix.getColumns, 503ValueMatrix.getColumnsScaledBy, 504ValueMatrix.getIndependentColumns, 505ValueMatrix.getMode, 506ValueMatrix.getRowCount, 507ValueMatrix.getScalingColumns, 508ValueMatrix.getValue, 509ValueMatrix.getValueMeaPoint, 511ValueMatrix.getValueVector, 512ValueMatrix.listColumns, 513ValueMatrix.listColumnsScaledBy, 515ValueMatrix.listIndependentColumns, 515ValueMatrix.listScalingColumns, 516ValueMatrix.removeValueMeaPoint, 517


© 2015/08/19 Version 1.33



622 INDEX

ValueMatrix.removeValueVector, 518ValueMatrix.setValue, 519ValueMatrix.setValueMeaPoint, 520ValueMatrix.setValueVector, 522ValueMatrix_Mode, 497ValueMatrixMode, 570values, 27, 28values localcolumn, 27, 28

WARNING, 570withUnit

ApplicationAttribute, 178withValueFlag

ApplicationAttribute, 178


© 2015/08/19 Version 1.33



ods object oriented api - highqsoft.com · ods object oriented api interface implementation version...

Documents