Check-in [00c9bc755a]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Checkpoint on how to translate document.
Timelines: family | ancestors | descendants | both | micca-develop
Files: files | file ages | folders
SHA1:00c9bc755aa1328d9b8bd535de906e4c3106c345
User & Date: andrewm 2019-03-11 19:44:32
Context
2019-03-13
16:59
Checkpoint on the how to translate with micca document. check-in: bc5f85b499 user: andrewm tags: micca-develop
2019-03-11
19:44
Checkpoint on how to translate document. check-in: 00c9bc755a user: andrewm tags: micca-develop
2019-02-23
16:24
Checkpoint on how to translate using micca document. Finished translating dynamics part. check-in: 604404cd7c user: andrewm tags: micca-develop
Changes

Changes to micca/doc/howto/Makefile.

61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
	$(NULL)

DBLATEX_PARAMS =\
	bibliography.numbered=0\
	index.numbered=0\
	doc.publisher.show=0\
	doc.toc.show=1\
	doc.lot.show=figure,table\
	toc.section.depth=2\
	doc.section.depth=0\
	$(NULL)

# draft.mode=yes
# draft.watermark=1

DOCINFO	=\







|
|







61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
	$(NULL)

DBLATEX_PARAMS =\
	bibliography.numbered=0\
	index.numbered=0\
	doc.publisher.show=0\
	doc.toc.show=1\
	doc.lot.show=figure,table,example\
	toc.section.depth=4\
	doc.section.depth=0\
	$(NULL)

# draft.mode=yes
# draft.watermark=1

DOCINFO	=\

Changes to micca/doc/howto/bibliography.txt.

29
30
31
32
33
34
35








36
37
38
39
40
41
42
43
    Sally Shlaer and Stephen J. Mellor,
    'Object Oriented Systems Analysis: Modeling the World in States',
    Prentice-Hall (1992),
    ISBN 0-13-629940-7.

[bibliography]
.Articles








- [[[ls-articulate]]] Leon Starr,
    'How to Build Articulate UML Class Models',
    2008,
    http://www.modelint.com/how-to-build-articulate-uml-class-models/
- [[[ls-time]]] Leon Starr,
    'Time and Synchronization in Executable UML',
    2008,
    http://www.modelint.com/time-and-synchronization-in-executable-uml/







>
>
>
>
>
>
>
>








29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
    Sally Shlaer and Stephen J. Mellor,
    'Object Oriented Systems Analysis: Modeling the World in States',
    Prentice-Hall (1992),
    ISBN 0-13-629940-7.

[bibliography]
.Articles
- [[[micca-litprog]]] G. Andrew Mangogna,
    'Micca: Translating XUML Models',
    2018,
    http://repos.modelrealization.com/cgi-bin/fossil/mrtools/doc/trunk/micca/doc/micca.pdf
- [[[micca-manual]]] G. Andrew Mangogna,
    'micca manual pages',
    2018,
    http://repos.modelrealization.com/cgi-bin/fossil/mrtools/doc/trunk/micca/doc/HTML/toc.html
- [[[ls-articulate]]] Leon Starr,
    'How to Build Articulate UML Class Models',
    2008,
    http://www.modelint.com/how-to-build-articulate-uml-class-models/
- [[[ls-time]]] Leon Starr,
    'Time and Synchronization in Executable UML',
    2008,
    http://www.modelint.com/time-and-synchronization-in-executable-uml/

Changes to micca/doc/howto/data.txt.

1









































































2
3



































































4
5
6
7
8
9
== Translating data









































































Translating data




































































* names as "C" identifiers

* data type translation


// vim:syntax=asciidoc:

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>






1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
== Translating data

The first facet of an XUML model to be translated is the data.
It is recommended that all the classes and relationships be defined
first and that you insure that `micca` reads the DSL contining just
the data specifications without error.
In subsequent additions to the domain configuration,
state models and domain activities are added.
Getting the foundations in data correct are essential to the
remaining parts of the translation and so they must be done first.

=== How memory is handled

`Micca` assumes that all domain data is held in the primary memory of
a processor and the memory is directly addressable.
This is a common situation, but it is important to realize that
there is no assumption of secondary storage such as a disk drive.

`Micca` also assumes that the maximum number of instances of each class
is defined at compile time.
The `micca` run-time does no no dynamic allocation of memory space
off of a system heap, _i.e._ there are no calls to `malloc()`.
Each class has its own pool of memory from which instances are created.
That pool must be sized for the worst case number of instances the
class will ever have and that size is known when the ``C'' code
for the translation is compiled.
Memory is handled in this way to make it more deterministic.

For programmers who are more accustomed to dynamic memory allocation,
worst case memory sizing may seem restrictive or sub-optimal.
In practice,
it is slightly more work to consider the number of instances a class
may have,
but rarely are _arbitrary_ numbers of class instances required.

For example,
one may consider wanting an arbitrary number of network connections.
In truth,
operating systems do not allow processes to consume extremely large
numbers of resources and even if the resources were available,
at some time the ability service connections runs up against the
compute power of the processor.
It may seem like an arbitrary number are required, but what if that
number were 7 million?
In practice,
the number of instances of a class are typically small.

Because all data is held in primary memory and the size of that
memory is known at compile time,
the platform specific model that `micca` targets has two characteristics
that significantly help the implementation.

. All class instances have an architecturally generated identifier
    that consists of its address in primary memory.
    This identifier is used internal to the domain for all references
    to the class instances.
. All class instances have an architecturally generated identifier
    that can be used outside of the domain in order to specify
    the identify of class instances requesting or receiving services.
    The external identifier is the index in the storage pool array
    of a class.
    It is integer valued and unique within a given class.
    To uniquely identify a class instance outside of a domain,
    we must know both the class to which the instance belongs and its
    external identifying integer value.

Neither of the previous characteristics is profound.
Most programs that use data from primary memory use a _pointer_ or
_object id_ as a reference handle.
Accessing the class indirectly through a reference is a fundamental
mechanism supported by the addressing modes of all modern processors.
The mechanism is so common that we often forget that we are imposing
an identification scheme on the underlying classes.

=== Translating data types

* strings are special
* sizing integers

=== Translating classes

In our usage here,
we are overloading the term _class_ to have different meanings.
A model class and a platform-specific class are two distinct things.
They are related.
They are counterparts of each other in the model and platform realms,
but they are very different entities, logically.
In this section,
we discuss how to transform the logic of a model class into the
specifications of an platform-specific class.
To be clear,
we will refer to _model class_ when we are discussing the class
characteristics as they are presented in the data model and
_platform class_ when we are discussing how the implementation
of the model level concepts are realized.

==== Purely descriptive attributes

Attributes that are descriptive in nature and play no other role in the
model class are declared using `attribute` commands.
For example,
a model class might appear as:

["plantuml",title="Pump class in a model"]
----
@startuml
hide methods
hide circle
skinparam class {
    BackgroundColor yellow
    BorderColor black
}

class Pump {
    Pump ID : ID    {I}
    Max pressure : MPa
    Min pressure : MPa
    Flow rate : Liters per minute
}
@enduml
----

The three attributes, *Max pressure*, *Min pressure*, and *Flow rate*
are descriptive of the characteristics of a *Pump* and serve no other
role in the model class.
They are specified in the platform class using the `attribute` commmand.

.Pump platform class 
----
class Pump {
    attribute Max_pressure MPa_t
    attribute Min_pressure MPa_t
    attribute Flow_rate LpM_t
}
----

Note, attribute names must be value ``C'' identifiers and we assume
that the `MPa_t` and `LpM_t` type aliases have been defined.



=== Translating relationships

* names as "C" identifiers

* data type translation


// vim:syntax=asciidoc:

Changes to micca/doc/howto/dynamics.txt.

52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
...
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
...
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
...
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
...
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
=== Defining states

To specify a state,
`micca` uses the `state` command.

Consider a simple light bulb.

["plantuml"]
----
@startuml
hide empty description
skinparam state {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
................................................................................
We discuss how to specify creation events <<creation-events,below>>.

=== Final states

The lifecycle of some classes is over when they enter a certain state.
Consider the state model below.

["plantuml"]
----
@startuml
hide empty description
skinparam state {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
................................................................................
the two signatures to match correctly.
However, `micca` does detect such errors.

Consider our previous state model with the addition that
a *Request* event carries with it a count of the number of items to
request and a size of items to request.

["plantuml"]
----
@startuml
hide empty description
skinparam state {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
................................................................................
It is signaled to a newly created instance when an asynchronous
instance creation is requested in an activity.
The name of the creation event must be supplied as part of
the process of asynchronously creating an instance.
The event may have parameters or not depending upon what the analytical
model has specified.

==== Assigner state models [[assigner-state-models]]

The nature of some associations between classes is competitive.
The concurrency rules of XUML imply that instances of the relationship
must be created by serializing the actions involved.
This is accomplished by associating a state model to the relationship
itself and those state models are called _assigner_ state models.
The archetypal example for assigner state models is the assignment
of store clerks to service customers:


["plantuml"]
----
@startuml
skinparam class {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
}
................................................................................
the association itself and _not_ to any particular class (indeed in this case,
the *Service* class may have its own state model).

`Micca` will arrange for the assigner to exist before the domain starts
to run and will place the assigner in the inital state as specified by
the `statemodel` script.

==== Multi-assigner models

Usually,
there is only a single instance of an assigner.
This was the case in the previous example.
However,
some competitive relationships are more complicated and are partitioned
by the instances of another class.







|







 







|







 







|







 







|










|







 







|







52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
...
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
...
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
...
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
...
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
=== Defining states

To specify a state,
`micca` uses the `state` command.

Consider a simple light bulb.

["plantuml",title="Light Bulb State Model"]
----
@startuml
hide empty description
skinparam state {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
................................................................................
We discuss how to specify creation events <<creation-events,below>>.

=== Final states

The lifecycle of some classes is over when they enter a certain state.
Consider the state model below.

["plantuml",title="State Model with Final State"]
----
@startuml
hide empty description
skinparam state {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
................................................................................
the two signatures to match correctly.
However, `micca` does detect such errors.

Consider our previous state model with the addition that
a *Request* event carries with it a count of the number of items to
request and a size of items to request.

["plantuml",title="State Model with State Parameters"]
----
@startuml
hide empty description
skinparam state {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
................................................................................
It is signaled to a newly created instance when an asynchronous
instance creation is requested in an activity.
The name of the creation event must be supplied as part of
the process of asynchronously creating an instance.
The event may have parameters or not depending upon what the analytical
model has specified.

=== Assigner state models [[assigner-state-models]]

The nature of some associations between classes is competitive.
The concurrency rules of XUML imply that instances of the relationship
must be created by serializing the actions involved.
This is accomplished by associating a state model to the relationship
itself and those state models are called _assigner_ state models.
The archetypal example for assigner state models is the assignment
of store clerks to service customers:


["plantuml",title="Clerk / Customer Association"]
----
@startuml
skinparam class {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
}
................................................................................
the association itself and _not_ to any particular class (indeed in this case,
the *Service* class may have its own state model).

`Micca` will arrange for the assigner to exist before the domain starts
to run and will place the assigner in the inital state as specified by
the `statemodel` script.

=== Multi-assigner models

Usually,
there is only a single instance of an assigner.
This was the case in the previous example.
However,
some competitive relationships are more complicated and are partitioned
by the instances of another class.

Changes to micca/doc/howto/intro.txt.

1
2
3
4
5
6
7
8







































9
10
11
12
13
14
15
..
33
34
35
36
37
38
39



40
41
42
43
44
45
46
...
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
...
152
153
154
155
156
157
158
159
160
161
162
163
164



165
166
167
168
169
170
171
172
...
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
...
221
222
223
224
225
226
227


228













229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
...
274
275
276
277
278
279
280
281
282
283
284
== Introduction

This paper presents a set of techniques to demonstrate
translating an
https://en.wikipedia.org/wiki/Executable_UML[Executable UML (XUML)]
domain model into a "C" based implementation using `micca`.

* what is micca ???








































=== Workflow overview

The following figure shows the overall workflow for creating a system
using modeling and translating with `micca`.

image::micca-translation.pdf[title="Workflow Overview"]
................................................................................
translation phase.

The Translator's role in completing the process
is to examine the contents of the domain model materials
and formulate a micca DSL source file that contains a platform
specific configuration of the domain model and is _derived_
from the domain model.



This document is written to explain that one particular step in the overall
workflow (shown in the light blue oval in the diagram).

Once the domain configuration is complete,
`micca` reads the file and captures the platform specfic elements
it contains.
Using this data,
................................................................................
attempts to translate the model.
The separation of analysis from translation is intended to separate the problem
essentials from the implemenatation artifacts.
It is *not* intended to erect a virtual wall across which political battles can
be waged with one side contending the models can't be made to run
and the other side contending that they are perfectly clear and consistent.

=== Available targets
Available targets

=== Complete model

Before translation can be begin,
it is necessary to have a complete model.
That seems like an obvious statement,
but in our usual rush to finish systems there is a natural tendency
to start translation before the model is complete.
In the end,
starting with a half-baked model wastes time,
especially if the person performing the translation
(as is our recommendation)
is not the same person who created the model.

................................................................................
to determine what the core concepts of a domain are.
Experience shows that domain models, like a conventional code base,
tend to have areas where it is less clear what the _right_ thing is
to do.
Usually, some doubts enter into the process near the domain boundary
and its interactions with other domains.
This seems to be a property of any collection of logic when exceeding a certain
size (which size is almost never exceeded by the simple examples usually
presented).

However,
domain models are precise and therefore don't have _fuzzy_ parts that stubbed
out or left open for interpretation or dangling for future elaboration.



So we consider the following a _minimal_ set of deliverables that
are required before translation can begin.[[model-contents]]

* A class model of the domain data. The class model must contain:
  - A UML class diagram (in accordance with XUML usage of class
    diagram constructs).
  - Written descriptions of each class, relationship and attribute.
    Writing descriptions of the class model elements is an essential
................................................................................
  - A description of each state and the role it plays in the lifecycle
    of the class.
  - A state activity description of the processing for each state.
    The processing should be described in an unambiguous action language
    or in action data flow diagrams.
* A state model for each relationship that requires an assigner
  to serialize the creation of an instance of the relationship.
  The contents of this state model are the same as for a state model
  of a class lifecycle.
* A set of instance operation descriptions for each class
    that defines them, to include:
  - A description of the function and interface of the operation.
  - The processing performed by the operation in terms of action language
    or a data flow diagram.
* A set of domain operation descriptions that include:
................................................................................
    purely data oriented fashion.
    Values of referential attributes indicate the relationship instances
    that are part of the initial instance population.
    Using action language to define initial data populations is not
    acceptible.

=== Model facets


Model facets -- three facets of the model. Translation order














=== Translation workflow summary

When a language compiler, say a ``C'' compiler, compiles a code file,
it does not produce the code according to the way the program should
have been written if you are a good programmer.
A badly structured piece of source code produces an equally badly
structured output.
The compiler can work only with the what it is given and it must
faithfully produce code, that when executed, accomplishes
the logic contained in the original source.
The compile is unaware of any intent in the code or any higher
order design in the system.

The same is true of translating XUML domain models.
A Translator does not produce code for the model as it would have
come from a good analysis.
The output can only be _derived_ from the model as it was
given by the Analyst.
If the model is overly complex and poorly conceived,
the resulting code will reflect that.

It is most important that the translation do not add or subtract
anything from the logic of the domain model.
The intent of translation is only to add the necessary software
technology to make the domain run on the intended platform.
Consequently,
a Translator tends to pay little attention to the details of
what a domain actually accomplishes.
It is a somewhat rote undertaking.
................................................................................
    characteristics.
. Translate the class model.
. Translate the state models.
. Translate the data flow diagrams or action language to "C" code.
. Construct an initial instance population.
. Construct the bridges between domains.

Each of these areas is below in a separate section.


// vim:syntax=asciidoc:





|

|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>
>
>







 







<
<
<





|







 







|
|

<
|
|
>
>
>
|







 







|







 







>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>





|



|

|








|

|







 







|



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
..
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
...
153
154
155
156
157
158
159



160
161
162
163
164
165
166
167
168
169
170
171
172
...
191
192
193
194
195
196
197
198
199
200

201
202
203
204
205
206
207
208
209
210
211
212
213
...
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
...
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
...
330
331
332
333
334
335
336
337
338
339
340
== Introduction

This paper presents a set of techniques to demonstrate
translating an
https://en.wikipedia.org/wiki/Executable_UML[Executable UML (XUML)]
domain model into a "C" based program using `micca`.

`Micca` is a model translation tool.
It works by accepting a platform specific description of an XUML
model and generates code that may be compiled into an executable
program.
`Micca` targets small to medium sized embedded systemsfootnote::[Exact
sizes are difficult to estimate. Normally, `micca` generated systems
run on bare-metal microcontrollers that contain at least 16 Kibytes
of program memory and at least 8 Kibytes of RAM.
The top end is not really fixed, although most microcontrollers top
out at about 1 Mibytes of program memory and 256 Kibytes of RAM.]
and small to
medium sized POSIX systems.footnote::[The primary use case for running
on a POSIX system is to perform testing on the generated domain
before it is moved onto the target hardware.
However, it is not unreasonable to field an application directly intended
to run in a POSIX environment.
In that environment, since the `micca` run-time is single threaded,
the upper end of scaling will limit the size of any POSIX application
where `micca` might be useful.]
The implementation language is ``C''.
`Micca` translations are intended for a class of applications that are
specific to the software platform for which it was created.
Architecturally,
`micca` translated domains are single threaded and use a callback
scheme to implement state machine transitions.
The class of applications is intended to be event driven and reactive,
waiting up as a result of external stimulus, performing a short lived
computation to produce a response and then going quiescent.

In the next section,
the overall workflow of accomplishing a model translation using `micca`
is discussed.
Subsequent chapters describe the various steps required to finish
the translation.

In addition to this document,
`micca` has a complete set of reference
<<micca-manual,manual pages>>.
It is recommended that you have those readily available before starting
any translation.

=== Workflow overview

The following figure shows the overall workflow for creating a system
using modeling and translating with `micca`.

image::micca-translation.pdf[title="Workflow Overview"]
................................................................................
translation phase.

The Translator's role in completing the process
is to examine the contents of the domain model materials
and formulate a micca DSL source file that contains a platform
specific configuration of the domain model and is _derived_
from the domain model.
We emphasize that the implementation is derived from the model.
To do otherwise, lessens the value of the model and calls into
question why the model was created at all.
This document is written to explain that one particular step in the overall
workflow (shown in the light blue oval in the diagram).

Once the domain configuration is complete,
`micca` reads the file and captures the platform specfic elements
it contains.
Using this data,
................................................................................
attempts to translate the model.
The separation of analysis from translation is intended to separate the problem
essentials from the implemenatation artifacts.
It is *not* intended to erect a virtual wall across which political battles can
be waged with one side contending the models can't be made to run
and the other side contending that they are perfectly clear and consistent.




=== Complete model

Before translation can be begin,
it is necessary to have a complete model.
That seems like an obvious statement,
but in our usual rush to finish systems there are many pressures
to start translation before the model is complete.
In the end,
starting with a half-baked model wastes time,
especially if the person performing the translation
(as is our recommendation)
is not the same person who created the model.

................................................................................
to determine what the core concepts of a domain are.
Experience shows that domain models, like a conventional code base,
tend to have areas where it is less clear what the _right_ thing is
to do.
Usually, some doubts enter into the process near the domain boundary
and its interactions with other domains.
This seems to be a property of any collection of logic when exceeding a certain
size.footnote::[which size is almost never exceeded by the
simple examples usually presented]


Domain models are precise and detailed and therefore don't have _fuzzy_ parts
that are stubbed out or left open for interpretation or dangling for future
elaboration.
An incomplete or vague model is simply not sufficient to perform a translation
which itself is supposed to be _derived_ from the model.
We consider the following a _minimal_ set of deliverables that
are required before translation can begin.[[model-contents]]

* A class model of the domain data. The class model must contain:
  - A UML class diagram (in accordance with XUML usage of class
    diagram constructs).
  - Written descriptions of each class, relationship and attribute.
    Writing descriptions of the class model elements is an essential
................................................................................
  - A description of each state and the role it plays in the lifecycle
    of the class.
  - A state activity description of the processing for each state.
    The processing should be described in an unambiguous action language
    or in action data flow diagrams.
* A state model for each relationship that requires an assigner
  to serialize the creation of an instance of the relationship.
  The contents of for an assigner state model are the same as for a state model
  of a class lifecycle.
* A set of instance operation descriptions for each class
    that defines them, to include:
  - A description of the function and interface of the operation.
  - The processing performed by the operation in terms of action language
    or a data flow diagram.
* A set of domain operation descriptions that include:
................................................................................
    purely data oriented fashion.
    Values of referential attributes indicate the relationship instances
    that are part of the initial instance population.
    Using action language to define initial data populations is not
    acceptible.

=== Model facets

The construction of an XUML model procedes by considering three
facets of the model:

.. the data facet where real world entities and associations are
    abstracted in to a set of logical predicates represented by data,
.. the dynamics facet where lifecycles of classes are represented by
    finite state machines, and
.. the processing facet where the computations of the domain are represented
    by an action language or data flow diagram.

Translation also procedes according to the three facets and in same order.
Data structures must be determined,
state machines are then specified and finally
the code required for the activities is written.
This preferred order yields the fastest and most consistent results.

=== Translation workflow summary

When a language compiler, say a ``C'' compiler, compiles a code file,
it does not produce the code according to the way the program should
have been written if you were a good programmer.
A badly structured piece of source code produces an equally badly
structured output.
The compiler can work only with the what it is given and it must
faithfully produce code that, when executed, accomplishes
the logic contained in the original source.
The compiler is unaware of any intent in the code or any higher
order design in the system.

The same is true of translating XUML domain models.
A Translator does not produce code for the model as it would have
come from a good analysis.
The output can only be _derived_ from the model as it was
given by the Analyst.
If the model is overly complex and poorly conceived,
the resulting implementation will reflect that.

It is most important that the translation does not add or subtract
anything from the logic of the domain model.
The intent of translation is only to add the necessary software
technology to make the domain run on the intended platform.
Consequently,
a Translator tends to pay little attention to the details of
what a domain actually accomplishes.
It is a somewhat rote undertaking.
................................................................................
    characteristics.
. Translate the class model.
. Translate the state models.
. Translate the data flow diagrams or action language to "C" code.
. Construct an initial instance population.
. Construct the bridges between domains.

Each of these areas is discussed in a separate section below.


// vim:syntax=asciidoc:

Changes to micca/doc/howto/marking.txt.

101
102
103
104
105
106
107



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139












140
141
142
143
144
145
146
147
148
149
150
151


152
153


154
155
156
157
158
159
160
...
161
162
163
164
165
166
167
168

169
170
171

172




































































































































































173
==== Class metadata

For classes, we are interested in determining if any activity in the
model does the following:

* Create an instance, either synchronously or asynchronously via a
  creation event.



* Delete an instance either synchronously or asynchronously as a result
  of entering a final state.
* Query the set of class instances based solely upon the values of identifying
  attributes.
* Query the set of class instances based upon the values of non-identifying
  attributes.

==== Attribute metadata

For class attributes,
we wish to know:

* Any attribute that is read.
* Any attribute whose value is updated.
* Any mathematically dependent attribute that is updated
  (this is an analysis error).

==== Relationship metadata

For relationships,
we are interested in the navigation of relationships by the activities
in the model. Specifically:

* Creating, deleting or updating the instances of a relationship.
    This includes subtype migration of one subtype into being instance of a
    different subtype.
* The direction of navigation of a relationship between the participating
  classes.
* Navigating generalization relationships from supertype to some subtype.
* Navigating generalization relationships from a subtype instance to
  its corresponding supertype instance.













=== Marking mechanics

The following is the suggested way to obtain and record the model metatdata
is:

* Start with a clean printout of the class diagram of the model on the
  largest size sheet of paper that can be conveniently obtained.
  Class diagrams for a cleanly presented model should be partitioned
  into smaller subsystems if the number of classes in the domain
  will not fit on readily available paper sizes.
  In practice, Letter size of A size paper is the most readily available
  and model drawings should take that into account.


* Read the action language or data flow diagrams of every processing
  activity in the model.


* While reading the model activities,
  annotate the class diagram with the information previously presented.
  For example,
  when action language statement reads an attribute, place an *R* next to the
  attribute's name.
  Similarly, attribute updates can be marked with a *U* or *W* character.
  The direction of relationship traversal can be annotated as an
................................................................................
  arrow pointing in the direction of the navigation and parallel to the
  relationship line on the class diagram.

The precise details of the notation used for the marking is not as important
as insuring that the previously mentioned information is gathered
and clearly indicated.
A project may choose to standarize the notation.
Do not hesitate to make notes on the diagram.

The results of this model marking analysis directly feeds the next steps in the
translation process.







































































































































































// vim:syntax=asciidoc:







>
>
>












|











|
|






>
>
>
>
>
>
>
>
>
>
>
>









|
|

>
>


>
>







 







|
>



>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
...
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
==== Class metadata

For classes, we are interested in determining if any activity in the
model does the following:

* Create an instance, either synchronously or asynchronously via a
  creation event.
  Note that migrating a subtype in a generalization relationship is
  conceptually a synchronous delete / create / relate operation (although in
  the implementation is may happen quite differently).
* Delete an instance either synchronously or asynchronously as a result
  of entering a final state.
* Query the set of class instances based solely upon the values of identifying
  attributes.
* Query the set of class instances based upon the values of non-identifying
  attributes.

==== Attribute metadata

For class attributes,
we wish to know:

* Any attribute whose value is read.
* Any attribute whose value is updated.
* Any mathematically dependent attribute that is updated
  (this is an analysis error).

==== Relationship metadata

For relationships,
we are interested in the navigation of relationships by the activities
in the model. Specifically:

* Creating, deleting or updating the instances of a relationship.
    This includes both creating instances of association classes and
    migrating subclass instances of a generalization to a different class.
* The direction of navigation of a relationship between the participating
  classes.
* Navigating generalization relationships from supertype to some subtype.
* Navigating generalization relationships from a subtype instance to
  its corresponding supertype instance.

==== State model metadata

For state models,
we are interested in the signaling of events and the reachability of
states.
Foreach state model record:

* Each event signaled.
* Each polymorphic event signaled.
* Any states, other than final states, that have no outgoing transitions.
* Any states, other than an inital state, that have no incoming transitions.

=== Marking mechanics

The following is the suggested way to obtain and record the model metatdata
is:

* Start with a clean printout of the class diagram of the model on the
  largest size sheet of paper that can be conveniently obtained.
  Class diagrams for a cleanly presented model should be partitioned
  into smaller subsystems if the number of classes in the domain
  does not fit on readily available paper sizes.
  In practice, Letter size or A size paper is the most readily available
  and model drawings should take that into account.
* Also obtain clean printouts of the state model diagrams for each
  class which has a lifecycle state model.
* Read the action language or data flow diagrams of every processing
  activity in the model.
  This includes the state activites, domain operations and instance-based
  operations.
* While reading the model activities,
  annotate the class diagram with the information previously presented.
  For example,
  when action language statement reads an attribute, place an *R* next to the
  attribute's name.
  Similarly, attribute updates can be marked with a *U* or *W* character.
  The direction of relationship traversal can be annotated as an
................................................................................
  arrow pointing in the direction of the navigation and parallel to the
  relationship line on the class diagram.

The precise details of the notation used for the marking is not as important
as insuring that the previously mentioned information is gathered
and clearly indicated.
A project may choose to standarize the notation.
Do not hesitate to make notes on the diagrams regarding the
behavior implied by the activity processing.
The results of this model marking analysis directly feeds the next steps in the
translation process.

=== Evaluating the marking

After the marking is completed,
it should be evaluated for the following situations
The results of the evaluation should be reported back to the
analyst for the domain.

==== Evaluating attributes

Class attributes play one or more roles in the abstraction of a class.
The roles of an attribute may be broadly classified as:

Descriptive attributes::
    Descriptive attributes characterize class instances by defining
    some aspect of the instance that pertains to the subject matter
    of the domain.
    For example,
    a *Motor* class might have an attribute of *Torque* which describes
    the amount of torque the motor produces.

Identifying attributes::
    Identifying attributes are those attributes which are a part of
    a class identifier.
    Each class has one or more identifiers.
    Each identifier consists of one or more attributes.
    The set of attributes forming an identifier may _not_ be a subset
    (proper or improper) of the attributes of another identifier
    of the class (_.i.e._ identifiers must be minimal identifiers).
    The values of the attributes of an identifier must be distinct
    among all the instances of a class.
    For example,
    a *Product Description* class might have two attributes,
    *Manufacturer Name* and *Model Name* that, together, are treated
    as an identifier.
    This implies that among all instances of *Product Description*,
    no two instances have the same values for both *Manufacturer Name*
    and *Model Name*.
+
Sometimes identifying attributes carry semantically meaningful
information, such as the previous example.
Some identifying attributes are system generated and have no
intrinsic semantic meaning.
The distinction is important in that the translation mechanisms
have to create system generated identifying attribute values.
Identifying attribute values that are semantically meaningful
usually are supplied from outside of the domain.
A fundamental distinction between the two types of identifiers also
relates to where the responsibility for insuring uniqueness lies.

Referential attributes::
    Referential attributes are those attributes which characterize the
    relationships between class instances.
    The real-world associations between classes are formalized by
    a relationship, either an association or a generalization.
    Referential attributes have values that are the same as the
    values of identifying attributes the other participating class.
    In this way,
    we know which particular instances are related to each other.

Attributes often serve multiple roles.
It is common for identifying attributes to also serve as referential
attributes.
Also,
if the identifier to which a referential attribute refers is
descriptive in nature,
then the referential attribute is also descriptive, transitively.

Attributes are also classified as being _independent_ or _dependent_.
An independent attribute may take on any value defined for the
data type of the attribute.
It's value is not constrained by the value of any other attribute.

A value of a dependent attribute is mathematically related to other
attributes.
Dependent attributes have a _formula_ which is calculated each time
they are read
and this formula must be supplied by the analyst.
It is an analysis error to attempt to write to a dependent attribute.
It is also an error to use a dependent attribute as an identifying
or referential attribute.

===== Evaluating descriptive attributes

For attributes which have a descriptive role,
the following situations should be noted.

Descriptive attributes neither read nor written::
    This is probably an analysis error. Attributes that are never
    accessed don't have much use.
Descriptive attributes read but not written::
    This situation could be analysis error or it might be that the domain
    expects the value to be bridged in and depends upon a service
    domain to keep the value up to date.
    This should be clear when the bridge specification for the domain
    is available.
Descriptive attributes written but not read::
    This situation, like the last, might be an analysis error or there
    might be a dependency on another domain which is expected to bridge
    the attribute value out.
    Again, this situation must be checked against the bridge
    specification for the domain.

===== Evaluating identifying attributes

For attributes which have an identifying role,
the following situations should be noted.

Identifying attributes that are written::
    In XUML,
    updating the value of an identifying attribute is _not_ allowed
    and this is an analysis error.
    Such an update would change the instance identification.
    This is an analysis error.
    The only way in XUML to change an instance is to delete it
    and then create a new one with different identifying attribute
    values.
Identifying attributes that are read::
    We make note of identifying attributes that are read and treated
    as descriptive attributes because it will have an impact on
    specifying the platform specifics required for translation.

===== Evaluating referential attributes

For attributes which have a referential role,
the following situations should be noted.

Referential attributes that are written::
    In XUML,
    updating the values of referential attributes is _not_ allowed
    and this is an analysis error.
    Such an update modifies the instances of the relationship which
    the referential attributes formalize.
    XUML action languages provide primitives to modify relationship
    instances and those must be used to change how instances are related.
Referential attributes that are read::
    If an attibute serves both referential and descriptive roles,
    domain activities may read the referential attribute.
    We make specific note this circumstance as it must be accounted for
    in the translation.

==== Evaluating relationships

Relationships that are never navigated::
    Relationships that are never navigated need not be translated and
    should be noted to the domain analyst as a potential error.
Relationships with a constant number of instances::
    Relationships that do not change either in number or in the
    participants are deemed _static_.
    This property allows for some optimizations in the translation.

==== Evaluating state models

Events that are never signaled::
    Events that are never signaled are an analysis error.
States with no outgoing transitions::
    States with no outgoing transitions are terminal states,
    _i.e._ there is no way to escape the state.
    This may or may not be an analysis error, but its existance should
    be noted.
States with no incoming transitions::
    States with no incoming transitions cannot be reached unless
    the class instances is created in that state.
    This may or may not be an analysis error, and it should be noted to the
    analyst.


// vim:syntax=asciidoc:

Changes to micca/doc/howto/processing.txt.

1










































2
3


4





















































































































































































































































































































































































































5
== Translating processing










































Translating processing

























































































































































































































































































































































































































// vim:syntax=asciidoc:

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|

>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
== Translating processing

The processing facet of a model is the most difficult to translate.
Translating domain actions requires the Translator to reformulate the
intent of an action language or data flow diagram into ``C'' language
statements.
The semantic gap between these representations is larger than that of
either the dynamics facet (where it is virtually zero) or the data facet
(where there are a relatively small set of rules and guidelines).

=== Action language -- what action language?

The first quandry we encounter is to determine how domain activities
are described to the Translator.
Since we don't transfer any machine readable content from the analysis effort,
there is no requirement for a formal description of how activities are
expressed.
Many action languages have been defined.
It is possible the analyst decided to express the processing facet at a
data flow diagram with associated descriptions of the processes.
It could be that the domain actions are written in a more informal pseudo-code.
Regardless of how the actions are expressed,
projects are strongly encouraged to adopt one particular way to express domain
actions for all the domains in the project.
Multiple types of action specifications only confuses the matter.

It turns out that, counter to what you might think,
the exact manner of expressing the model processing actions is not
as important is might seem.
In well designed models,
most activities are small and highly focused in what they must accomplish.
What is important is that the actions be expressed in a form that is
clear and unambiguous.

In our discussion and examples here,
we will used a variety of ways to show model actions and how they are
translated using `micca`.
Sometimes a pseudo-code narrative is sufficient.
However,
we will tend to use an action language called, _Scrall_, the most.
Scrall is an open source action language designed to leverage the
distinct semantics of XUML.footnote::[Need a reference here!]

=== Categories of processing

Broadly speaking,
domain actions fall into two categories:

. Expression evaluation and flow of control.
    Actions need to be able to compute things, such as adding or
    multiplying values. Actions need to be able to test values
    and change the flow of execution. 
    These are basic operations required to perform any reasonable computation.
. Model level actions.
    Action languages have primitives that affect model level components.
    For example, signaling an event to an instance is a model level
    action that is usually expressed as a basic construct in the action
    language.

Examined from a different perspective,
these two categories of actions can also be seen as:

. Constructs that are directly supported by the implementation language
    (``C'' in our case) and for which there is a direct mapping
    from the action onto the implementation language.
. Constructs that are built upon the implementation language using data
    and code constructs to implement higher order operations on model
    components.

Consider the following action snippet:

----
(Altitude < Minimum)?
    Pull up -> me
----

The intent of the action is to test whether the altitude value
is less than some minimum and if so,
then to signal the *Pull up* event to the instance running the actions
(_i.e._ *me*).
A translation of these ideas to ``C'' might look like:

[source,c]
----
unsigned Altitude ;
unsigned Minimum ;

// some code to assign values to both Altitude and Miniumum

if (Altitude < Minumum) {
    // OK, now what? How to I signal an event?
}
----

Clearly,
signaling an event to an instance is not a base concept in ``C''
and there is no direct, handy statement in the language that will do it.
Consequently,
`micca` has devised data structures and supplies code as part of the run-time
library to perform that operation.
There is nothing mysterious about that code.
It is ordinary ``C'' code and can be viewed like any other ``C''
implementation.
The function to signal events is called `mrt_SignalEvent()` and it accepts
arguments required to accomplish the model level action of sending an event
signal to a class instance.
It is possible to write the ``C'' code that invokes `mrt_SignalEvent()`
directly, and that would cause the signal to be generated.

The difficulty of coding directly against the run-time library interfaces is:

. There is a large cognitive burden to understand the details of the
    run-time API.
. Direct coding against the run-time library API strongly couples the
    translation to the run-time interface and could prevent future changes
    to the run-time that might be required to correct errors or extend
    the functionality.

The `micca` solution to this is to provide an _embeddable_ command language
that generates the code needed for model level actions.
One significant advantage of the embedded commands is that `micca` has
access to the platform specific model when the code generation happens.
Consequently,
error diagnosis is much improved.
If you attempt to signal an event to a class instance and that instance
does not have such an event,
`micca` is able to diagnose that condition and issue an appropriate error
message.

=== `Micca` embedded command language

An activity in a `micca` translation, _e.g._ a state activity,
appears as ordinary ``C'' code with other commands embedded into the code.
The commands are embedded by surrounding them with the `<%` and `%>`
characters.
Our previous example would appear as:

[source,c]
----
unsigned Altitude ;
unsigned Minimum ;

// some code to assign values to both Altitude and Miniumum

if (Altitude < Minumum) {
<%  my signal Pull_up       %>
}
----

There are a few rules about the embedded commands:

. The command syntax is the same as for `micca` itself, _i.e._ it is Tcl
    syntax.
. Leading or trailing whitespace around the embedded
    command does not matter.  So you may format
    the embedded commands in whatever way you find clearest.
    The above formatting tries to keep the `<%` and `%>` markers
    out of the way to make indentation more apparent.
. Embedded commands *do not nest*.
. Some embedded commands generate ``C'' code statements and include all
    the necessary semicolon punctuation.
    Other embedded commands are intended to be used in expressions and
    so do not place semicolons in the output.
    The reference documentation for the embedded command language states
    which behavior each command has, but you will quickly know
    the difference by the intent of each embedded command.
. During the code generation, the embedded command is removed from the input
    and the results of its execution is placed in the output at the same
    location.
. Since it is unknown how many ``C'' statements a command may generate,
    all statements should be treated as _compound_ statements and surrounded
    by curly braces (as we did in the `if` test of the previous example).

==== Generated code

Most people who perform a model translation using `micca` are curious about
the contents of the generated ``C'' code.
It usually takes some experience to trust the tooling and examining the
code can garner that trust.
In the end,
everything must end up as ``C'' code and we should be able to read
that code.
What follows is a sample showing a state activity and its generated code.

First, we show the `micca` source.
This is a state activity, so it would be part of a state model.

----
statemodel {
    # Code for states, events, et.al.

    state Autocycle_Session_Deactivate {} {
    <%  my update Deactivate true               %>
    <%  my signal Deactivate                    %>
    }
}
----

And the following is the generated code snippet.

[source,c]
----
static void
Autocycle_Session_Deactivate(
    struct Autocycle_Session *const self)
// <%  my update Deactivate true               %>
// <%  my signal Deactivate                    %>
{
    MRT_INSTRUMENT_ENTRY
    // instance self update Deactivate true
    self->Deactivate = true ;
    // instance self signal Deactivate {}
    mrt_SignalEvent(6, self, self, NULL, 0) ; // Deactivate
}
----

There are several points of interest:

. State activities are turned into ordinary ``C'' functions.
    Most names are made file static to avoid cluttering
    the global space of names and to lessen the chance of a name
    conflict.
    State activities to not return values.
    All of their side effects are recording in the class data.
. Each state activity function has an argument called, `self`, which
    is a reference to the class instance for which the action is
    being run.
. The contents of the state action is placed as a comment at the
    beginning of the function body.
. `MRT_INSTRUMENT_ENTRY` is a macro that can be used for logging
    and instrumentation output or it can be defined to be empty and
    no additional code is generated.
. As each embedded command is expanded, a comment containing the
    command is placed in the ``C'' code.
    In this example, `my signal` is the same as `instance self`.
    The `my` prefix is just a shorthand.
. Updating an attribute is done via pointer indirection on the instance
    using structure members defined as part of the class's attributes.
. Signaling an event happens by invoking a function in the run-time
    with the proper argument values.
    In this case the *Deactivate* event has been numbered `6`,
    and the event is self-directed with no parameters.
    `Micca` generates all the numbers used to encode things such
    as states and events.
. The output code is neatly formatted.
    Although the code is not examined often,
    during debugging you may be setting breakpoints in the generated code and
    it is helpful if it is readable and there are clues about how the generated
    code relates back to the model.

We do not show any other generated code in this document.
How the code is generated is discussed in the
<<micca-litprog,literate source document>>
for `micca`.
Code generation test cases are
http://repos.modelrealization.com/cgi-bin/fossil/mrtools[available]
for those interested in
the precise details of how the generated output appears.

As we stated previously,
model actions are a mix of ordinary ``C'' code plus embedded commands
to perform model level operations.
In the end,
the result looks like ``C'' but with what can be imagined as
unusually looking function invocations to perform the model level
semantics.

The following sections group the embedded commands based on
model level components such as classes or relationships.
Embedded commands are presented, along with some example action language,
to show how the intent of the action language is rendered into
the embedded commands.

=== Embedded commands for classes

In this section we examine the support for operating on classes.
This includes:

* Creating class instances
* Deleting class instances
* Searching for class instances
* Iterating across class instances

==== Synchronous creation of class instances

To create an instance,
the values of *all* attributes must be supplied.
Attribute values may be supplied explicitly at the point of creation
or by default values or by declaring the attribute to be zero initialized.
(Note that dependent attributes are not initalized since they are
computed by a formula at each access).
All attributes also means that all relationship associations must
be defined at the point of creation.
This insistence insures that there is never any _partially_ initialized
instances floating round in the program.

In Scrall, a synchronous instance creation would appear as:

.Scrall action
----
ac .= *Aircraft(Tail: t, Altitude: a, Heading: h, Location: l, Airspeed:s)
----

This assumes `t`, `a`, `h`, `l`, and `s` are variables with appropriate
values.

The corresponding embedded command is:

.Micca translation
----
<%  Aircraft create ac Tail t Altitude a Heading h Location l Airspeed s %>
----

Note it is not necessary to declare a variable name, `ac`, to hold
the instance reference value.
The `micca` code generator will automatically declare the variable if
needed.

When relationship references must be specified,
this is done using the relationship number and an instance reference
variable.
Note the specification of relationships is _not_ done using the values
of referential attributes.
Rather, the notion is abstracted away from the individual attributes
and the association is expressed in terms of the number of the relationship
and a reference to the related instance.
In this case the action language might appear as:

.Scrall action
----
v .= *Owned Vehicle( License number:l ) &R1 me
----

.Micca translation
----
<%  Owned_Vehicle create License_number l R1 self   %>
----

Note that the requirement to supply instance references at creation
time to satisfy the referential attribute values will impose an order
to instance creation in certain cases.
For example,
classes related across a generalization relationship must be created
in supertype to subtype order since the subtype instance must have
an instance reference to its related supertype instance to satisfy
the referential integrity.
So, if there were class definitions such as:

.Micca class definition
----
class Lamp {
    attribute Manufacturer {char[32]}
    attribute Model ModelType_t
}
class Table_Lamp {
    attribute Height unsigned
}
class Desk_Lamp {
    attribute Wattage unsigned
}

generalization R22 Lamp Table_Lamp Desk_Lamp
----

Then creating an instance of a *Desk_Lamp* requires creating an
instance of *Lamp* and that must be done first.

.Micca translation
----
<%  Lamp create lamp Manufacturer {"Edison"} Model L100     %>
<%  Desk_Lamp create dlamp Wattage 100 R22 lamp             %>
----

Also note in the `micca create` command,
the order of attributes and relationship names does not matter.

==== Asynchronous creation of class instances

.Scrall action
----
New folder(Parent: parent id) -> *Folder
----

.Micca translation
----
<%  Folder createasync New_folder {Parent parent_id}        %>
----

==== Searching for class instances

`Micca` provides two embedded commands to locate class instances,
`findByName` and `findWhere`.

The first command, `findByName` is rather specialized.
When the initial instance population is defined,
each initial instance is given a _name_.
That name is used to handle relationship associations in the
inital instances and stands for an instance reference.
It can do the same at run time.
For example,
if there is a single instance of some class named, `singleton`,
the you can directly reference using `findByName`.

.Micca translation
----
<%  Schedule findByName singleton theSchedule       %>
----

This will result in an instance reference to the `singleton` instance
of the `Schedule` class being place in the ``C'' variable called,
`theSchedule`.
So if you know by context that you want a particular instance that
was defined in the initial instance population,
the `findByName` command will obtain is by direct means without any
searching.

A more general search is obtained using the `findWhere` command.

.Scrall action
----
airports in my country .= Airport(1, Country : my country)
----

.Micca translation
----
<%  Airport findWhere airports_in_my_country\
        {strcmp(airports_in_my_country->Country, my_country) == 0}       %>
----

This translation assumes that the `Country` attribute is a string
and the `my_country` variable points to a string.
So `strcmp()` is used to make the comparison.
The `findWhere` command sequentially searchs the instances of the
class assigning a reference to the instance variable and evaluating
the condition.
It stops when it finds the first match and the instance reference will
be `NULL` if no match is found.

* types of model level actions
  ** actions associated with instances
  ** actions associated with relationships
  *** navigating
  *** subtype migration
  ** actions associated with state machines
  ** instance sets
  ** operations
  *** domain operations
  *** instance operations
  *** class operations
  ** external entities



// vim:syntax=asciidoc:

Changes to micca/doc/howto/syntax.txt.

1
2
3






4



































































































































































































































































































5
== Syntax considerations
Syntax considerations











































































































































































































































































































// vim:syntax=asciidoc:

<

>
>
>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

1

2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
== Syntax considerations


Before you can start composing the domain specification for `micca`,
you need to understand the syntax of the DSL used.
The `micca` DSL syntax is documented in the manual pages for `micca`.
The easiest way to obtain the man pages is to request `micca`
for the documentation.
Executing the command:

----
micca -doc
----

causes `micca` to place a copy of the man pages in a sub-directory of the
current directory called, `miccadoc` footnote:[The `micca` executable
contains a number of files that can be copied out.
This insures the files are consistent with the version of `micca`
you are running].
The man pages are in HTML which your favorite browser can render.
In this section,
we discuss some of the syntax of the DSL used to describe an XUML
domain.
This section is _not_ a detailed enumeration of the commands,
the man pages provide the ultimate reference for the DSL.
Rather,
our intention here is to give you a broad overview and a few tips and
hints for the `micca` DSL.

`Micca` is written in the
http://www.tcl-lang.org[Tcl]
programming language.
Tcl is a command-oriented language,
similar in some ways to a command shell language that you might use to run
programs from a terminal window.
The features of Tcl make it useful for creating domain specific
languages,
especially those that are intended to appear as declarative specifications.
In fact,
the DSL for `micca` is actually a Tcl script.
`Micca` arranges for the script to be executed in an environment
where when the _commands_ in the script are executed,
the platform specific description of an XUML domain is generated.
Fortunately,
little knowledge Tcl syntax is required to work with `micca` and
we cover the points that you need below.

Like many other command-oriented languages,
Tcl syntax is concerned with spliting up a command line into _words_.
Tcl semantics are entirely tied up in the execution of the commands.
Tcl syntax deals with the way a command is split up into words.
Word splitting is done based on whitespace.
The first word is taken as the command and the remaining words
are passed as arguments to the command.
This is similar to languages such as the Unix shell.
Also similar to other command languages,
quoting syntax is used to embed whitespace into an argument.
When whitespace characters are required to be embedded in an command
argument,
the entire argument is quoted.
There are only
http://www.tcl-lang.org/man/tcl8.6/TclCmd/Tcl.htm[twelve rules of syntax]
for Tcl.
For our purposes using `micca`,
you only need a few and you can pick up what you need to know
by reading the examples given here.
There are many commands in the Tcl language,
but you will only need the ones given in the `micca` man pages.
Once you have assimulated a few syntax rules,
you can effectively forget that you are dealing with a larger
programming language.

=== Quoting

Tcl uses braces (`{}`) to quote a string and prevent it from being
parsed into words and otherwise interpreted.
Everything from the open brace to its _matching_ close brace is considered
a single argument and the brace characters themselves are discarded.

To describe a domain using the micca DSL, you use the `domain` command.

.Domain command example
==============
----
domain atc {
    # A set of commands that are used to describe an XUML domain.
}
----
==============

In this example,
`domain` is a command and `atc` is the name of the domain we wish
to specify.
A domain is defined by a script of other commands and in this case
that script is contained with braces.
All the characters between the braces (minus the brace characters themselves)
are considered as one argument to the `domain` command.
So, the `domain` command takes three arguments.

Extending the above example,
we can include the `class` command, which is used to define
an XUML class.

.Class command example
==============
----
domain atc {
    # A set of commands that are used to describe an XUML domain.

    # Define a class
    class Controller {
        # A set of commands that describe the characteristics of a class.
    }
}
----
==============

So, the `class` command can be used as part of the `domain` script.
The `class` command takes an argument that is the name of the class and also
takes a script of commands to define the characteristics of the class.
Note, the braces used to define the boundary of the `class` command
script do _not_ affect the determination of the `domain` command
argument.
This is because the `class` script braces are _matched_, _i.e._ occur
as a open brace (`{`) followed, at some point, by a closed brace (`}`).

=== Quoting hell

At some point you may find a `micca` script being rejected with
an error that makes it appear as if nothing is working.
Often the reason has to do with quoting.
This is sometimes referred to as _quoting hell_ since it can be
bothersome to find the minor syntax error that sets things right.
Matching braces is a good first place to look for finding such mistakes.
Text editors usually support some notion of finding a matching brace.

=== Comments

Comments in Tcl have a quirk to them.
The comment character is the hash (`#`) character.
The hash and all the remaining characters on the line are discarded.
The quirk is that the hash character must come at a point where
the beginning of a command word is expected.
In practice,
it boils down to a few rules:

. Comments on a line by themselves, with only whitespace preceding the
    hash character operate as you would expect, _i.e._ the entire line
    is discarded.
. Comments after a command on the same line must be preceded by a
    semicolon (`;`). The semicolon is a command separator (as is a new line).
. Comments that contain unmatched braces must precede the unmatched
    brace character with a backslash escape (`\`).

The following example shows the cases.

.Comment example
==============
[source,tcl]
----
# This is a typical comment on a line by itself.

puts "my name is fred" ; # If there is a command on the same line, use a semicolon.

# This comment contains an umatched open brace, \{
----
==============

=== Commenting out commands

Commenting out code using the usual comment characters is somewhat
problematic because of the quirky nature of Tcl comments.
The best approach, if you feel you must comment out some code,
is to surround the section with an always false `if` command.

.Commenting out commands example
==============
[source,tcl]
----
if 0 {
    # Any thing in the enclosing braces is not interpreted.
    # Make sure that all the braces inside the if are matched.

    # For example, here the Motor class definition is not interpreted.
    class Motor {
        # Motor definition commands.
    }
}
----
==============


=== Line continuation

Command in Tcl are separated by either newline characters or
by semicolons.
Usually, a single logical command is simply placed on a line by itself.
If the command is longer than you want for a physical line,
then a logical command can be continued onto the next line by
ending the line with a backslash character (`\`).
The backslash character must be immediately followed by the newline
character for the line continuation to have affect.
The result is that the backslash character, newline character and
any leading whitespace on the following line are replaced with a single
space.

In the following example,
the `attribute` command is split over three lines, using two line
continuations.

.Line continuation example
==============
[source,tcl]
----
class Motor {
    attribute\
        Manufacturer int\
        Model int
}
----
==============


=== Special characters in Tcl and C

Part of the specification of a domain includes ``C'' code for the
activities of the domain.
That ``C'' code is specified in the domain configuration and passed
along to the output and eventually to the ``C'' compiler.
Both Tcl and ``C'' treat some characters as special.
The double quotes character (`"`) and brackets (`[]`) have meaning
both for Tcl and for ``C''.
Since Tcl examines any text first,
if you want to pass quotes or brackets on to the ``C'' compiler,
they must be enclosed in braces.
For example,
if a class has an attribute that is a string,
it might be defined as:

.Special characters example
==============
----
domain pump {
    class Model {
        attribute Model_Name {char[25]}
        # ... other class commands
    }
}
----
==============

The `attribute` command specifies a class attribute.
Here, we define an attribute called, `Model_Name`, and give its ``C''
data type name as `char[25]` (a 25 byte character array).
Notice that the data type specification is in braces to prevent
`micca` from interpreting the bracket characters.
Should you get an error to the effect of, ``unknown command: 25'',
you can look for bracket characters not surrounded by braces
(in Tcl, brackets are used for command nesting).

Similarly,
if you were defining an instance of the `Model` class for the initial
instance population you might specify:

.Double quoted characters example
==============
----
population pump {
    class Model {
        instance ar-model Model_Name {"ar-27-np"}
        # ... other population commands
    }
}
----
==============

Note in this case,
we want to define a `Model` instance with the name, `"ar-27-np"`.
It is important that the quote characters get to the ``C'' compiler
since that has a specific meaning in declaring a string literal.
However,
double quotes are meaningful to `micca` and so it is necessary to
enclose the value of the `Model_Name` attribute in braces.
A good rule of thumb is to enclose in brackets anything you want to make sure
gets all the way through to the ``C'' compiler untouched.

=== Other Tcl commands

Since a `micca` description of an XUML domain is actually a Tcl script,
you do have the entire power of the Tcl language available when defining
a domain.
In practice,
that power is seldom, if ever, used.
The `micca` DSL was designed to appear as a declarative specification.
There is really little use for variables or control structures
in describing the semantics of an XUML domain, and
using other Tcl language features is discouraged.
The commands of the DSL are all that are really needed to
describe a domain.


// vim:syntax=asciidoc: