Check-in [a3d130ad8e]
Not logged in

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

Overview
Comment:Checkpoint on how to translate with micca document.
Timelines: family | ancestors | descendants | both | micca-develop
Files: files | file ages | folders
SHA1:a3d130ad8ea4038e3a9d216d14b957cc08766e0a
User & Date: andrewm 2019-03-14 16:09:34
Context
2019-03-15
15:59
Checkpoint on how to translate with micca document. check-in: d6f2378197 user: andrewm tags: micca-develop
2019-03-14
16:09
Checkpoint on how to translate with micca document. check-in: a3d130ad8e user: andrewm tags: micca-develop
2019-03-13
16:59
Checkpoint on the how to translate with micca document. check-in: bc5f85b499 user: andrewm tags: micca-develop
Changes

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

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
..
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
...
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
...
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
...
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
...
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
...
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
...
460
461
462
463
464
465
466










































































467










































































































































































468











469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
...
528
529
530
531
532
533
534
535






536























































































































537
    #       eentity
    #       typealias
    #       interface
    #       prologue
    #       epilogue

    class Controller {
        # Class commands define the implementation classes.
        # These are:
        #       attribute
        #       classop
        #       instop
        #       statemodel
        #       polymorphic
        #       constructor
................................................................................
`Micca` assumes that all domain data is held in the primary memory of
a processor and, consequently, the memory is directly addressable.
This is a common situation, but it is important to emphasize that
there is no assumption of secondary storage such as a disk drive
and no presumed persistance as might be provided by a database
management system.
The execution architecture provide by `micca` is _not_ targeted
at the class of applications which would require external data storage.

`Micca` also insists that the maximum number of instances of each class
is defined at compile time.
The `micca` run-time does no dynamic memory allocation
from a system heap, _i.e._ there are no calls to `malloc()`.
Each class has its own pool of memory where instances are either part of
the initial instance population or are created at run-time.
The memory pool is declared as a ``C'' variable of array type.
Initial instances differ from dynamically created instances by
providing initial values for each attribute.
The memory pool for a class 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.

The most important concepts about how data is structured by `micca` are:

. Each implementation class definition is converted into a ``C'' structure
    definition.
. The instances of a class are stored in an array of structures corresponding
    to the implementation class definition and the size of the
    array is fixed at compile time.

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,
................................................................................
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 to 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.
Furthermore,
if your application truly makes demands for very large numbers of class
instances,
them you should choose a different target translation platform
than `micca` provides.
................................................................................

. 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 an instance outside of a domain,
    we must know both the class to which the instance belongs and its
    external identifying integer value.
    `Micca` automatically generates pre-processor symbols for this
................................................................................

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 logically different entities
and that distinction must be clear in the translators thinking.
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,
................................................................................
}

Part "1..*" -- "1" "Part Description" : R1

@enduml
----

Assume that there is an activity in the model which determines the
the serial numbers of all the *Parts* manufactured by the Acme company.
That activity is a search of the *Part* instances finding those
whose *Manufacturer* attribute equals "Acme".
In this situation,
*Part.Manufacturer* can be eliminated from the platform class,
but *Part Description.Manufacturer* must be retained.
The search must then be coded to navigate the *R1* association
................................................................................
by following the relationship (perhaps multiple relationships) we must
eventually arrive at an identifying attribute value.

So the above situation might be translated as:

----
class Part_Description {
    attribute Manufacturer : {char[25]}
    attribute Model_Number : {char[25]}
    attribute Color : unsigned
}

class Part {
    attribute Serial_Number {char[25]}

    classop MRT_InstSet findByManufacturer {manuf {char const *}} {
    <%  Part instset matchedParts                                       %>
................................................................................
by navigating the *R1* association.
So, no *Manufacturer* attribute is stored in a *Part* and any
time the *Manufacture* attribute value is needed,
it is obtained by navigating the relationship.

=== Translating relationships











































































* no NULLs and the necessity of associative classes










































































































































































* one-to-many associations as composition












=== Populating the data

The final step in translating the data model for a domain is to
specify its population.
Populating the data model consists of specifying _initial instances_
and the amount of storage to allocate for each platform class.
Initial instances are those class instances that exist before the
domain runs.
As dicussed previously,
each platform class has its own storage pool for instances.
In addition to initial instances,
you can specify the number of additional slots to allocate to the
storage pool.
The total number of instances is then the sum of the initial instances
and the number of additional slots allocated for run-time usage.
Note, if an initial instance is deleted at run-time, then
its storage slot becomes available for subsequent use by a run-time
create instance.

It is advisable to keep the population of a domain in a file separate
from its configuration.
As translated domains are tested,
it is convenient to use a variety of different populations
to drive the code execution paths for testing.
`Micca` will read multiple files for a domain, so keeping
test populations separate from production populations is convenient.

The analytical materials supply for translation must include
a population of the data model.
The recommended practice is to supply the population in
tabular notation, one set of class instances per page,
similar to a page in a spreadsheet.
Values for all attributes are supplied.
It is possible to specify the model level population purely by
data values.

The `micca` `population` command is used to define the storage
requirements and any initial instances for the domain.
One of the few command ordering requirements for `micca` is that
the `population` command must follow the domain definition given
by the `domain` command.
The following shows a brief sketch of a population.

.Domain command example
==============
----
population atc {
    # Population commands define the data values in a domain
    # These are:
    #       class
    #       assigner
................................................................................
    }

    # ...
    # and so on, giving the population of the domain
}
----
==============































































































































// vim:syntax=asciidoc:







|







 







|


|



|








|

|


|







 







|







 







|







 







|





|
|







 







|







 







|
|
|







 







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









|







|
|









|








|






|







 








>
>
>
>
>
>

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

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
..
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
...
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
...
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
...
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
...
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
...
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
...
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
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
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
...
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
    #       eentity
    #       typealias
    #       interface
    #       prologue
    #       epilogue

    class Controller {
        # Class commands define the platform classes.
        # These are:
        #       attribute
        #       classop
        #       instop
        #       statemodel
        #       polymorphic
        #       constructor
................................................................................
`Micca` assumes that all domain data is held in the primary memory of
a processor and, consequently, the memory is directly addressable.
This is a common situation, but it is important to emphasize that
there is no assumption of secondary storage such as a disk drive
and no presumed persistance as might be provided by a database
management system.
The execution architecture provide by `micca` is _not_ targeted
at the class of applications which would require secondary data storage.

`Micca` also insists that the maximum number of instances of each class
be defined at compile time.
The `micca` run-time does no dynamic memory allocation
from a system heap, _i.e._ there are no calls to `malloc()`.
Each class has its own pool of memory where instances are either part of
the initial instance population or created at run-time.
The memory pool is declared as a ``C'' variable of array type.
Initial instances differ from dynamically created instances by
providing initial values for each attribute.
The memory pool for a class 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.

The most important concepts about how data is managed by `micca` are:

. Each platform class definition is converted into a ``C'' structure
    definition.
. The instances of a class are stored in an array of structures corresponding
    to the platform class definition and the size of the
    array is fixed at compile time.

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,
................................................................................
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 to 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 or 250 million?
In practice,
the number of instances of a class are typically small.
Furthermore,
if your application truly makes demands for very large numbers of class
instances,
them you should choose a different target translation platform
than `micca` provides.
................................................................................

. 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 identity 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 an instance outside of a domain,
    we must know both the class to which the instance belongs and its
    external identifying integer value.
    `Micca` automatically generates pre-processor symbols for this
................................................................................

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 logically different entities
and that distinction must be clear in a Translator's thinking.
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 XUML data model and
_platform class_ when we are discussing how the `micca` 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,
................................................................................
}

Part "1..*" -- "1" "Part Description" : R1

@enduml
----

Assume that there is an activity in the model which determines
the serial numbers of all the *Parts* manufactured by the Acme company.
That activity is a search of the *Part* instances finding those
whose *Manufacturer* attribute equals "Acme".
In this situation,
*Part.Manufacturer* can be eliminated from the platform class,
but *Part Description.Manufacturer* must be retained.
The search must then be coded to navigate the *R1* association
................................................................................
by following the relationship (perhaps multiple relationships) we must
eventually arrive at an identifying attribute value.

So the above situation might be translated as:

----
class Part_Description {
    attribute Manufacturer {char[25]}
    attribute Model_Number {char[25]}
    attribute Color unsigned
}

class Part {
    attribute Serial_Number {char[25]}

    classop MRT_InstSet findByManufacturer {manuf {char const *}} {
    <%  Part instset matchedParts                                       %>
................................................................................
by navigating the *R1* association.
So, no *Manufacturer* attribute is stored in a *Part* and any
time the *Manufacture* attribute value is needed,
it is obtained by navigating the relationship.

=== Translating relationships

Model relationships represent constraints on the number and conditionality
of how class instances are associated with each other in the real world.
Fundamentally,
the multiplicity and conditionality of a relationship restricts
membership in the underlying set that class instances represent.
In a model,
relationships are realized by referential attributes having values
equal to those of identifying attributes.
Since `micca` supplies a unique identifier for class instances,
those identifiers may be used to realize relationships for
platform classes.

`Micca` supports translating the relationships by:

* Generating data structures and providing operations
  to handle the references for instances that participate in a relationship.
* Verifying at run-time that the constraints implied by the relationship
  are not violated by the execution of domain activities.

==== Translating simple associations

Consider the following model fragment:

["plantuml",title="Simple association"]
----
@startuml
hide methods
hide circle
skinparam class {
    BackgroundColor yellow
    BorderColor black
    LineColor black
    ArrowColor black
}

class Warehouse {
    Name : string            {I}
    Location : MailingAddress
}

class "Warehouse Clerk" as WC {
    Clerk ID : arbitrary ID   {I}
    Clerk Name : Name
    Warehouse : string      {R25}
}

Warehouse "1" -- "1..*" WC : "is employed by\nR25\nemploys"

@enduml
----

This fragment shows an _at least one_ to _one_ association between
a *Warehouse Clerk* and a *Warehouse*.
This situation would be translated as:

----
association R25 Warehouse_Clerk 1..*--1 Warehouse
----

The `association` command defines the characteristics of the
association between classes.
The syntax of the multiplicity and conditionality, _i.e._ **1..*--1**,
is intended to be mnemonic of the notation used in the
XUML class diagram.
Note this argument has no embedded whitespace.

The class which contains the referential attributes appears first
in the command arguments.
This is the _referring_ class.
The other participant is the _referenced_ class.
This distinction will become more important later,
but for now, simple association are always specfied from the
referring class to the referenced class.

==== Translating associative classes

Some associations require an associative class to realize the mapping
between participating instances.
An association class is required for:

* Associations that are _many_ to _many_ in multiplicity.
* Associations that represent partial functions, namely,
  *0..1--0..1*, **0..\*--0..1**, and **1..*--0..1**.
* Associations that have descriptive attributes describing properties
  of the association itself,
  _i.e._ associations with attributes that are not strictly referential.

Instances of the association class correspond directly to instances
of the relationship.
Association class instances directly enumerate the mapping between
the instances sets of the participating classes
To translate an association class,
the `association` command takes an `-associator` option.
Consider the following model fragment:

["plantuml",title="Association class"]
----
@startuml
hide methods
hide circle
skinparam class {
    BackgroundColor yellow
    BorderColor black
    LineColor black
    ArrowColor black
}

class "Product" as P {
    Product ID : UPC
    Product Name : string
}

class "Shopping Cart" as SC {
    Cart ID : arbitrary ID
    Total Value : currency
}

class "Product Selection" as PS {
    Product ID : UPC      {R14}
    Cart ID : arbitrary ID  {R14}
    Quantity : count
}

P "1..*" - "0..*" SC
(P, SC) .. PS : R14
@enduml
----

This association would be translated as:

----
association R14 -associator Product_Selection Product 1..*--0..* Shopping_Cart
----

==== Translating generalizations

Consider the following model fragment:

["plantuml",title="Product generalization"]
----
@startuml
hide methods
hide circle
skinparam class {
    BackgroundColor yellow
    BorderColor black
    LineColor black
    ArrowColor black
}

class "Product" as P {
    Product ID : UPC    {I}
    Name : string
    Unit Price : currency
}

class "Book Product" as BP {
    Product ID : UPC {I,R22}
    Title : string
}

class "Recording Product" as RP {
    Product ID : Universal Product Code {I,R22}
    Run Time : time
}

P <|-- BP : R22
P <|-- RP : R22
@enduml
----

This is a generalization relationship.
In XUML,
a generalization does _not_ represent inheritance.
Rather, it represents a disjoint set partitioning.
Strictly speaking,
the relationship graphic should be annotated with `{complete, disjoint}`, but
since this is the only type of generalization used in XUML, the
annotation is usually dropped as graphical clutter.

This situation would be translated as:

----
generalization R22 Product Book_Product Recording_Product
----

_i.e._ we use the `generalization` command giving the name of the relationship,
the name of the superclass and the names of the subclasses which participate
in the generalization.

`Micca` provides two ways to store instances that participate in a
generalization:

Reference::
  In this technique,
  subclass instances have their own storage pools and a reference
  to the superclass is embedded in the subclass data structure.
  Navigating from subclass to superclass is accomplished by
  de-referencing the superclass reference.
Union::
  In this technique,
  the superclass is defined to contain, as part of its data structure,
  a union of the data structures of the subclass of the generalization.
  There is no separate instance storage pool for the subclasses.
  Navigating from the subclass to the superclass is accomplished by
  pointer arithmetic.

In the previous example,
if we had chosen to implement *R22* in a union,
we would have written:

----
generalization R22 -union Product Book_Product Recording_Product
----

The trade-offs for the two types of storage are:

* Generalizations implemented by reference are applicable to all situations.
  The cost is the memory in the subclass to store the reference to the
  superclass and the memory in the superclass to store a reference
  to the subclass.
  There is a separate memory pool for each subclass and these must be
  allocated.
  If there are no instances of a particular subclass,
  then its memory pool is not used.
* Generalizations implemented by union save the storage of pointer values.
  The memory pool of the superclass serves as memory for subclass instances.
  However, if there is a large discrepancy in the size of subclass instances,
  then memory may not be as well utilized as in the case of references.

The computation to navigate the relationship is negligible in both cases.

For most generalizations,
the `-union` implementation works well.
There is one case where it cannot be used.
If a subclass is subject to a compound generalization,
_i.e._ a class serves a subclass role in multiple independent
generalizations,
then only one of the generalizations may use the `-union` option
and the others must use `-reference` (which is the default if neither
option is specified).
This situation is rare.

==== Static associations

For associations which are _static_,
_i.e._ the population of relation instances does not change over the
course of running the domain,
the `association` command takes a `-static` option.
This option changes the relationship storage mechanism for
associations with multiplicity greater than one to be
an array of pointers of fixed length.
Normally,
association of multiplicity greater than one use linked lists to
store the references of the relationship.
The `-static` option can reduce memory usage and simplify the code
generated to navigate the relationship toward the _many_ side.

=== Populating the data

The final step in translating the data model for a domain is to
specify its population.
Populating the data model consists of specifying _initial instances_
and the amount of storage to allocate for each platform class.
Initial instances are those class instances that exist before the
domain runs.
As discussed previously,
each platform class has its own storage pool for instances.
In addition to initial instances,
you can specify the number of additional slots to allocate to the
storage pool.
The total number of instances is then the sum of the initial instances
and the number of additional slots allocated for run-time usage.
Note, if an initial instance is deleted at run-time, then
its storage slot becomes available for subsequent use by
an instance created at run-time.

It is advisable to keep the population of a domain in a file separate
from its configuration.
As translated domains are tested,
it is convenient to use a variety of different populations
to drive the code execution paths for testing.
`Micca` will read multiple files for a domain, so keeping
test populations separate from production populations is convenient.

The analytical materials supplied to the translation must include
a population of the data model.
The recommended practice is to supply the population in
tabular notation, one set of class instances per page,
similar to a page in a spreadsheet.
Values for all attributes are supplied.
It is possible to specify the model level population purely by
data values.

The `population` command is used to define the storage
requirements and any initial instances for the domain.
One of the few command ordering requirements for `micca` is that
the `population` command must follow the domain definition given
by the `domain` command.
The following shows a brief sketch of a population.

.Domain population example
==============
----
population atc {
    # Population commands define the data values in a domain
    # These are:
    #       class
    #       assigner
................................................................................
    }

    # ...
    # and so on, giving the population of the domain
}
----
==============

The `population` command takes the name of the domain to be populated
and a script of population commands to specify the characteristics
of the population.
For brevity,
in the following examples we assume the commands are contained in a
`population` script.

=== Initial instance names

Part of the process of defining a population involves not only
specifying values for the attributes but also insuring the
relationship references are specified.
As we have previous discussed,
referential attributes are usually elided from the model class when
formulating the platform class.
We can deduce the relationship references from the model population
by examining the values of the referential attributes and finding
the corresponding values in the other participating class of the
relationship.
But for platform classes,
we are taking a different view of relationship references and
using referential attribute values is not an option open to us.
So,
each initial instance is given a _name_.
Each instance name must be unique within the class of the instance.
The instance name serves as a means of specifying to which instances
relationships refer.
The instance name serves as a surrogate for the referential attribute
values.
So when we specify instances,
the relationship number, _e.g._ *R27*, and the name of an instance
are used to specify which instance are related.

=== Initial instances

`Micca` provides two commands to specify initial instances.
The `instance` command specifies values for a single class instance.
The `table` command specfies multiple instances in a tabular layout.

Referring to a previous example,
assume the analysis model has specified the following initial instance
population.
Here the data is presented in tabullar form and the population is
entirely specified by the data values of the model attributes.

[options="header",cols="3*<",title="Part Description Population",width="50%"]
|===========
|Manufacturer       |Model Number       |Color
|"Acme"             |"S27"              |22
|"Sunshine"         |"B42"              |47
|===========

[options="header",cols="3*<",title="Part Population",width="50%"]
|===========
|Manufacturer       |Model Number       |Serial Number
|"Acme"             |"S27"              |"A001"
|"Acme"             |"S27"              |"A002"
|"Sunshine"         |"B42"              |"B034"
|"Sunshine"         |"B42"              |"B037"
|===========

For the platform classes,
the referential attributes in *Part* were elided.
Remaining are the *Serial_Number* attribute and
the fact that *Part* is the referring class in *R1*.
This situation may be translated as follows.

----
class Part_Description {
    instance screw Manufacturer {"Acme"} Model_Number {"A27"} Color 22
    instance bolt Manufacturer {"Sunshine"} Model_Number {"S42"} Color 47
}

class Part {
    table       {Serial_Number  R1}\
    s1          {"A001"       screw}\
    s2          {"A002"       screw}\
    b1          {"B034"       bolt}\
    b30         {"B037"       bolt}
}
----

Here we have chosen to use the `instance` command for populating
the Part_Description class and the `table` command for the Part class.
Note that the referential attributes in the model class
(_i.e._ *Manufacturer* and *Model Number*)
have been replaced by specifying that *R1* is satisfied by referencing
the *screw* or *bolt* named instances from *Part_Description*.

=== Class storage allocation

The `allocate` command is use to specify an additional number of class
instance storage slots.
The total number of instances for a given class is the number of
initial instances plus the number given in the `allocate` command.

For the previous example,
we can allocate 10 additional instances memory slots for the
*Part_Description* class as follows:

----
class Part_Description {
    instance screw Manufacturer Acme Model_Number A27 Color red
    instance bolt Manufacturer Sunshine Model_Number S42 Color blue

    allocate 10
}
----

The maximum number of *Part_Description* instances that can exist
simultaneously is 12, two defined as initial instances and 10 allocated
for run-time creation.
Note, that at run time, there is no distinction between initial instances
and unallocated instances.
So, deleting an instance that was specified as an initial instance
makes its memory available to be used to create an instance at run-time.

=== Populating associative classes
Populating associative classes

=== Populating associative classes in reflexive relationships
Populating associative classes in reflexive relationships




// vim:syntax=asciidoc:

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

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
..
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
...
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
...
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
...
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
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''.
................................................................................
The Translator is a human being.
The material transferred (as indicated by the dashed line in the figure)
is a set of diagrams and text which we
discuss <<model-contents,below>>.
Note that no machine readable content is transferred directly to the
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,
code is generated for the domain.
The code consists of a ``C'' source file and a ``C'' header file.

The source files for all the domains in the system,
along with any bridge code or other conventionally realized code
files are then compiled and linked together to form an executable
for the program.


Also supplied to the build process is the run-time code required
by `micca`.
Much of the code generated by `micca` depends upon or drives
the operation of its run-time code.
For example,
the state machine dispatch that sequences the lifecycles of class instances
is implemented in the run-time code and driven by data supplied in the
domain ``C'' source code.
We do *not* describe here how `micca` or its run-time code operate.

`Micca` and the run-time are fully described
http://repos.modelrealization.com/cgi-bin/fossil/mrtools/wiki?name=MiccaPage[elsewhere].




There are several points of interest in this workflow.

* The tooling for the analysis is completely separated from that of the
  translation.
  Ideally, it would be more convenient to automate the translation
  process by eliminating the human translator.
................................................................................
  difficult.
  The solution chosen here is to apply human intelligence to bridge the
  tooling gap.
  We do not consider this any more unusual than applying human
  intelligence to write any other computer program.
* Because a human is involved,
  there are substantial possiblities for tailoring the solution to the
  specfic needs of the target platform.
  This can be quite difficult when attempting the translation with
  generic tooling intented to support a wide array or the lowest common
  denominator of platforms.
* There is substantial amount of the system that is conventionally coded.
  Bridge code is supplied manually.
  Low level operating system or device specific code is usually required to
  interface to the external world.
................................................................................
especially if the person performing the translation
(as is our recommendation)
is not the same person who created the model.

The need for a complete model does *not* imply that the
model has to satisfy every possible requirement that could be envisioned
for the domain.
The necessity for the domain model be complete and self-consistent
does *not* necessarily imply that it is complete in terms
of the services it provides to the system.
Experience shows that models,
like conventional code bases,
benefit from incremental, iterative development.
Call it agile or waterfall or whatever you like,
skilled practitioners of software development do not build systems
in one strictly sequential undertaking.
Development is iterative and the results of one iteration help direct
subsequent efforts.
The usual recommendation is to model core concepts that are central
to the subject matter of the domain and work out from there to more
peripheral concepts.
Of course such recommendations have little to offer in terms of how
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.
We eschew the concept of elaboration,






preferring to view translation as a discontinuous step of taking a logical
statement of a problem and applying computing technology to achieve an
executable solution.
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]]

................................................................................
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.
Rather, a Translator's focus is on formulating clear and concise program
statements to reflect the actions of the model.
Translation concerns are those of the computing platform and not







|







 







|
<
|
|
|







|
|








>
>





|
|
|
|
>


>
>
>







 







|







 







|
|
|




|
|













|
|




|
>
>
>
>
>
>
|







 







>
|
|







|





>







13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
..
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
...
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
...
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
...
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
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 translated 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''.
................................................................................
The Translator is a human being.
The material transferred (as indicated by the dashed line in the figure)
is a set of diagrams and text which we
discuss <<model-contents,below>>.
Note that no machine readable content is transferred directly to the
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 which 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 specific domain elements it
contains.
Using this data,
code is generated for the domain.
The code consists of a ``C'' source file and a ``C'' header file.

The source files for all the domains in the system,
along with any bridge code or other conventionally realized code
files are then compiled and linked together to form an executable
for the program.
This is the conventional way that multiple ``C'' source code files are
built into an executable.
Also supplied to the build process is the run-time code required
by `micca`.
Much of the code generated by `micca` depends upon or drives
the operation of its run-time code.
For example,
the state machine dispatch that sequences the lifecycles of class instances is
implemented in the run-time code and driven by data supplied in the ``C''
source code for a domain.
We do *not* describe here how `micca` or its run-time code operate
in detail.
`Micca` and the run-time are fully described
http://repos.modelrealization.com/cgi-bin/fossil/mrtools/wiki?name=MiccaPage[elsewhere].
In this document,
only an overview of the run-time operation is given to
provide the context required for translating the domain.

There are several points of interest in this workflow.

* The tooling for the analysis is completely separated from that of the
  translation.
  Ideally, it would be more convenient to automate the translation
  process by eliminating the human translator.
................................................................................
  difficult.
  The solution chosen here is to apply human intelligence to bridge the
  tooling gap.
  We do not consider this any more unusual than applying human
  intelligence to write any other computer program.
* Because a human is involved,
  there are substantial possiblities for tailoring the solution to the
  specific needs of the target platform.
  This can be quite difficult when attempting the translation with
  generic tooling intented to support a wide array or the lowest common
  denominator of platforms.
* There is substantial amount of the system that is conventionally coded.
  Bridge code is supplied manually.
  Low level operating system or device specific code is usually required to
  interface to the external world.
................................................................................
especially if the person performing the translation
(as is our recommendation)
is not the same person who created the model.

The need for a complete model does *not* imply that the
model has to satisfy every possible requirement that could be envisioned
for the domain.
The necessity for the domain model be complete and self-consistent does *not*
necessarily imply that it is complete in terms of the requirements allocated by
the system or the services it provides to the system.
Experience shows that models,
like conventional code bases,
benefit from incremental, iterative development.
Call it agile or waterfall or whatever you like,
skilled and effective practitioners of software development do not build
systems in one strictly sequential undertaking.
Development is iterative and the results of one iteration help direct
subsequent efforts.
The usual recommendation is to model core concepts that are central
to the subject matter of the domain and work out from there to more
peripheral concepts.
Of course such recommendations have little to offer in terms of how
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
sizefootnote::[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.
We reject the entire concept of elaboration as corrosive to the
separation of problem logic and implementation technology.
The conflation of incremental model development with
incremental elaboration of model details is especially destructive
to obtaining full value for the modeling effort.
Translation replaces the vague concepts of _high level_ or _low level_
with a more precise notion of platform independent and platform dependent.
We view translation as a discontinuous step of taking a logical
statement of a problem and applying computing technology to achieve an
executable solution.
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]]

................................................................................
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.
Despite the amazing abilities of modern compilers at code optimization,
the compiler is unaware of any intent in the code or any higher
order design in the system as a whole.

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 translation 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.
That job alone is difficult enough.
Consequently,
a Translator tends to pay little attention to the details of
what a domain actually accomplishes.
It is a somewhat rote undertaking.
Rather, a Translator's focus is on formulating clear and concise program
statements to reflect the actions of the model.
Translation concerns are those of the computing platform and not

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

130
131
132
133
134
135
136
















137
138
139
140
141
142
143
...
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
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
................................................................................
==== 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.
    It might be the case that the analyst has included a relationship
    in the model which will be used in a subsequent iteration.
    The relationship can be added easily when it is later used
    by some activity.
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.
    Note that for associations with an associative class, the number of
    instances of the relationship equals the number of instances of the
    associative class.
    For associations realized by referential attibutes in one of the
    participants,
    the number of instances of the relationship equals the number of instances
    of the class that contains the referential attributes.
    The number of instances of a generalization equals the number of instances
    of the class which serves as the superclass of the generalization.
Associations that are partial functions::
    Associations with multiplicity and conditionality of:
    .. 0..1 to 0..1
    .. 0..* to 0..1
    .. 1..* to 0..1

+







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







 







|





<
<
<
<
<
<
<
<
<







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
...
361
362
363
364
365
366
367
368
369
370
371
372
373









374
375
376
377
378
379
380
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.
    For associations with an associative class, the number of
    instances of the relationship equals the number of instances of the
    associative class.
    Creating or deleting an instance of an associative class
    creates or deletes an instance of the relationships the associative
    class realizes.
    For associations realized by referential attibutes in one of the
    participants,
    the number of instances of the relationship equals the number of instances
    of the class that contains the referential attributes.
    Creating or deleting an instance of a class which contains
    referential attributes also modifies the relationship instances.
    The number of instances of a generalization equals the number of instances
    of the class which serves as the superclass of the generalization.
    Migration of the type of a subclass to another type is conceptually
    a delete / create / re-relate operation.
* 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
................................................................................
==== 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.
    It might be the case that the analyst has included a relationship
    in the model which will be used in a subsequent iteration.
    The relationship can be added easily when it is actually used
    by some activity.
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.









Associations that are partial functions::
    Associations with multiplicity and conditionality of:
    .. 0..1 to 0..1
    .. 0..* to 0..1
    .. 1..* to 0..1

+

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

200
201
202
203
204
205
206




207
208
209
210
211
212
213
214
215
216
...
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
The backslash character must be immediately followed by the
newlinefootnote:[We refer the the last character as the _newline_
character. Different environments have different notions of how
the end of an text record is encoded.
Tcl automatically takes these differences into account and we are safe
to think of text records as simply being newline terminated.]
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
==============
................................................................................
}
----
==============

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 braces anything you want to insure
is passed through untouched to the ``C'' compiler.

=== Other Tcl commands







>
>
>
>


|







 







|







200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
...
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
The backslash character must be immediately followed by the
newlinefootnote:[We refer the the last character as the _newline_
character. Different environments have different notions of how
the end of an text record is encoded.
Tcl automatically takes these differences into account and we are safe
to think of text records as simply being newline terminated.]
character for the line continuation to have affect.
Be careful if you text editor inserts arbitrary whitespace at the end
of a line.
Those editors usually have a setting to remove extraneous whitespace
at the end of lines.
The result is that the backslash character, newline character and
any leading whitespace on the following line are replaced with a single
space character.

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

.Line continuation example
==============
................................................................................
}
----
==============

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 they have 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 braces anything you want to insure
is passed through untouched to the ``C'' compiler.

=== Other Tcl commands