You are on page 1of 200

SDAI C Library

Reference Manual

STEP Tools Software

Contributors
Written by Jochen Fritz.
Additional material provided by Charles Gilman, Martin Hardwick, David Loffredo, and Jeff Young.

Copyright 1991-2010 STEP Tools, Inc. All Rights Reserved.


This document contains proprietary and confidential information of STEP Tools, Inc. The contents of this
document may not be disclosed to third parties, copied, or duplicated in any form, in whole or in part, without
the prior written permission of STEP Tools, Inc.
ST-Developer, STEP-NC Machine, ST-Viewer, and the ST prefix are trademarks of STEP Tools, Inc. STEP
Tools is a registered trademark of STEP Tools, Inc. Other brand or product names are the trademarks or
registered trademarks of their respective holders.

STEP Tools, Inc.


14 First Street
Troy, New York 12180
Phone . . . . . . .
Fax . . . . . . . . .
E-Mail . . . . . . .
Web. . . . . . . . .

(518) 687-2848
(518) 687-4420
info@steptools.com
http://www.steptools.com

Contents

Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii
1 SDAI Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1
The STEP Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2
The SDAI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3
ST-Developer and the SDAI C Binding . . . . . . . . . . . . . . . . . . . . . . . .
1.3.1 ROSE and the SDAI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4
Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.1 Font Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1
1
2
2
2
3
4

2 SDAI Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2
Compiling and Running SDAI Applications . . . . . . . . . . . . . . . . . . . . . 5
2.2.1 Compiling SDAI Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2.2 The SDAI Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3
SDAI Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.1 SDAI Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.2 Primitive Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.3 Entity Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.4 Aggregates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4
SDAI Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.4.1 Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.4.2 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.4.3 SDAI Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.4.4 Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.5 Schema Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4.6 Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4.7 Get and Put Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.4.8 Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.4.9 Attribute Data Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.4.10 Aggregates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.4.11 SELECTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

SDAI C LIBRARY REFERENCE MANUAL

III

CONTENTS

...........................
...........................
...........................
...........................
...........................
...........................
...........................

24
25
26
27
28
29
29

3 SDAI Library Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


3.1
Changes from v9 to v10 and later . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2
Changes from v8 to v9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Part 24 IS Conformance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 Low-Level Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 Other changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3
Changes from v7 to v8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 Recompile EXPRESS Parse Data . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Updating SELECT Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.3 New models created in STEP format . . . . . . . . . . . . . . . . . . . . . . . .
3.3.4 Part 21 File Accessor functions . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.5 Other Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4
Changes from 1.6 to v7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1 New Library Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.2 Dictionary Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.3 EXPRESS Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.4 Schema Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.5 Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.6 Strong Type Checking for Aggregates . . . . . . . . . . . . . . . . . . . . . . .
3.4.7 Unset Attribute Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.8 ROSE Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5
Property Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1 New Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.2 Corrected Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

31
31
31
31
32
32
33
33
33
34
34
34
35
36
36
37
37
37
38
39
40
40
40
42

4 Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.1 Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.2 Conformance Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.3 Unimplemented Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2
sdaiAccessModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3
sdaiAccessModelBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4
sdaiAdd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5
sdaiAddModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6
sdaiAddModelBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7
sdaiBeginning() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.8
sdaiCloseRepository() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.9
sdaiCloseSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.10 sdaiCreateADB() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.11 sdaiCreateAggr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.12 sdaiCreateAggrADB() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.13 sdaiCreateAggrBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

43
43
43
44
47
47
48
49
50
51
51
52
52
53
54
55
56

2.4.12
2.4.13
2.4.14
2.4.15
2.4.16
2.4.17
2.4.18

IV

Inverse Attributes . . . . . . . . .
Dictionary Data . . . . . . . . . . .
Interfacing with ROSE . . . . . .
Part 21 File Accessor functions
Low-Level Model API . . . . . . .
Multiple Schemas . . . . . . . . .
Property Functions . . . . . . . .

STEP TOOLS, INC.

CONTENTS

4.14
4.15
4.16
4.17
4.18
4.19
4.20
4.21
4.22
4.23
4.24
4.25
4.26
4.27
4.28
4.29
4.30
4.31
4.32
4.33
4.34
4.35
4.36
4.37
4.38
4.39
4.40
4.41
4.42
4.43
4.44
4.45
4.46
4.47
4.48
4.49
4.50
4.51
4.52
4.53
4.54
4.55
4.56
4.57
4.58
4.59

sdaiCreateAggrADBBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateComplexInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateComplexInstanceBN() . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateEmptyADB() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateInstanceBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateIterator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateModelBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateNestedAggr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateNestedAggrADB() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateNestedAggrByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateNestedAggrByIndexADB() . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateNestedAggrByItr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateNestedAggrByItrADB() . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateNPL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateSchemaInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiCreateSchemaInstanceBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiDeleteADB() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiDeleteInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiDeleteIterator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiDeleteModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiDeleteNPL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiDeleteSchemaInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiDeleteSchemaInstanceBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiEnd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiEndModelAccess() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiErrorQuery() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiFarCopyInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiFindInstanceRolesOf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiFindInstanceTypeOf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiFindInstanceUsedIn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiFindInstanceUsedInBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiFindInstanceUsers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetADBType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetADBTypePath() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetADBValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetAggrByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetAggrByIterator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetAllAttrs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetAttr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetAttrBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetAttrDefinition() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetAttrDefinitionBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetAttrs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiGetAttrsBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

SDAI C LIBRARY REFERENCE MANUAL

56
57
58
59
59
60
61
62
63
64
65
65
66
67
67
68
69
69
70
71
71
72
72
73
74
74
75
76
77
77
78
79
80
80
81
82
83
84
84
85
86
87
88
89
89
91

CONTENTS

4.60
4.61
4.62
4.63
4.64
4.65
4.66
4.67
4.68
4.69
4.70
4.71
4.72
4.73
4.74
4.75
4.76
4.77
4.78
4.79
4.80
4.81
4.82
4.83
4.84
4.85
4.86
4.87
4.88
4.89
4.90
4.91
4.92
4.93
4.94
4.95
4.96
4.97
4.98
4.99
4.100
4.101
4.102
4.103
4.104
4.105

VI

sdaiGetComplexEntity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
sdaiGetComplexEntityBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
sdaiGetDescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
sdaiGetEntity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
sdaiGetEntityExtent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
sdaiGetEntityExtentBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
sdaiGetInstanceModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
sdaiGetInstanceType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
sdaiGetLowerIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
sdaiGetMemberCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
sdaiGetPersistentLabel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
sdaiGetSessionId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
sdaiGetSchema() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
sdaiGetSchemaInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
sdaiGetUpperIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
sdaiInsertAfter() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
sdaiInsertBefore() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
sdaiInsertByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
sdaiInsertNestedAggrAfter() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
sdaiInsertNestedAggrAfterADB() . . . . . . . . . . . . . . . . . . . . . . . . . . 104
sdaiInsertNestedAggrBefore() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
sdaiInsertNestedAggrBeforeADB() . . . . . . . . . . . . . . . . . . . . . . . . . 105
sdaiInsertNestedAggrByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
sdaiInsertNesterAggrByIndexADB() . . . . . . . . . . . . . . . . . . . . . . . . 106
sdaiIsInstanceOf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
sdaiIsInstanceOfBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
sdaiIsEqual() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
sdaiIsKindOf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
sdaiIsKindOfBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
sdaiIsMember() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
sdaiIsSDAIKindOf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
sdaiIsSDAIKindOfBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
sdaiIsSDAISubtypeOf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
sdaiIsSDAISubtypeOfBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
sdaiIsSubtypeOf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
sdaiIsSubtypeOfBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
sdaiLogicalCompare() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
sdaiNearCopyInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
sdaiNext() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
sdaiOpenRepository() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
sdaiOpenRepositoryBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
sdaiOpenSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
sdaiPrevious() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
sdaiPromoteModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
sdaiPutADBTypePath() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
sdaiPutADBValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

STEP TOOLS, INC.

CONTENTS

4.106
4.107
4.108
4.109
4.110
4.111
4.112
4.113
4.114
4.115
4.116
4.117
4.118
4.119
4.120
4.121
4.122
4.123
4.124
4.125
4.126
4.127
4.128
4.129
4.130
4.131
4.132
4.133
4.134
4.135
4.136
4.137
4.138
4.139
4.140
4.141
4.142
4.143
4.144
4.145
4.146
4.147
4.148
4.149
4.150
4.151

sdaiPutAggrByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiPutAggrByIterator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiPutAllAttrs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiPutAttr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiPutAttrBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiPutAttrs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiPutAttrsBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiRemove() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiRemoveByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiRemoveByIterator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiRemoveModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiRemoveModelBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiRenameModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiRenameSchemaInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiRenameSchemaInstanceBN() . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiResetArrayIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiRestoreErrorHandler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiSaveChanges() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiSetErrorHandler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiTestArrayByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiTestArrayByItr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiTestAttr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiTestAttrBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiUndoChanges() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiUnsetADB() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiUnsetArrayByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiUnsetArrayByItr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiUnsetAttr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiUnsetAttrBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateAggrSizes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateAggrUni() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateArrayNotOptional() . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateAttrTypes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateBinaryWidth() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateGlobalRule() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateGlobalRuleBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateInverseAttrs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateRealPrecision() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateReferenceDomain() . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateRequiredAttrs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateSchemaInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateStringWidth() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateTypePath() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateUniqueness() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateUniquenessBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sdaiValidateWhereRule() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

SDAI C LIBRARY REFERENCE MANUAL

122
123
124
124
125
126
127
128
128
129
129
130
131
131
132
132
133
133
134
135
135
136
137
137
138
139
139
140
140
141
142
142
143
144
144
145
146
147
147
148
149
149
150
151
152
153

VII

CONTENTS

4.152 sdaiValidateWhereRuleBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153


5 Extension Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2
_sdaiAddSchema() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3
_sdaiDisplay() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4
_sdaiDisplayADB() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5
_sdaiDisplayAggr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6
_sdaiDisplayModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7
_sdaiFindModelBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8
_sdaiGenerateFullDictionary() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.9
_sdaiGetAllAttrDefinitions () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.10 _sdaiGetAggr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.11 _sdaiGetAppInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.12 _sdaiGetComplexEntityBN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.13 _sdaiGetDerivedAttrDefinitions() . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.14 _sdaiGetDomainForEntity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.15 _sdaiGetEntityForDomain() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.16 _sdaiGetEntityId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.17 _sdaiGetEntityInModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.18 _sdaiGetErrorName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.19 _sdaiGetExplcitAttrDefinitions() . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.20 _sdaiGetGenerateFullDictionary() . . . . . . . . . . . . . . . . . . . . . . . . . .
5.21 _sdaiGetHeaderDescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.22 _sdaiGetHeaderName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.23 _sdaiGetInstanceSectionModel() . . . . . . . . . . . . . . . . . . . . . . . . . .
5.24 _sdaiGetInverseAttrDefinitions() . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.25 _sdaiGetModel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.26 _sdaiGetProp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.27 _sdaiGetPropType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.28 _sdaiGetRoseAggregate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.29 _sdaiGetRoseDesign() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.30 _sdaiGetRoseStructure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.31 _sdaiGetSchemaList() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.32 _sdaiGetSubtypes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.33 _sdaiGetSupertypes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.34 _sdaiGetUniquenessDefinitions() . . . . . . . . . . . . . . . . . . . . . . . . . .
5.35 _sdaiRemoveProp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.36 _sdaiRescanRepository() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.37 _sdaiSaveAs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.38 _sdaiSetModelFormat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.39 _sdaiSetProp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.40 _sdaiVerbose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

155
155
155
156
156
156
156
157
157
158
158
158
159
159
160
160
161
161
162
162
162
163
164
165
165
165
166
167
167
168
168
168
169
169
169
170
170
171
171
172
173

6 SDAI Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175


6.1
Session Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

VIII

STEP TOOLS, INC.

CONTENTS

6.2
6.3
6.4

Population Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178


Parameter Data Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Dictionary Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

SDAI C LIBRARY REFERENCE MANUAL

IX

CONTENTS

STEP TOOLS, INC.

1 SDAI Overview

1.1

The STEP Standard


The ISO STEP Standards (ISO 10303) define a methods for the exchange of engineering product data. These standards can be grouped into infrastructure components and industry specific information models. The infrastructure components
include the following specifications:

The EXPRESS information modeling language (Part 11)

An EXPRESS-driven data exchange file specification (Part 21)

An EXPRESS-driven data XML file specification (Part 28)

An EXPRESS-driven application programming interface (SDAI) with bindings


to the C, C++, Java, and IDL languages (Parts 22-26)

A conformance testing framework (Part 31)

A library of general purpose information models for things like geometry, topology, product identification, dates, times, etc. (The 40-series parts)

In addition to the infrastructure parts of STEP, the standard includes EXPRESS information models for the exchange of data within a particular industrial domain including Explicit Drafting (Part 201), Associative Drafting (Part 202), Configuration
Controlled 3D Assemblies (Part 203), Automotive Design (Part 214), and many
others (Electrical, Shipbuilding, Sheet Metal, etc.)

SDAI C LIBRARY REFERENCE MANUAL

1 SDAI OVERVIEW

1.2

The SDAI
The Standard Data Access Interface (SDAI) defines an application programming
interface to EXPRESS defined data, such as STEP APs. STEP defines the SDAI operations and information models in Part 22 (ISO 10303-22:1998). Separate bindings
describe how these operations appear in a specific programming language. SDAI
bindings are defined for C, C++, and Java. Bindings for CORBA/IDL and Fortran
were begun but never completed. This document describes the binding for C as it is
defined in Part 24 (ISO 10303-24:2001) and implemented in ST-Developer.
SDAI bindings come in two flavorsearly-bound and late-bound. An early-bound
API defines access functions for a specific EXPRESS schema. Early-bound APIs
are implemented using an EXPRESS compiler that generates code for a schema.
The SDAI C is a late-bound API. Late-bound APIs have a fixed set of functions
that do not change with the schema. A late binding generally uses compiled representation of the EXPRESS schema, called the data dictionary. The SDAI data dictionary is defined in Part 22, Clause 6.

1.3

ST-Developer and the SDAI C


Binding
ST-Developer includes an implementation of the C language binding to the SDAI
(Part 24). This is a late-bound, Ccallable, library of functions which enables applications to access STEP data. The ST-Developer SDAI library features optional support for an EXPRESS interpreter. The interpreter can validate global rules, local
(where) rules; and the calculate the value of derived attributes.

1.3.1

ROSE and the SDAI


In addition to the SDAI C interface, ST-Developer also includes a high performance, C++ interface to STEP data called ROSE. A STEP application can use either or both interfaces. The SDAI interface itself is implemented on top of the
ROSE library, and includes a set of functions which map between the ROSE and the
SDAI views of data. Each interface has some advantages over the other that you
should be aware of when creating an application.
The ROSE library has the following advantages over the SDAI C library:

STEP TOOLS, INC.

1 SDAI OVERVIEW

Applications can either be early-bound or late bound. The C SDAI is exclusively late-bound.

The ROSE library contains advanced traversal and manipulation features that
are not available in the SDAI. While the SDAI is bound by an ISO specification, the ROSE interface has evolved from years of demanding application development, and contains features attuned to the specific needs of STEP
application developers.

ROSE is the native interface for ST-Developer. In the SDAI, there is a translation layer which maps the SDAI data structures to the corresponding ROSE objects. This mapping makes an SDAI application a bit slower and larger than the
corresponding ROSE application.

The ROSE library provides an object-oriented API which leverages the


strengths of the C++ language. The SDAI library provides a function-based interface which is not object-oriented.

The SDAI Library has the following advantages over the ROSE library

1.4

The SDAI library can be utilized from C applications, as well as C++ code. The
ROSE library is exclusively a C++ interface.

The SDAI is an international standard, making code that uses it portable across
SDAI implementations.

The ROSE library can only retrieve the values of explicit attributes; the SDAI
can also obtain the values of derived and inverse attributes. Since the SDAI library includes an EXPRESS interpreter, the SDAI can also validate a data set
against the constraints in its information model, while the ROSE library cannot.

Manual Organization
This manual describes the SDAI library and the techniques necessary to develop
SDAI applications using ST-Developer.
SDAI Programming (Section 2, pp. 5) describes the details necessary develop SDAI
applications with ST-Developer.
SDAI Library Changes (Section 3, pp. 31) summarizes

the differences between var-

ious versions of the SDAI library.

SDAI C LIBRARY REFERENCE MANUAL

1 SDAI OVERVIEW

Function Reference

(Section 4, pp. 43) documents the standard SDAI functions.

Extension Functions (Section

5, pp. 155) documents the ST-Developer extension

functions to the SDAI.


SDAI Schemas (Section 6, pp. 175) describes the EXPRESS information models de-

fined by the SDAI.

1.4.1

Font Conventions
Within the body of a paragraph, functions, keywords, and filenames are shown in
bold, such as libsdai.a or /usr/local/bin. Function names are shown with trailing parenthesis, such as sdaiOpenSession() or sdaiGetAttrBN().
Function prototypes are listed with each parameter on a separate line and the function name set off in bold as shown below.
SdaiAppInstance sdaiCreateInstance(
SdaiModel model,
SdaiEntity entity
);

Programming examples are shown in a separate paragraph, in a typewriter-style


font:
SdaiSet extent = sdaiGetEntityExtentBN (model, "curve");
SditItrerator itor = sdaiCreateIterator (extent);
while (sdaiNext(itor)) {
SdaiInstance inst=NULL;
sdaiGetAggrByItrator (itor, sdaiINSTANCE, &inst);
/* Process the value in the instance */
}

Attributes and entities from EXPRESS information models, are indicated in bold.
When referring to an attribute of a specific entity, the entity name is separated from
the attribute name with a dot such as schema_instance.repository. This refers to the
repository attribute of the schema_instance entity.

STEP TOOLS, INC.

2 SDAI Programming

2.1

Overview
This chapter provides the information necessary to develop applications with STDevelopers SDAI C interface. We describe how to compile and run SDAI application with ST-Developer, followed by a description of the SDAI C data types, and
some programming techniques for manipulating them.

2.2

Compiling and Running SDAI


Applications
To compile an SDAI application, you must tell your compiler to use the SDAI header file and libraries by specifying the ST-Developer include path in the compiler invocation, and also include following the statement in the C code:
#include <sdai.h>

Before you can run the application, you must insure that you have the ROSE metadata and possibly the EXPRESS parse data for your schemas. This information for
many common information models is included with ST-Developer; for other information models, you must use the EXPRESS compiler to generate the data:
% expfront -rose infomodel.exp

SDAI C LIBRARY REFERENCE MANUAL

2 SDAI PROGRAMMING

2.2.1

Compiling SDAI Applications


In every source file that calls an SDAI function, include the <sdai.h> header file.
This file is included in the standard ST-Developer header file directory (pointed to
by the ROSE_INCLUDE environment variable). Link your application against either
the sdai or sdai_validate library and the rose library.
This example shows how to compile a simple SDAI application, sdai_test.c. The
application consists of a single file, are we will compile and link the program in one
step. The command to compile the code on a UNIX system is:
% cc -I$ROSE_INCLUDE sdai_test.c -L$ROSE_LIB -lsdai -lrose

or, on a Windows system:


C:> cl /I"%ROSE_INCLUDE%" sdai_test.c /LIBPATH:"%ROSE_LIB%" \
sdai.lib rose.lib

If you are using the sdai_validate version of the library, you must also link against
the advanced EXPRESS interpreter library: expi. On a UNIX system, you must also
link against the system math library (-lm). The above example, on a UNIX workstation, utilizing the interpreter is:
% cc -I$ROSE_INCLUDE sdai_test.c -L$ROSE_LIB -lsdai_validate \
-lexpi -lrose -lm

The same command on a Windows machine is:


C:> cl /I"%ROSE_INCLUDE%" sdai_test.c /LIBPATH:"%ROSE_LIB%" \
sdai_vaildate.lib expi.lib rose.lib

2.2.2

The SDAI Dictionary


The data dictionary describes the structure of an information model to the application. For more information about the contents of the dictionary, see Dictionary Schema (Section 6.4, pp. 183). The SDAI library generates the dictionary at run-time
from a ROSE schema file, and an EXPRESS parse model. If the EXPRESS parse
data is absent or is an old version, the library generated a limited form of the dictionary, which is sufficient for many SDAI applications. With the parse data, the SDAI
to generates a complete, correct dictionary containing all the type, rules, and attributes in the EXPRESS information model.
Like all ST-Developer applications, the SDAI requires that you have a ROSE schema file for each information model you wish to use. The release includes schema

STEP TOOLS, INC.

2 SDAI PROGRAMMING

files for many of the standard schemas (in $ROSE/system_db/schemas); if you are
using one of these schemas, the necessary information has already been generated.
If you do not already have the ROSE schema file, use the EXPRESS compiler to
create the ROSE schema file and the EXPRESS parse data with the command:
% expfront -rose <expressfile>

where <expressfile> is the EXPRESS file containing the information model your
application uses. If you do not require the parse data, you can add the -writenone
option to the EXPRESS compiler command line. The parse data is required in the
following cases:

Your application uses the EXPRESS interpreter to get the values for derived attributes, or to validate rules

Your application needs to access the values of inverse attributes.

The application examines the SDAI dictionary, and needs to determine the exact type of every attribute. (Without the complete dictionary, you will not get
the correct types of defined types of primitives, except in SELECTS)

As with the ROSE schema files, ST-Developer provides the EXPRESS parse data
models for a common set of information models. You will only need to generate the
parse data for those information models that are not provided in ST-Developer.
The EXPRESS parse files can be large, and can take time to load. If your application
does not require the parse data, you can request that the SDAI library not load it. In
this case, the data dictionary will be the limited version, based only on the information in the ROSE schema file. You can control the operation of this feature with the
_sdaiGenerateFullDictionary() (Section 5.8, pp. 157) function. If you call this function with a value of sdaiFALSE, the EXPRESS parse data is not loaded. The following code disables the generation of the full dictionary:
_sdaiGenerateFullDictionary(sdaiFALSE);

The dictionary for the SDAI internal models (session, dictionary, etc.) is generated
the same way in the sdaiOpenSession() function, so you may not want to turn off
dictionary generation until after you open the session since a number of commonly
accessed items in the SDAI dictionary are actually inverse attributes.

SDAI C LIBRARY REFERENCE MANUAL

2 SDAI PROGRAMMING

2.3

SDAI Data Types


The SDAI provides access to EXPRESS defined data from the C programming language. This section describes how EXPRESS data types are mapped to C data types
by the SDAI. These types are all defined in the <sdai.h> header file.

2.3.1

SDAI Constants
The <sdai.h> header file defines a number of constants. All constants start with lowercase sdai, with the actual constant name in all capitals.

2.3.2

sdaiNULL

Instance or aggregate which does not exist

sdaiTRUE
sdaiFALSE
sdaiUNKNOWN

Boolean and Logical values

sdaiBIT0
sdaiBIT1

Binary Values

sdaiE
sdaiPI

Mathematical constant e (2.718281...)


Mathematical constant pi (3.141592...)

Primitive Types
The SDAI binding defines several data types which are used for parameters for the
functions defined in the binding. In general, you should use the SDAI defined type,
rather than the underlying C type, since the underlying type may change from one
version or implementation to another. These types are:
EXPRESS Type

SDAI C Type

BINARY
BOOLEAN
ENUMERATION
INTEGER
LOGICAL
NUMBER
REAL
STRING

SdaiBinary
SdaiBoolean
SdaiEnum
SdaiInteger
SdaiLogical
SdaiReal
SdaiReal
SdaiString

Underlying C Type
SdaiBit *
int
char *
long
int
double
double
char *

Strings are ordinary NULL terminated C strings, thus SDAI strings can be used as
arguments for the standard C string functions.

STEP TOOLS, INC.

2 SDAI PROGRAMMING

A binary is represented as a NULL-terminated string of sdaiBIT0 and sdaiBIT1. In


this implementation, this means that binaries are ASCII strings, of the characters 0
and 1. To get the length of a binary, use the C function strlen().
Enumeration values are represented as (NULL-terminated) strings.

2.3.3

Entity Instances
An entity instance (or just instance) is represented by the C type SdaiInstance.
There are a number of more specific types of SdaiInstance, and these may be used
where a handle of type SdaiInstance is required. They are organized into the following conceptual type hierarchy.
SdaiInstance
SdaiAppInstance
SdaiModel
SdaiRep
SdaiSession
SdaiAttr
SdaiExplicitAttr
SdaiNamedType
SdaiEntity
SdaiDefinedType
SdaiWhereRule
SdaiUniRule
SdaiGlobalRule
SdaiSchema
SdaiSchemaInstance
SdaiTrx

Thus, a handle of type SdaiModel may be used as a parameter to the function


sdaiGetAttrBN, even though the prototype requires an argument of type
SdaiInstance.

2.3.4

Aggregates
Aggregates are represented by the C type SdaiAggr. Aggregates consist of bags,
sets, arrays and lists, and are conceptually organized into the following type hierarchy:
SdaiAggr
SdaiOrderedAggr
SdaiArray
SdaiList
SdaiUnorderedAggr

SDAI C LIBRARY REFERENCE MANUAL

2 SDAI PROGRAMMING

SdaiSet
SdaiBag

Any more specific type may be used in place of a more general type. For example,
any of the above types may be used where an SdaiAggr is required.

2.4

SDAI Operations
An SDAI session represents a set of operations upon a data set. All SDAI operations
occur within the context of a session. The STEP data instances themselves are contained in SDAI models. Each model is contained in a repository. An SDAI application must manipulate sessions, repositories and models to access the actual STEP
data. In general, an SDAI application performs the following steps:
open session
open repository
open model(s)
manipulate data
close model(s)
close repository
close session

This section describes how to perform these operations with the SDAI library.

2.4.1

Memory Management
Strings, enumerations, and binaries are represented as NULL terminated C strings.
When a value of one of these types is passed as a parameter to the SDAI library, the
library copies the value, if necessary. After the call, the application may dispose of
the original string.
When the SDAI returns such a value to the application, the application should treat
it as read-only. The contents of the memory will not be disturbed at least until the
next call that returns a string, binary, or enumerator.

2.4.2

Error Handling
The SDAI identifies exceptional events by generating errors. Application are notified of errors in two ways error handler functions, and error codes. In addition,

10

STEP TOOLS, INC.

2 SDAI PROGRAMMING

many API functions may return special values to indicate that something exceptional occurred during the call.
When an error occurs, the SDAI calls an error handler. The default error handler
prints a message identifying the error on standard output and continues. You may
wish to replace the error handler with your own function to customize the error handling of your SDAI application. The library maintains a stack of error handlers. To
push a handler onto the stack, use the sdaiSetErrorHandler() function. To pop the top
handler off the stack and restore a previous handler, use the sdaiRestoreErrorHandler() function.
The sdaiErrorQuery() function returns the error code of the most recent error to occur in the application. The error that is reported did not necessarily originate from
the most recent SDAI call, but rather was the result of the most recent call which
resulted in an error. This function also clears the error code. If you need to determine if a specific call completed without error, call sdaiErrorQuery() before and after the callfirst to clear any old error code, and then after the call to obtain the
error that resulted from your call.
The following error codes are defined by the binding:
sdaiNO_ERR
sdaiSS_OPN
sdaiSS_NAVL
sdaiSS_NOPN
sdaiRP_NEXS
sdaiRP_NAVL
sdaiRP_OPN
sdaiRP_NOPN
sdaiTR_EAB
sdaiTR_EXS
sdaiTR_NAVL
sdaiTR_RW
sdaiTR_NRW
sdaiTR_NEXS
sdaiMO_NDEQ
sdaiMO_NEXS
sdaiMO_NVLD
sdaiMO_DUP
sdaiMX_NRW
sdaiMX_NDEF
sdaiMX_RW
sdaiMX_RO
sdaiSD_NDEF
sdaiED_NDEF
sdaiED_NDEQ
sdaiED_NVLD
sdaiRU_NDEF
sdaiEX_NSUP
sdaiAT_NVLD

SDAI C LIBRARY REFERENCE MANUAL

No error
Session open
SDAI not available
Session is not open
Repository does not exist
Repository not available
Repository open
Repository is not open
Transaction ended abnormally
Transaction exists
Transaction currently not available
Transaction read-write
Transaction not read-write
Transaction does not exist
SDAI-model not domain equivalent
SDAI-model does not exist
SDAI-model invalid
SDAI-model duplicate
SDAI-model access not read-write
SDAI-model access not defined
SDAI-model access read-write
SDAI-model access read-only
Schema definition not defined
Entity definition not defined
Entity definition not domain equivalent
Entity definition invalid
Rule not defined
Expression evaluation not supported
Attribute invalid

11

2 SDAI PROGRAMMING

sdaiAT_NDEF
sdaiSI_DUP
sdaiSI_NEXS
sdaiEI_NEXS
sdaiEI_NAVL
sdaiEI_NVLD
sdaiEI_NEXP
sdaiSC_NEXS
sdaiSC_EXS
sdaiAI_NEXS
sdaiAI_NVLD
sdaiAI_NSET
sdaiVA_NVLD
sdaiVA_NEXS
sdaiVA_NSET
sdaiVT_NVLD
sdaiIR_NEXS
sdaiIR_NSET
sdaiIX_NVLD
sdaiER_NSET
sdaiOP_NVLD
sdaiFN_NAVL
sdaiAB_NEXS
sdaiSY_ERR

2.4.3

Attribute not defined


Schema instance duplicate
Schema instance does not exist
Entity instance does not exist
Entity instance not available
Entity instance invalid
Entity instance not exported
Scope does not exist
Scope exists
Aggregate instance does not exist
Aggregate instance invalid
Aggregate instance is empty
Value invalid
Value does not exist
Value not set
Value type invalid
Iterator does not exist
Current member is not defined
Index invalid
Event recording not set
Operator invalid
Function not available
ADB does not exist
Underlying system error

SDAI Session
All SDAI operations must be performed in the context of a session. To begin a session call sdaiOpenSession(). After you are finished with the SDAI, use sdaiCloseSession() to terminate the session. There may only be one session open at a time,
but sessions may be opened and closed multiple times during the life of the process.
The sdaiOpenSession() function returns the handle of an entity instance for the session object. This instance is known as the SDAI session object. The handle of the
session object must be saved for future calls such as sdaiOpenRepository() and
sdaiCloseSession(). The SDAI session object provides an application access to the
SDAI implementations internal state. The session object is an entity instance, in the
session schema, defined in Part 22 as:
ENTITY sdai_session;
sdai_implementation : implementation;
recording_active
: BOOLEAN;
errors
: LIST [0:?] OF error_event;
known_servers
: SET [1:?] OF sdai_repository;
active_servers
: SET [1:?] OF sdai_repository;
active_models
: SET [1:?] OF sdai_model;
data_dictionary
: OPTIONAL schema_instance;
INVERSE
active_transaction : SET [0:1] OF sdai_transaction

12

STEP TOOLS, INC.

2 SDAI PROGRAMMING

FOR owning_session;
END_ENTITY;

2.4.4

Repositories
A repository is a collection of SDAI models which represents the physical organization of a database. A repository must be opened before its contents can be accessed. This implementation provides a repository named standard_3.0 which
contains files in the search path defined by the ROSE_DB environment variable. You
can use rose ls to see which models are in the current path. In the session model,
a repository is defined by the entities sdai_repository and sdai_repository_contents:
ENTITY sdai_repository;
name
: STRING;
contents
: sdai_repository_contents;
description : STRING;
INVERSE
session : sdai_session FOR known_servers;
UNIQUE
UR1: name, session;
END_ENTITY;
ENTITY sdai_repository_contents;
models : SET[0:?] OF sdai_model;
schemas : SET[0:?] OF schema_instance;
INVERSE
repository : sdai_repository FOR contents;
END_ENTITY;

To open a repository, use either sdaiOpenRepository() (Section 4.99, pp. 117) or


sdaiOpenRepositoryBN() (Section 4.100, pp. 118). If you know the name of the repository, use sdaiOpenRepositoryBN():
SdaiSession sess;
SdaiRep repo;
session = sdaiOpenSession();
repo = sdaiOpenRepositoryBN (session, "standard_3.0");

If you do not know which repositories will be available, you can examine the set of
repositories provided in the known_servers attribute of the SDAI session object,
and open any or all of the repositories found there. The following program prints
out all the repositories available to the application:
#include <sdai.h>
$include <stdio.h>
int main()

SDAI C LIBRARY REFERENCE MANUAL

13

2 SDAI PROGRAMMING

{
SdaiSession sess;
SdaiAggr reposet=NULL;
SdaiIterator itor;
SdaiString reponame;
SdaiInstance repo;
sess = sdaiOpenSession ();
sdaiGetAttrBN (sess, "known_servers", sdaiAGGR, &reposet);
itor = sdaiCreateIterator (reposet);
while (sdaiNext (itor)) {
repo = NULL;
sdaiGetAggrByIterator (itor, sdaiINSTANCE, &repo);
if (!repo) continue; /* paranoia check, should not happen*/
sdaiGetAttrBN (repo, "name", sdaiSTRING, &reponame);
printf ("Repository: %s\n", reponame);
}
sdaiCloseSession (sess);
return 0;
}

2.4.5

Schema Instances
A schema instance is a set of models which are conceptually related on some way.
Schema instances are used to define a scope over which global and uniqueness rules
of an EXPRESS schema are evaluated. A model may belong to multiple schema instances.
Schema are represented as a rose file in a repository based on the
schema_instance_schema. This schema contains the following entity which defines a single schema instance:
ENTITY sdai_schema_instance;
associated_models : SET [0:?] OF STRING;
native_schema
: STRING;
change_date
: STRING;
validation_date : STRING;
validation_result : LOGICAL;
validation_level : INTEGER;
END_ENTITY;

When a schema instance is accessed, the SDAI library converts the schema instance
to the internal form defined in the population model:
ENTITY schema_instance;
name
: STRING;
associated_models : SET [0:?] OF sdai_model;
native_schema
: schema_definition;

14

STEP TOOLS, INC.

2 SDAI PROGRAMMING

repository
: sdai_repository;
change_date
: OPTIONAL time_stamp;
validation_date : time_stamp;
validation_result : LOGICAL;
validation_level : INTEGER;
UNIQUE
UR1: name, repository;
WHERE
WR1: SELF IN SELF.repository.contents.schemas;
END_ENTITY;

As an extension to the standard, ST-Developer allows you to specify a model instead of a schema instance for most functions that take a schema instance as a parameter.

2.4.6

Models
Each repository contains a number of models. In the ST-Developer implementation,
a model corresponds to a RoseDesign which, in turn, corresponds to a STEP
Part 21, or ROSE file (*.stp or *.rose).
A model may be opened in either read-only or read-write mode. In a read-only model, any operation which changes the contents of the model is disallowed and generates an error. When an attribute refers to an instance in a different model, the second
model is opened implicitly in read-only mode, if it is not already open. In the session model, a model is defined by the entities sdai_model and sdai_model_contents:
ENTITY sdai_model;
name
: STRING;
contents
: sdai_model_contents;
underlying_schema : schema_definition;
repository
: sdai_repository;
change_date
: OPTIONAL time_stamp;
mode
: OPTIONAL access_type;
INVERSE
associated_with : SET [0:?] OF schema_instance FOR
associated_models;
UNIQUE
UR1: repository, name;
WHERE
WR1: SELF IN SELF.repository.contents.models;
END_ENTITY;
ENTITY sdai_model_contents;
instances
: SET[0:?] OF entity_instance;
folders
: SET[0:?] OF entity_extent;
populated_folders : SET[0:?] OF entity_extent;
END_ENTITY;

SDAI C LIBRARY REFERENCE MANUAL

15

2 SDAI PROGRAMMING

Use the sdaiAccessModelBN() (Section 4.3, pp. 48) function to open a model by
name. If you do not know the model's name, you can look through the set of models
associated with a repository by examining contents.sdai_models attribute in an
open repository.
New models can be created with sdaiCreateModelBN() (Section 4.22, pp. 63) or sda(Section 4.21, pp. 62). After a new model is created, you will need
to open it (in read-write mode) before any data can be stored in it:

iCreateModel()

SdaiModel newmod = sdaiCreateModelBN ("modname","config_control_design");


sdaiAccessModel (newmod, sdaiRW);

2.4.7

Get and Put Functions


There are a number of functions in the binding which retrieve data for the application. Rather than having a separate get and put function for every primitive type, the
SDAI provides a single version of each get or put function which takes a parameter
identifying the type that is requested. To specify the type of the value being accessed, the <sdai.h> header defines the enumeration type SdaiPrimitiveType which includes the following values:
sdaiAGGR
sdaiBINARY
sdaiBOOLEAN
sdaiENUM
sdaiINSTANCE
sdaiINTEGER
sdaiLOGICAL
sdaiREAL
sdaiSTRING

Get Functions
All get functions such as sdaiGetAttr() (Section 4.54, pp. 86) or sdaiGetAggrByIterator() (Section 4.52, pp. 84) have the same final two parameters: one of type
sdaiPrimitiveType called type and one of type void * named value. To use these functions, you must pass the address of an object of the which the SDAI will fill in. The
type parameter to identifies the primitive type of object you have passed in. The
specified type must correspond to the C type that you are passing in, and not necessarily to the EXPRESS type of the attribute you are retrieving. If necessary and possible, the SDAI library converts the EXPRESS representation to the requested type.
If this conversion is not possible an error, usually sdaiVT_NVLD (value type is invalid), is generated.

16

STEP TOOLS, INC.

2 SDAI PROGRAMMING

The following code fragment retrieves the value of the attribute named fooatt from
instance inst, using sdaiGetAttrBN() (Section 4.55, pp. 87). The return value (the
variable val) is initialized to sdaiNULL, so that the application can determine if the
call was successful. If sdaiGetAttrBN() fails, an error is generated, and the value is
never filled in, leaving val with its previous, undefined value. This may result in a
segmentation fault, or other undefined behavior, if the garbage value is ever used in
a future SDAI call.
SdaiAppInstance val = sdaiNULL;
sdaiGetAttrBN (inst, "fooatt", sdaiINSTANCE, &val);

Because sdaiGetAttrBN() returns the contents of val, it is possible to chain multiple


calls.
SdaiInstance ival=sdaiNULL;
SdaiREAL realval;
sdaiGetAttrBN (sdaiGetAttrBN(inst, "fooatt", sdaiINSTANCE, &inst1),
"baratt", sdaiREAL, &realval);

If the requested type had been a primitive (That is, for example, a string, integer, or
real) the function would have returned the address that was passed in as parameter
value, rather that the value that was placed there.

Put Functions
The SDAI provides a number of functions which allow an application to update the
data. Theses functions include sdaiPutAttr() (Section 4.109, pp. 124), sdaiPutADBValue() (Section 4.105, pp. 122), sdaiAdd() (Section 4.4, pp. 49), and many others.
All of the put functions require the same final two parameters: one of type SdaiPrimitiveType identifying the type of the data, and another of the requested type containing the actual data.
Warning The get functions final parameter is specified in the header files as ...,
so be aware that your C compiler is not be able to any catch type mismatch errors,
which could result in undefined behavior.

As in the get functions, the type parameter specifies the type of the parameter, and
not the type of the underlying attribute which is being set. The value is converted
when possible. If the value cannot be converted to the underlying type, the library
generates an error (usually sdaiVT_NVLD).
The following example uses the sdaiPutAttr() function to put a real value into an attribute named realatt:
sdaiPutAttrBN (inst, "realatt", sdaiREAL, 3.651);

SDAI C LIBRARY REFERENCE MANUAL

17

2 SDAI PROGRAMMING

You could also specify the value as an integer, and the interface converts it to a real
value.
sdaiPutAttrBN (inst, "realatt", sdaiRINTEGER, 42);

2.4.8

Instances
Each entity instance consists of a set of attributes, as defined in an EXPRESS information model. These attributes may be retrieved with the functions sdaiGetAttr()
and sdaiGetAttrBN(). The sdaiCreateInstance() (Section 4.18, pp. 59) and sdaiCreateInstanceBN() (Section 4.19, pp. 60) functions create new entity instance.
SdaiInstance inst;
inst = sdaiCreateInstanceBN (model, "cartesian_point");

Each model contains a set of entity extents. An entity extent is the set of all the instances of a specific type and its subtypes in a model. These provide one common
method for beginning traversals of a models data. The entity extents can be found
in the sdai_model_contents in the folders and populated_folders attributes, or by
using the convenience functions sdaiGetEntityExtent() (Section 4.64, pp. 95) and
sdaiGetEntityExtentBN() (Section 4.65, pp. 95). The following code outlines such a
traversal over all objects of type curve.
SdaiSet extent = sdaiGetEntityExtentBN (model, "curve");
SditItrerator itor = sdaiCreateIterator (extent);
while (sdaiNext(itor)) {
SdaiInstance inst=NULL;
sdaiGetAggrByItrator (itor, sdaiINSTANCE, &inst);
/* Process the value in the instance */
}

2.4.9

Attribute Data Blocks


The SDAI interface provides a mechanism for dealing with arbitrarily-typed data
known as Attribute Data Blocks (ADBs). An ADB is a strongly typed union of all
the SDAI-defined C types. An ADB may be used in place of a value in any get or
put functions.
An ADB is created by using sdaiCreateADB() (Section 4.10, pp. 53) to create an
ADB and sets its value, or by using sdaiCreateEmptyADB() (Section 4.17, pp. 59) to
create an ADB without a value. Set the ADBs value with sdaiPutADBValue() (Section 4.105, pp. 122) or by passing the ADB to a get function.

18

STEP TOOLS, INC.

2 SDAI PROGRAMMING

Attribute Data Blocks provide a convenient way to copy attributes from one instance to another without having to worry about the actual underlying type. Without
ADBs, this would require a large switch statement to process every possible attribute type. The following function copies a single attribute from one instance to
another, assuming that the two instances are the same type. This code correctly copies the values of SELECT typed attributes.
void copyAttr (SdaiAttribute att, SdaiAppInstance src, SdaiAppInstance dest)
{
SdaiADB adb = sdaiCreateEmptyADB();
sdaiGetAttr (src, att, sdaiADB, &adb); /*Get the value to the ADB*/
sdaiPutAttr (dest, att, sdaiADB, adb); /* Put the value */
}

2.4.10

Aggregates
An aggregate is a collection of values defined in an EXPRESS information model.
There are four basic types of aggregates: bags, sets, lists and arrays. Bags and sets
are unordered, arrays and lists are ordered; arrays and bags may contain the same
element multiple times; sets and lists may not. To provide these semantics, the
SDAI provides several methods to manipulate arrays.
If an aggregate-typed attribute is unset (such as when its owning instance is newly
created), the aggregate must be created with sdaiCreateAggr() (Section 4.11, pp. 54)
before values can be added to the aggregate.
An iterator is an SDAI-defined object which traverses an aggregate. Unlike other
access methods, iterators can be used to access on all types of aggregates, and provide a simple way to traverse them. The following is an example of an array traversal using an iterator:
SdaiItr itor; /* The iterator */
itor = sdaiCreateIterator (agg); /* Create an iterator over the aggregate*/
while (sdaiNext (itor))
{
/* Get the value. Replace TYPE on the next line with the actual type*/
sdaiGetAggrByIterator (itor, TYPE, &VALUE);
/* Process the value */
}
sdaiDeleteIterator (itor); /* Clean up */

There are other methods available for retrieving the elements of aggregates, which
allow random access by index, such as sdaiGetAggrByIndex() (Section 4.51, pp. 84).
These may only be used on ordered aggregates. This restriction is strictly enforced
for all data types.

SDAI C LIBRARY REFERENCE MANUAL

19

2 SDAI PROGRAMMING

Non Persistent Lists


Non Persistent Lists (NPLs) are used as parameters to several SDAI functions, such
as sdaiFindInstanceUsedIn() (Section 4.45, pp. 79), where the function may fill the
NPL with the appropriate values. NPLs may also be used for application specific
purposes. The may only contain entity instances (no aggregates or primitives). Use
the sdaiCreateNPL() (Section 4.29, pp. 68) function to create a new, empty NPL. After you are finished using the NPL, use sdaiDeleteNPL() (Section 4.36, pp. 72) to
free the memory used by the nonpersistent list.

2.4.11

SELECTS
A SELECT data type is an EXPRESS defined type whose value is one of a set of
named types. Each of the types that a SELECT may have is called a element. SELECT types are similar to C union constructs, except that the elements of a SELECT are strongly typed. The STEP AP information models utilize SELECT types
to constrain attribute values in ways would be impossible or awkward to do with
inheritance. A select is defined in EXPRESS as follows:
TYPE sel = SELECT (type1, type2, type3);
END_TYPE;

The element may not be an EXPRESS primitive type such as INTEGER, REAL or
STRING. A select can contain defined types of primitives in the SELECT:
TYPE realval = REAL;
END_TYPE;
TYPE sel = SELECT (type1, realval);
END_TYPE;

Since SELECT types are themselves named types, one SELECT may include another as a element:
TYPE innersel = SELECT (type1, type2);
END_TYPE;
TYPE outersel = SELECT (innersel, type3);
END_TYPE;

To use the SDAI to retrieve the value of a SELECT-typed attribute, use either the
sdaiGetAttr() or the sdaiGetAttrBN() function. If you do not know the actual primitive type, you must use an Attribute Data Block (ADB) to retrieve the value, then
extract it from there. Using the following EXPRESS type definition:
TYPE sel = SELECT (type1, realval);

20

STEP TOOLS, INC.

2 SDAI PROGRAMMING

END_TYPE;
TYPE seltype = SELECT (a, realval);
END_TYPE;
ENTITY a;
END_ENTITY;
ENTITY b;
foo : seltype;
END_ENTITY;

if you have an instance of ENTITY b stored in the variable b_val, and you wish to
retrieve the value of its foo attribute, you could use the following code:
SdaiInstance b_val;
SdaiReal rval;
sdaiGetAttrBN (b_val, foo, sdaiREAL, &rval);

In the proceeding example, the sdaiGetAttrBN() call will only succeed if the value
of the attribute is a realval type, which in turn is defined as a REAL. If the value of
the SELECT attribute was not a realval, the SDAI implementation would generate
a VT_NVLD error. If the type of the SELECT is a reference to an instance of entity
a, you can retrieve the value as follows:
SdaiInstance instval;
sdaiGetAttrBN (b_val, "foo", sdaiINSTANCE, &instval);

In the proceeding example, we assumed a priori knowledge of the SELECT attributes type. In a non-trivial SDAI application, this is not likely to be the case, so
you would use an Attribute Data block to get the value of the attribute:
SdaiADB adb = sdaiCreateEmptyADB();
sdaiGetAttrBN (b_val, "foo", sdaiADB, &adb);

Now the attribute value in stored in the ADB. We can examine type of the value
and take appropriate action:
SdaiPrimitiveType type = sdaiGetADBType (adb);
if (type == sdaiREAL) {
printf ("We have a REAL\n");
} else if (type == sdaiINSTANCE) {
printf ("We have a instance\n");
}

In some cases, the underlying primitive type in insufficient to properly identify the
type of the SELECT attribute. For these cases the SDAI provides the sdaiGetADBTypePath() (Section 4.49, pp. 82) function. This function returns the exact type of

SDAI C LIBRARY REFERENCE MANUAL

21

2 SDAI PROGRAMMING

a SELECT. In the following EXPRESS, the mreal type has several elements that
are based on the REAL primitive type.
TYPE a_real = REAL;
END_TYPE;
TYPE b_real = REAL;
END_TYPE;
TYPE c_real = REAL;
END_TYPE;
TYPE mreal = SELECT (a_real, b_real, c_real);
END_TYPE;
ENTITY mreal_ent;
x : mreal;
END_ENTITY;

In this example, we will examine the value of the x attribute of an mreal_ent and
determine if its type is a_real, b_real, or a c_real. This is done by getting the value
(with sdaiGetAttrBN()) into an ADB, then using sdaiGetADBTypePath() to obtain the
exact type.
SdaiADB adb = sdaiCreateEmptyADB();
SdaiInstance val; /* This is an mreal_ent */
SdaiInteger count;
SdaiString * att_path;
char * sel_type;
sdaiGetAttrBN (val, "x", sdaiADB, &adb);
att_path = sdaiGetADBTypePath (adb, &count);
if (count != 1) {
/* We have a problem. */
fprintf (stderr, "Expecting exactly one element in the type type\n");
}
sel_type = att_path[0];
if (!strcmp (sel_type, "a_real") {
/* We have a a_real */
SdaiReal val;
sdaiGetADBValue (adb, sdaiREAL, &val);
printf ("a_real: value=%f\n", val);
}
else if (!strcmp (sel_type, "b_real") {
/* We have a b_real */
} else if (!strcmp (sel_type, "c_real") {
/* We have a c_real */
} else {
fprintf (stderr, "Got unexpected type: %s\n", sel_type);
}

22

STEP TOOLS, INC.

2 SDAI PROGRAMMING

When the value of a SELECT typed attribute is itself another SELECT, the
sdaiGetADBTypePath() function returns an array of strings identifying the element
of each nested SELECT in the attributes value. In the following EXPRESS, the
value of attribute a of entity entval, is always ultimately a REAL, but there is a number of possible types that the SELECT can have.
TYPE r1 = REAL;
END_TYPE;
TYPE r2 = r1;
END_TYPE;
TYPE sel1 = SELECT (r1, r2);
END_TYPE;
TYPE sel2 = SELECT (r1, sel1);
END_TYPE;
TYPE sel3 = SELECT (sel1, sel2);
END_TYPE;
ENTITY entval;
a : sel3;
END_ENTITY;

Consider in instance of sel3 with a type consisting of the following SELECT elements:
sel3 -> sel1 -> r2

In this case, the type path would for the attribute would be {sel1, r2}. Note that
r1 is not in the path because it is a not a element, but rather is just the definition for
the r2 type.
To set the value of a SELECT-typed attribute use the sdaiPutAttr() or
sdaiPutAttrBN() functions. Unless you are putting an entity instance into the SELECTtyped attribute, you must use an ADB and set the type path with the
sdaiPutADBTypePath() function. If you attempt to set a primitive value directly, or
do not set the type path, you will get a VT_NVLD error.
Using the EXPRESS above, we will create and populate an instance of entval:
SdaiInstance val;
SdaiModel model;
SdaiADB adb;
SdaiString type_path[] = {"sel1", "r2"};
int element_count = sizeof(type_path)/sizeof(type_path[0]);
val = sdaiCreateInstanceBN (model, "entval");

SDAI C LIBRARY REFERENCE MANUAL

23

2 SDAI PROGRAMMING

adb = sdaiCreateADB (sdaiREAL, 2.56);


sdaiPutADBTypePath (adb, element_count,type_path);
sdaiPutAttrBN (val, "a", sdaiADB, adb);

When you use the sdaiPutADBTypePath() function, you specify an array of SELECT names identifying the type of the attribute. You do not have to specify every
element though, but only the final element for primitive types. For entity types, you
can omit the type path all together. If you do not provide enough information to
uniquely identify the type path, the system will choose a path which can hold the
value. If the path specified is impossible to instantiate, the put function generates a
VT_NVLD error. If in the previous example the type_path variable were initialized
as:
SdaiString type_path[] = {rx};

The sdaiPutAttrBN() function would generate an error because there is no rx type in


the sel3 SELECT type. On the other hand, is you had initialized the path with the
as follows:
SdaiString type_path[] = {r2};

the sdaiPutAttrBN function would still correctly update the value, but the exact type
path used could be anything that ends in r2. The exact path chosen would be either
{sel1, r2} or {sel2, sel1, r2}.
Part 21 exchange file only keep enough path information to validate WHERE rules
of defined types. This means that the previous examples, when written to a STEP
file, generate the following line:
#30=ENTVAL(R2(2.56));

Note that there is no sel1 or sel2 anywhere in the entity record.

2.4.12

Inverse Attributes
An inverse attribute is an EXPRESS attribute which is defines a USEDIN construct
as a specific attribute. You must have the full dictionary available in order to access
inverse attribute values. To retrieve an inverse attribute use sdaiGetAttr() or
sdaiGetAttrBN(), with a type of sdaiAGGR, (or sdaiADB). The inverse attribute will
be constructed and placed into a newly created NPL. This NPL will only valid until
the next inverse attribute is queried. While the SDAI may delete the NPL automatically, the application can also free the non-persistent list with sdaiDeleteNPL()
when it is finished using it. (This is a ST-Developer extension to Part 24 for backward compatibility.)

24

STEP TOOLS, INC.

2 SDAI PROGRAMMING

SdaiNPL inv= sdaiNULL;


sdaiGetAttrBN (inst, "invatt", sdaiAGGR, &inv);
/* Do something with the values */
sdaiDeleteNPL (inv); /* optional as per IS */

In EXPRESS, inverse attributes can have a type of an entity or an aggregate, in the


SDAI an inverse attribute is always returned as an aggregate. In this implementation
of the SDAI, a traversal over the entire model is required to evaluate an inverse attribute, making it an expensive operation. Thus, inverse values should be cached by
the application when possible.

2.4.13

Dictionary Data
The SDAI dictionary contains a representation of the EXPRESS information models used in the session. While it is possible to navigate the dictionary from the session object, it is generally not necessary to do so. The SDAI provides functions to
retrieve the most commonly needed data from the dictionary. These functions include sdaiGetSchema() (Section 4.72, pp. 99), sdaiGetEntity() (Section 4.63, pp.
94), and sdaiGetAttrDefinition() (Section 4.56, pp. 88), which retrieve schemas, entity definitions, and attribute definitions, respectively.
If an operation is performed many times, it is generally better to retrieve the definition from the dictionary and avoid using the functions which perform an operation
by name. Doing so also helps prevent misspelling entity and attribute names in your
application.
For example, the following code which used sdaiGetAttrBN:
sdaiGetAttrBN (inst, "att", sdaiINTEGER, &intval);

performs the exact same function as the following code:


SdaiEntity ent = sdaiGetInstanceType (inst); /* Get the entity definition*/
SdaiAttr att = sdaiGetAttrDefinition (ent, "att"); /* Look up attribute */
sdaiGetAttr (inst, att, sdaiINTEGER, &intval);

The second version is more complex, but if you need to perform the same operation
several times, you can avoid many expensive string comparisons in the SDAI by using sdaiGetAttr(), rather than sdaiGetAttrBN().

SDAI C LIBRARY REFERENCE MANUAL

25

2 SDAI PROGRAMMING

2.4.14

Interfacing with ROSE


The SDAI library is built on top of the ROSE C++ class library, which it uses for
low-level data management and file I/O. It is possible to access and manipulate the
underlying ROSE objects from an SDAI application, however there are several issues that must be considered.

The ROSE class library is not part of the SDAI standard.

Any code that accesses ROSE must be written in C++. The SDAI binding is a
C language interface, so you must compile at least part of your application with
a C++ compiler.

The SDAI interface, and not the ROSE library keeps track of each models access mode (read-only or read-write). The ROSE library is therefore unable to
enforce read-only access to a model. This means that making changes to instances in a read-only model under ROSE may succeed, while the same operation from the SDAI will generate a sdaiMX_NWR error.

Several SDAI functions internally perform ROSE traversals. You should avoid
leaving a traversal open when an SDAI call is made.

The instances and aggregates of the SDAI session model are handled internally by
the SDAI and do not have an associated ROSE object. If you attempt to retrieve the
RoseObject pointer to such an object, a NULL value is returned. The header <rose.h>
must be included before <sdai.h>. If this is not done, the ROSE specific declarations
in <sdai.h> will not be made available to the application.
The SDAI/ROSE interface consists of the following functions:
RoseStructure* _sdaiGetRoseStructure (SdaiAppInstance inst);
RoseAggregate* _sdaiGetRoseAggregate (SdaiAggr inst);
SdaiAppInstance _sdaiGetAppInstance (RoseStructure * obj);
SdaiAggr _sdaiGetAggr (RoseAggregate * obj);
RoseDesign * _sdaiGetRoseDesign (SdaiModel mod);
SdaiModel _sdaiGetModel (RoseDesign * des);
SdaiEntity _sdaiGetEntityForDomain (RoseDomain * dom);
RoseDomain * _sdaiGetDomainForEntity (SdaiEntity ent);
_sdaiGetInstanceSectionModel (SdaiInstance inst);

These functions convert aggregates and instances between ROSE and the SDAI
representations. If the conversion cannot be performed, these functions return
NULL.
A SELECT in the SDAI is almost transparent, while in ROSE, it is represented as
a RoseUnion. RoseUnions may be nested, but in ROSE, a RoseUnion must be explicitly created and populated. If the SELECT is nested, a RoseUnion object must

26

STEP TOOLS, INC.

2 SDAI PROGRAMMING

be created for each level of the SELECT.

2.4.15

Part 21 File Accessor functions


The SDAI library contains a few conveniences functions the access and manipulate
the STEP Part 21 file information. This functionality is provided in three extension
functions which allow you get access the entity identifiers, and the Part 21 header
information.
The _sdaiGetEntityId() (Section 5.16, pp. 161) function returns the STEP Entity ID
(the #number) from a STEP file. This is useful for identifying specific instances in
error messages.
int id = _sdaiGetEntityId (inst);

The _sdaiGetHeaderDescription() (Section 5.21, pp. 163) and


_sdaiGetHeaderName() (Section 5.22, pp. 164) functions to allow an SDAI application to access and manipulate the Part 21 file header entities. These entities are defined as follows:
ENTITY file_description;
description
: LIST [1:?] OF STRING (256);
implementation_level : STRING (256);
END_ENTITY;
ENTITY file_name;
name
: STRING (256);
time_stamp
: STRING (256);
author
: LIST [1:?] OF STRING (256);
organization : LIST [1:?] OF STRING (256);
preprocessor_version : STRING (256);
originating_system
: STRING (256);
authorization
: STRING (256);
END_ENTITY;

For example, you can add the authors name of a header field with the following
code:
SdaiAggr auth;
SdaiInstance name;
name = _sdaiHeaderName (model);
sdaiGetAttrBN (name, "author", sdaiAGGR, &auth);
sdaiInsertByIndex (auth, 0, sdaiSTRING, "Fred Foo");

SDAI C LIBRARY REFERENCE MANUAL

27

2 SDAI PROGRAMMING

2.4.16

Low-Level Model API


In the ST-Developer implementation of the SDAI, a model corresponds to a data
file. With the support of Edition 2 of Part 21 and the file sections that this provides,
this mapping is not a seamless interface between Part 21 and the SDAI interface.
For this reason, the SDAI includes a low-level model interface, where a model corresponds to either RoseDesign, or RoseDesignSection. The idea behind the low-level API is to directly use the ROSE interface to read and write files, access design
sections, and manage the application life cycle. You can then use the SDAI to access
instances, validate rules, and traverse rules. This is especially helpful if you have
written utility functions that take SDAI values as parameters, but you want to call
then from a ROSE application.
In the following example, the SDAI session, repository, and model do not need to
be directly accessed. Instead, the code finds a RoseDesign, and then obtains the corresponding SDAI model.
#include <rose.h>
#include <sdai.h>
int main () {
RoseDesign * des = ROSE.findDesign ("data");
SdaiModel * mod = _sdaiGetModel (des);
SdaiSet points = sdaiGetEntityExtentBN (mod, "point");
/* Iterate over the points */
}

The _sdaiGetModel() (Section 5.25, pp. 165) function can take either a RoseDesign,
or a RoseDesignSection. If the function is passed a RoseDesignSection, the model
that is created will only refer to the design section. This is how multiple section Part
21 file can be manipulated in the SDAI.
Since a model can be represent either a RoseDesign or a RoseDesignSection, the
sdaiGetInstanceModel() (Section 4.66, pp. 96) function needs to be determine which
type of model to return. If the instance is contained in a model that has been explicitly opened with sdaiAccessModel() (Section 4.2, pp. 47), the function returns the
model corresponding to the instances RoseDesign. Otherwise, it returns the model
that corresponds to the objects design section. This behavior maintains full SDAI
semantics for pure SDAI applications, but for hybrid ROSE/SDAI applications, it
gets the finest-grained model available or the instance.
Use _sdaiGetInstanceSectionModel() (Section 5.23, pp. 165) if you need the model
for an instances design section. This function always returns the model corresponding to the design section regardless of whether or not the model was opened through
the SDAI, or implicitly through some other method.

28

STEP TOOLS, INC.

2 SDAI PROGRAMMING

2.4.17

Multiple Schemas
The ROSE library supports a list of schema for each model, which the SDAI does
not support. In a pure SDAI application, there is a one-to-one correspondence between a model and its schema. When dealing with Part 21 files that have multiple
sections with several schemas, you may need to access the models schema list.
The multiple schema support is handled by _sdaiAddSchema() (Section 5.2, pp.
155), which adds a schema a models list of schema, and _sdaiGetSchemaList() (Section 5.31, pp. 168), which populates an NPL with the complete set of schemas that
the schema contains.

2.4.18

Property Functions
A property is a way for an application to associate additional data with an SDAI instance. By using properties, an application can avoid the traversal costs associated
with evaluating an inverse attributes, or making sdaiFindInstanceUsedIn() (Section
4.45, pp. 79) calls. This can be used, for example, to keep back pointers or to tag an
instance with application specific data. The property functions are not specified in
Part 24, but rather are an ST-Developer extension to the interface.
A property is represented by the C type void*. The interpretation of the property is
entirely up to the application it can be a SDAI instance handle, a pointer to an
application defined data structure, or the value can be cast to an integer. The values
of properties are not saved between sessions.
An instance may have any number of properties attached to it. To distinguish between multiple properties, each property is identified by a property type. Use the
_sdaiGetPropType() (Section 5.27, pp. 167) function to obtain a property type identifier. Each call to this function allocates a new, unique, type identifier, so the return
value must be stored in memory locations that will remain accessible for the life of
the application. The best way to allocate property types is to do so in the initialization code of your application, then store the values in global variables.
_SdaiPropType name_prop; /* This should be a global variable
SdaiAppInstance inst1, inst2;
name_prop = _sdaiGetPropType();
/* Find the instances for inst1 and inst2 */
/* Store the properties */
_sdaiSetProp (name_prop, inst1, "testobj1");
_sdaiSetProp (name_prop, inst2, "testobj2");

SDAI C LIBRARY REFERENCE MANUAL

29

2 SDAI PROGRAMMING

/* Print the properties out */


printf ("Name=%s\n", (char*)_sdaiGetProp(name_prop, inst1));
printf ("Name=%s\n", (char*)_sdaiGetProp(name_prop, inst2));

After obtaining a type identifier, you can then define properties of instances. The
_sdaiSetProp() (Section 5.39, pp. 172) function sets the value of an instances property. If the instance already has an existing property of the specified type, the old
value is replaced with the new value.
The _sdaiGetProp() (Section 5.26, pp. 166) function to retrieves the value of a property. The application must then cast this value to the appropriate type to operate on
it. This function returns a NULL pointer if the property is currently unset.
To remove a property from an instance, use the _sdaiRemoveProp() (Section 5.35,
pp. 170) function. This function does not clean up any memory referenced by the
property. If your property refers to dynamically allocated memory, you should free
it before calling _sdaiRemoveProp() to avoid memory leaks in your application.

30

STEP TOOLS, INC.

3 SDAI Library Changes

3.1

Changes from v9 to v10 and later


Except for bug fixes, there have been no changes to the SDAI library API functions
past the ST-Developer v9 release.

3.2

Changes from v8 to v9
In ST-Developer v9, the SDAI interface incorporates several changes. In general,
these changes add functionality and fix bugs. Code which works against the v8 interface will continue to function without any source code changes. The additional
functionality is in the form of a low-level interface which provides a cleaner interface with the ROSE library.
If you decide to recompile your existing code to take advantage of the new features
in the SDAI library, you should recompile the entire project to avoid unpleasant surprises at link or run time.

3.2.1

Part 24 IS Conformance
Part 24 has recently been published as an International Standard by ISO. The SDAI
library conforms to this specification. You will not need to change your code to con-

SDAI C LIBRARY REFERENCE MANUAL

31

3 SDAI LIBRARY CHANGES

form this specification.


The IS standard specifies that the non-persistent lists created by retrieving the value
of INTERSE attributes are now only guaranteed until the next call that retrieves an
inverse attribute. This means that applications no longer need to call sdaiDeleteNPL() to release the NPL. This automatic deletion has not yet been implemented in
the ST-Developer version 9 release, so you should continue to manually delete the
NPL, or else your application will experience a memory leak. We do plan to implement this feature in a future release.

3.2.2

Low-Level Interface
For many applications, the higher-level, application management portion of the
SDAI only adds complexity to the application without adding any real value. For
this reason, the Version 9 release of the SDAI library provides a low-level interface
in which you avoid the sdaiOpenSession()/sdaiOpenRepository()/
sdaiAccessModel() calls, and instead use to ROSE library to access a design, then
directly manipulate the data.
This new functionality enables SDAI applications to access and manipulate Part 21
files with multiple data sections, as well as making it easier to write utility functions. For more information, see Low-Level Model API (Section 2.4.16, pp. 28).

3.2.3

Other changes
This release of the SDAI adds support for multiple schemas. It is now possible to
manipulate Part 21 exchange files without resorting to the ROSE interface. See Multiple Schemas (Section 2.4.17, pp. 29) for more information.
The library now has a several convenience functions that efficiently perform queries against the data dictionary. These functions provide a convenient, and fast
method to get the full set of attributes (local and inherited), determine all the super
and subtypes of an entity in a schema, and to get all the uniqueness rules that apply
to in entity. These functions are _sdaiGetAllAttrDefinitions () (Section 5.9, pp. 158),
_sdaiGetDerivedAttrDefinitions() (Section 5.13, pp. 159),
_sdaiGetExplcitAttrDefinitions() (Section 5.19, pp. 162),
_sdaiGetInverseAttrDefinitions() (Section 5.24, pp. 165), _sdaiGetSubtypes() (Section 5.32, pp. 169); _sdaiGetSupertypes() (Section 5.33, pp. 169), and
_sdaiGetUniquenessDefinitions() (Section 5.34, pp. 169).
This library now has a new _sdaiSaveAs() function. See _sdaiSaveAs() (Section
5.37, pp. 171) for more information.

32

STEP TOOLS, INC.

3 SDAI LIBRARY CHANGES

A bug that causes the application to crash if it open, closes and reopens a session
has been corrected.
A bug caused the library to crash with null-pointer access when reading the EXPRESS parse data for a schema that has a defined type whose underlying type is an
aggregate has been corrected.

3.3

Changes from v7 to v8
ST-Developer Version 8 includes a number of improvements in the SDAI C binding. In addition to a few bug fixes, the SDAI library now provides a more convenient interface for manipulating SELECT types, and a few extension functions for
handling Part 21 headers and entity IDs.

3.3.1

Recompile EXPRESS Parse Data


Due to changes in the EXPRESS compiler, you will need to recompile any parse
data files (e.g. *_EXPX.rose) you are using. If the system encounters old parse data,
it generates the message:
WARNING: Old version of parse data: file_EXPX. Ignoring it.

and uses does not extend the dictionary data beyond the information contained in
the ROSE schema file. This means the EXPRESS interpreter, INVERSE attributes,
and rule checking will not function until you recompile the EXPRESS file with the
command:
expfront schema.exp

All the parse data for information models included with ST-Developer has been recompiled. You only need to recompile you own EXPRESS schemas.

3.3.2

Updating SELECT Attributes


The sdaiPutAttr() and sdaiPutAttrBN() functions are now more forgiving when operating on SELECT typed attributes. In previous releases, you needed to specify a
path through the tree of selects which specified every defined type that was involved. In the new version, these rules have been significantly relaxed. If the value

SDAI C LIBRARY REFERENCE MANUAL

33

3 SDAI LIBRARY CHANGES

you are setting is an ENTITY type, you do not need to indicate a type path at all,
rather the system will find and utilize an appropriate path. In the case of primitives,
you still need to provide a type path, but you only need to specify enough of the type
path to identify the attribute.
See SELECTS (Section 2.4.11, pp. 20) form more information.

3.3.3

New models created in STEP format


When you create a new SDAI model with sdaiCreateModel(), the model will be
written out as a STEP Part 21 file by default. In previous versions, the file was written out as a rose file. If you want to write a file in binary format, call
_sdaiSetModelFormat(model, standard).

This change only effect newly created files; any model that was read in from a file
is written out in the same format that is was read in. This change only effects the
SDAI, and not the ROSE library.

3.3.4

Part 21 File Accessor functions


The SDAI library now contains a few conveniences functions the access and manipulate the STEP Part 21 information. The _sdaiGetEntityId() function returns the
STEP Entity ID (e.g. line number) from a step file.
int id = _sdaiGetEntityId (inst);

In addition, the SDAI now contains the _sdaiHeaderDescription() and


_sdaiHeaderName() functions to manipulate the Part 21 header information.

3.3.5

Other Changes
In the v7 version of the SDAI library, a number of aggregate manipulation functions
(such as sdaiAdd()) did not correctly operate, and instead indicated an errors for
what should be legal operations. This bug has been corrected.
A bug in the v7 version of the SDAI library where sdaiTestAggrByIndex() and released functions always returned true has been fixed.
Past versions of the SDAI library generated names of entity_definition instances for

34

STEP TOOLS, INC.

3 SDAI LIBRARY CHANGES

complex types incorrectly. The new version now correctly generates the names as
defined in Part 22, with the supertypes (sorted alphabetically) separated by the +
character.
In addition, we have improved the speed of the sdaiGetAttr() function.
We have cleaned up the namespace so that the SDIA library exports no functions
except those that begin with sdai or _sdai. You may still notice some namespace
pollution, but there is now nothing beyond what the ROSE library provides.

3.4

Changes from 1.6 to v7


We have made several changes and improvements to the current SDAI library since
the ST-Developer 1.6 release. Due to these changes, the current version is now installed as the default SDAI library. It now features validation functions, schema instance support, an extended interface to the ROSE-level data structures, an interface
to the advanced EXPRESS interpreter, and a number of bug fixes.
The SDAI dictionary is now generated at run-time, thus the express2sdai_dis utility
has been eliminated from the release. When a model is loaded into memory (with
sdaiAccessModel(), or related functions), the SDAI generates a dictionary based on
the models ROSE schema. It then, completes the dictionary to include the types attribute and rules in the advanced EXPRESS compiler parse data.
The library now includes an optional interface to an EXRESS interpreter. The interpreter can be used to get the values of derived attributes, and to validate where and
global rules defined in the EXPRESS information model. A number of validation
function which do not require the EXPRESS interpreter are also now implemented.
This release of the SDAI library supports schema instances. A schema instance is a
set of models which are related in some application-defined way. A model may belong to more than on schema instance. Schema instances are used to identify the set
of data over which global and uniqueness rules are evaluated.
This interface better conforms to Part 24 and Part 22. Attribute of all types, including REAL and INTEGER can be unset with the sdaiUnsetAttr() function. The aggregate access functions (e.g sdaiGetAggrByIndex(), etc.) are now stricter in
validating their parameters for the correct aggregate type.
The functions which provide the interface between the ROSE library have been extended, to allow applications to mix the ROSE and the SDAI APIs. We have also
added a new feature property feature by which an application can easily associate

SDAI C LIBRARY REFERENCE MANUAL

35

3 SDAI LIBRARY CHANGES

data with an SDAI instance.

3.4.1

New Library Names


The current version of the SDAI library is now installed as the default version of the
SDAI. When you compile an SDAI application you should use the sdai.h header file
in $ROSE_INCLUDE. (The old $ROSE_INCLUDE/sdaidis include directory has been
removed from the release.) The SDAI library has been similarly renamed from -lsdaidis or sdaidis.lib to -lsdai or sdai.lib.
The old CD version, which used to be the default, is still available. If you wish to
use the old version add $ROSE_INCLUDE/sdaicd to your include path, and link
against -lsdaicd or sdaicd.lib.

3.4.2

Dictionary Generation
The SDAI dictionary is now generated at run-time. When a model is accessed, the
ROSE library loads the corresponding schema file; the SDAI library then generates
the dictionary for the schema. If an EXPRESS parse data file can be located, the
SDAI library uses it to generate a complete dictionary for the schema.
Due the this run-time schema generation the express2sdai_dis utility is no longer
required, and has been removed from the release. You should now use the advanced
EXPRESS compile, expxfront, to generate the EXPRESS parse data files instead.
At times, an application may wish to directly access the dictionary without loading
a model based on the schema. In previous releases, an application was required to
explicitly load the dictionary model with code like:
dict = sdaiAccessModelBN(reop, "config_control_design_SDAI_DICT", sdaiRO);

This no longer works in the new release. Instead, you should use the
sdaiGetSchema() (Section 4.72, pp. 99) function instead. This function causes the
dictionary to be generated in the same way as when a model is loaded.
See The SDAI Dictionary (Section 2.2.2, pp. 6) for more information about how the
data dictionary is now from the ROSE schema and EXPRESS parse data.

36

STEP TOOLS, INC.

3 SDAI LIBRARY CHANGES

3.4.3

EXPRESS Interpreter
The SDAI library now contains an interface to the advanced EXPRESS interpreter.
The interpreter is used to validate global and where rules, and to calculate the values
of derived attributes. The release includes two versions of the SDAI library one
with the interpreter, and one without it. You must link against the version with the
interpreter before using any on the features described in this section. See Compiling
SDAI Applications (Section 2.2.1, pp. 6) for more information about compiling
SDAI applications with the EXPRESS interpreter.
In addition to linking with the correct version of the libraries, you must have the full
dictionary (and EXPRESS parse data) available at run-time to utilize the interpreter.
The EXPRESS interpreter is used to calculate derived attributes by the sdaiGetAttr()
(Section 4.54, pp. 86) and sdaiGetAttrBN() (Section 4.55, pp. 87) functions. In addition to getting the values of derived attributes, the EXPRESS interpreter is also
used to validate global and where rules by the following functions:

3.4.4

sdaiValidateGlobalRule() (Section

sdaiValidateGlobalRuleBN()

sdaiValidateWhereRule()

sdaiValidateWhereRuleBN() (Section

4.140, pp. 144)

(Section 4.141, pp. 145)

(Section 4.151, pp. 153)


4.152, pp. 153)

Schema Instances
Schema instances are now supported by the SDAI library. While previous versions
had a minimal, stub versions of schema instances available, the new version fully
supports the required operations of schema instances. See Schema Instances (Section 2.4.5, pp. 14) for more information.

3.4.5

Validation
The SDAI library now supports a number of validation functions. These functions
check if a portion of a data set conforms to the constrains defined in the EXPRESS
information model. All of the validation functions require that the complete dictionary be generated (e.g. the EXPRESS parse data must be loaded), and several functions sdaiValidateGlobalRule(), sdaiValidateGlobalRuleBN(),
sdaiValidateWhereRule(), and sdaiValidateWhereRuleBN()also require that the

SDAI C LIBRARY REFERENCE MANUAL

37

3 SDAI LIBRARY CHANGES

you link against the library with the EXPRESS interpreter.


The validation functions are the following:

sdaiValidateAggrSizes() (Section

sdaiValidateAggrUni()

sdaiValidateArrayNotOptional() (Section

sdaiValidateBinaryWidth()

(Section 4.139, pp. 144)

sdaiValidateInverseAttrs()

(Section 4.142, pp. 146)

sdaiValidateSchemaInstance()

sdaiValidateStringWidth()

sdaiValidateUniqueness() (Section

sdaiValidateUniquenessBN()

3.4.6

4.135, pp. 141)

(Section 4.136, pp. 142)


4.137, pp. 142)

(Section 4.146, pp. 149)

(Section 4.147, pp. 149)


4.149, pp. 151)

(Section 4.150, pp. 152)

sdaiValidateGlobalRule() (Section

4.140, pp. 144)

sdaiValidateGlobalRuleBN()

(Section 4.141, pp. 145)

sdaiValidateWhereRule()

sdaiValidateWhereRuleBN() (Section

(Section 4.151, pp. 153)


4.152, pp. 153)

Strong Type Checking for Aggregates


The aggregate access functions now validate the types of their parameters. In the
past release any type of aggregate, as long as it was an attribute of a application instance, could be used as a parameter for any aggregate access function. In this release, the correct function must be used or an error, usually sdaiAI_NVLD, is
generated.
The following functions require the aggregate parameter to be an unordered aggregate (e.g. bag or set)

38

sdaiAdd()

sdaiCreateNestedAggr()

(Section 4.4, pp. 49)


(Section 4.23, pp. 64)

STEP TOOLS, INC.

3 SDAI LIBRARY CHANGES

sdaiCreateNestedAggrADB()

sdaiRemove() (Section

(Section 4.24, pp. 65)

4.113, pp. 128)

The following functions require the aggregate parameter to be an ordered aggregate


(e.g. array or list)

sdaiCreateNestedAggrByIndex()

(Section 4.25, pp. 65)

sdaiCreateNestedAggrByIndexADB()

sdaiGetAggrByIndex()

sdaiPutAggrByIndex() (Section

(Section 4.26, pp. 66)

(Section 4.51, pp. 84)


4.106, pp. 122)

The following functions require the aggregate parameter to be an array.

sdaiTestArrayByIndex()

(Section 4.125, pp. 135)

sdaiGetLowerIndex()

sdaiGetUpperIndex() (Section

sdaiUnsetArrayByIndex() (Section

(Section 4.68, pp. 97)


4.74, pp. 101)
4.131, pp. 139)

The following functions require the aggregate parameter to be a list:

3.4.7

sdaiInsertByIndex()

sdaiInsertNestedAggrByIndex() (Section

sdaiInsertNesterAggrByIndexADB()

sdaiRemoveByIndex() (Section

(Section 4.77, pp. 102)


4.82, pp. 106)

(Section 4.83, pp. 106)

4.114, pp. 128)

Unset Attribute Values


The SDAI library now supports unset value for all types. Past releases did not support unset values for integer and real number types. The sdaiUnsetAttr() (Section
4.133, pp. 140) function now correctly removes the value from any attribute. It you
try to access an unset attribute, the SDAI generates an sdaiAT_NDEF error.

SDAI C LIBRARY REFERENCE MANUAL

39

3 SDAI LIBRARY CHANGES

3.4.8

ROSE Access Functions


This release of the SDAI adds a number of functions that assist in interfacing with
the underlying ROSE library. The ROSE library provides low-level data management functionality for the SDAI, and sometimes an SDAI application need to directly call ROSE methods. The _sdaiGetRoseDesign(), and _sdaiGetModel()
functions convert between RoseDesigns and SDAI models. The
_sdaiGetEntityForDomain() and _sdaiGetDomainForEntity() functions convert between ROSE and SDAI meta-data. See Interfacing with ROSE (Section 2.4.14, pp.
26) for more information.

3.5

Property Functions
This release of the SDAI library contains a set of extension function which allow
you to associate application-specific data with an application instance. A property
is implemented as a void* that is associated with an instance. By using properties,
an SDAI application can avoid using lookup tables or other data structures to associate additional, data with a specific instance.
For more information about using this feature, see Property Functions (Section
2.4.18, pp. 29). The API functions which implement properties are _sdaiGetProp()
(Section 5.26, pp. 166); _sdaiGetPropType() (Section 5.27, pp. 167);
_sdaiRemoveProp() (Section 5.35, pp. 170); and _sdaiSetProp() (Section 5.39, pp.
172).

3.5.1

New Functions
The following functions have been added to the SDAI library for the ST-Developer
Version 7 release.

40

sdaiAddModelBN()

(Section 4.6, pp. 51)

sdaiCreateAggrADB() (Section

sdaiCreateAggrADBBN()

sdaiDeleteSchemaInstanceBN()

sdaiGetSchemaInstance()

4.12, pp. 55)

(Section 4.14, pp. 56)


(Section 4.38, pp. 74)

(Section 4.73, pp. 100)

STEP TOOLS, INC.

3 SDAI LIBRARY CHANGES

sdaiInsertNestedAggrAfterADB() (Section

4.79, pp. 104)

sdaiInsertNesterAggrByIndexADB()

sdaiIsEqual()

sdaiRemoveModelBN()

sdaiRenameSchemaInstanceBN()

(Section 4.120, pp. 132)

sdaiValidateAggrSizes() (Section

4.135, pp. 141)

sdaiValidateAggrUni()

sdaiValidateArrayNotOptional() (Section

sdaiValidateBinaryWidth()

(Section 4.139, pp. 144)

sdaiValidateInverseAttrs()

(Section 4.142, pp. 146)

sdaiValidateSchemaInstance()

sdaiValidateStringWidth()

sdaiValidateGlobalRule() (Section

sdaiValidateGlobalRuleBN()

sdaiValidateUniqueness() (Section

sdaiValidateUniquenessBN()

sdaiValidateWhereRule()

sdaiValidateWhereRuleBN() (Section

_sdaiFindModelBN() (Section

5.7, pp. 157)

_sdaiGenerateFullDictionary()

(Section 5.8, pp. 157)

_sdaiGetComplexEntityBN()

_sdaiGetDomainForEntity() (Section

5.14, pp. 160)

_sdaiGetEntityForDomain() (Section

5.15, pp. 160)

_sdaiGetEntityInModel()

(Section 4.83, pp. 106)

(Section 4.86, pp. 108)

SDAI C LIBRARY REFERENCE MANUAL

(Section 4.117, pp. 130)

(Section 4.136, pp. 142)


4.137, pp. 142)

(Section 4.146, pp. 149)

(Section 4.147, pp. 149)


4.140, pp. 144)

(Section 4.141, pp. 145)


4.149, pp. 151)

(Section 4.150, pp. 152)

(Section 4.151, pp. 153)


4.152, pp. 153)

(Section 5.12, pp. 159)

(Section 5.17, pp. 161)

41

3 SDAI LIBRARY CHANGES

_sdaiGetGenerateFullDictionary() (Section

_sdaiGetModel()

_sdaiGetProp()

_sdaiGetPropType() (Section

_sdaiGetRoseDesign() (Section

_sdaiRemoveProp() (Section

_sdaiRescanRepository() (Section

_sdaiSetModelFormat()

3.5.2

5.20, pp. 162)

(Section 5.25, pp. 165)

(Section 5.26, pp. 166)


5.27, pp. 167)
5.29, pp. 168)

5.35, pp. 170)


5.36, pp. 170)

(Section 5.38, pp. 171)

_sdaiSetProp() (Section

5.39, pp. 172)

Corrected Bugs
A number of bugs and other problems in the ST-Developer 1.6 version of the SDAI
library have been corrected:

42

A severe memory leak in the Non-Persistent Lists (NPLs) has been fixed.

Dictionary instances are now created with the correct lower-case names.

The _sdaiGetAllAttrDefinitions() function did not correctly return inherited attributes. This problem has been corrected

Redeclared attribute are handled correctly in the library. There was a bug in the
ST-Developer 1.6 release which could make a the contents of a model inaccessible if the schema contained redeclared attributes

You may pass a full path name to sdaiAccessModel(). Previous releases contained a bug that required the application specify the model name as it was
stored in the repository.

The attributes member of entity_definition in the dictionary now works correctly. This is an inverse attribute, which was incorrectly defined in the dictionary
for the SDAI dictionary model.

Complex entities are created and initialized when a model is loaded, rather than
on demand. This allows you to browse the dictionary to find the complex types
in the ROSE working set.

STEP TOOLS, INC.

4 Function Reference

4.1

Introduction
This chapter provides an alphabetical reference to the functions provided by the
SDAI C programming library.

4.1.1

Organization
Each functions description begins with the functions prototype. After the prototype, there is a description of the functions purpose and its parameters. This section also describes any side effects that the function may have, and what value, if
any, is returned by the function.

Errors
The errors section lists the errors, and gives a brief explanation of what conditions
can cause each error to be flagged.

Example
For some of the functions, this manual provides an example of how the code may
be used. Unless otherwise indicated, this example is neither a complete program nor
function, but rather an outline which briefly demonstrates how the function may be
used.

SDAI C LIBRARY REFERENCE MANUAL

43

4 FUNCTION REFERENCE

See Also
The See Also section provides cross reference to related functions in the SDAI
binding, provides a reference to the clauses in the SDAI standard (both Part 22 and
Part 24) which define the function.

4.1.2

Conformance Class
The SDAI implementation described in this document supports the following conformance classes:

Level 2 of transaction support

Level 2 of expression evaluation support

Level 1 of event recording support

Level 1 of scope support

Level 1 of domain equivalence support.

This means that the this implementation provides the support required by implementation class 1 and class 2 except for scope support. It conforms to Implementation Class 4, with the exception of session recording support.
The following table is derived from Table 7 from ISO 10303-22. It shows what
functionality is required by which implementation class (Y means the functionally
is required, N means it is not; D or E means that a subset of the functionality is required). The table cells that are highlighted are identify the functionality that is
present or exceeded in this implementation.
Operation

44

Implementation Class
1

Open Session

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Record error

N*

N*

N*

Start event recording

N*

N*

N*

Stop event recording

N*

N*

N*

Close session

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Open repository

Y*

Y*

Y*

Y*

Y*

Y*

Y*

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Operation

Implementation Class
1

Start transaction read-write access

N*

N*

N*

N*

Start transaction read-only access

N*

N*

N*

N*

Commit

N*

N*

N*

N*

Abort

N*

N*

N*

N*

End transaction access and commit

N*

N*

N*

N*

End transaction access and abort

N*

N*

N*

N*

Create non-persistent list

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Delete non-persistent list

Y*

Y*

Y*

Y*

Y*

Y*

Y*

SDAI query

N*

N*

N*

N*

Create SDAI -model

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Create schema instance

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Close repository

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Delete schema instance

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Rename schema instance

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Add SDAI-model

D*

D*

Y*

D*

D*

Y*

Y*

Remove SDAI-model

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Validate global rule

N*

N*

E*

N*

N*

E*

Y*

Validate uniqueness rule

N*

Y*

Y*

Y*

Y*

Y*

Y*

Validate instance reference domain

N*

Y*

Y*

Y*

Y*

Y*

Y*

Validate schema instance

N*

Y*

Y*

Y*

Y*

Y*

Y*

Is validation current

N*

Y*

Y*

Y*

Y*

Y*

Y*

SDAI -model operations (not Save


Undo, get dictionary)

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Get entity definition

N*

Y*

Y*

Y*

Y*

Y*

Y*

Save and Undo

N*

N*

N*

Y*

N*

N*

N*

Scope operations

N*

N*

N*

N*

Get complex entity definition

N*

N*

N*

N*

N*

N*

Y*

SDAI C LIBRARY REFERENCE MANUAL

45

4 FUNCTION REFERENCE

Operation

46

Implementation Class
1

Is subtype of

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Is SDAI subtype of

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Is domain equivalent with

N*

N*

N*

Get population dependent bound

N*

Get attribute

E*

E*

E*

E*

E*

E*

Get instance type

N*

Y*

Y*

Y*

Y*

Y*

Y*

Entity instance operations

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Find entity instance users

N*

N*

Y*

N*

N*

Y*

Y*

Find entity instance usedin

N*

N*

Y*

N*

N*

Y*

Y*

Get attribute value bound

Find roles played

N*

N*

N*

N*

N*

N*

Y*

Find data types

N*

N*

N*

N*

N*

N*

Y*

Copy application instance

D*

D*

D*

D*

Application instance operations ex- Y*


cept validation and label

Y*

Y*

Y*

Y*

Y*

Y*

Application instance operations:


persistent label operations

N*

N*

N*

Y*

Y*

Y*

Y*

Get description

Y*

Y*

Y*

Y*

Y*

Y*

Y*

Application instance operations:


simple validation

N*

Y*

Y*

Y*

Y*

Y*

Y*

Application instance operations:


validation

N*

E*

E*

E*

E*

E*

Y*

Entity and application instance


bound related aggregate operations

N*

E*

E*

E*

E*

E*

Y*

All entity and application instance


non-bound related aggregate operations

Y*

Y*

Y*

Y*

Y*

Y*

Y*

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.1.3

Unimplemented Functions
There are a number of functions defined in Part 22, but not documented here. These
functions are not included in the conformance class that this SDAI implementation
provides, and will generate the error FN_NAVL (function is not available) if they are
called. These unimplemented functions consist of the following:
sdaiAddToExportList();
sdaiAddToScope();
sdaiBreakTrx();
sdaiEndTrx();
sdaiGetAggrElementBoundByIndex()
sdaiGetAggrElementBoundByItr();
sdaiGetAttrBound();
sdaiGetAttrBoundBN();
sdaiGetExportList();
sdaiGetLowerBound();
sdaiGetOwnedScopeInstances();
sdaiGetScope();
sdaiGetScopeOwner();
sdaiGetUpperBound()
sdaiIsDeqWith();
sdaiIsDeqWithBN();
sdaiIsRecordingOn();
sdaiIsScopeOwner();
sdaiIsValidationCurrent();
sdaiQuery();
sdaiRecordEvent();
sdaiReindexArray();
sdaiRemoveFromExportList();
sdaiRemoveFromScope();
sdaiScopedCopyInSameModel();
sdaiScopedCopyToOtherModel();
sdaiScopedDelete();
sdaiSetEventRecording();
sdaiStartTrx();
sdaiValidateScopeReferenceRestrictions();

4.2

sdaiAccessModel()
SdaiModel sdaiAccessModel(
SdaiModel model,
SdaiAccessMode mode
);

The sdaiAccessModel() function makes the instances in an SDAI model available


for access as either real-only or read-write. Until this function is called, any attempt

SDAI C LIBRARY REFERENCE MANUAL

47

4 FUNCTION REFERENCE

to access the contents of a model results in an error. The parameter mode must be
specified as sdaiRW (for read-write) or sdaiRO (for read only).
This function causes model.contents, model.underlying_schema andmodel.mode to
be set. This function returns the parameter model unless there was an error in which
case it returns sdaiNULL.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiRP_NOPN
sdaiMX_RO
sdaiMX_RW

session is not open


NULL or invalid model
repository not open
model is already open in read-only mode
model is already open in read-write mode

Example
SdaiModel mod;
sdaiAccessModel (mod, sdaiRW);

See Also
sdaiAccessModelBN() (Section

4.3, pp. 48);sdaiEndModelAccess() (Section 4.40,


pp. 75); ISO 10303- 22- 10.7.3, 10.7.6; ISO 10303- 24- 6.5.3

4.3

sdaiAccessModelBN()
SdaiModel sdaiAccessModelIBN(
SdaiRep repository,
SdaiString modelName,
SdaiAccessMode mode
);

The sdaiAccessModelBN() function makes the instances in an SDAI model available for access as either real-only or read-write. Until this function is called, any attempt to access the contents of a model will result in an error.

48

repository

the repository containing the model to be accessed. This repository


must be opened for access.

modelName

The name of the model to be opened. This can be obtained by exam-

STEP TOOLS, INC.

4 FUNCTION REFERENCE

ining repository.contents.models.
mode

sdaiRW

(for read-write) or sdaiRO (for read only) access

This function causes model.contents, model.underlying_schema and model.mode


to be set. This function returns the model accessed unless there was an error in
which case it returns sdaiNULL.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiRP_NOPN
sdaiRP_NEXS
sdaiMX_RO
sdaiMX_RW

session is not open


NULL or invalid model
repository not open
NULL repository {this error is not in p22/24}
model is already open in read-only mode
model is already open in read-write mode

Example
SdaiModel mod;
SdaiSession sess = sdaiOpenSession();
SdaiRep rep = sdaiOpenRepositoryBN (sess, "standard_3.0");
mod = sdaiAccessModelBN (rep, "data", sdaiRW);

See Also
sdaiAccessModel() (Section 4.2, pp. 47); sdaiEndModelAccess() (Section 4.40, pp.

75); ISO 10303-22- 10.7.4, 10.7.6; ISO 10303-24- 6.5.3

4.4

sdaiAdd()
void sdaiAdd(
SdaiUnorderedAggr unorderedAggr,
SdaiPrimitiveType valueType,
<TYPE> value
);

The sdaiAdd() function adds a value to an unordered aggregate. The valueType parameter identifies the type of the value parameter and should be sdaiINTEGER,
sdaiREAL, sdaiBOOLEAN, sdaiLOGICAL, sdaiSTRING, sdaiBINARY, sdaiENUM,
sdaiINSTANCE, sdaiAGGR or sdaiADB.

SDAI C LIBRARY REFERENCE MANUAL

49

4 FUNCTION REFERENCE

Errors
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW
sdaiSS_NOPN
sdaiVT_NVLD

aggregate does not exist


aggregate is internal or is not unordered
model is not writable
session is not open
value type cannot be converted to type of aggregate

See Also
ISO 10303-22-10.14.1; ISO 10303-24-6.12.1

4.5

sdaiAddModel()
void sdaiAddModel(
SdaiSchemaInstance schemaInstance,
SdaiModel model
);

The sdaiAddModel() function adds a new model to a schema instance.

Errors
sdaiSS_NOPN
sdaiSI_NEXS
sdaiMO_NEXS
sdaiRP_NOPN
sdaiMX_NDEF

session not open


schema instance does not exist
model does not exist, or NULL value passed in
model's repo is not open
model not open

See also
ISO 10303 - 22- 10.6.3; ISO 10303 - 24- 6.4.3

50

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.6

sdaiAddModelBN()
void sdaiAddModelBN (
SdaiSchemaInstance schemaInstance,
SdaiRep repository,
SdaiString modelName
);

The sdaiAddModelBN() function adds a model to an existing schema instance. The


model is identified by name in a repository.

Errors
sdaiSS_NOPN
sdaiSI_NEXS
sdaiMO_NEXT
sdaiRP_NOPN
sdaiMX_NDEF

session not open


schema instance does not exist
model does not exist, or NULL value passed in
models repo is not open
model not open

Example
sdaiAddModelBN (si, rep, "aModel");

See Also
ISO10303-22-10.6.3; ISO10303-24-6.4.3

4.7

sdaiBeginning()
void sdaiBeginning(
SdaiIterator iterator
);

The sdaiBeginning() function moves an iterator to the beginning of the aggregate.


The current value of the iterator is then unset. The next sdaiNext() call will set the
iterator to the aggregates first element.

SDAI C LIBRARY REFERENCE MANUAL

51

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NEXS

session not open


iterator NULL
aggregate does not exist or is empty

See Also
sdaiNext() (Section

4.8

4.98, pp. 116); ISO 10303-22-10.12.5; ISO 10303-24-6.10.5

sdaiCloseRepository()
void sdaiCloseRepository(
SdaiRep repository,
);

The sdaiCloseRepository() function closes a repository and all of the models contained in it. Any further attempts to access the repository will generate errors, and
any attempt to access any instance, in any model in the closed repository is undefined.

Errors
sdaiRP_NEXS
sdaiRP_NOPN

sdaiNULL repository
repository not open

See Also
ISO 10303-22- 10.5.3; ISO 10303-24- 6.3.3

4.9

sdaiCloseSession()
void sdaiCloseSession(
SdaiSession session
);

The sdaiCloseSession() function ends the SDAI session. No further SDAI opera-

52

STEP TOOLS, INC.

4 FUNCTION REFERENCE

tions may be performed after a session is closed.


This function takes a parameter session, which identifies the session to be closed.
This parameter should be the return value from the most recent call to sdaiOpenSession().

Errors
sdaiSS_NOPN:

the session was not open.

Example
SdaiSession sess;
.
.
.
sess = sdaiOpenSession();
.
. /* SDAI Operations here */
.
sdaiCloseSession(sess);

See Also
ISO 10303-22- 10.4.5; ISO 10303-24- 6.2.4

4.10

sdaiCreateADB()
SdaiADB sdaiCreateADB(
SdaiPrimitiveType valueType,
<TYPE> value
);

The sdaiCreateADB() function creates an Attribute Data Block (ADB). An ADB is


a typed union which can contain any SDAI data type. The Part 22 specification does
not permit an ADB to be passed to this function, however, this implementation will
permit it, copying the type and value of the ADB into the newly created ADB.
The parameter valueType identifies the type of parameter value, and should be one
of the following: sdaiINTEGER, sdaiREAL, sdaiBOOLEAN, sdaiLOGICAL,
sdaiSTRING, sdaiBINARY, sdaiENUM, sdaiINSTANCE, sdaiAGGR, or sdaiADB. The

SDAI C LIBRARY REFERENCE MANUAL

53

4 FUNCTION REFERENCE

value

parameter identifies the data to be stored in the new ADB.

This function returns the handle of the newly created ADB. This ADB should be
freed by calling sdaiDeleteADB() after you are finished using it.

Errors
sdaiSS_NOPN
sdaiVT_NVLD

session is not open


valueType is not a legal type for this function.

Example
SdaiADB adb1, adb2, adb3;
SdaiInstance inst;
adb1 = sdaiCreateADB (sdaiINTEGER, 12);
adb2 = sdaiCreateADB (sdaiSTRING, "String in an ADB");
adb3 = sdaiCreateADB (sdaiINSTANCE, inst);

See Also
(Section 4.17, pp. 59); sdaiDeleteADB() (Section 4.32, pp.
70); ISO 10303-24- 6.2.12.1
sdaiCreateEmptyADB()

4.11

sdaiCreateAggr()
SdaiAggr sdaiCreateAggr(
SdaiAppInstance instance,
SdaiExplicitAttr attribute
);

The sdaiCreateAggr function() creates a new, empty aggregate as the value of an attribute in an instance. This function is used to set attributes that have aggregate slot
types.
This function returns the newly created aggregate.

Errors
sdaiSS_NOPN

54

session not open

STEP TOOLS, INC.

4 FUNCTION REFERENCE

sdaiEI_NEXS
sdaiMX_NRW
sdaiAT_NDEF
sdaiED_NVLD
sdaiVA_NSET
sdaiAT_NVLD

NULL entity/entity not an application instance


model not writable
NULL attribute
entity object is not an entity
attribute is unset
attribute is not an aggregate

See Also
ISO 10303-22-10.11.5; ISO 10303-24-6.9.6

4.12

sdaiCreateAggrADB()
SdaiAggr sdaiCreateAggrADB (
SdaiAppInstance instance,
SdaiExplicitAttr attr,
SdaiADB block
);

The sdaiCreateAggrADB() function creates a new, empty aggregate as the value of


an attribute. This function is used to set the values of attribute that have aggregate
types. The block parameter is used to identify the type of the attribute in the event
that it is a SELECT.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMX_NRW
sdaiAT_NDEF
sdaiED_NVLD
sdaiVA_NSET
sdaiAT_NVLD

session not open


NULL entity/entity not an application instance
model not writable
NULL attribute
entity object is not an entity
attribute is unset
attribute is not an aggregate

See Also
ISO 10303-24-6.9.6; ISO 10303-22-10.11.5

SDAI C LIBRARY REFERENCE MANUAL

55

4 FUNCTION REFERENCE

4.13

sdaiCreateAggrBN()
SdaiAggr sdaiCreateAggrBN(
SdaiAppInstance instance,
SdaiString attributeName
);

The sdaiCreateAggr() function creates a new, empty aggregate as the value of an attribute in an instance. The parameter attributeName identifies the attribute where
the aggregate is created.
This function returns the newly created aggregate.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMX_NRW
sdaiAT_NDEF
sdaiED_NVLD
sdaiVA_NSET
sdaiAT_NVLD
sdaiED_NDEF

session not open


NULL entity/entity not an application instance
model not writable
NULL attribute
entity object is not an entity
attribute is unset
attribute is not an aggregate
entity definition NULL or not defined

See Also
ISO 10303-22-10.11.5; ISO 10303-24-6.9.6

4.14

sdaiCreateAggrADBBN()
SdaiAggr sdaiCreateAggrADBBN (
SdaiAppInstance instance,
SdaiString attributeName,
SdaiADB adb
);

The sdaiCreateAggrBNADB() function creates a new, empty aggregate as the value


of an attribute. This function is used to set the values of attribute that have aggregate
types. The block parameter is used to identify the type of the attribute in the event
that it is a SELECT.

56

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Note
In past releases, this function was named sdaiCreateAggrBNADB(). This function
was omitted from earlier drafts of Part 24, and when it was added the name was
changed to be is sdaiCreateAggrADBBN().

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMX_NRW
sdaiAT_NDEF
sdaiED_NVLD
sdaiVA_NSET
sdaiAT_NVLD

session not open


NULL entity/entity not an application instance
model not writable
NULL attribute
entity object is not an entity
attribute is unset
attribute is not an aggregate

See Also
ISO 10303-24-6.9.6; ISO 10303-22-10.11.5

4.15

sdaiCreateComplexInstance()
SdaiAppInstance sdaiCreateComplexInstance(
SdaiModel model,
SdaiNPL entityList
);

The sdaiCreateComplexInstance() function creates an instance of a complex (ANDOR) entity. The entity must be in the working set for the compiled EXPRESS schema. The entityList parameter is an NPL, filled with entity_definition instances,
which define the supertypes of the requested complex type.
This is a convenience function which basically calls sdaiGetComplexEntity() followed by sdaiCreateInstance(). If you need to create several complex instances of
the same type, it is more efficient to call sdaiGetComplexEntity() once, then use
sdaiCreateInstance() to create the individual instances.
This function returns the handle of the newly created instance. If there was an error,
sdaiNULL is returned.

SDAI C LIBRARY REFERENCE MANUAL

57

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiED_NDEF
sdaiED_NVLD
sdaiMO_NEXS
sdaiRP_NOPN
sdaiMX_NRW

session not open


NPL is not valid or NULL or list is empty, entity not in schema
an entity in the list is not valid
model does not exist, or NULL value passed in
model's repo is not open
model not read-write

See Also
sdaiCreateInstance() (Section 4.18, pp. 59); sdaiGetComplexEntity() (Section 4.60,
pp. 92); sdaiCreateComplexInstanceBN() (Section 4.16, pp. 58); ISO 10303-24-

6.5.10.1

4.16

sdaiCreateComplexInstanceBN()
SdaiAppInstance sdaiCreateComplexInstanceBN(
SdaiModel model,
SdaiInteger nameNumber
SdaiString * nameVector
);

The sdaiCreateComplexInstanceBN() function creates an instance of a complex


(AND-OR) entity by name. The complex entity must be in the working set for the
compiled EXPRESS schema. The parameter nameVector is an array of strings (size
is the parameter nameNumber) containing entity names for the supertypes of the
complex entity.
This is a convenience function which calls sdaiGetComplexEntityBN() followed by
sdaiCreateInstance(). If you need to create several complex instances of the same
type, it is more efficient to call sdaiGetComplexEntityBN() once, then use sdaiCreateInstance() to create the individual instances.
This function returns the handle of the newly created instance. If there was an error,
returned.

sdaiNULL is

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiED_NDEF
sdaiRP_NOPN

58

session is not open


NULL or invalid model
entity not in EXPRESS
model's repo is not open

STEP TOOLS, INC.

4 FUNCTION REFERENCE

sdaiED_NVLD
sdaiMX_NRW

entity is not in model's schema


model not read-write

See Also
sdaiCreateInstance() (Section 4.18, pp. 59); sdaiGetComplexEntity() (Section 4.60,

pp. 92); ISO 10303-24- 6.5.10.1

4.17

sdaiCreateEmptyADB()
SdaiADB sdaiCreateEmptyADB();

The sdaiCreateEmptyADB() creates an empty Attribute Data Block (ADB). The type
and value of the newly created ADB are unset, and any attempt to retrieve the value
from the ADB will generate an error until it is populated.

Errors
sdaiSS_NOPN

session is not open

Example
SdaiADB adb;
adb = sdaiCreateADB();

See Also
(Section 4.10, pp. 53); sdaiDeleteADB() (Section 4.32, pp. 70);
ISO 10303-24- 6.2.12.1
sdaiCreateADB()

4.18

sdaiCreateInstance()
SdaiAppInstance sdaiCreateInstance(
SdaiModel model,
SdaiEntity entity
);

SDAI C LIBRARY REFERENCE MANUAL

59

4 FUNCTION REFERENCE

The sdaiCreateInstance() function creates a new instance of the specified entity in


a specified model. The entity must be defined in the model's schema or an error is
generated.
This function returns a handle to the newly created instance. On error, sdaiNULL is
returned.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiRP_NOPN
sdaiED_NDEF
sdaiED_NVLD

session not open


model does not exist, or NULL value passed in
model's repo is not open
entity definition NULL or not defined
entity is not in model's schema

Example
SdaiSession sess;
SdaiRep repo;
SdaiModel mod;
SdaiEntity ent;
SdaiAppInstance inst;
:
sess = sdaiOpenSession();
repo = sdaiOpenRepository (sess, "standard_3.0");
mod = sdaiAccessModelBN (repo, "modname", sdaiRW);
:
ent = sdaiGetEntity (mod, "cartesian_point");
inst = sdaiCreateInstance (mod, ent);

See Also
sdaiCreateInstanceBN() (Section

4.19, pp. 60); ISO 10303-22- 10.7.9; ISO 10303-

24- 6.5.7

4.19

sdaiCreateInstanceBN()
SdaiAppInstance sdaiCreateInstanceBN(
SdaiModel model,
SdaiString entityName
);

60

STEP TOOLS, INC.

4 FUNCTION REFERENCE

The sdaiCreateInstanceBN() function creates a new instance in a specified model,


of the type whose name is specified by the parameter entityName.
This function returns a handle to the newly created instance. On error, sdaiNULL is
returned.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiMX_NDEF
sdaiED_NDEF
sdaiRP_NOPN

session not open


NULL or invalid model
model not accessible
cannot find entity or NULL name
model's repo is not open

Example
SdaiSession sess;
SdaiRep repo;
SdaiModel mod;
SdaiEntity ent;
SdaiAppInstance inst;:
sess = sdaiOpenSession();
repo = sdaiOpenRepository (sess, "standard_3.0");
mod = sdaiAccessModelBN (repo, "modname", sdaiRW);
:
:
inst = sdaiCreateInstanceBN (mod, "cartesian_point");

See Also
sdaiCreateInstance() (Section 4.18, pp. 59); ISO 10303-22- 10.7.9; ISO 10303-24-

6.5.7

4.20

sdaiCreateIterator()
SdaiIterator sdaiCreateIterator(
SdaiAggr aggregate
);

The sdaiCreateIterator() function creates an iterator over an aggregate specified by


parameter aggregate. An iterator is an object that permits access to the elements in
an aggregate one element at a time. This is the preferred way to access the elements

SDAI C LIBRARY REFERENCE MANUAL

61

4 FUNCTION REFERENCE

of an aggregate.
If successful, this function returns the handle of the newly created iterator, otherwise, it returns sdaiNULL.

Errors
sdaiSS_NOPN
sdaiAI_NEXS

session not open


NULL aggregate

See Also
ISO 10303-22-10.12.3; ISO 10303-24-6.10.3

4.21

sdaiCreateModel()
sdaiModel sdaiCreateModel(
SdaiRep repository,
SdaiString modelName,
SdaiSchema schema
);

The sdaiCreateModel() function creates a new SDAI model. The model is associated
with a single repository (repository) and a single schema (schema). The repository
must be open, and requested modelName must be unique within the repository. It
returns a handle for the new model. The new model will be saved as a STEP Part
21 file, by default.
In this implementation, the sdaiCreateModel() function does not effect any persistent changes (e.g. no files are created) in the repository until the model is saved.

Errors
sdaiSS_NOPN
sdaiRP_NEXS
sdaiRP_NOPN
sdaiMO_DUP
sdaiSD_NDEF

62

session not open


repository is sdaiNULL or not repository
rep not open
model with name already exists
schema is NULL or in invalid

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Example
SdaiSession sess;
SdaiRep repo;
SdaiSchema sch;
SdaiModel mod;
sess = sdaiOpenSession ();
repo = sdaiOpenRepositoryBN (sess, "standard_3.0");
sch = sdaiGetSchema ("configuration_controlled_design");
mod = sdaiCreateModel (repo, "newmod", sch);

See Also
sdaiOpenRepository() (Section 4.99, pp. 117); sdaiOpenRepositoryBN() (Section
4.100, pp. 118); sdaiCreateModelBN() (Section 4.22, pp. 63); ISO 10303-22- 10.5.1;

ISO 10303-24- 6.3.1

4.22

sdaiCreateModelBN()
SdaiModel sdaiCreateModelBN(
SdaiRep repository,
SdaiString modelName,
SdaiString schemaName
);

The sdaiCreateModel() function creates a new SDAI model. The model is associated
with a single repository (parameter repository) and a single schema. The schema is
specified by in the schemaName parameter. The new model will be saved as a STEP
Part 21 file, by default.The repository must be open, and requested model name
must be unique within the repository.
In this implementation, this function does not effect any persistent changes (e.g. no
files are created) in the repository until the model is saved.

Errors
sdaiSS_NOPN
sdaiRP_NEXS
sdaiRP_NOPN
sdaiMO_DUP
sdaiSD_NDEF

session not open


repository is sdaiNULL or not repository
rep not open
model with name already exists
cannot find requested schema

SDAI C LIBRARY REFERENCE MANUAL

63

4 FUNCTION REFERENCE

Example
SdaiSession sess;
SdaiRep repo;
SdaiSchema sch;
SdaiModel mod;
sess = sdaiOpenSession ();
repo = sdaiOpenRepositoryBN (sess, "standard_3.0");
mod = sdaiCreateModel (repo, "newmod",
"configuration_controlled_design");

See Also
sdaiOpenRepository() (Section 4.99, pp. 117); sdaiOpenRepositoryBN() (Section
4.100, pp. 118); sdaiCreateModel() (Section 4.21, pp. 62); ISO 10303-22- 10.5.1;

ISO 10303-24- 6.3.1

4.23

sdaiCreateNestedAggr()
SdaiAggr sdaiCreateNestedAggr(
SdaiUnorderedAggr aggregate
);

The sdaiCreateNestedAggr() function creates a new aggregate and adds it to the unordered aggregate of aggregates specified by parameter aggregate.

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW

session is not open


aggregate does not exist
aggregate is internal and thus not writable
model is not writable

See Also
ISO 10303-22-10.14.2; ISO 10303-24-6.12.2

64

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.24

sdaiCreateNestedAggrADB()
SdaiAggr sdaiCreateNestedAggrADB(
SdaiUnorderedAggr aggregate,
SdaiADB selaggrInstance
);

The sdaiCreateNestedAggr() function creates a new aggregate and adds it to the unordered aggregate specified as parameter aggregate. An ADB is provided to specify
the type of the aggregate in case the function is dealing with an aggregate of SELECTs.
This function returns the newly created aggregate, and the ADB contains the newly
created aggregate.

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW
sdaiAB_NEXS

session is not open


aggregate does not exist
aggregate is internal and thus not writable
model is not writable
NULL ADB

See Also
ISO 10303-22-10.14.2; ISO 10303-24-6.12.2

4.25

sdaiCreateNestedAggrByIndex()
SdaiAggr sdaiCreateNestedAggrByIndex(
SdaiOrderedAggr aggregate,
SdaiAggrIndex index
);

The sdaiCreateNestedAggrByIndex() function creates a nested aggregate at a specific index of the aggregate instance specified by parameter aggregate.
This function returns the newly create aggregate instance.

SDAI C LIBRARY REFERENCE MANUAL

65

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW
sdaiIX_NVLD

session is not open


aggregate does not exist
aggregate is invalid
model is not writable
index is invalid

See Also
ISO 10303-22-10.16.2; ISO 10303-24-6.14.2

4.26

sdaiCreateNestedAggrByIndexADB()
SdaiAggr sdaiCreateNestedAggrByIndexADB(
SdaiOrderedAggr aggregate,
SdaiAggrIndex index,
SdaiADB selaggrInstance
);

The sdaiCreateNestedAggrByIndexADB() function creates a nested aggregate at a


specific index of a specified aggregate instance. An ADB is used to specify the type
of the aggregate when the members of the aggregate are SELECT typed objects.
This function returns the newly created aggregate instance. The ADBs value is set
to the new aggregate.

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW
sdaiIX_NVLD

session is not open


aggregate does not exist
aggregate is invalid
model is not writable
index is invalid

See Also
ISO 10303-22-10.16.2; ISO 10303-24-6.14.2

66

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.27

sdaiCreateNestedAggrByItr()
SdaiAggr sdaiCreateNestedAggrByItr(
SdaiIterator current
);

The sdaiCreateNestedAggrByItr() function creates a new nested aggregate in an aggregate instance. The new aggregate replaces the current value at the iterator
current.
This function returns the newly created aggregate.

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiMX_NRW
sdaiIR_NSET
sdaiVA_NSET

session not open


iterator NULL
write permission denied, or iterator is not writable
Iterator not at a valid index
Aggregate cannot be populated with an aggregate

See Also
ISO 10303-22-10.13.1; ISO 10303-24-6.11.1

4.28

sdaiCreateNestedAggrByItrADB()
SdaiAggr sdaiCreateNestedAggrByItrADB(
SdaiIterator current,
SdaiADB selaggrInstance
);

The sdaiCreateNestedAggrByItrADB() function creates a new nested aggregate in an


aggregate instance. This function should be used instead of
sdaiCreatedNestedAggrByItr() when the aggregate consists of SELECT type attributes to disambiguate the type of the new aggregate.
This function returns the newly created aggregate. The new aggregate is also placed
into the ADB specified by the parameter selaggrInstance.

SDAI C LIBRARY REFERENCE MANUAL

67

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiMX_NRW
sdaiIR_NSET
sdaiVA_NSET
sdaiAB_NEXS

session not open


iterator NULL
write permission denied, or aggregate is not writable.
Iterator not at a valid index
Aggregate cannot be populated with an aggregate
NULL ADB

See Also
ISO 10303-22-10.13.1; ISO 10303-24-6.11.1

4.29

sdaiCreateNPL()
SdaiNPL sdaiCreateNPL();

The sdaiCreateNPL() function creates a non-persistent list. A non-persistent list is


an SDAI aggregate which contains entity instances. The list may not be assigned to
an attribute (e.g. with sdaiPutAttrBN) and will be automatically deleted when the
session is closed. A non-persistent list (NPL) handle may be used in any SDAI function that takes a list as an argument.
This function returns a handle for a newly created non-persistent list. When you are
finished using it, you should call sdaiDeleteNPL() to release the memory consumed
by the NPL.

Errors
sdaiSS_NOPN

session is not open

Example
SdaiNPL list;
:
:
list = sdaiCreateNPL ();
:
:
sdaiDeleteNPL (list);

68

STEP TOOLS, INC.

4 FUNCTION REFERENCE

See Also
sdaiDeleteNPL;ISO

4.30

10303-22- 10.4.12;ISO 10303-24- 6.2.8

sdaiCreateSchemaInstance()
sdaiSchemaInstance sdaiCreateSchemaInstance(
SdaiString schemaInstanceName,
SdaiSchema schema,
SdaiRep repository
);

The sdaiCreateSchemaInstance() function create a new schema instance. A schema


instance is a collection of models which may have reference between them. Support
for schema instances is very limited in this implementation currently. They are nonpersistent, and only a single model may be added to a schema instance. This will be
changed when ROSE has full domain interoperability support.

Errors
sdaiSS_NOPN
sdaiSD_NDEF

session is not open


schema not defined

See Also
ISO 10303-22- 10.5.1; ISO 10303-24- 6.3.2

4.31

sdaiCreateSchemaInstanceBN()
SdaiSchemaInstance sdaiCreateSchemaInstanceBN(
SdaiString schemaInstanceName,
SdaiString schemaName,
SdaiRep repository
);

The sdaiCreateSchemaInstanceBN() function creates a schema new schema instance. A schema instance is a collection of models (not necessarily of the same underlying schema) which may have references between them.

SDAI C LIBRARY REFERENCE MANUAL

69

4 FUNCTION REFERENCE

Support for schema instances is very limited. They are non-persistent and do not
support domain equivalence. This will be changed after ROSE has full domain interoperability support

Errors
sdaiSS_NOPN
sdaiSD_NDEF

session is not open


schema not defined

See Also
ISO 10303-22- 10.5.1; ISO 10303-24- 6.3.2

4.32

sdaiDeleteADB()
void sdaiDeleteADB(
SdaiADB block,
);

The sdaiDeleteADB() function releases the internal storage associated with an Attribute Data Block(ADB). Any attempt to refer to the ADB handle after calling this
function is undefined.

Errors
sdaiSS_NOPN
sdaiAB_NEXS

session not open


adb is sdaiNULL

See Also
ISO 10303-24- 6.2.12.6

70

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.33

sdaiDeleteInstance()
void sdaiDeleteInstance(
SdaiAppInstance instance
);

The sdaiDeleteInstance() function deletes the entity instance specified by parameter


instance. Any access to the instance after it has been deleted is undefined.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMX_NRW

session not open


NULL entity/entity not an application instance
model not writable

See Also
ISO 10303-22-10.11.2; ISO 10303-24-6.9.3

4.34

sdaiDeleteIterator()
void sdaiDeleteIterator(
SdaiIterator iterator
);

The sdaiDeleteIterator() function deletes an iterator. Any attempts to access the iterator after it has been deleted are undefined.

Errors
sdaiSS_NOPN
sdaiIR_NEXS

session not open


iterator NULL

See Also
ISO 10303-22-10.12.4; ISO 10303-24-6.10.4

SDAI C LIBRARY REFERENCE MANUAL

71

4 FUNCTION REFERENCE

4.35

sdaiDeleteModel()
void sdaiDeleteModel(
SdaiModel model
);

The sdaiDeleteModel() function removes a model and all its contents from memory,
then permanently removes the model from its repository.
In the standard_3.0 filesystem repository, the rose or step file is deleted.

Errors
sdaiSS_NOPN
sdaiMO_NEXS

session is not open


NULL or invalid model

Example
SdaiModel mod;
:
:
sdaiDeleteModel (mod);

See Also
ISO 10303-22- 10.7.1; ISO 10303-24- 6.5.1

4.36

sdaiDeleteNPL()
void sdaiDeleteNPL(
SdaiNPL list
);

The sdaiDeleteNPL() function deletes a non-persistent list (NPL). After this function is called, the list handle specified is invalid, and any attempts to use it in any
other function are undefined.

72

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiAI_NEXS

session is not open


a sdaiNULL handle was passed

Example
see sdaiCreateNPL;

See Also
sdaiCreateNPL()

(Section 4.29, pp. 68);ISO 10303-22- 10.4.13; ISO 10303-24-

6.2.9

4.37

sdaiDeleteSchemaInstance()
void sdaiDeleteSchemaInstance(
SdaiSchemaInstance schemaInstance
);

The sdaiDeleteSchemaInstance() function deletes a specified schema instance from


its repository. Any attempt to use a deleted schema instance in undefined.

Errors
sdaiSS_NOPN
sdaiSI_NEXS

session not open


schema instance does not exist

See also
ISO 10303-22- 10.6.1; ISO 10303-24- 6.4.1

SDAI C LIBRARY REFERENCE MANUAL

73

4 FUNCTION REFERENCE

4.38

sdaiDeleteSchemaInstanceBN()
void sdaiDeleteSchemaInstanceBN (
SdaiString schemaInstanceName,
SdaiRep repository
);

The sdaiDeleteSchemaInstanceBN() function deletes a schema instance from a repository. The schema instance to be deleted is identified by a name in an open repository. The schema instance is then permanently removed from both memory and
from the repository

Errors
sdaiSS_NOPN
sdaiSI_NEXS

session not open


schema instance does not exist

Example
sdaiDeleteSchemaInstanceBN ("unwanted", repo);

See Also
ISO 10303-22-10.6.1; ISO 10303-24-6.4.1

4.39

sdaiEnd()
void sdaiEnd(
SdaiIterator iterator
);

The sdaiEnd() function positions an iterator at the end of an aggregate. The iterator's
current value in unset. The next call to sdaiPrevious() will set the iterator to the aggregates last element. This function may only be used on iterators that are traversing ordered aggregates.

Errors
sdaiSS_NOPN

74

session not open

STEP TOOLS, INC.

4 FUNCTION REFERENCE

sdaiIR_NEXS
sdaiAI_NVLD

iterator NULL
iterator is not rewindable

See Also
sdaiBeginning() (Section 4.7, pp. 51); sdaiPrevious() (Section 4.102, pp. 120); ISO
10303-22-10.15.2; ISO 10303-24-6.13.2

4.40

sdaiEndModelAccess()
void sdaiEndModelAccess(
SdaiModel model
);

The sdaiEndModelAccess() ends access to a model. The instances in the model may
no longer be accessed after this call. Accessing any of the model's instances after
this call is undefined. This function does not save the model. If you want the changes to be saved, you must save the model yourself with sdaiSaveChanges() before
ending access.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiMX_NDEF

session not open


NULL or invalid model
model not accessible

Example
SdaiSession sess;
SdaiRep repo;
SdaiModel mod;
:
sess = sdaiOpenSession();
repo = sdaiOpenRepository (sess, "standard_3.0");
:
mod = sdaiAccessModelBN (repo, "modname", sdaiRO);
:
sdaiSaveChanges (mod);
sdaiEndModelAccess (mod);

SDAI C LIBRARY REFERENCE MANUAL

75

4 FUNCTION REFERENCE

See Also
sdaiSaveChanges()

(Section 4.123, pp. 133); ISO 10303-22- 10.7.5, 10.7.7; ISO

10303-24- 6.5.5

4.41

sdaiErrorQuery()
SdaiErrorCode sdaiErrorQuery();
SdaiErrorQuery() returns

the error code of the most recent SDAI function to generate an error, then clears the error code. If a session is not open, the function returns
sdaiSS_NOPN. If there is no error, it then returns sdaiNO_ERR.
The error code is not cleared by a successful SDAI function call. The only way to
clear the error code is to call sdaiErrorQuery().

Errors
sdaiSS_NOPN

session is not open

Example
sdaiErrorQuery () /* clear error code */
sdaiGetAttrBN (inst, "att", sdaiINTEGER, &intval);
errcode = sdaiErrorQuery();
/* Get the error code */
newcode = sdaiErrorQuery();
/* new code == sdaiNO_ERR since
the error was cleared by the previous line*/

See Also
ISO 10303-24- 6.1.3.1;

76

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.42

sdaiFarCopyInstance()
SdaiAppInstance sdaiFarCopyInstance(
SdaiAppInstance instance,
SdaiModel model
);

The sdaiFarCopyInstance() function creates a new instance within the model identified by parameter model, with the same attribute values as the instance specified
by parameter instance.
This function returns a handle to the newly created instance.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiSS_NOPN
sdaiMO_NEXS
sdaiRP_NOPN
sdaiMX_NRW

session not open


NULL entity/entity not an application instance
session not open
model does not exist, or NULL value passed in
model's repo is not open
model not read-write

See Also
ISO 10303-22-10.11.2; ISO 10303-24-6.9.2

4.43

sdaiFindInstanceRolesOf()
SdaiNPL sdaiFindInstanceRolesOf(
SdaiInstance instance,
SdaiNPL domain,
SdaiNPL resultList
);

The sdaiFindInstanceRolesOf() function determines in which attributes a specified


instance is referenced as a value from another objects. It then adds the attribute to a
specified NPL (resultList).
The domain parameter is ignored by this implementation, int the future it will be
used to specify the schema instances over which the search is to be performed.

SDAI C LIBRARY REFERENCE MANUAL

77

4 FUNCTION REFERENCE

If an error occurs, this function returns sdaiNULL, otherwise it returns the resultList
parameter.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS
sdaiED_NDEF

session not open


NULL entity/entity not an application instance
NPL is not valid or NULL
NPL is not valid or NULL (is isComplex is true)

See Also
ISO 10303-22-10.10.11; ISO 10303-24-6.8.11

4.44

sdaiFindInstanceTypeOf()
SdaiNPL sdaiFindInstanceTypeOf(
SdaiInstance instance,
SdaiNPL resultList
);

The sdaiFindInstanceTypeOf() finds all the types that an instance belongs to. This
set of types includes the instance's entity, any supertypes, any SELECT types the
entity (or any supertype) belongs to, and any defined types of the selects.
instance

the instance whose types are to be found

resultList

an existing NPL to which the types will be appended. This list will
have instances of type entity_definition or defined_type added to it.

If there is no error, this function returns the resultList parameter. If an error occurs
sdaiNULL is returned.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS
sdaiED_NDEF

78

session not open


NULL entity
NPL is not valid or NULL
NPL is not valid or NULL (is isComplex is true)

STEP TOOLS, INC.

4 FUNCTION REFERENCE

See Also
ISO 10303-22-10.10.12; ISO 10303-24-6.8.12

4.45

sdaiFindInstanceUsedIn()
SdaiNPL sdaiFindInstanceUsedIn(
SdaiInstance instance,
SdaiAttr role,
SdaiNPL domain,
SdaiNPL resultList
);

The sdaiFindInstanceUsedIn() function finds the instances which reference a specified entity instance from a specified attribute. This function searches the instances
in the model containing specified instance.
This function searches all instances of the type that have role as an attribute. If that
attribute has value instance (or contains instance, where the attribute is an aggregate), then the instance is added to resultList.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS
sdaiAT_NDEF
sdaiED_NVLD

session not open


NULL entity not Application instance
NPL is not valid or NULL
NULL attribute
attribute object is not an attribute

See Also
ISO 10303-22-10.10.9; ISO 10303-24-6.8.9

SDAI C LIBRARY REFERENCE MANUAL

79

4 FUNCTION REFERENCE

4.46

sdaiFindInstanceUsedInBN()
SdaiNPL sdaiFindInstanceUsedInBN(
SdaiInstance instance,
SdaiString roleName,
SdaiNPL domain,
SdaiNPL resultList
);

The sdaiFindInstanceUsedInBN() function finds the instances which reference a


specified entity instance from a specified attribute. This function searches the instance in the model containing specified instance.
This function searches all instances of the type that have rolename as an attribute.
If that attribute has value instance (or contains instance, where the attribute is an
aggregate), then the instance is added to resultList.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS
sdaiAT_NDEF
sdaiED_NVLD
sdaiAT_NDEF

session is not open


NULL entity not Application instance
NPL is not valid or NULL
NULL attribute
attribute object is not an attribute
attribute not found, cannot parse roleName

See Also
ISO 10303-22-10.10.9; ISO 10303-24-6.8.9

4.47

sdaiFindInstanceUsers()
SdaiNPL sdaiFindInstanceUsers(
SdaiInstance instance,
SdaiNPL domain,
SdaiNPL resultList
);

The sdaiFindInstanceUsers() function finds the instances which reference a specified entity instance. This function searches the instance in the model containing the
specified instance. The instance are placed into the specified non-persistent list, resultList.

80

STEP TOOLS, INC.

4 FUNCTION REFERENCE

If the call was successful, this function returns the save value as the parameter resultList. If there is an error, it returns sdaiNULL.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS

session not open


NULL entity or entity not SdaiAppInstance
NPL is not valid or NULL

See Also
ISO 10303-22-10.10.8; ISO 10303-24-6.8.8

4.48

sdaiGetADBType()
SdaiPrimitiveType sdaiGetADBType(
SdaiADB block
);

This function returns the type of the value in an Attribute Data Block.

Errors
SS_NOPN
VT_NVLD
VA_NSET
AB_NEXS

session not open


cannot convert type
ADB is empty or sdaiNULL value passed in
adb is sdaiNULL

Example
SdaiADB adb;
switch (sdaiGetADBType(adb)) {
case sdaiINTEGER:
/* value is an integer */
break;
case sdaiREAL:
/* value is a real */
break;
}

SDAI C LIBRARY REFERENCE MANUAL

81

4 FUNCTION REFERENCE

See Also
ISO 10303-24- 6.2.12.4

4.49

sdaiGetADBTypePath()
SdaiString * sdaiGetADBTypePath(
SdaiADB block,
SdaiInteger * typeNameNumber
);

The sdaiGetADBTypePath() retrieves the type path in an ADB. This function returns an array of strings containing the type path. The length of this list is placed in
the typeNameNumber parameter. The array will persist until the next call to
sdaiGetADBTypePath().

Errors
sdaiAB_NEXS
sdaiSS_NOPN

NULL ADB
session not open

Example
SdaiADB adb;
int i;
SdaiString * typenames;
SdaiInteger nrtypes = 0;
sdaiGetADBTypePath (adb, &nrtypes);
for (i=0; i<nrtypes; i++) {
SdaiString type = typenames[i];
/* Process the type */
}

See Also
ISO 10303-24-6.18

82

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.50

sdaiGetADBValue()
void* sdaiGetADBValue(
SdaiADB block,
SdaiPrimitiveType valueType,
void *value);

The sdaiGetADBValue() function gets, converts and returns the value in an Attribute
Data Block (ADB). The block parameter specifies the ADB whose value is being
retrieved; valueType is the type of the value being retrieved; value is the address
where the function will place the value.
If there is an error, this function returns sdaiNULL, otherwise, if the requested type
is a primitive, the function returns the parameter value, otherwise, it returns the handle of the instance or aggregate.

Errors
sdaiVT_NVLD
sdaiAB_NEXS
sdaiVA_NSET

ADB value not converted to the requested type


ADB is NULL
ADB is empty or value is NULL

Example
SdaiADB adb;
SdaiReal val;
SdaiInstance instl
/* Do something to set the ADB value */
sdaiGetADBValue (adb, sdaiREAL, &val);
/* Get an instance value */
sdaiGetADBValue (adb, sdaiINSTANCE, &inst);

See Also
ISO 10303-24- 6.2.12.2

SDAI C LIBRARY REFERENCE MANUAL

83

4 FUNCTION REFERENCE

4.51

sdaiGetAggrByIndex()
void* sdaiGetAggrByIndex(
SdaiOrderedAggr aggregate,
SdaiAggrIndex index,
SdaiPrimitiveType valueType,
void *value
);

The sdaiGetAggrByIndex() function retrieves the value from an ordered aggregate


by index. This function may only be called on arrays and lists. For other types of
aggregates, use an iterator.
The valueType specifies the type of the value parameter. This should be
sdaiINTEGER, sdaiREAL, sdaiBOOLEAN, sdaiLOGICAL, sdaiSTRING, sdaiBINARY,
sdaiENUM, sdaiINSTANCE, sdaiAGGR, or sdaiADB.
If there is an error, this function returns sdaiNULL, otherwise, if the requested type
is a primitive, the function returns the parameter value, otherwise, it returns the handle of the instance or aggregate.

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiVT_NVLD
sdaiIX_NVLD

session is not open


aggregate does not exist
aggregate is not ordered
type is invalid
bad index

See Also
ISO 10303-22-10.15.1; ISO 10303-24-6.13.1

4.52

sdaiGetAggrByIterator()
void* sdaiGetAggrByIterator(
SdaiIterator iterator,
SdaiPrimitiveType valueType,
void *value
);

The sdaiGetAggrByIterator() function returns the current element from an iterator in

84

STEP TOOLS, INC.

4 FUNCTION REFERENCE

an aggregate. This is the preferred way to extract data from an aggregate, since it
will work on any type of aggregate unlike sdaiGetAggrByIndex().
The valueType parameter specifies the type of the value parameter. Its value should
be should be sdaiINTEGER, sdaiREAL, sdaiBOOLEAN, sdaiLOGICAL, sdaiSTRING,
sdaiBINARY, sdaiENUM, sdaiINSTANCE, sdaiAGGR or sdaiADB
If there is an error, this function returns sdaiNULL, otherwise, if the requested type
is a primitive, the function return the parameter value, otherwise, it returns the handle of the instance or aggregates.

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NEXS
sdaiVT_NVLD
sdaiIR_NSET

session not open


iterator does not exist
aggregate does not exist or is empty
type cannot be converted
ADB is not set to a value

See Also
ISO 10303-22-10.12.7; ISO 10303-24-6.10.7

4.53

sdaiGetAllAttrs()
SdaiADB* sdaiGetAllAttrs(
SdaiInstance instance,
SdaiInteger *numberAttr
);

The sdaiGetAllAttrs() function retrieves all the explicit attributes from an entity instance. This function is only supported for application instances. The attribute are
returned as a array of ADB's. The size of this array is placed into the integer referred
to by the numberAttr parameter.
This function returns an array of ADBs. The size of the array is returned in the parameter numberAttr. This array and its contents will remain valid until the next call
to sdaiGetAllAttrs. Do not call sdaiDeleteADB() on the elements of this array, since
they are automatically deleted.

SDAI C LIBRARY REFERENCE MANUAL

85

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMX_NRW

session not open


NULL entity/entity not an application instance
model not read-write

See Also
ISO 10303-24-6.8.13.2

4.54

sdaiGetAttr()
void* sdaiGetAttr(
SdaiInstance instance,
SdaiAttr attribute,
SdaiPrimitiveType valueType,
void *value
);

The sdaiGetAttr function() returns the value of one of the attributes of an entity instance. The valueType parameter identifies the type of the value parameter. This
should be sdaiINTEGER, sdaiREAL, sdaiBOOLEAN, sdaiLOGICAL, sdaiSTRING,
sdaiBINARY, sdaiENUM, sdaiINSTANCE, sdaiAGGR, or sdaiADB.
This function will get the values of all explicit attributes. Inverse and derived attributes can only be obtained if the full dictionary is available. See The SDAI Dictionary (Section 2.2.2, pp. 6) for more information. For derived attributes, you must
link against the sdai_validate library so that the EXPRESS interpreter is available
to evaluate the attribute.
If an error was generated, this function returns sdaiNULL, otherwise, if valueType is
sdaiINSTANCE, sdaiAGGR, or sdaiADB, a handle for the requested object is returned. Otherwise, the return value is the same pointer as the value parameter.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiSS_NOPN
sdaiAT_NDEF
sdaiED_NVLD
sdaiVA_NSET
sdaiVT_NVLD

86

session is not open


entity instance is NULL
session not open
NULL attribute
attribute object is not an attribute
value is not set
invalid type

STEP TOOLS, INC.

4 FUNCTION REFERENCE

sdaiFN_NAVL
sdaiAT_NVLD

derived attribute is not supported


attribute is not in instance

Example
SdaiInstance inst;
SdaiAttribute attr;
SdaiInteger intval;
:
:
sdaiGetAttr (inst, att, sdaiINTEGER, &intval);

See Also
sdaiGetAttrBN() (Section

4.55, pp. 87); ISO 10303-22- 10.10.1; ISO 10303-24-

6.8.1

4.55

sdaiGetAttrBN()
void* sdaiGetAttrBN(
SdaiInstance instance,
SdaiString attributeName,
SdaiPrimitiveType valueType,
void *value
);

This function returns the value of one of the attributes of an entity instance. To avoid
repeated name lookups, you should use sdaiGetAttr() instead of this function if you
will be processing large numbers of objects.
The valueType parameter specifies the type of the value parameter. This should be
sdaiINTEGER, sdaiREAL, sdaiBOOLEAN, sdaiLOGICAL, sdaiSTRING, sdaiBINARY,
sdaiENUM, sdaiINSTANCE, sdaiAGGR, or sdaiADB.
This function will get the values of all explicit attributes. Inverse and derived attributes can only be obtained if the full dictionary is available. See The SDAI Dictionary (Section 2.2.2, pp. 6) for more information. For derived attributes, you must
link against the sdai_validate library so that the EXPRESS interpreter is available
to evaluate the attribute.
If an error was generated, this function returns sdaiNULL, otherwise, if valueType is
sdaiINSTANCE, sdaiAGGR, or sdaiADB, a handle for the requested object is returned. Otherwise, the return value is the same pointer as the value parameter.

SDAI C LIBRARY REFERENCE MANUAL

87

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiEI_NEXT
sdaiSS_NOPN
sdaiAT_NDEF
sdaiED_NVLD
sdaiVA_NSET
sdaiVT_NVLD
sdaiFN_NAVL
sdaiAT_NVLD

session is not open


entity instance is NULL
session not open
NULL attribute
attribute object is not an attribute
value is not set
invalid type
derived attribute is not supported
attribute is not in instance

See Also
sdaiGetAttr()

4.56

(Section 4.54, pp. 86); ISO 10303-22- 10.10.1; ISO 10303-24- 6.8.1

sdaiGetAttrDefinition()
SdaiAttr sdaiGetAttrDefinition(
SdaiEntity entity,
SdaiString attrName
);

The sdaiGetAttrDefinition() function returns one of the attribute definitions of an entity type. The attribute to be found is passed specified in the attrName parameter.
The function returns the attribute definition if found, otherwise sdaiNULL.

Errors
sdaiSS_NOPN
sdaiED_NDEF
sdaiAT_NDEF

session not open.


entity not defined.
attribute not defined for the entity.

See Also
sdaiGetAttrDefinitionBN() (Section

88

4.57, pp. 89); ISO 10303-24- 6.7.5.1

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.57

sdaiGetAttrDefinitionBN()
SdaiAttr sdaiGetAttrDefinitionBN(
SdaiString schemaName,
SdaiString entityName,
SdaiString attrName
);

The getGetAttrDefinitionBN() function returns one of the attribute definitions of an


entity type.
schemaName

the name of the schema in which to find the entity.

entityName

the name of the entity containing the attribute.

attrName

the name of the attribute within the entity type.

This function returns attribute definition if found, otherwise sdaiNULL.

Errors
sdaiSS_NOPN
sdaiSD_NDEF
sdaiED_NDEF
sdaiAT_NDEF

session not open.


schema is not defined.
entity not defined.
attribute not defined for the entity.

See Also
sdaiGetAttrDefinition()

4.58

(Section 4.56, pp. 88); ISO 10303-24- 6.7.5.1

sdaiGetAttrs()
void sdaiGetAttrs(
SdaiInstance instance,
SdaiInteger numberAttr,
SdaiAttr attribute,
SdaiPrimitiveType valueType,
void *value,
...);

The sdaiGetAttrs() function gets the values of one or more attributes from an entity
instance.

SDAI C LIBRARY REFERENCE MANUAL

89

4 FUNCTION REFERENCE

instance

the entity instance from which the attribute are to be retrieved.

numberAttr

the number of attribute to be read.

attribute

the first attribute to be read

valueType

the type of the first attribute.

value

pointer to an object of type specified in valueType where the first


value is placed.

...

the parameters attribute valueType and value are repeated for every
attribute that is to be read. There must be as many attribute triples as
numberAttr.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiSS_NOPN
sdaiAT_NDEF
sdaiED_NVLD
sdaiVA_NSET
sdaiVT_NVLD
sdaiAT_NVLD

session is not open


entity instance is NULL
session not open
NULL attribute
attribute object is not an attribute
value is not set
invalid type
attribute is in instance

Example
sdaiGetAttrs (inst, 3,
att1, sdaiINTEGER, &intval,
att2, sdaiSTRING, &strval,
att3, sdaiINSTANCE, &instval);

See Also
sdaiGetAttrsBN() (Section

90

4.59, pp. 91); ISO 10303-24-6.8.13.1

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.59

sdaiGetAttrsBN()
void sdaiGetAttrsBN(
SdaiInstance instance,
SdaiInteger numberAttr,
SdaiString attributeName,
SdaiPrimitiveType valueType,
void *value,
...);

The sdaiGetAttrsBN() function gets the values of one or more attributes from an entity instance specified by parameter instance.
numberAttr

the number of attributes to be read.

attributeName

the name of the first attribute to be read

valueType

the type of the first attribute.

value

pointer to an object of type specified in valueType where the first


value is placed.

...

the parameters attributeName, valueType and value are repeated for


every attribute that is to be read. There must be as many attribute triples as numberAttr.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiSS_NOPN
sdaiAT_NDEF
sdaiED_NVLD
sdaiVA_NSET
sdaiVT_NVLD
sdaiAT_NVLD

session is not open


entity instance is NULL
session not open
NULL attribute
attribute object is not an attribute
value is not set
invalid type
attribute is in instance

See Also
sdaiGetAttrs() (Section

SDAI C LIBRARY REFERENCE MANUAL

4.58, pp. 89); ISO 10303-24-6.8.13.1

91

4 FUNCTION REFERENCE

4.60

sdaiGetComplexEntity()
SdaiEntity sdaiGetComplexEntity(
SdaiNPL entityList
);

The sdaiGetComplexEntity() searches a schema for a complex (AND_OR) entity


definition and returns it. The complex type must be declared in the working set
when the schema is compiled into the ROSE schema file.
The entityList parameter specifies a non-persistent list consisting of
entity_definition instances that represent the supertypes of the complex entity.
This function returns an instance handle to an instance of type entity_definition,
where entity_definition identifies the requested complex instance.

Errors
sdaiSS_NOPN
sdaiED_NDEF
sdaiED_NVLD

session not open


NPL is not valid or NULL or list is empty, entity not in schema
an entity in the list is not valid

See Also
ISO 10303-22-10.9.1; ISO 10303-24-6.7.1

4.61

sdaiGetComplexEntityBN()
SdiaEntity sdaiGetComplexEntityBN(
SdaiString schemaName,
SdaiInteger nameNumber,
SdaiString *nameVector
);

The sdaiGetComplexEntityBN() function returns the entity_definition, if any, for the


entity data type composed of the entity types whose names are supplied. The entity
type to be returned must have been compiled into the ROSE schema using the working set option of expfront. This function will not construct a complex entity on the
fly.
schemaName

92

the name of the schema in which to find entity definitions.

STEP TOOLS, INC.

4 FUNCTION REFERENCE

nameNumber

the number of entity names supplied in the nameVector argument.

nameVector

pointer to a vector of entity names.

This function returns the corresponding entity definition if it exists, otherwise


sdaiNULL.

Errors
sdaiSS_NOPN
sdaiSD_NDEF
sdaiED_NDEF
sdaiED_NVLD

session not open.


schema is not defined.
list of names is NULL or empty, or entity is not in the schema.
an entity name in the list is not valid.

See Also
ISO 10303-22- 10.9.1; ISO 10303-24- 6.7.1

4.62

sdaiGetDescription()
SdaiString sdaiGetDescription(
SdaiAppInstance instance,
SdaiString descriptionBuffer
);

The sdaiGetDescription() function gets a human-readable description of an entity


instance specified by parameter instance. In this implementation, this function returns the instances type. The description is a NULL terminated string, and is placed
into descriptionBuffer. This buffer should be at least 1024 characters.
This function returns the descriptionBuffer parameter.

Errors
sdaiSS_NOPN
sdaiEI_NEXS

session not open


NULL entity/entity not an application instance

See Also
ISO 10303-22-10.11.8; ISO 10303-24-6.9.9

SDAI C LIBRARY REFERENCE MANUAL

93

4 FUNCTION REFERENCE

4.63

sdaiGetEntity()
SdaiEntity sdaiGetEntity(
SdaiModel model,
SdaiString name
);

The sdaiGetEntity() function finds an entity definition by name in a model's schema.


This function looks in the model's schema for an entity_definition instance with the
specified name.
This function returns an instance of entity_definition, if the instance could be found.
Otherwise, it returns sdaiNULL and flags an error.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiMX_NDEF
sdaiED_NDEF

session not open


NULL or invalid model
model not accessible
cannot find entity or NULL name

Example
SdaiSession sess;
SdaiRep repo;
SdaiModel mod;
SdaiEntity ent;
:
sess = sdaiOpenSession();
repo = sdaiOpenRepository (sess, "standard_3.0");
mod = sdaiAccessModelBN (repo, "modname", sdaiRO);
:
ent = sdaiGetEntity (mod, "cartesian_point");

See Also
ISO 10303-22- 10.7.8; ISO 10303-24- 6.5.6

94

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.64

sdaiGetEntityExtent()
SdaiSet sdaiGetEntityExtent(
SdaiModel model,
SdaiEntity entity
);

The sdaiGetEntityExtent() function gets an entity extent for a model. An entity extent is the set of all instances of a specified entity (or its subtypes). The entity extents may also be obtained by examining model.contents.folders, however this
function is more convenient.
This function returns an object of type SdaiSet containing all the objects of the requested type.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiRP_NOPN
sdaiED_NDEF
sdaiMX_NDEF

session not open


model does not exist, or NULL value passed in
model's repo is not open
entity definition NULL or not defined
model access not defined

See Also
ISO 10303-24- 6.5.10.2; sdaiGetEntityExtentBN() (Section 4.65, pp. 95)

4.65

sdaiGetEntityExtentBN()
SdaiSet sdaiGetEntityExtentBN(
SdaiModel model,
SdaiString entityName
);

The sdaiGetEntityExtentBN() function gets an entity extent for a model. An entity


extent is the set of all instances of a specified entity (or its subtypes). The entity extents may also be obtained by examining model.contents.folders. The type is specified by name as the parameter entityName.
This function returns an object of type SdaiSet containing all the objects of the requested type.

SDAI C LIBRARY REFERENCE MANUAL

95

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiRP_NOPN
sdaiED_NDEF
sdaiMX_NDEF

session not open


model does not exist, or NULL value passed in
model's repo is not open
entity definition NULL or not defined
model access not defined

See Also
ISO 10303-24- 6.5.10.2; sdaiGetEntityExtent() (Section 4.64, pp. 95);

4.66

sdaiGetInstanceModel()
SdaiModel sdaiGetInstanceModel(
SdaiInstance instance
);

The sdaiGetInstancemodel() function returns the model containing the instance


specified by parameter instance.
This functions returns a handle for the instance's model. If there is an error, it returns
sdaiNULL.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMO_NEXS

session not open


entity instance does not exist
instance has no model

See Also
ISO 10303-22-6.8.3; ISO 10303-24-10.10.3

96

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.67

sdaiGetInstanceType()
SdaiEntity sdaiGetInstanceType(
SdaiInstance instance
);

The sdaiGetInstanceType() function returns the type (entity_definition) on an entity


instance.
This function returns a handle to an instance of type SdaiEntity.

Errors
sdaiSS_NOPN
sdaiEI_NEXS

session not open


NULL entity

See Also
ISO 10303-22-10.10.4; ISO 10303-24-6.8.4

4.68

sdaiGetLowerIndex()
SdaiInteger sdaiGetLowerIndex(
SdaiArray array
);

The sdaiGetLowerIndex() function determines the lower index in an array. EXPRESS allows arrays to have user-defined upper and lower bounds, and this function returns the lower bound of an array. In this implementation, arrays always
begin at zero, and so this function always returns 0.

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD

session is not open


aggregate does not exist
aggregate is not an array

ISO 10303-22-10.17.3; ISO 10303-24-6.15.3

SDAI C LIBRARY REFERENCE MANUAL

97

4 FUNCTION REFERENCE

4.69

sdaiGetMemberCount()
SdaiInterger sdaiGetMemberCount(
SdaiAggr aggregate
);

The sdaiGetMemberCount() function returns a count of the number of elements in


an aggregate.

Errors
sdaiSS_NOPN
sdaiAI_NEXS

session not open.


the aggregate does not exist.

See Also
ISO 10303-22- 10.12.1; ISO 10303-24- 6.10.1

4.70

sdaiGetPersistentLabel()
SdaiString sdaiGetPersistentLabel(
SdaiAppInstance instance,
SdaiString labelBuffer
);

The sdaiGetPersistentLabel() function returns a persistent identifier for an application instance. The persistent label is a string of at most 256 characters, and is placed
into the memory pointed to by the labelBuffer parameter.

Errors
sdaiSS_NOPN
sdaiAI_NEXS

session not open.


the aggregate does not exist.

See also
sdaiGetSessionId() (Section 4.71, pp. 99); ISO 10303 - 22-10.11.6; ISO 10303 - 24-

6.9.7

98

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.71

sdaiGetSessionId()
SdaiAppInstance sdaiGetSessionId(
SdaiRep repository,
SdaiString label
);

The sdaiGetSessionId() function finds that instance which has a specific persistent
label in the repository specified by the parameter repository.

Errors
sdaiSS_NOPN
sdaiEI_NEXS

session not open


entity instance was not found

See also
sdaiGetPersistentLabel() (Section 4.70, pp. 98); ISO 10303 - 22-10.11.7; ISO 10303

- 24-6.9.8

4.72

sdaiGetSchema()
SdaiSchema sdaiGetSchema(
SdaiString schemaName
);

The sdaiGetSchema() function finds and returns a schema definition by name. If the
dictionary does not exist, this function generates it from the rose schema file, and
possibly the EXPRESS parse data. It returns the appropriate schema_definition object from the dictionary model.
If successful, this function returns the handle of the appropriate schema_definition
entity. Otherwise, it returns sdaiNULL.

Errors
sdaiSS_NOPN
sdaiSD_NDEF
sdaiRP_NOPN

session not open


cannot find schema or NULL value
repository is not open

SDAI C LIBRARY REFERENCE MANUAL

99

4 FUNCTION REFERENCE

Example
SdaiSchema sch;
sch = sdaiGetSchema (schemaName);

See Also
ISO 10303-24- 6.4.10.1

4.73

sdaiGetSchemaInstance()
SdaiSchemaInstance sdaiGetSchemaInstance(
DdaiString schemaInstanceName,
SdaiRep repository
);

The sdaiGetSchemaInstance() function finds a schema instance by name in a repository.

Errors
sdaiSS_NOPN
sdaiRP_NEXS
sdaiRP_NOPN
sdaiSI_NEXS

session not open


NULL or invalid repo
repository is not open
could not find schema instance

Example
SdaiSchemaInstance si;
si = sdaiGetSchemaInstance ("siname", rep);

See Also
ISO 10303-24-6.4.10.2

100

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.74

sdaiGetUpperIndex()
SdaiInteger sdaiGetUpperIndex(
SdaiArray array
);

The sdaiGetUpperIndex() function returns the maximum index value in an array.


This function returns the highest index at which an element may be placed. (In this
implementation, the upper index is one less than the size of the array.)

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD

session is not open


aggregate does not exist
aggregate is not an array

See Also
ISO 10303-22-10.17.4; ISO 10303-24-6.15.4

4.75

sdaiInsertAfter()
void sdaiInsertAfter(
SdaiIterator iterator,
SdaiPrimitiveType valueType,
<TYPE> value);

The sdaiInsertAfter() function inserts a value into an ordered aggregate after the current position of an iterator.

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NVLD
sdaiMX_NRW
sdaiIR_NSET
sdaiAI_NVLD
sdaiVT_NVLD

session not open


iterator NULL
aggregate/iterator not writable
write permission denied
iterator has no current member
aggregate is invalid
invalid type

SDAI C LIBRARY REFERENCE MANUAL

101

4 FUNCTION REFERENCE

See also
ISO 10303-22-10.19.2; ISO 10303-24-6.17.2

4.76

sdaiInsertBefore()
void sdaiInsertBefore(
SdaiIterator iterator,
SdaiPrimitiveType valueType,
<TYPE> value
);

The sdaiInsertBefore() function inserts value into an ordered aggregate before the
current value in an iterator.

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NVLD
sdaiMX_NRW:
sdaiIR_NSET
sdaiAI_NVLD
sdaiVT_NVLD

session not open


iterator NULL
aggregate/iterator not writable
write permission denied
iterator has no current member
aggregate is invalid
invalid type

See Also
ISO 10303-22-10.19.1; ISO 10303-24-6.17.1

4.77

sdaiInsertByIndex()
void sdaiInsertByIndex(
SdaiList list,
SdaiAggrIndex index,
SdaiPrimitiveType valueType,
<TYPE> value);

The sdaiInsertByIndex() function inserts a value into a list at the specified index.

102

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW
sdaiIX_NVLD
sdaiAI_NVLD
sdaiVT_NVLD

session is not open


aggregate does not exist
aggregate is internal and thus not writable
model is not writable
index not valid
aggregate not valid
type invalid

See Also
ISO 10303-22-10.19.3; ISO 10303-24-6.17.3

4.78

sdaiInsertNestedAggrAfter()
SdaiAggr sdaiInsertNestedAggrAfter(
SdaiIterator iterator
);

The sdaiInsertNestedAggrAfter() function creates a nested aggregate and inserts a


value into an aggregate after the current value.
This function returns the newly created aggregate

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NVLD
sdaiMX_NRW:

session not open


iterator NULL
aggregate/iterator not writable
write permission denied

See Also
ISO 10303-22-10.19.5; ISO 10303-24-6.17.5

SDAI C LIBRARY REFERENCE MANUAL

103

4 FUNCTION REFERENCE

4.79

sdaiInsertNestedAggrAfterADB()
SdaiAggr sdaiInsertNestedAggrAfterADB(
SdaiIterator iterator,
SdaiADB selaggrInstance
);

The sdaiInsertNestedAggrAfterADB() function creates and inserts an aggregate into


an aggregate after the current value of an iterator. The selaggrInstance is an ADB
identifying the type of the aggregate to be created in the event the elements of the
aggregates are SELECTS. This ADB is also populated with the newly created aggregate.
This function returns the newly created aggregate

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NVLD
sdaiMX_NRW:

session not open


iterator NULL
aggregate/iterator not writable
write permission denied

See Also
ISO 10303-22-10.19.5; ISO 10303-24-6.17.5

4.80

sdaiInsertNestedAggrBefore()
SdaiAggr sdaiInsertNestedAggrBefore(
SdaiIterator iterator
);

The sdaiInsertNestedAggrBefore() function creates and inserts a new aggregate instance into the aggregate specified by the iterator before the current value of the iterator.
This function returns the newly created aggregate.

104

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NVLD
sdaiMX_NRW:

session not open


iterator NULL
aggregate/iterator not writable
write permission denied

See Also
ISO 10303-22-10.19.4; ISO 10303-24-6.17.4

4.81

sdaiInsertNestedAggrBeforeADB()
SdaiAggr sdaiInsertNestedAggrBeforeADB(
SdaiIterator iterator,
SdaiADB selaggrInstance
);

The sdaiInsertNestedAggrBeforeADB() function creates and inserts a new aggregate


instance into an aggregate before the current value.
The selaggrInstance parameter is an ADB which identifies the type of the aggregate
to be created in the event the elements of the aggregates are SELECTS. This ADB
is also populated with the newly created aggregate.
This function returns the newly created aggregate.

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NVLD
sdaiMX_NRW

session not open


iterator NULL
aggregate/iterator not writable
write permission denied

See Also
ISO 10303-22-10.19.4; ISO 10303-24-6.17.4

SDAI C LIBRARY REFERENCE MANUAL

105

4 FUNCTION REFERENCE

4.82

sdaiInsertNestedAggrByIndex()
SdaiAggr sdaiInsertNestedAggrByIndex(
SdaiList list,
SdaiAggrIndex index
);

The sdaiInsertNestedAggrByIndex() function creates and inserts a new aggregate instance into an existing aggregate.
The function returns new newly created aggregate.

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW

session is not open


aggregate does not exist
aggregate is internal and thus not writable
model is not writable

See Also
ISO 10303-22-10.19.6; ISO 10303-24-6.17.6

4.83

sdaiInsertNesterAggrByIndexADB()
SdaiAggr sdaiInsertNestedAggrByIndexADB(
SdaiList list,
SdaiAggrIndex index,
SdaiADB selaggrInstance
);

The sdaiInsertNestedAggrByIndexADB() function creates and inserts a new aggregate instance into an existing aggregate.
The selaggrInstance parameter specifies an ADB identifying the type of the aggregate to be created in the event the elements of the aggregates are SELECTS. This
ADB is also populated with the newly created aggregate.
The function returns the newly created aggregate.

106

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiAB_NEXS
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW

NULL ADB
session is not open
aggregate does not exist
aggregate is internal and thus not writable
model is not writable

See Also
ISO 10303-22-10.19.6; ISO 10303-24-6.17.6

4.84

sdaiIsInstanceOf()
SdaiBoolean sdaiIsInstanceOf(
SdaiInstance instance,
SdaiEntity entity
);

The sdaiIsInstanceOf() function determines whether an instance is of a specified


type. For this function to return true, the instance must be an instance of the specified entity definition (parameter entity), and not a subtype.
If instance is an instance of entity this function return sdaiTRUE, otherwise it returns
sdaiFALSE. If an error occurs, it returns sdaiFALSE.

Errors
sdaiSS_NOPN
sdaiEI_NEXS

session not open


NULL entity

See Also
ISO 10303-22-10.10.5; ISO 10303-24-6.8.5

SDAI C LIBRARY REFERENCE MANUAL

107

4 FUNCTION REFERENCE

4.85

sdaiIsInstanceOfBN()
SdaiBoolean sdaiIsInstanceOfBN(
SdaiInstance instance,
SdaiString entityName
);

The sdaiIsInstanceOfBN() function determines whether an instance is of a specified


type. For this function to return true, the instance must be an instance of the type,
and not a subtype.
If instance is an instance of the entity specified by parameter entityName this function returns sdaiTRUE, otherwise it returns sdaiFALSE. If an error occurs, it returns
sdaiFALSE.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiED_NDEF

session not open


NULL entity
entity definition NULL or not defined

See Also
ISO 10303-22-10.10.5; ISO 10303-24-6.8.5

4.86

sdaiIsEqual()
SdaiBoolean sdaiIsEqual(
SdaiInstance inst1,
SdaiInstance inst2
);

The sdaiIsEqual() function determines if two instance handles refer to the same underlying entity instance.

Example
SdaiInstance foo;
SdaiInstance bar;
if (sdaiIsEqual(foo, bar)) {

108

STEP TOOLS, INC.

4 FUNCTION REFERENCE

printf ("Equal\n");
}

See Also
ISO 10303-24-6.1.4.1

4.87

sdaiIsKindOf()
SdaiBoolean sdaiIsKindOf(
SdaiInstance instance,
SdaiEntity entity
);

The sdaiIsKindOf() function determines whether an instance is of a specified type or


one of its subtypes.
instance

the instance to be tested

entity

the type to compare.

This function returns sdaiTRUE if instance is an instance of entity of is one of its


subtypes. Otherwise, it returns sdaiFALSE.

Errors
sdaiSS_NOPN
sdaiEI_NEXS

session not open


NULL entity

See Also
ISO 10303-22-10.10.6; ISO 10303-24-6.8.6

SDAI C LIBRARY REFERENCE MANUAL

109

4 FUNCTION REFERENCE

4.88

sdaiIsKindOfBN()
SdaiBoolean sdaiIsKindOfBN(
SdaiInstance instance,
SdaiString entityName
);

The sdaiIsKindOfBN() function determines whether an instance is of a specified type


or one of its subtypes.
instance

the instance to be tested

entityName

name of the type to compare.

This function return sdaiTRUE if instance is an instance of entity of is one of its subtypes. Otherwise, it returns sdaiFALSE.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiED_NDEF

session not open


NULL entity
entity definition NULL or not defined

See Also
ISO 10303-22-10.10.6; ISO 10303-24-6.8.6

4.89

sdaiIsMember()
SdaiBoolean sdaiIsMember(
SdaiAggr aggregate,
SdaiPrimitiveType valueType,
<TYPE> value
);

The sdaiIsMember() function determines whether a given value is present as an element of a given aggregate.
This function returns sdaiTRUE if the given value is present in the aggregate,
if not or if error.

sdaiFALSE

110

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiVT_NVLD
sdaiAI_NEXS

session not open.


the given value could not be converted appropriate type
the aggregate does not exist.

See Also
ISO 10303-22- 10.12.2; ISO 10303-24- 6.10.2

4.90

sdaiIsSDAIKindOf()
SdaiBoolean sdaiIsSDAIKindOf(
SdaiInstance instance,
SdaiEntity entity
);

The sdaiIsSDAIsKindOf() function determines whether an instance is of a specified


type or one of its subtypes. This function also considers the type hierarchy is in
SDAI population schema.
This function return sdaiTRUE if instance is an instance of entity of is one of its subtypes. Otherwise, it returns sdaiFALSE.

Errors
sdaiSS_NOPN
sdaiEI_NEXS

session not open


NULL entity

See Also
ISO 10303-22-10.10.7; ISO 10303-24-6.8.7

SDAI C LIBRARY REFERENCE MANUAL

111

4 FUNCTION REFERENCE

4.91

sdaiIsSDAIKindOfBN()
SdaiBoolean sdaiIsSDAIKindOfBN(
SdaiInstance instance,
SdaiString entityName
);

The sdaiIsSDAIKindOfBN() function determines whether an instance is of a specified type or one of its subtypes. This function also considers the type hierarchy is in
SDAI population schema. (That is, the inheritance hierarchy is rooted at
entity_instance, rather than an entity without any supertypes.)
This function return sdaiTRUE if instance is an instance of entity of is one of its subtypes. Otherwise, it returns sdaiFalse.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiED_NDEF

session not open


NULL entity
entity definition NULL or not defined

See Also
ISO 10303-22-10.10.7; ISO 10303-24-6.8.7

4.92

sdaiIsSDAISubtypeOf()
SdaiBoolean sdaiIsSDAISubtypeOf(
SdaiEntity subtype,
SdaiEntity supertype
);

This function determines whether an entity is a subtype of (or the same as) another
entity. SDAI-specific entities are allowed. (That is, the inheritance hierarchy is
rooted at entity_instance, rather than an entity without any supertypes.)
The function returns sdaiTRUE if the types are the same or if subtype is a subtype
of supertype; sdaiFALSE otherwise.

112

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiED_NDEF

session not open.


an entity is not defined.

See Also
ISO 10303-22- 10.9.3; ISO 10303-24- 6.7.3

4.93

sdaiIsSDAISubtypeOfBN()
SdaiBoolean sdaiIsSDAISubtypeOfBN(
SdaiString schemaName,
SdaiString subName,
SdaiString superName
);

The sdaiIsSDAISubtypeOfBN() function determines whether an entity is a subtype


of (or the same as) another entity. SDAI-specific entity names are allowed.
This function returns sdaiTRUE if the types are the same or if subName names a subtype of superName; sdaiFALSE otherwise.

Errors
sdaiSS_NOPN
sdaiSD_NDEF
sdaiED_NDEF

session not open.


schema is not defined.
an entity is not defined.

See Also
ISO 10303-22- 10.9.3; ISO 10303-24- 6.7.3

SDAI C LIBRARY REFERENCE MANUAL

113

4 FUNCTION REFERENCE

4.94

sdaiIsSubtypeOf()
SdaiBoolean sdaiIsSubtypeOf(
SdaiEntity subtype,
SdaiEntity supertype
);

This function determines whether an entity is a subtype of (or the same as) another
entity.
This function returns sdaiTRUE if the types are the same or if subtype is a subtype
of supertype, sdaiFALSE otherwise.

Errors
sdaiSS_NOPN
sdapED_NDEF

session not open.


an entity is not defined.

See Also
ISO 10303-22- 10.9.2; ISO 10303-24- 6.7.2

4.95

sdaiIsSubtypeOfBN()
SdaiBoolean sdaiIsSubtypeOfBN(
SdaiString schemaName,
SdaiString subName,
SdaiString superName
);

The sdaiIsSubtypeOfBN() function determines whether an entity is a subtype of (or


the same as) another entity.
This function returns sdaiTRUE if the types are the same or if subName names a subtype of superName, otherwise it returns sdaiFALSE.

Errors
sdaiSS_NOPN
sdaiSD_NDEF

114

session not open.


schema is not defined.

STEP TOOLS, INC.

4 FUNCTION REFERENCE

sdaiED_NDEF

an entity is not defined.

See Also
ISO 10303-22- 10.9.2; ISO 10303-24- 6.7.2

4.96

sdaiLogicalCompare()
int sdaiLogicalCompare(
SdaiLogical value1,
SdaiLogical value2
);
sdaiLogicalCompare() compares two logical values. Logical values are defined such

that
sdaiFALSE

< sdaiUNKNOWN < sdaiTRUE

The function returns 0, +1 or -1 according to the following:


value1 < value2
value1 == value2
value1 > value2

-1
0
+1

Unlike most other SDAI functions, sdaiLogicalCompare() can be called when there
is no open session.

Errors
This function does not generate SDAI errors under any conditions.

Example
The following call:
val = sdaiLogicalCompare (sdaiFalse, sdaiUNKNOWN);

Returns the value -1

SDAI C LIBRARY REFERENCE MANUAL

115

4 FUNCTION REFERENCE

See Also
ISO 10303-24- 6.1.2.1

4.97

sdaiNearCopyInstance()
SdaiAppInstance sdaiNearCopyInstance(
SdaiAppInstance instance
);

The sdaiNearCopyInstance() function creates a new instance within the same model
and with the same attribute values as an instance.
This function returns a handle to the newly created instance.

Errors
sdaiSS_NOPN
sdaiEI_NEXS

session not open


NULL entity/entity not an application instance

See Also
ISO 10303-22-10.11.1; ISO 10303-24-6.9.1

4.98

sdaiNext()
SdaiBoolean sdaiNext(
SdaiIterator iterator
);

The sdaiNext() function advances an iterator to the next element. In a newly created
iterator, or after sdaiBeginning() has been called, the first call to sdaiNext will advance the iterator to the first element.
This function returns a boolean value indicating whether or not the iterator was advanced to the next element. This allows sdaiNext() to be easily used in a while loop
to iterate over all the aggregate's elements.

116

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NEXS

session not open


iterator does not exist
aggregate does not exist or is empty

Example
/*To iterate over every element in an aggregate: */
SdaiIterator itor;
itor = sdaiCreateIterator (aggr);
while (sdaiNext (itor)) {
/* Get the value (replace TYPE with the aggregate type) */
sdaiGetAggrByIterator (itor, TYPE, &value);
/* Now process the element */
}
sdaiDeleteIterator(itor);

See Also
ISO 10303-22-10.12.6; ISO 10303-24-6.10.6

4.99

sdaiOpenRepository()
SdaiRep sdaiOpenRepository(
SdaiSession session
SdaiRep repository
);

The sdaiOpenRepository() function opens a repository and makes it possible to create and access models in that repository. The repository handle may be obtained
from the session object in the attribute known_servers. If you know the name of the
repository to open, it may be more convenient to use sdaiOpenRepositoryBN.
The function returns the handle of the newly opened repository.

Errors
sdaiSS_NOPN
sdaiRP_NEXS

session is not open


repository specified is sdaiNULL, or is not a repository

SDAI C LIBRARY REFERENCE MANUAL

117

4 FUNCTION REFERENCE

Example
/* This code finds and opens the first non-system repository found in
the system */
SdaiSession sess = sdaiNULL;
SdaiAggr reposet = sdaiNULL;
SdaiIterator itor;
SdaiString reponame;
SdaiInstance repo;
sess = sdaiOpenSession ();
sdaiGetAttrBN (sess, "known_servers", sdaiAGGR, &reposet);
itor = sdaiCreateIterator (reposet);
sdaiNext (itor);
do {
sdaiGetAggrByIterator (itor, sdaiINSTANCE, &repo);
sdaiGetAttrBN (repo, "name", sdaiSTRING, &reponame);
} while (!strcmp(reponame, "SDAI_INTERNAL") && sdaiNext(itor));
repoval = sdaiOpenRepository (sess, sdaiNULL);

See Also
sdaiOpenRepositoryBN()

(Section 4.100, pp. 118); ISO 10303-22- 10.4.5;ISO

10303-24- 6.2.4

4.100

sdaiOpenRepositoryBN()
SdaiRep sdaiOpenRepositoryBN(
SdaiSession session,
SdaiString repositoryName
);

The sdaiOpenRepositoryBN() function opens a repository by name. In this implementation the filesystem repository ($ROSE_DB) is named standard_3.0. This
function takes two parameters, this first, session, is the current SDAI session object, the second, repositoryName is the name of the repository to be opened.

118

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiRP_NEXS

session is not open


repository specified does not exist

See Also
ISO 10303-22- 10.4.5; ISO 10303-24- 6.2.4

4.101

sdaiOpenSession()
SdaiSession sdaiOpenSession();

The sdaiOpenSession() function initializes the internal SDAI data structures for
further SDAI calls. This function must be called before any other SDAI function.
If there was no error, sdaiOpenSession() returns a handle to an instance of
sdai_session, otherwise it returns sdaiNULL.

Errors
sdaiSS_OPN

session is already open

Example
SdaiSession sess;
sess = sdaiOpenSession();

See Also
sdaiCloseSession() (Section 4.9, pp. 52); ISO

10303-22- 10.3.1; ISO 10303-24-

6.1.1

SDAI C LIBRARY REFERENCE MANUAL

119

4 FUNCTION REFERENCE

4.102

sdaiPrevious()
SdaiBoolean sdaiPrevious(
SdaiIterator iterator
);

The sdaiPrevious() function positions an iterator, iterator to the previous element.


This function may only be used on iterators that are traversing ordered aggregates.
This function returns a boolean value indicating whether the aggregate was successfully positioned.

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NVLD

session not open


iterator NULL
iterator is not rewindable

See Also
sdaiNext() (Section

4.103

4.98, pp. 116); ISO 10303-22-10.15.3; ISO 10303-24-6.13.3

sdaiPromoteModel()
void sdaiPromoteModel(
SdaiModel model
);

The sdaiPromoteModel() function converts a read-only model to a read-write model.


The model must be open in read-only mode. After a successful call to this function,
the model will be open in read-write mode, and model.mode is set to read_write.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiMX_NDEF
sdaiMX_RW

120

session not open


sdaiNULL or invalid model
model not accessible
model access is read-write

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Example
SdaiModel mod;
sdaiAccessModel (mod, sdaiRO);
sdaiPromoteModel (mod);

See Also
ISO 10303-22- 10.7.4; ISO 10303-24- 6.5.4

4.104

sdaiPutADBTypePath()
void sdaiPutADBTypePath(
SdaiADB block,
SdaiInteger typeNameNumber,
SdaiString * typeNameVector
);

The sdaiPutADBTypePath() sets the type path in an ADB. This is a list of strings that
specify a path through a hierarchy of nested SELECT types.
block

the ADB whose type path is set.

typeNameNumber

number of strings in the type list


typeNameVector

an array of strings (size given in previous parameter)

Errors
sdaiAB_NEXS
sdaiSS_NOPN

NULL ADB
session not open

See Also
ISO 10303-24-6.18

SDAI C LIBRARY REFERENCE MANUAL

121

4 FUNCTION REFERENCE

4.105

sdaiPutADBValue()
void sdaiPutADBValue(
SdaiADB block,
SdaiPrimitiveType valueType,
<TYPE> value
);

This functions sets the type and value of an Attribute Data Block (ADB). The type
is specified as valueType, and the value is in the parameter value.

Errors
sdaiSS_NOPN
sdaiVT_NVLD
sdaiAB_NEXS

session not open


cannot convert type
adb is sdaiNULL

Example
SdaiADB adb;
adb = sdaiCreateEmptyADB();
sdaiPutADBValue (adb, sdaiINTEGER, 12);

See Also
ISO 10303-24- 6.2.12.3

4.106

sdaiPutAggrByIndex()
void sdaiPutAggrByIndex (
SdaiOrderedAggr aggregate,
SdaiAggrIndex index,
SdaiPrimitiveType valueType,
<TYPE> value
);

The sdaiPutAggrByIndex() function sets the value of a specified element of an aggregate to a specified index.
The value parameter is an object of the type specified in valueType that indicates the
value to be put in the aggregate.

122

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW
sdaiVT_NVLD
sdaiIX_NVLD

session is not open


aggregate does not exist
aggregate is invalid
model is not writable
type of value is not compatible with the type of the aggregate
index is invalid

See Also
ISO 10303-22-10.16.1; ISO 10303-24-6.14.1

4.107

sdaiPutAggrByIterator()
void sdaiPutAggrByIterator(
SdaiIterator iterator,
SdaiPrimitiveType valueType,
<TYPE> value
);

The sdaiPutAggrByIterator() function sets the current value of an element of an aggregate referenced by the specified iterator.
The value parameter is an object of the type specified in valueType that indicates the
value to be put in the aggregate.

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiMX_NRW
sdaiVT_NVLD
sdaiIR_NSET
sdaiAI_NEXS
sdaiAI_NVLD

session not open


iterator NULL
write permission denied, or iterator is not writable
invalid type
iterator is unset
aggregate is NULL or missing
aggregate/iterator not writable

See Also
ISO 10303-22-10.13.2; ISO 10303-24-6.11.2

SDAI C LIBRARY REFERENCE MANUAL

123

4 FUNCTION REFERENCE

4.108

sdaiPutAllAttrs()
void sdaiPutAllAttrs(
SdaiAppInstance appInstance,
SdaiInteger numberAttr,
SdaiADB *values
);

The sdaiPutAllAttrs() function updates all the attributes in an application instance.


appInstance

the instance whose attributes are being set


number of attributes to be set. This is the size of the values array.

numberAttr
values

array of ADBs containing the values to be set. The parameters are in


the same order as they are in a part 21 file. (i.e. attribute in the order
they are defined in EXPRESS, supertypes first, redefined attributes
where they are first defined)

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMX_NRW

session not open


NULL entity/entity not an application instance
model not writable

See Also
ISO 10303-24-6.9.20.2; _sdaiGetAllAttrDefinitions () (Section 5.9, pp. 158)

4.109

sdaiPutAttr()
void sdaiPutAttr(
SdaiAppInstance instance,
SdaiExplicitAttr attribute,
SdaiPrimitiveType valueType,
<TYPE> value
);

The sdaiPutAttr() function sets the value of the attribute specified by parameter
attribute in the instance specified by parameter instance. The value parameter is an
object of the type specified in valueType that indicates the value to be put in the attribute.

124

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMX_NRW
sdaiVT_NVLD
sdaiAT_NVLD

session not open


NULL entity/entity not an application instance
model not writable
type of attribute cannot be converted to requested type
attribute is invalid

See Also
ISO 10303-22-10.11.3; ISO 10303-24-6.9.4

4.110

sdaiPutAttrBN()
void sdaiPutAttrBN(
SdaiAppInstance instance,
SdaiString attributeName,
SdaiPrimitiveType valueType,
<TYPE> value
);

The sdaiPutAttrBN() function sets the value of the attribute specified by name in parameter attributeName in the instance specified by parameter instance. The value
parameter is an object of the type specified in valueType that indicates the value to
be put in the attribute.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMO_NEXS
sdaiED_NDEF
sdaiAT_NDEF
sdaiMX_NRW
sdaiVT_NVLD
sdaiAT_NVLD

session not open


entity instance does not exist
instance has no model
entity definition NULL or not defined
NULL or bad attribute
model not writable
type of attribute cannot be converted to requested type
attribute is invalid

See Also
ISO 10303-22-10.11.3; ISO 10303-24-6.9.4

SDAI C LIBRARY REFERENCE MANUAL

125

4 FUNCTION REFERENCE

4.111

sdaiPutAttrs()
void sdaiPutAttrs(
SdaiAppInstance appInstance,
SdaiInteger numberAttr,
SdaiExplicitAttr attribute,
SdaiPrimitiveType valueType,
<TYPE> value,
...
);

The sdaiPutAttrs() function sets the value of one or more attributes in an instance to
the user specified value.
appInstance

the instance to be updated

numberAttr

the number of attributes to be updated

attribute

the first attribute to be updated

valueType

the type the first value

value

an object of the type indicated in valueType. This is the first value to


be put.

...

Parameters attribute, valueType, and value repeated numberAttr


times for every attribute up be updated.

Errors
sdaiEI_NEXS
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMX_NRW
sdaiVT_NVLD
sdaiAT_NVLD

NULL instance
session not open
NULL entity/entity not an application instance
model not writable
type of attribute cannot be converted to requested type
attribute is invalid

See Also
ISO 10303-24-6.9.20.1

126

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.112

sdaiPutAttrsBN()
void sdaiPutAttrsBN(SdaiAppInstance appInstance,
SdaiInteger numberAttr,
SdaiString attributeName,
SdaiPrimitiveType valueType,
<TYPE> value,
...);

The sdaiPutAttrs() function sets the value of one or more attributes in an instance to
user specified values.
appInstance

the instance to be updated

numberAttr

the number of attribute to be updated

attributeName

the name of the first attribute to be set

valueType

the type the first value

value

an object of the type indicated in valueType. This is the first value to


be put.

...

Parameters attributeName, valueType, and value repeated numberAttr times for every attribute up be updated.

Errors
sdaiEI_NEXS
sdaiSS_NOPN
sdaiEI_NEXS
sdaiMX_NRW
sdaiVT_NVLD
sdaiAT_NVLD

NULL instance
session not open
NULL entity/entity not an application instance
model not writable
type of attribute cannot be converted to requested type
attribute is invalid

See Also
ISO 10303-24-6.9.20.1

SDAI C LIBRARY REFERENCE MANUAL

127

4 FUNCTION REFERENCE

4.113

sdaiRemove()
void sdaiRemove(
SdaiUnorderedAggr unorderedAggr,
SdaiPrimitiveType valueType,
<TYPE> value
);

The sdaiRemove() function removes a value from an unordered aggregate. If the aggregate contains more than one instance, a single instance is removed.

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW
sdaiAI_NVLD
sdaiVA_NEXS

session is not open


aggregate does not exist
aggregate is internal and thus not writable
model is not writable
Invalid aggregate
element of specified value does not exist in aggregate

See Also
ISO 10303-22-10.14.3; ISO 10303-24-6.12.3

4.114

sdaiRemoveByIndex()
void sdaiRemoveByIndex(
SdaiList list,
SdaiAggrIndex index
);

The sdaiRemoveByIndex() function removes a specified element from an aggregate


at the index specified by parameter index.

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW
sdaiIX_NVLD

128

session is not open


aggregate does not exist
aggregate is internal and thus not writable
model is not writable
index is invalid

STEP TOOLS, INC.

4 FUNCTION REFERENCE

See Also
ISO 10303-22-10.19.7; ISO 10303-24-6.17.7

4.115

sdaiRemoveByIterator()
void sdaiRemoveByIterator(
SdaiIterator iterator
);

The sdaiRemoveByIterator() removes the current element from an aggregate as referenced by an iterator.

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiIR_NSET
sdaiAI_NVLD
sdaiMX_NRW:

session not open


iterator NULL
iterator is at beginning or end
aggregate/iterator not writable
write permission denied, or iterator is not writable (and

See Also
ISO 10303-22-10.13.3; ISO 10303-24-6.11.3

4.116

sdaiRemoveModel()
void sdaiRemoveModel(
SdaiSchemaInstance schemaInstance,
SdaiModel model
);

The sdaiRemoveModel() function removes a model from a specified schema instance.

Errors
sdaiSS_NOPN

session not open

SDAI C LIBRARY REFERENCE MANUAL

129

4 FUNCTION REFERENCE

sdaiSI_NEXS
sdaiMO_NEXS
sdaiRP_NOPN
sdaiMX_NDEF

schema instance does not exist


model does not exist, or NULL value passed in
model's repo is not open
model not open

See also
ISO 10303 - 22- 10.6.4; ISO 10303 - 24- 6.4.4

4.117

sdaiRemoveModelBN()
void sdaiRemoveModelBN (
SdaiSchemaInstance schemaInstance,
SdaiRep repository,
SdaiString modelName
);

The sdaiRemoveModelBN() function removes a model from a schema instance. The


model is identified by name in a repository.

Errors
sdaiSS_NOPN
sdaiSI_NEXS
sdaiMO_NEXT
sdaiRP_NOPN

session not open


schema instance does not exist
model does not exist, or NULL value passed in
models repo is not open

Example
sdaiRemoveModel (si, rep, "modName");

See Also
ISO 10303-22-10.6.4; ISO 10303-24-6.4.4

130

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.118

sdaiRenameModel()
void sdaiRenameModel(
SdaiModel model,
SdaiString modelName
);

The sdaiRenameModel() function permanently renames a model in a repository.

See Also
ISO 10303-22-7.210.; ISO 10303-24-6.5.2

4.119

sdaiRenameSchemaInstance()
void sdaiRenameSchemaInstance(
SdaiSchemaInstance schemaInstance,
SdaiString schemaInstanceName
);

The sdaiRenameSchemaInstance() function renames a schema instance to a new


name.

Errors
sdaiSS_NOPN
sdaiSI_NEXS

session not open


schema instance does not exist

See also
ISO 10303-22- 10.6.2; ISO 10303-24- 6.4.2

SDAI C LIBRARY REFERENCE MANUAL

131

4 FUNCTION REFERENCE

4.120

sdaiRenameSchemaInstanceBN()
void sdaiRenameSchemaInstanceBN (
SdaiString schemaInstanceOldName,
SdaiRep repository,
SdaiString schemaInstanceName
);

The sdaiRenameSchemaInstanceBN() function renames a schema instance in a repository. The schema instance is identified by name.

Errors
sdaiSS_NOPN
sdaiSI_NEXS
sdaiSI_DUP

session not open


schema instance does not exist
duplicate name

Example
sdaiRenameSchemaInstance ("oldname", repo, "newname");

See Also
ISO 10303-22-10.6.2; ISO 10303-24-6.4.2

4.121

sdaiResetArrayIndex()
void sdaiResetArrayIndex(
SdaiArray array,
SdaiAggrIndex lower,
SdaiAggrIndex upper
);

The sdaiResetArrayIndex() resizes an array by resetting the upper an lower bounds.


In this implementation, the lower bound must be zero, and the upper bound must >=
0.

132

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW
sdaiSY_ERR

session is not open


aggregate does not exist
aggregate is internal and thus not writable
model is not writable
bounds are invalid

See Also
ISO 10303-22-10.18.4; ISO 10303-24-6.16.4

4.122

sdaiRestoreErrorHandler()
SdaiErrorHandler sdaiRestoreErrorHandler();

The sdaiRestoreErrorHandler() function pops a handler off the stack that was
pushed on by a call to sdaiSetErrorHandler(). The return value is the function pointer
that was popped off the stack. If the stack was empty, NULL is returned.

Example
See sdaiSetErrorHandler()

See Also
sdaiSetErrorHandler();

4.123

ISO 10303-24- 6.1.3.3

sdaiSaveChanges()
void sdaiSaveChanges(
SdaiModel model
);

The sdaiSaveChanges() function causes a model and all its associated instances to
be saved. Any call to sdaiUndoChanges() after a call to sdaiSaveChanges() will restore the model to the state it was in at the time the model was last saved.

SDAI C LIBRARY REFERENCE MANUAL

133

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiMO_NEXT
sdaiRP_NOPN

session not open


model does not exist, or NULL value passed in
model's repository is not open

See Also
sdaiUndoChanges() (Section

4.129, pp. 137); ISO 10303-22- 10.7.11; ISO 10303-

24- 6.5.9

4.124

sdaiSetErrorHandler()
void SdaiErrorHandler function(
SdaiErrorProc handler
);

The sdaiSetErrorHandler() function replaces the default error handler with one provided by the user. The previous handler is pushed onto an internal stack and may be
restored by calling sdaiRestoreErrorHandler().
The error handler must conform to the following prototype:
void error_fn (SdaiErrorCode errcode);

You may push the default error handler onto that stack by passing NULL as the handler function.

Example
void handler (SdaiErrorCode)
{
printf ("Oops, we got an error!\n");
}
sdaiSetErrorHandler (handler);
:
:
sdaiRestoreErrorHandler (); /* restore original handler */

134

STEP TOOLS, INC.

4 FUNCTION REFERENCE

See Also
sdaiRestoreErrorHandler(); ISO

4.125

10303-24- 6.1.3.2

sdaiTestArrayByIndex()
SdaiBoolean sdaiTestArrayByIndex(
SdaiArray array,
SdaiAggrIndex index
);

The sdaiTestArrayByIndex() function tests if an element of an array is set.


This function returns sdaiTRUE if the index was set, otherwise, it returns
sdaiFALSE.

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD

session is not open


aggregate does not exist
aggregate is invalid

See Also
ISO 10303-22-10.17.1; ISO 10303-24-6.15.1

4.126

sdaiTestArrayByItr()
SdaiBoolean sdaiTestArrayByItr(
SdaiIterator iterator
);

The sdaiTestArrayByItr() function tests whether the current value of an iterator is set.
This function returns sdaiTRUE if the element in the iterator was set, otherwise, it
returns sdaiFALSE.

SDAI C LIBRARY REFERENCE MANUAL

135

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiIR_NEXS

session not open


iterator NULL

See Also
ISO 10303-22-10.17.2; ISO 10303-24-6.15.2

4.127

sdaiTestAttr()
SdaiBoolean sdaiTestAttr(
SdaiInstance instance,
SdaiAttr attribute
);

The sdaiTestAttr() function tells whether an attribute of an instance has a value. In


this implementation, this function always returns sdaiTRUE on an attribute of type
SdaiInteger, SdaiReal, SdaiBoolean, or SdaiLogical, since these types do not have a
valid unset value.
This function returns sdaiTRUE if the attribute has a value in the entity instance, otherwise sdaiFALSE.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAT_NVLD
sdaiAT_NDEF
sdaiED_NVLD

session not open


entity instance does not exist
att is not explicit attribute
NULL attribute
attribute object is not an attribute

See Also
ISO 10303-22- 10.10.2; ISO 10303-24- 6.8.2; sdaiTestAttrBN() (Section 4.128, pp.
137)

136

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.128

sdaiTestAttrBN()
SdaiBoolean sdaiTestAttrBN(
SdaiInstance instance,
SdaiString attributeName
);

The sdaiTestAttrBN() function tells whether an attribute in an entity instance has a


value. This function always returns sdaiTRUE on an attribute of type SdaiInteger,
SdaiReal, SdaiBoolean, or SdaiLogical, since these types do not have a valid unset
value.
This function returns sdaiTRUE if the attribute has a value in the entity instance, otherwise it returns sdaiFALSE.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAT_NVLD
sdaiAT_NDEF
sdaiED_NVLD

session not open


entity instance does not exist
att is not explicit attribute
NULL attribute
attribute object is not an attribute

See Also
ISO 10303-22- 10.10.2; ISO 10303-24- 6.8.2;sdaiTestAttr() (Section 4.127, pp.
136)

4.129

sdaiUndoChanges()
void sdaiUndoChanges(
SdaiModel model
);

The sdaiUndoChanges() function restores a model to the state it was in when it was
last saved. Any changes made since that time are undone. In this implementation,
the model's instances are reassigned, so any access to handles before the calling
sdaiUndoChanges() are undefined.

SDAI C LIBRARY REFERENCE MANUAL

137

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiMO_NEXT
sdaiRP_NOPN

session not open


model does not exist, or NULL value passed in
model's repository is not open

See Also
sdaiSaveChanges()

(Section 4.123, pp. 133); ISO 10303-22- 10.7.10; ISO 10303-

24- 6.5.8

4.130

sdaiUnsetADB()
void sdaiUnsetADB(
SdaiADB block
);

The sdaiUnsetADB() function clears the value stored in an ADB. The result will be
the same as an ADB created by sdaiCreateEmptyADB(). Any attempt to get the value
in the ADB after calling this function will result in an error.

Errors
sdaiSS_NOPN
sdaiAB_NEXS

session not open


adb is sdaiNULL

Example
SdaiADB adb;
sdaiUnsetADB (adb);

See Also
ISO 10303-24- 6.2.12.5

138

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.131

sdaiUnsetArrayByIndex()
void sdaiUnsetArrayByIndex(
SdaiArray array,
SdaiAggrIndex index
);

The sdaiUnsetArrayByIndex() function unsets an element of an aggregate. The element to be unset is specified by index as the parameter index.

Errors
sdaiSS_NOPN
sdaiAI_NEXS
sdaiAI_NVLD
sdaiMX_NRW

session is not open


aggregate does not exist
aggregate is internal and thus not writable
model is not writable

See Also
ISO 10303-22-10.18.1; ISO 10303-24-6.16.1

4.132

sdaiUnsetArrayByItr()
void sdaiUnsetArrayByItr(
SdaiIterator iterator
);

The sdaiUnsetArrayByItr() function unsets the current value of an aggregate referenced by an iterator.

Errors
sdaiSS_NOPN
sdaiIR_NEXS
sdaiAI_NVLD
sdaiAI_NEXS
sdaiMX_NRW

session not open


iterator NULL
aggregate/iterator not writable
aggregate does not exist or is empty
model is not writable

SDAI C LIBRARY REFERENCE MANUAL

139

4 FUNCTION REFERENCE

See Also
ISO 10303-22-10.18.2; ISO 10303-24-6.16.2

4.133

sdaiUnsetAttr()
void sdaiUnsetAttr(
SdaiAppInstance instance,
SdaiExplicitAttr attribute
);

The sdaiUnsetAttr() function removes the value from an attribute. After an attribute
in unset, all future attempts to access it will result in an error.

Errors
sdaiAT_NDEF
sdaiAT_NVLD
sdaiED_NVLD
sdaiEI_NEXS
sdaiMX_NRW
sdaiSS_NOPN

NULL attribute
att is not explicit attribute or attribute cannot be unset
entity object is not an entity
NULL entity/entity not an application instance
model not writable
session not open

See Also
ISO 10303-22-10.11.4; ISO 10303-24-6.9.5

4.134

sdaiUnsetAttrBN()
void sdaiUnsetAttrBN (
SdaiAppInstance instance,
SdaiString attributeName
);

The sdaiUnsetAttrBN() function removes the value of an attribute.

140

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiAT_NDEF
sdaiAT_NVLD
sdaiED_NVLD
sdaiEI_NEXS
sdaiMX_NRW
sdaiSS_NOPN

NULL attribute
att is not explicit attribute or attribute cannot be unset
entity object is not an entity
NULL entity/entity not an application instance
model not writable
session not open

Example
sdaiUnsetAttrBN (inst, "attrname");

See Also
sdaiUnsetAttr()

(Section 4.133, pp. 140); ISO 10303-22-10.11.4; ISO 10303-24-

6.9.5

4.135

sdaiValidateAggrSizes()
SdaiLogical sdaiValidateAggrSizes (
SdaiAppInstance instance,
SdaiNPL list
);

The sdaiValidateAggrSizes() function checks that all aggregate typed attributes are
of legal sizes.
Any attributes that do not conform to the constraint are appended to the NPL provided as the list parameter.
This function return sdaiTRUE if the instance conforms to the rule; sdaiFALSE if it
violates the constraint; and sdaiUNKNOWN is there is an error, or the system is unable to determine if it conforms.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS

session not open


NULL entity/entity not an application instance
NPL is not valid or NULL

SDAI C LIBRARY REFERENCE MANUAL

141

4 FUNCTION REFERENCE

See Also
ISO 10303-22-10.11.13; ISO 10303-24-6.9.14

4.136

sdaiValidateAggrUni()
SdaiBoolean sdaiValidateAggrUni (
SdaiAppInstance instance,
SdaiNPL list
);

The sdaiValidateAggrUni() function checks that all aggregates declared to have


unique elements (e.g. sets) do not have any duplicates.
Any attributes that do not conform to the constraint are appended to the NPL provided as the list parameter.
This function return sdaiTRUE if the instance conforms to the rule; sdaiFALSE if it
violates the constraint; and sdaiUNKNOWN is there is an error, or the system is unable to determine if it conforms.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS

session not open


NULL entity/entity not an application instance
NPL is not valid or NULL

See Also
ISO 10303-22-10.11.14; ISO 10303-24-6.9.15

4.137

sdaiValidateArrayNotOptional()
SdaiBoolean sdaiValidateArrayNotOptional (
SdaiAppInstance instance,
SdaiNPL list
);

142

STEP TOOLS, INC.

4 FUNCTION REFERENCE

The sdaiValidateArrayNotOptional() function checks that all array-typed attributes


in the specified instance that require it, have values. (That is, that the arrays contains
no empty slots.)
Any attributes that do not conform to the constraint are appended to the NPL provided as the list parameter.
This function return sdaiTRUE if the instance conforms to the rule; sdaiFALSE if it
violates the constraint; and sdaiUNKNOWN is there is an error, or the system is unable to determine if it conforms.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS

session not open


NULL entity/entity not an application instance
NPL is not valid or NULL

See Also
ISO 10303-22-10.11.15; ISO 10303-24-6.9.16

4.138

sdaiValidateAttrTypes()
SdaiLogical sdaiValidateAttrTypes(
SdaiAppInstance instance,
SdaiNPL list
);

The sdaiValidateAttrTypes() function determines if the attributes of an instance are


of the correct types. In this implementation, the types of attribute are validated
when the attribute is set (e.g by sdaiPutAttr()), and the put function generates the
sdaiVT_NVLD error is the type is invalid. Because of this behavior in the put functions, that attribute always have the correct types, so this function always returns
sdaiTRUE.

Errors
sdaiSS_NOPN

session is not open

SDAI C LIBRARY REFERENCE MANUAL

143

4 FUNCTION REFERENCE

See also
ISO 10303 - 22-10.11.13; ISO 10303 - 24-6.9.14

4.139

sdaiValidateBinaryWidth()
SdaiLogical sdaiValidateBinaryWidth (
SdaiAppInstance appInstance,
SdaiNPL list
);

The sdaiValidateBinaryWidth() function checks that all binary typed attributes in an


instance are of a length allowed by the information model.
Any attributes that do not conform to the constraint are appended to the NPL provided as the list parameter.
This function return sdaiTRUE if the instance conforms to the rule; sdaiFALSE if it
violates the constraint; and sdaiUNKNOWN is there is an error, or the system is unable to determine if it conforms.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS

session not open


NULL entity/entity not an application instance
NPL is not valid or NULL

See Also
ISO 10303-22-10.11.17; ISO 103030-24-6.9.18

4.140

sdaiValidateGlobalRule()
SdaiLogical sdaiValidateGlobalRule (
SdaiSchemaInstance schemaInstance,
SdaiGlobalRule rule, SdaiNPL list
);

144

STEP TOOLS, INC.

4 FUNCTION REFERENCE

The sdaiValidateGlobalRule() function determines if a schema instance (or model)


conforms to a specific global rule. This function is only available if you linked
against the sdaivalidate library because it requires the EXPRESS interpreter.
The schemaInstance parameter identifies the schema instance over which the
checking is performed. This parameter may, as an extension, be a model, if you wish
to validate the global rule in a single model.
The list parameter is ignored. Part 24 documents it as a non persistent list which
contains the instances which do not conform to the validation, however, for many
global rules, there is no single instance responsible for the rule failing.
The function returns sdaiTRUE if the schema instance conforms to all the constraints. It returns sdaiFALSE, if one or more of the constraints are not met, and it
returns sdaiUNKNOWN if there is an error, or if it is unable to determine is the constraints are met.

Errors
sdaiSS_NOPN
sdaiRU_NDEF
sdaiSI_NEXS

session not open


invalid or NULL scheme def
schema instance does not exist

Example
sdaiValidateGlobalRule (si, rule, sdaiNULL);

See Also
ISO 10303-22-10.6.5; ISO 10303-24-6.4.5.

4.141

sdaiValidateGlobalRuleBN()
SdaiLogical sdaiValidateGlobalRuleBN (
SdaiSchemaInstance schemaInstance,
SdaiString ruleName,
SdaiNPL list
);

The sdaiValidateGlobalRuleBN() function determines if a schema instance (or model) conforms to a specific global rule. This function is only available if you linked

SDAI C LIBRARY REFERENCE MANUAL

145

4 FUNCTION REFERENCE

against the sdaivalidate library because it requires the EXPRESS interpreter.


The schemaInstance parameter identifies the schema instance over which the
checking is performed. This parameter may, as an extension, be a model, if you wish
to validate the global rule in a single model.
The list parameter is ignored. Part 24 documents it as a non persistent list which
contains the instances which do not conform to the validation; however, for many
global rules, there is no single instance responsible for the rule failing.
The function returns sdaiTRUE if the schema instance conforms to all the constraints. It returns sdaiFALSE, if one or more of the constraints are not met, and it
returns sdaiUNKNOWN if there is an error, or if it is unable to determine is the constraints are met.

Errors
sdaiSS_NOPN
sdaiRU_NDEF
sdaiSI_NEXS

session not open


invalid or NULL scheme def
schema instance does not exist

Example
sdaiValidateGlobalRuleBN (si, "rule", sdaiNULL);

See Also
ISO 10303-22-10.6.5; ISO 10303-24-6.4.5

4.142

sdaiValidateInverseAttrs()
SdaiBoolean sdaiValidateInverseAttrs (
SdaiAppInstance instance,
SdaiNPL list
);

The sdaiValidateInverseAttrs() function validates that the constraints defined by inverse attribute are met.

146

STEP TOOLS, INC.

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS

session not open


NULL entity/entity not an application instance
NPL is not valid or NULL

See Also
ISO 10303-22-10.11.11; ISO 10303-24-6.9.12

4.143

sdaiValidateRealPrecision()
SdaiLogical sdaiValidateRealPrecision(
SdaiAppInstance appInstance,
SdaiNPL list
);

The sdaiValidateRealPrecision() function determines if the real attributes in an instance have sufficient precision as defined by the EXPRESS. In this implementation, this function always return sdaiTRUE because ST-Developer always uses
doubles to store real values.

Errors
sdaiSS_NOPN

session is not open.

See also
ISO 10303 - 22-10.11.18; ISO 10303 - 24-6.9.19

4.144

sdaiValidateReferenceDomain()
SdaiLogical sdaiValidateReferenceDomain(
SdaiSchemaInstance schemaInstance,
SdaiAppInstance appInstance,
SdaiNPL list
);

SDAI C LIBRARY REFERENCE MANUAL

147

4 FUNCTION REFERENCE

The sdaiValidateReferenceDomain() function determines if all the attribute of an instance occur within a specified schema instance.

Errors
sdaiSS_NOPN
sdaiSI_NEXS
sdaiEI_NEXS
sdaiAI_NEXS

session not open


schema instance does not exist
NULL entity/entity not an application instance
NPL is not valid or NULL

See also
ISO 10303 - 22- 10.6.7; ISO 10303 - 24- 6.4.7

4.145

sdaiValidateRequiredAttrs()
SdaiBoolean sdaiValidateRequiredAttrs(
SdaiAppInstance instance,
SdaiNPL list
);

The sdaiValidateRequiredAttrs() function determines if all the required attributes


(e.g. those attribute not flagged as OPTIONAL in the EXPRESS code) are set. Any
required attribute that was not set is added to the non-persistent list specified by the
parameter list. In this implementation, the function will never flag an attribute of
type integer, real, boolean or logical as unset, since there is no valid unset value.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS

session not open


NULL entity/entity not an application instance
NPL is not valid or NULL

See also
ISO 10303 - 22-10.11.10; ISO 10303 - 24-6.9.11

148

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.146

sdaiValidateSchemaInstance()
SdaiLogical sdaiValidateSchemaInstance (
SdaiSchemaInstance schemaInstance
);

The sdaiValidateSchemaInstance() function validates a schema instance. The validation includes


The schemaInstance parameter, as an extension to part 24, may be a model in addition to a schema instance.
The function returns sdaiTRUE if the schema instance conforms to all the constraints. It returns sdaiFALSE, if one or more of the constraints are not met, and it
returns sdaiUNKNOWN if there is an error, or if it is unable to determine is the constraints are met.

Errors
sdaiFN_NAVL
sdaiSS_NOPN
sdaiSI_NEXS

in interpreter available
session is not open
schema instance does not exist

Example
if (sdaiValidationSchemaInstance(si))
printf ("Schema instance OK\n");

See Also
ISO 10303-22-10.5.8; ISO 10303-24-6.4.8

4.147

sdaiValidateStringWidth()
SdaiLogical sdaiValidateStringWidth (
SdaiAppInstance appInstance,
SdaiNPL list
);

The sdaiValidateStringWidth() function checks that all string typed attributes in an

SDAI C LIBRARY REFERENCE MANUAL

149

4 FUNCTION REFERENCE

instance are of a length allowed by the information model.


Any attributes that do not conform to the constraint are appended to the NPL provided as the list parameter.
This function return sdaiTRUE if the instance conforms to the rule; sdaiFALSE if it
violates the constraint; and sdaiUNKNOWN is there is an error, or the system is unable to determine if it conforms.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiAI_NEXS

session not open


NULL entity/entity not an application instance
NPL is not valid or NULL

See Also
ISO 10303-22-10.11.16; ISO 10303-24-6.9.17

4.148

sdaiValidateTypePath()
SdaiLogical sdaiValidateTypePath(
SdaiAppInstance appInstance,
SdaiNPL list
);

The sdaiValidateTypePath() function determines if the attributes of an instance have


valid types. In this implementation, the function always returns sdaiTRUE, since the
type checking is done when the attribute is set.

Errors
sdaiSS_NOPN

session is not open

See also
ISO 10303 - 24-6.18.3

150

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.149

sdaiValidateUniqueness()
SdaiLogical sdaiValidateUniqueness(
SdaiSchemaInstance schemaInstance,
SdaiUniRule uniRule,
SdaiNPL list
);

the sdaiValidateUniqueness() function evaluates a uniqueness rule over a schema


instance (or model).
The schemaInstance parameter, as an extension to part 24, may be a model in addition to a schema instance.
The list parameter must be a preexisting NPL. Any instance which contains duplicated values is appended to the list.
The function returns sdaiTRUE if the schema instance conforms to all the constraints. It returns sdaiFALSE, if one or more of the constraints are not met, and it
returns sdaiUNKNOWN if there is an error, or if it is unable to determine is the constraints are met.

Errors
sdaiSS_NOPN
sdaiSI_NEXS
sdaiRU_NDEF
sdaiAI_NEXS
sdaiEX_NSUP

session is not open


schema instance does not exist
rule NULL or bad object
NPL is not valid or NULL
EXPRESS interpreter not available

Example
SdaiNPL list = sdaiCreateNPL();
sdaiValidateUniqueness (si, rule, list);

See Also
ISO 10303-22-10.6.6; ISO 10303-24-6.4.6

SDAI C LIBRARY REFERENCE MANUAL

151

4 FUNCTION REFERENCE

4.150

sdaiValidateUniquenessBN()
SdaiLogical sdaiValidateUniquenessBN (
SdaiSchemaInstance schemaInstance,
SdaiString entityName,
SdaiString uniRuleName,
SdaiNPL list
);

the sdaiValidateUniquenessBN() function evaluates the uniqueness rule over a schema instance (or model). The rule is identified by name within an entity.
The schemaInstance parameter, as an extension to part 24, may be a model in addition to a schema instance.
The list parameter must be a preexisting NPL. Any instance which contains duplicated values is appended to the list.
The function returns sdaiTRUE if the schema instance conforms to all the constraints. It returns sdaiFALSE, if one or more of the constraints are not met, and it
returns sdaiUNKNOWN if there is an error, or if it is unable to determine is the constraints are met.

Errors
sdaiSS_NOPN
sdaiRU_NDEF
sdaiSI_NEXS
sdaiAI_NEXS
sdaiEX_NSUP

session not open


invalid or NULL scheme def
schema instance does not exist
NPL is not valid or NULL
EXPRESS interpreter not available

Example
SdaiNPL list = sdaiCreateNPL();
sdaiValidateUniquenessBN (si, "entity", "rule", list);

See Also
ISO 10303-22-10.6.6; ISO 10303-24-6.4.6

152

STEP TOOLS, INC.

4 FUNCTION REFERENCE

4.151

sdaiValidateWhereRule()
SdaiLogical sdaiValidateWhereRule (
SdaiAppInstance instance,
SdaiWhereRule rule
);

The sdaiValidateWhereRule function determines if an instance conforms to a where


rule. This function requires that the application be linked against the sdaivalidate library, so that the EXPRESS interpreter is available.
This function returns sdaiTRUE if the instance conforms to the rule; sdaiFALSE if it
violates the constraint; and sdaiUNKNOWN is there is an error, or the system is unable to determine if it conforms.

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiRU_NDEF
sdaiFN_NAVL

session is not open


object is NULL or incorrect
rule NULL or missing
no EXPRESS interpreter

See Also
ISO 10303-22-10.11.9; ISO 10303-24-6.9.10

4.152

sdaiValidateWhereRuleBN()
SdaiLogical sdaiValidateWhereRuleBN (
SdaiAppInstance instance,
SdaiString ruleName
);

The sdaiValidateWhereRuleBN() function determines if an instance conforms to a


where rule. This function requires that the application be linked against the
sdaivalidate library, so that the EXPRESS interpreter is available.
This function return sdaiTRUE if the instance conforms to the rule; sdaiFALSE if it
violates the constraint; and sdaiUNKNOWN is there is an error, or the system is unable to determine if it conforms.

SDAI C LIBRARY REFERENCE MANUAL

153

4 FUNCTION REFERENCE

Errors
sdaiSS_NOPN
sdaiEI_NEXS
sdaiRU_NDEF
sdaiFN_NAVL

session is not open


object is NULL or incorrect
rule NULL or missing
no EXPRESS interpreter

See Also
ISO 10303-22-10.11.9; ISO 10303-24-6.9.10

154

STEP TOOLS, INC.

5 Extension Functions

5.1

Introduction
This chapter provides an alphabetical reference to the functions provided as extensions to the SDAI binding by this implementation. These functions provide functionality that is either missing from Part 22, or which could be implemented in using
the operations defined by the specification, but would be very inconvenient or inefficient to do so.

5.2

_sdaiAddSchema()
void _sdaiAddSchema (
SdaiModel mod,
SdaiSchema sch
);

The _sdaiAddSchema function adds a schema to the schema list of a model. This
allows a model to reference multiple schemas (a non-standard SDAI feature).

SDAI C LIBRARY REFERENCE MANUAL

155

5 EXTENSION FUNCTIONS

5.3

_sdaiDisplay()
void _sdaiDisplay (
SdaiInstance obj
);

The _sdaiDisplay() function displays a single instance on stdout.

5.4

_sdaiDisplayADB()
void _sdaiDisplayADB(
SdaiADB adb
);

The_sdaiDisplayADB() function displays an ADB on stdout.

5.5

_sdaiDisplayAggr()
void _sdaiDisplayAggr (
SdaiAggr agg
);

The_sdaiDisplayAggr() function displays a single aggregate on stdout.

5.6

_sdaiDisplayModel()
void _sdaiDisplayModel(
SdaiModel mod
);

The _sdaiDisplayModel() function displays a model on stdout. This output could get
extremely long on a large model.

156

STEP TOOLS, INC.

5 EXTENSION FUNCTIONS

5.7

_sdaiFindModelBN()
SdaiModel _sdaiFindModelBN (
SdaiRep repository,
SdaiString modelName
);

The _sdaiFindModelBN() extension function finds a model by name in a repository.


This function is similar to sdaiAccessModelBN except that it does not generate an
error is the model is already open for either read-only or read-write access.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiRP_NOPN

session is not open


NULL or invalid model
repository not open

See Also
sdaiAccessModelBN() (Section

5.8

4.3, pp. 48)

_sdaiGenerateFullDictionary()
void _sdaiGenerateFullDictionary (
SdaiBoolean val
);

The _sdaiGenerateFullDictionary() function sets an internal flag which determines


whether the SDAI library will generate a complete dictionary model, or a simplified
version. If the val parameter is sdaiTRUE, then the interface creates a complete dictionary; if val is sdaiFALSE, the interface does not generate a complete dictionary.
By default, it does generate a complete dictionary.
Normally, a full dictionary is generated if the EXPRESS parse data can be found. If
the internal flag set by this function, however, is false, then the full dictionary is
never generated. This function is provided for performance critical application,
where load time is important, and none of the features of the complete dictionary
are required (e.g inverse attributes, uniqueness constraints, EXPRESS interpreter,
etc.).

SDAI C LIBRARY REFERENCE MANUAL

157

5 EXTENSION FUNCTIONS

See Also
_sdaiGetGenerateFullDictionary()

5.9

(Section 5.20, pp. 162)

_sdaiGetAllAttrDefinitions ()
SdaiNPL _sdaiGetAllAttrDefinitions (
SdaiEntity entity,
SdaiNPL resultList
);

The _sdaiGetAllAttrDefinitions() function determines all the explicit attributes an


entity has (both local and inherited), and places them in the non persistent list referred to by the resultList parameter.

Errors
sdaiSS_NOPN - session not open
sdaiED_NDEF - entity definition NULL or not defined
sdaiAI_NEXS - NPL is not valid or NULL

5.10

_sdaiGetAggr()
SdaiAggr _sdaiGetAggr (
RoseAggregate * obj
);

The _sdaiGetAggr() function returns the SDAI aggregate associated with a ROSE
objects. This function should only be used on persistent objects.

5.11

_sdaiGetAppInstance()
SdaiAppInstance _sdaiGetAppInstance (
RoseStructure * obj
);

158

STEP TOOLS, INC.

5 EXTENSION FUNCTIONS

The _sdaiGetAppInstance() function returns the SDAI instance associated with a


ROSE objects. This function should only be used on persistent objects.

5.12

_sdaiGetComplexEntityBN()
SdaiEntity _sdaiGetComplexEntityBN (
SdaiModel model,
SdaiInteger nameNumber,
SdaiString *nameVector
);

The _sdaiGetComplexEntityBN() function works just like the


sdaiGetComplexEntityBN except that the model is specified by handle rather than
by name.

Errors
sdaiSS_NOPN
sdaiNO_NEXS
sdaiED_NDEF

session is not open


NULL or invalid model
entity not in EXPRESS

See Also
sdaiGetComplexEntityBN()

5.13

(Section 4.61, pp. 92)

_sdaiGetDerivedAttrDefinitions()
SdaiNPL _sdaiGetDerivedAttrDefinitions (
SdaiEntity entity,
SdaiNPL list
);

The _sdaiGetDerivedAttrDefinitions() function determines the derived attributes of


an entity and places them into a user specified non-persistent list. This information
can be determined be examining the dictionary, but this function provides a more
efficient and convenient way to determine this information.

SDAI C LIBRARY REFERENCE MANUAL

159

5 EXTENSION FUNCTIONS

5.14

_sdaiGetDomainForEntity()
RoseDomain * _sdaiGetDomainForEntity (
SdaiEntity ent
);

The _sdaiGetDomainForEntity() function retrieves RoseDomain associated with a


given SDAI entity_definition.
This function is only available to C++ applications, and <rose.h> must be included
before <sdai.h>.

Errors
sdaiSS_NOPN
sdaiED_NDEF

session not open


entity definition NULL or not defined

See Also
_sdaiGetEntityForDomain() (Section

5.15

5.15, pp. 160)

_sdaiGetEntityForDomain()
SdaiEntity _sdaiGetEntityForDomain (
RoseDomain * dom
);

The _sdaiGetEntityForDomain() function retrieves the SDAI entity_definition associated with a specific RoseDomain.
This function is only available to C++ applications, and <rose.h> must be included
before <sdai.h>.

See Also
_sdaiGetDomainForEntity() (Section

160

5.14, pp. 160)

STEP TOOLS, INC.

5 EXTENSION FUNCTIONS

5.16

_sdaiGetEntityId()
int _sdaiGetEntityId (
SdaiAppInstance inst
);

The _sdaiGetEntityId() function returns the entity ID from a Part 21 file. If the entity is not in a model that was read in from a Part 21 file, this function returns 0.

Example
printf (Have entity ID: %d\n, _sdaiGetEntityId(inst));

See Also
RoseObject::entity_id() in the Rose Library Reference Manual.

5.17

_sdaiGetEntityInModel()
SdaiEntity _sdaiGetEntityInModel(
SdaiModel model,
SdaiString name
);

The _sdaiGetEntityInModel() extension function finds an entity_instance within a


specific (dictionary) model. This function can be used to traverse the dictionary
model, where there is no model based on the dictionary loaded.

Example
This example finds the definition for cartesian_point in the dictionary for Part 203.
SdaiSchema sch;
SdaiModel mod;
SdaiEntity cart_pt_ent;
sch = sdaiGetSchema ("config_control_design");
mod = sdaigetInstanceModel (sch);
cart_pt_ent = _sdaiGetEntityInModel (mod, "cartesian_point");

SDAI C LIBRARY REFERENCE MANUAL

161

5 EXTENSION FUNCTIONS

See Also
sdaiGetEntity()

5.18

(Section 4.63, pp. 94)

_sdaiGetErrorName()
SdaiString _sdaiGetErrorName(
SdaiErrorCode code
);

The sdaiGetErrorName() function returns the name of an SDAI error. This returns a
string of the form AI_NVLD. It may be helpful within error handling routines. This
function returns a string containing the error code.

5.19

_sdaiGetExplcitAttrDefinitions()
SdaiNPL _sdaiGetExplicitAttrDefinitions (
SdaiEntity entity,
SdaiNPL list
);

The _sdaiGetExplicitAttrDefinitions() function determines the explicit attributes of


an entity and places them into a user specified non-persistent list. This information
can be determined be examining the dictionary, but this function provides a more
efficient and convenient way to determine this information.

5.20

_sdaiGetGenerateFullDictionary()
SdaiBoolean _sdaiGetGenerateFullDictionary ();

The _sdaiGetGenerateFullDictionary() function returns the value of the internal flag


that is set by the _sdaiGenerateFullDictionary function. If true, the SDAI library attempts to generate a complete dictionary.

162

STEP TOOLS, INC.

5 EXTENSION FUNCTIONS

See Also
_sdaiGenerateFullDictionary() (Section 5.8, pp. 157)

5.21

_sdaiGetHeaderDescription()
int _sdaiGetHeaderDescription (
SdaiModel mod
);

The _sdaiGetHeaderDescription() function returns description instance from the


STEP Part 21 file corresponding to the model. This instance may be queried to set
the fields in the Part 21 file header, or its attributes may be changed to set the fields
in the file header when the file is written out. Changes made to the header entities
will only be saved if the model is saved as a Part 21 file; likewise, the header entities
will have a default value if the model was not read in from a Part 21 file.
The description entity returned by this function is defined by the following EXPRESS:
ENTITY file_description;
description
: LIST [1:?] OF STRING (256);
implementation_level : STRING (256);
END_ENTITY;

Example
SdaiAggr desc_list;
SdaiInstance desc;
desc = _sdaiHeaderDescription (model);
sdaiGetAttrBN (name, description, sdaiAGGR, &desc_list);
sdaiInsertByIndex (auth, 0, sdaiSTRING, A Sample STEP File);

See Also
RoseDesign::header_description() in the Rose Library Reference Manual.

SDAI C LIBRARY REFERENCE MANUAL

163

5 EXTENSION FUNCTIONS

5.22

_sdaiGetHeaderName()
int _sdaiGetHeaderName(
SdaiModel mod
);

The _sdaiGetHeaderName() function returns name instance from the STEP Part 21
file corresponding to the model. This instance may be queried to set the fields in the
Part 21 file header, or its attributes may be changed to set the fields in the file header
when the file is written out. Changes made to the header entities will only be saved
if the model is saved as a Part 21 file; likewise, the header entities will have a default
value if the model was not read in from a Part 21 file.
The name entity returned by this function is defined by the following EXPRESS:
ENTITY file_name;
name
: STRING (256);
time_stamp
: STRING (256);
author
: LIST [1:?] OF STRING (256);
organization : LIST [1:?] OF STRING (256);
preprocessor_version : STRING (256);
originating_system
: STRING (256);
authorization
: STRING (256);
END_ENTITY;

Example
SdaiAggr auth;
SdaiInstance name;
name = _sdaiHeaderName (model);
sdaiGetAttrBN (name, author, sdaiAGGR, &auth);
sdaiInsertByIndex (auth, 0, sdaiSTRING, Fred Foo);

See Also
RoseDesign::header_name() in the Rose Library Reference Manual.

164

STEP TOOLS, INC.

5 EXTENSION FUNCTIONS

5.23

_sdaiGetInstanceSectionModel()
SdaiModel _sdaiGetInstanceSectionModel(
SdaiInstance inst
);

The _sdaiGetIntanceSectionModel() function returns the model for the design section containing the specified instance. When dealing with models that have multiple
data sections, this function allows you to access a specific section, and determine
which section an instance belongs to.

See Also
_sdaiGetModel() (Section 5.25, pp. 165). Low-Level Model API (Section 2.4.16, pp.

28)

5.24

_sdaiGetInverseAttrDefinitions()
SdaiNPL _sdaiGetInverseAttrDefinitions (
SdaiEntity entity,
SdaiNPL list
);

The _sdaiGetInverseAttrDefinitions() function determines the inverse attributes of


an entity and places them into a user specified non-persistent list. This information
can be determined be examining the dictionary, but this function provides a more
efficient and convenient way to determine this information.

5.25

_sdaiGetModel()
SdaiModel _sdaiGetModel (
RoseDesign * des
);
SdaiModel _sdaiGetModel (
RoseDesignSection * des
);

SDAI C LIBRARY REFERENCE MANUAL

165

5 EXTENSION FUNCTIONS

The _sdaiGetRoseDesign() function returns the SDAI model associated with a


RoseDesign or RoseDesignSection. This function is only available to C++ applications, and <rose.h> must be included before <sdai.h>.
The version of _sdaiGetRoseDesign() that takes a RoseDesignSection, always returns a model associated with a design section. The version that takes a RoseDesign,
tries to find an existing, fully functional, sdai_model for the design. If such a model
has not been opened, it creates a light-weight model for the design.

Errors
sdaiMO_NEXS - model does not exist

See Also
_sdaiGetRoseDesign()

(Section 5.29, pp. 168); Low-Level Model API (Section

2.4.16, pp. 28)

5.26

_sdaiGetProp()
void* _sdaiGetProp (
_SdaiPropType type,
SdaiAppInstance inst
);

The _sdaiGetProp() function returns the value of a property attached to an instance.


This function returns the property as a void * a generic pointer to any type of data.
You are responsible for casting the value to the appropriate type.

Errors
sdaiSS_NOPN
sdaiEI_NEXS

session not open


NULL entity/entity not an application instance

Example
See _sdaiSetProp() (Section 5.39, pp. 172)

166

STEP TOOLS, INC.

5 EXTENSION FUNCTIONS

See Also
_sdaiGetPropType() (Section 5.27, pp. 167); _sdaiSetProp() (Section 5.39, pp. 172);
_sdaiRemoveProp() (Section 5.35, pp. 170)

5.27

_sdaiGetPropType()
_SdaiPropType _sdaiGetPropType ();

The _sdaiGetPropType() extension function allocates a new property type identifier.


This function must be called to obtain a property identifier which can be used as a
parameter to the other property function.
The return value of this function should be cached in a global variable, or other location where the value will be available for as long as the property may be used. If
this function is called a second time, a second unique property identifier is generated.

Example
See _sdaiSetProp() (Section 5.39, pp. 172)

See Also
_sdaiGetPropType() (Section 5.27, pp. 167); _sdaiSetProp() (Section 5.39, pp. 172);
_sdaiRemoveProp() (Section 5.35, pp. 170)

5.28

_sdaiGetRoseAggregate()
RoseAggregate* _sdaiGetRoseAggregate (
SdaiAggr inst
);

The _sdaiGetRoseAggregate() function returns the ROSE aggregate which corresponds to an SDAI aggregate. If the aggregate does not have a corresponding ROSE
objects (e.g session objects), this function returns NULL.

SDAI C LIBRARY REFERENCE MANUAL

167

5 EXTENSION FUNCTIONS

5.29

_sdaiGetRoseDesign()
RoseDesign * _sdaiGetRoseDesign (
SdaiModel mod
);

The _sdaiGetRoseDesign() function returns the RoseDesign associated with an


SDAI model. This function is only available to C++ applications, and <rose.h>
must be included before <sdai.h>.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiMX_NDEF

session not open


NULL or invalid model
model not accessable

See Also
_sdaiGetModel()

5.30

(Section 5.25, pp. 165)

_sdaiGetRoseStructure()
RoseStructure* _sdaiGetRoseStructure (
SdaiAppInstance inst
);

The _sdaiGetRoseStructure() function returns the ROSE object which corresponds


to an entity instance. If the instance does not have a corresponding ROSE objects
(e.g session objects), this function returns NULL.

5.31

_sdaiGetSchemaList()
void _sdaiGetSchemaList (
SdaiModel mod,
SdaiNPL list
);

168

STEP TOOLS, INC.

5 EXTENSION FUNCTIONS

The _sdaiGetSchemaList function returns the schema list for a model. This is a nonstandard extension to the SDAI which allows you to manipulate data files what have
multiple schemas. This function takes an existing NPL (the list parameter), and populates it with instances of SdaiSchema, one for every schema the model has.

5.32

_sdaiGetSubtypes()
SdaiNPL _sdaiGetSubtypes (
SdaiEntity entity,
SdaiNPL list
);

The _sdaiGetSubypes() function determines the complete set of subtypes of an entity, and places them into a user specified non-persistent list. This information can
be determined be examining the dictionary, but this function provides a more efficient and convenient way to determine this information.

5.33

_sdaiGetSupertypes()
SdaiNPL _sdaiGetSupertypes (
SdaiEntity entity,
SdaiNPL list
);

The _sdaiGetSupertypes() function determines the complete list of supertypes of an


entity, and places them into a user specified non-persistent list. This information can
be determined be examining the dictionary, but this function provides a more efficient and convenient way to determine this information.

5.34

_sdaiGetUniquenessDefinitions()
SdaiNPL _sdaiGetUniquenessDefinitions (
SdaiEntity entity,
SdaiNPL list
);

The _sdaiGetUniquenssDefinitions() function determines the uniqueness rules of an

SDAI C LIBRARY REFERENCE MANUAL

169

5 EXTENSION FUNCTIONS

entity and places them into a user specified non-persistent list. This information can
be determined be examining the dictionary, but this function provides a more efficient and convenient way to determine this information.

5.35

_sdaiRemoveProp()
void _sdaiRemoveProp (
_SdaiPropType type,
SdaiAppInstance inst
);

The _sdaiRemoveProp() function removes a property from an instance.

Errors
sdaiSS_NOPN
sdaiEI_NEXS

session not open


NULL entity/entity not an application instance

See Also
_sdaiGetPropType() (Section 5.27, pp. 167); _sdaiSetProp() (Section 5.39, pp. 172);
_sdaiGetProp() (Section 5.26, pp. 166)

5.36

_sdaiRescanRepository()
void _sdaiRescanRepository (
SdaiRep repository
);

The _sdaiRescanRepository() function causes the SDAI library to recalculate the


set of models in a repository. This may be necessary if another application creates
a new model after the current process has already opened a repository, and the SDAI
application wishes to access the newly created model.

Errors
sdaiRP_NEXS

170

NULL or invalid repo

STEP TOOLS, INC.

5 EXTENSION FUNCTIONS

sdaiRP_NOPN
sdaiSS_NOPN

repository is not open


session not open

Example
_sdaiRescanRepository(repo);

5.37

_sdaiSaveAs()
void _sdaiSaveAs (
SdaiModel model,
SdaiString asname
);

The _sdaiSaveAs() function saves a model under a specified name.

5.38

_sdaiSetModelFormat()
void _sdaiSetModelFormat(
SdaiModel mod,
SdaiString format
);

The _sdaiSetModelFormat() extension function sets the file format for a model. This
function merely exposes the RoseDesign::format() method to SDAI applications.
The format parameter identifies the file format to use. Legal values include rose,
for text rose files; standard for compact binary files; and step for STEP Part 21
exchange files. The default format is the same as the model was read in from. New
models default to standard.

Errors
sdaiSS_NOPN
sdaiMO_NEXS
sdaiMX_NDEF

session not open


NULL or invalid model
model not accessable

SDAI C LIBRARY REFERENCE MANUAL

171

5 EXTENSION FUNCTIONS

Example
_sdaisetModelFormat (mod, "step");

See Also
RoseDesign::format() in the Rose Library Reference Manual.

5.39

_sdaiSetProp()
void _sdaiSetProp (
_SdaiPropType type,
SdaiAppInstance inst,
void * value
);

The _sdaiSetProp() function sets the value of a property.


A property is a piece of user data attached to an SDAI instance. This feature allows
you to avoid creating hash table or other data structures to associate additional data
with an instance. An instance may have multiple properties associated with it, however each property must have a unique type. Properties are not stored when the
model is saved. They may by used to keep back pointers, or other data associated
with the value.
The property is defined as a void * a pointer to any type of data. You are responsible for casting the value to the correct C type before accessing the value.

Errors
sdaiSS_NOPN
sdaiEI_NEXS

session not open


NULL entity/entity not an application instance

Example
SdaiAppInstance inst1, inst2;
_SdaiPropType name_prop = _sdaiGetPropType();
/* Find the instances for inst1 and inst2 */
/* Store the properties */
_sdaiSetProp (name_prop, inst1, "testobj1");

172

STEP TOOLS, INC.

5 EXTENSION FUNCTIONS

_sdaiSetProp (name_prop, inst2, "testobj2");


/* Print the properties out */
printf ("Name=%s\n", (char*)_sdaiGetProp(name_prop, inst1));
printf ("Name=%s\n", (char*)_sdaiGetProp(name_prop, inst2));

See Also
_sdaiGetPropType() (Section 5.27, pp. 167); _sdaiGetProp() (Section 5.26, pp. 166);
_sdaiRemoveProp() (Section 5.35, pp. 170)

5.40

_sdaiVerbose()
void _sdaiVerbose(
SdaiBoolean print_messages
);

The _sdaiVerbose function is used to control ROSE error reporting. By default, the
SDAI is in verbose mode. To make the binding more quiet, call _sdaiVerbose() with
the parameter sdaiFALSE before any other call.
This function only effects ROSE error reporting. To control SDAI error reporting,
use sdaiSetErrorHandler().

See Also
sdaiSetErrorHandler()

SDAI C LIBRARY REFERENCE MANUAL

(Section 4.124, pp. 134)

173

5 EXTENSION FUNCTIONS

174

STEP TOOLS, INC.

6 SDAI Schemas

The SDAI specification defines four schemas for its own use. These are the session
schema, the population schema, the parameter data schema and the dictionary schema. This chapter contains the complete EXPRESS for the SDAI schemas with annotations. In general, the instances in the SDAI schemas are manipulated by various
SDAI functions (e.g. sdaiOpenRepository(), sdaiAccessModel()), however they are
available for direct access for those cases where the application needs to examine
the internals of the SDAI. Instances of entities in the SDAI schemas may not be
created or modified explicitly using SDAI functions, however instances may be created, deleted or modified implicitly by other SDAI operations.

6.1

Session Schema
The session schema describes the state of the SDAI. The entities in the session
schema represent global data structures in the session. There are also data structures
which are associated with specific models. These data definitions can be found in
the population schema.
SCHEMA session_schema;
REFERENCE FROM parameter_data_schema
( entity_instance,
aggregate_instance );
USE FROM population_schema;
(* Access type is identifies the type of access to models, and transactions *)

SDAI C LIBRARY REFERENCE MANUAL

175

6 SDAI SCHEMAS

TYPE access_type = ENUMERATION OF


(read_only,
read_write);
END_TYPE;

The error_base type is used for event logging. (Event logging is not supported in
this implementation, so the error_base type is not used.)
TYPE error_base = SELECT
(entity_instance,
aggregate_instance);
END_TYPE;

A time stamp is a string in ISO 8601 format which identifies a date and time. It has
the format:
year-month-day T hour:min:second[+-]timezone

Where hour is in 24 hour format, and the timezone is the number of hours difference
from Uniersal Time (GMT). For example, 2:46 PM on September 10, 1997 in the
Eastern Time zone of the United States would be written as:
1997-9-10T14:46:32+06

In EXPRESS, a time stamp is defined by the time_stamp type.


TYPE time_stamp = STRING(256);
END_TYPE;

The sdai_session entity provides access to all objects in the session. There is exactly one instance of sdai_session within an SDAI session. This instance is known
as the session object, and is created and returned by the sdaiOpenSession() function.
ENTITY sdai_session;
sdai_implementation : implementation;
recording_active
: BOOLEAN; (* always false in this implementation*)
errors
: LIST [0:?] OF error_event; (* always unset *)
known_servers
: SET [1:?] OF sdai_repository;
active_servers
: SET [1:?] OF sdai_repository;
active_models
: SET [1:?] OF sdai_model;
data_dictionary
: OPTIONAL schema_instance;
INVERSE
active_transaction : SET [0:1] OF sdai_transaction FOR owning_session;
END_ENTITY;

The implementation entity describes the conformance classes supported by an SDAI


implementation.

176

STEP TOOLS, INC.

6 SDAI SCHEMAS

ENTITY implementation;
name
level
sdai_version
binding_version
implementation_class
transaction_level
expression_level
recording_level
scope_level
domain_equivalence_level
END_ENTITY;

:
:
:
:
:
:
:
:
:
:

STRING;
STRING;
STRING;
STRING;
INTEGER;
INTEGER;
INTEGER;
INTEGER;
INTEGER;
INTEGER;

A repository is a collection of models. A repository always appears in


session.known_servers, and appears in session.active_servers when it is open. The
actual models can be found in the contents attribute.
ENTITY sdai_repository;
name
: STRING;
contents
: sdai_repository_contents;
description : STRING;
INVERSE
session : sdai_session FOR known_servers;
UNIQUE
UR1: name, session;
END_ENTITY;
ENTITY sdai_repository_contents;
models : SET[0:?] OF sdai_model;
schemas : SET[0:?] OF schema_instance;
INVERSE
repository : sdai_repository FOR contents;
END_ENTITY;

Transactions are not provided in this implementation, so there will be no instances


of sdai_transaction in the session. Instead of transaction, the SDAI library provides
the Save and Undo functionality, which makes more sense for filesystem based repositories.
ENTITY sdai_transaction;
mode
: access_type;
owning_session : sdai_session;
END_ENTITY;

Events are used for logging, which is not supported in this implementation, so there
will be no instances of event, or error_event in the session.
ENTITY event
ABSTRACT SUPERTYPE OF (error_event);
function_id : STRING;

SDAI C LIBRARY REFERENCE MANUAL

177

6 SDAI SCHEMAS

time
END_ENTITY;

: time_stamp;

ENTITY error_event
SUBTYPE OF (event);
error
: INTEGER;
description : OPTIONAL STRING;
base
: OPTIONAL error_base;
END_ENTITY;
END_SCHEMA; -- session_schema

6.2

Population Schema
The SDAI population schema defines entities that describe the organization of a
model. The instances in the population schema are any data that is associated with
a model except for the actual instances that the model contains. These definitions
describe schema instance, model, scope, and entity extent entities.
SCHEMA population_schema;
REFERENCE FROM parameter_data_schema
( entity_instance,
application_instance );
REFERENCE FROM session_schema
( sdai_session,
sdai_repository,
access_type,
time_stamp );
USE FROM dictionary_schema;

A schema instance is a collection of related models.


ENTITY schema_instance;
name
: STRING;
associated_models : SET [0:?] OF sdai_model;
native_schema
: schema_definition;
repository
: sdai_repository;
change_date
: OPTIONAL time_stamp;
validation_date : time_stamp;
validation_result : LOGICAL;
validation_level : INTEGER;
UNIQUE
UR1: name, repository;
WHERE

178

STEP TOOLS, INC.

6 SDAI SCHEMAS

WR1: SELF IN SELF.repository.contents.schemas;


END_ENTITY;

The sdai_model entity defines a model. A model is an application defined collection of instances of entities in a single schema.
ENTITY sdai_model;
name
: STRING;
contents
: sdai_model_contents;
underlying_schema : schema_definition;
repository
: sdai_repository;
change_date
: OPTIONAL time_stamp;
mode
: OPTIONAL access_type;
INVERSE
associated_with : SET [0:?] OF schema_instance FOR associated_models;
UNIQUE
UR1: repository, name;
WHERE
WR1: SELF IN SELF.repository.contents.models;
END_ENTITY;

The sdai_model_contents entity provides listings of the entity instances in a model


grouped by type.
ENTITY sdai_model_contents;
instances
: SET[0:?] OF entity_instance;
folders
: SET[0:?] OF entity_extent;
populated_folders : SET[0:?] OF entity_extent;
END_ENTITY;

An entity extent contains all the instances of a single type or its subtypes in a specific model. Entity extents can be found in the folders and populated_folders attribute of sdai_model_contents. The sdaiGetEntityExtent() function returns the set
of instances in an entity extent (that is, the instances attribute), and in general is a
more convenient way to access this data.
ENTITY entity_extent;
definition : entity_definition;
instances : SET[0:?] OF entity_instance;
INVERSE
owned_by : sdai_model_contents FOR folders;
END_ENTITY;

Scopes are not supported in this implementation.


ENTITY scope;
owner
: application_instance;
owned
: SET [1:?] OF application_instance;
export_list : SET [0:?] OF application_instance;
UNIQUE

SDAI C LIBRARY REFERENCE MANUAL

179

6 SDAI SCHEMAS

UR1: owner;
WHERE
WR2: NOT (owner IN owned);
END_ENTITY;
END_SCHEMA; -- population_schema

6.3

Parameter Data Schema


The parameter data schema defines entities that are never instantiated, but rather are
EXPRESS place holders for the C data types used in an SDAI implementation. Unlike the session, population, and dictionary schemas; attributes of instances defined
in the parameter data schema cannot be queried by an SDAI application.
SCHEMA parameter_data_schema;
REFERENCE FROM population_schema
( schema_instance,
sdai_model,
sdai_model_contents );
REFERENCE FROM session_schema
( sdai_repository );
TYPE primitive = SELECT
(aggregate_instance,
assignable_primitive);
END_TYPE;
TYPE assignable_primitive = SELECT
(entity_instance,
string_value,
binary_value,
integer_value,
number_value,
enumeration_value,
select_value,
real_value,
boolean_value,
logical_value);
END_TYPE;
TYPE aggregate_primitive = SELECT
(aggregate_instance,
select_aggregate_instance);
END_TYPE;
TYPE string_value = STRING;

180

STEP TOOLS, INC.

6 SDAI SCHEMAS

END_TYPE;
TYPE binary_value = BINARY;
END_TYPE;
TYPE integer_value = INTEGER;
END_TYPE;
TYPE real_value = REAL;
END_TYPE;
TYPE number_value = SELECT
(real_value,
integer_value);
END_TYPE;
TYPE boolean_value = BOOLEAN;
END_TYPE;
TYPE logical_value = LOGICAL;
END_TYPE;
TYPE bound_instance_value = INTEGER;
END_TYPE;
TYPE query_source = SELECT
(aggregate_instance,
sdai_model,
sdai_repository,
schema_instance) ;
END_TYPE;

The following description for an iterator is for the EXPRESS models benefit only
and does not represent the SDAI implementations internal representation of an iterator. In this implementation, an iterator is not an entity instance.
ENTITY iterator;
subject
: aggregate_instance;
current_member : OPTIONAL primitive;
END_ENTITY;

The entity_instance entity represents an instance of an EXPRESS defined entity.


This is equivalent to the SDAI C type SdaiInstance.
ENTITY entity_instance
ABSTRACT SUPERTYPE OF (ONEOF(sdai_instance, application_instance));
END_ENTITY;

The application_instance entity represents the entity instances defined by application specific information models (that is, the application protocols). Except for entities defined in the four SDAI schemas, every instance manipulated by an

SDAI C LIBRARY REFERENCE MANUAL

181

6 SDAI SCHEMAS

application is an instance of this entity. Application instances are represented by


the C type SdaiAppInstance in the SDAI C binding.
ENTITY application_instance
SUBTYPE OF (entity_instance);
END_ENTITY;

The entity sdai_instance represents those entities defined in the four SDAI schemas.
ENTITY sdai_instance
ABSTRACT SUPERTYPE OF (ONEOF(dictionary_instance,
session_instance))
SUBTYPE OF (entity_instance);
END_ENTITY;

The dictionary_instance entity represents an instance of an entity in the SDAI dictionary schema.
ENTITY dictionary_instance
SUBTYPE OF (sdai_instance);
END_ENTITY;

The session_instance entity represents in instance of an entity in the SDAI session


schema.
ENTITY session_instance
SUBTYPE OF (sdai_instance);
END_ENTITY;
ENTITY attribute_value;
END_ENTITY;
ENTITY select_value
SUPERTYPE OF (ONEOF(select_aggregate_instance));
END_ENTITY;
ENTITY select_aggregate_instance
SUBTYPE OF (select_value);
END_ENTITY;
ENTITY enumeration_value;
END_ENTITY;
ENTITY aggregate_instance
ABSTRACT SUPERTYPE OF (ONEOF(unordered_collection,
ordered_collection));
END_ENTITY;
ENTITY unordered_collection
ABSTRACT SUPERTYPE OF (ONEOF(set_instance, bag_instance))

182

STEP TOOLS, INC.

6 SDAI SCHEMAS

SUBTYPE OF (aggregate_instance);
END_ENTITY;
ENTITY set_instance
SUBTYPE OF (unordered_collection);
END_ENTITY;
ENTITY bag_instance
SUBTYPE OF (unordered_collection);
END_ENTITY;
ENTITY ordered_collection
ABSTRACT SUPERTYPE OF (ONEOF(list_instance, array_instance))
SUBTYPE OF (aggregate_instance);
END_ENTITY;
ENTITY list_instance
ABSTRACT SUPERTYPE OF (ONEOF(non_persistent_list_instance,
schema_defined_list_instance))
SUBTYPE OF (ordered_collection);
END_ENTITY;
ENTITY schema_defined_list_instance
SUBTYPE OF (list_instance);
END_ENTITY;
ENTITY non_persistent_list_instance
SUBTYPE OF (list_instance);
contents : LIST[0:?] OF primitive;
END_ENTITY;
ENTITY array_instance
SUPERTYPE OF (ONEOF(application_indexed_array_instance))
SUBTYPE OF (ordered_collection);
END_ENTITY;
ENTITY application_indexed_array_instance
SUBTYPE OF (array_instance);
END_ENTITY;
END_SCHEMA; -- parameter_data_schema

6.4

Dictionary Schema
The dictionary schema provides a description of an EXPRESS information model
for an SDAI application's benefit. An application may query the dictionary to determine the structure of an information model.

SDAI C LIBRARY REFERENCE MANUAL

183

6 SDAI SCHEMAS

SCHEMA dictionary_schema;
TYPE base_type = SELECT
(simple_type,
aggregation_type,
named_type);
END_TYPE;
TYPE constructed_type = SELECT
(enumeration_type,
select_type);
END_TYPE;

An underlying_type entity is used to represent the underlying type of a defined type.


TYPE underlying_type = SELECT
(simple_type,
aggregation_type,
defined_type,
constructed_type);
END_TYPE;

The type_or_rule type is used by the entities implicit_item_id and where_rule.


TYPE type_or_rule = SELECT
(named_type,
global_rule);
END_TYPE;

The explicit_or_derived type is used to define which attribute is being redeclared by


a derived attribute (see derived_attribute).
TYPE explicit_or_derived = SELECT
(explicit_attribute,
derived_attribute);
END_TYPE;

The type express_id represents a string which is used as an EXPRESS identifier.


Instances of express_id are used to specify the names of entities, types, rules and
attributes.
TYPE express_id = STRING;
END_TYPE;

An info_object_id is used to provide a full description of an EXPRESS information


model. This description is defined in the ISO document describing the AP.
TYPE info_object_id = STRING;

184

STEP TOOLS, INC.

6 SDAI SCHEMAS

END_TYPE;

A schema_definition entity instance contains all the information about a single


schema. Every entity, type and rule in a schema refers to the corresponding
schema_definition. An instance of this type is returned by the function
sdaiGetSchema().
ENTITY schema_definition;
name
: express_id;
identification : OPTIONAL info_object_id;
INVERSE
entities
: SET [0:?] OF entity_definition FOR parent_schema;
types
: SET [0:?] OF defined_type FOR parent_schema;
global_rules
: SET [0:?] OF global_rule FOR parent_schema;
external_schemas : SET [0:?] OF external_schema FOR native_schema;
UNIQUE
UR1 : identification;
END_ENTITY;

These next few entities can be used to determine which entities have been interfaced
from other schemas (with USE and REFERENCE).
ENTITY interface_specification;
current_schema_id : express_id;
explicit_items
: SET [1:?] OF explicit_item_id;
implicit_items
: SET [0:?] OF implicit_item_id;
END_ENTITY;
ENTITY interfaced_item
ABSTRACT SUPERTYPE OF (ONEOF (explicit_item_id,
implicit_item_id));
foreign_schema_id : express_id;
END_ENTITY;
ENTITY explicit_item_id
ABSTRACT SUPERTYPE OF (ONEOF (used_item, referenced_item))
SUBTYPE OF ( interfaced_item );
local_definition : named_type;
original_id
: OPTIONAL express_id;
END_ENTITY;
ENTITY used_item
SUBTYPE OF ( explicit_item_id );
END_ENTITY;
ENTITY referenced_item
SUBTYPE OF ( explicit_item_id );
END_ENTITY;
ENTITY implicit_item_id
SUBTYPE OF ( interfaced_item );
local_definition : type_or_rule;

SDAI C LIBRARY REFERENCE MANUAL

185

6 SDAI SCHEMAS

END_ENTITY;
ENTITY external_schema;
name
: express_id;
native_schema : schema_definition;
INVERSE
for_types : SET [1:?] OF domain_equivalent_type FOR owner;
END_ENTITY;

The domain_equivalent_type entity is used to capture domain equivalence information. In this implementation, the entity will never be instantiated.
ENTITY domain_equivalent_type;
external_type_id : express_id;
native_type
: named_type;
owner
: external_schema;
END_ENTITY;

The named_type entity represents the named types in EXPRESS. This entity is the
super type, of SELECTs, defined types, and entity definition.
ENTITY named_type
ABSTRACT SUPERTYPE OF (ONEOF(entity_definition, defined_type));
name
: express_id;
where_rules : LIST [0:?] OF where_rule;
parent_schema : schema_definition;
END_ENTITY;

A defined_type entity instance represents the EXPRESS TYPE statement.


ENTITY defined_type
SUBTYPE OF (named_type);
domain : underlying_type;
END_ENTITY;

An entity_definition describes the structure on an entity. Note, however, that the list
is attributes is declared as an INVERSE. This means that there is no way to determine
the order that the attributes were defined in the original EXPRESS schema or a Part
21 file. If you need this information, you can use _sdaiGetAllAttrDefinitions().
ENTITY entity_definition
SUBTYPE OF (named_type);
supertypes : LIST [0:?] OF UNIQUE entity_definition;
complex
: BOOLEAN;
instantiable : BOOLEAN;
independent : BOOLEAN;
INVERSE
attributes
: SET [0:?] OF attribute FOR parent_entity;
uniqueness_rules : SET [0:?] OF uniqueness_rule FOR

186

STEP TOOLS, INC.

6 SDAI SCHEMAS

parent_entity;
global_rules
END_ENTITY;

: SET [0:?] OF global_rule FOR entities;

The attribute entity describes a single attribute of an instance. An instance of the


attribute type corresponds to the C type SdaiAttr.
ENTITY attribute
ABSTRACT SUPERTYPE OF (ONEOF(derived_attribute,
explicit_attribute,
inverse_attribute));
name
: express_id;
parent_entity : entity_definition;
END_ENTITY;

There are three subtypes of attribute. Each defines a specific type of attribute derived, explicit, or inverse.
ENTITY derived_attribute
SUBTYPE OF (attribute);
domain
: base_type;
redeclaring : OPTIONAL explicit_or_derived;
END_ENTITY;
ENTITY explicit_attribute
SUBTYPE OF (attribute);
domain
: base_type;
redeclaring : OPTIONAL explicit_attribute;
optional_flag : BOOLEAN;
END_ENTITY;
ENTITY inverse_attribute
SUBTYPE OF (attribute);
domain
: entity_definition;
redeclaring
: OPTIONAL inverse_attribute;
inverted_attr : explicit_attribute;
min_cardinality : OPTIONAL bound;
max_cardinality : OPTIONAL bound;
duplicates
: BOOLEAN;
END_ENTITY;

A uniqueness_rule entity represents an EXPRESS uniqueness rule.


ENTITY uniqueness_rule;
label
: OPTIONAL express_id;
attributes
: LIST [1:?] OF attribute;
parent_entity : entity_definition;
END_ENTITY;

SDAI C LIBRARY REFERENCE MANUAL

187

6 SDAI SCHEMAS

A where_rule entity represents an EXPRESS where rule. The actual definition of


the rule is not included here, but is stored internally by the implementation.
ENTITY where_rule;
label
: OPTIONAL express_id;
parent_item : type_or_rule;
END_ENTITY;

A global_rule entity represents an EXPRESS global rule. The actual definition of


the rule is not included here, but is stored internally by the implementation.
ENTITY global_rule;
name
: express_id;
entities
: LIST [1:?] OF entity_definition;
where_rules : LIST [1:?] OF where_rule;
parent_schema : schema_definition;
END_ENTITY;

The simple_type entity an its subtypes define the EXPRESS simple types.
ENTITY simple_type
ABSTRACT SUPERTYPE OF (ONEOF(integer_type, real_type,
string_type,
binary_type, logical_type, boolean_type, number_type));
END_ENTITY;
ENTITY number_type
SUBTYPE OF (simple_type);
END_ENTITY;
ENTITY integer_type
SUBTYPE OF (simple_type);
END_ENTITY;
ENTITY real_type
SUBTYPE OF (simple_type);
precision : OPTIONAL bound;
END_ENTITY;
ENTITY string_type
SUBTYPE OF (simple_type);
width
: OPTIONAL bound;
fixed_width : BOOLEAN;
END_ENTITY;
ENTITY binary_type
SUBTYPE OF (simple_type);
width
: OPTIONAL bound;
fixed_width : BOOLEAN;
END_ENTITY;

188

STEP TOOLS, INC.

6 SDAI SCHEMAS

ENTITY logical_type
SUBTYPE OF (simple_type);
END_ENTITY;
ENTITY boolean_type
SUBTYPE OF (simple_type);
END_ENTITY;

The enumeration_type entity represents an express enumeration.


ENTITY enumeration_type;
elements : LIST [1:?] OF UNIQUE express_id;
END_ENTITY;

The select_type entity represents an EXPRESS defined SELECT.


ENTITY select_type;
selections : SET [1:?] OF named_type;
END_ENTITY;

The aggregation_type entity and its subtypes define the various kinds of aggregates
that can be represented in EXPRESS.
ENTITY aggregation_type
ABSTRACT SUPERTYPE OF (ONEOF(variable_size_aggregation_type,
array_type));
element_type : base_type;
END_ENTITY;
ENTITY variable_size_aggregation_type
ABSTRACT SUPERTYPE OF (ONEOF(set_type, bag_type, list_type))
SUBTYPE OF (aggregation_type);
lower_bound : bound;
upper_bound : OPTIONAL bound;
END_ENTITY;
ENTITY set_type
SUBTYPE OF (variable_size_aggregation_type);
END_ENTITY;
ENTITY bag_type
SUBTYPE OF (variable_size_aggregation_type);
END_ENTITY;
ENTITY list_type
SUBTYPE OF (variable_size_aggregation_type);
unique_flag : BOOLEAN;
END_ENTITY;
ENTITY array_type
SUBTYPE OF (aggregation_type);
lower_index : bound;

SDAI C LIBRARY REFERENCE MANUAL

189

6 SDAI SCHEMAS

upper_index : bound;
unique_flag : BOOLEAN;
optional_flag : BOOLEAN;
END_ENTITY;

The bound entity and its subtypes are used to represent the lengths of strings and
binaries, and the size of aggregates. If the bound is of constant size it is implemented as an instance of integer_bound; if the bound is dependent on some EXPRESS
defined expression, it is instantiated as a population_dependent_bound.
ENTITY bound
ABSTRACT SUPERTYPE OF (ONEOF(integer_bound,
population_dependent_bound));
END_ENTITY;
ENTITY population_dependent_bound
SUBTYPE OF (bound);
END_ENTITY;
ENTITY integer_bound
SUBTYPE OF (bound);
bound_value : INTEGER;
END_ENTITY;
END_SCHEMA;

190

STEP TOOLS, INC.