Package micca 1.1.6
Meta category    Model Translation
Meta description The micca package is an XUML translation scheme written
Meta description in Tcl.
Meta entrysource micca.tcl
Meta included    micca.tcl typename/typeparser.tcl
Meta platform    tcl
Meta require     logger

Package micca 1.1.7
Meta category    Model Translation
Meta description The micca package is an XUML translation scheme written
Meta description in Tcl.
Meta entrysource micca.tcl
Meta included    micca.tcl typename/typeparser.tcl
Meta platform    tcl
Meta require     logger

[vset version 1.1.6]
[manpage_begin micca-DSL n [vset version]]
[comment {
# This software is copyrighted 2015 - 2019 by G. Andrew Mangogna.
# The following terms apply to all files associated with the software unless
# explicitly disclaimed in individual files.
# 
# The authors hereby grant permission to use, copy, modify, distribute,

[vset version 1.1.7]
[manpage_begin micca-DSL n [vset version]]
[comment {
# This software is copyrighted 2015 - 2019 by G. Andrew Mangogna.
# The following terms apply to all files associated with the software unless
# explicitly disclaimed in individual files.
# 
# The authors hereby grant permission to use, copy, modify, distribute,

[vset version 1.1.6]
[manpage_begin micca-Embedded n [vset version]]
[comment {
# This software is copyrighted 2015 - 2019 by G. Andrew Mangogna.
# The following terms apply to all files associated with the software unless
# explicitly disclaimed in individual files.
# 
# The authors hereby grant permission to use, copy, modify, distribute,

[vset version 1.1.7]
[manpage_begin micca-Embedded n [vset version]]
[comment {
# This software is copyrighted 2015 - 2019 by G. Andrew Mangogna.
# The following terms apply to all files associated with the software unless
# explicitly disclaimed in individual files.
# 
# The authors hereby grant permission to use, copy, modify, distribute,

[vset version 1.1.6]
[manpage_begin micca 1 [vset version]]
[comment {
# This software is copyrighted 2015 - 2019 by G. Andrew Mangogna.
# The following terms apply to all files associated with the software unless
# explicitly disclaimed in individual files.
# 
# The authors hereby grant permission to use, copy, modify, distribute,

[vset version 1.1.7]
[manpage_begin micca 1 [vset version]]
[comment {
# This software is copyrighted 2015 - 2019 by G. Andrew Mangogna.
# The following terms apply to all files associated with the software unless
# explicitly disclaimed in individual files.
# 
# The authors hereby grant permission to use, copy, modify, distribute,

[vset version 1.1.6]
[manpage_begin portal 3 [vset version]]
[comment {
# This software is copyrighted 2015 - 2019 by G. Andrew Mangogna.
# The following terms apply to all files associated with the software unless
# explicitly disclaimed in individual files.
# 
# The authors hereby grant permission to use, copy, modify, distribute,

[vset version 1.1.7]
[manpage_begin portal 3 [vset version]]
[comment {
# This software is copyrighted 2015 - 2019 by G. Andrew Mangogna.
# The following terms apply to all files associated with the software unless
# explicitly disclaimed in individual files.
# 
# The authors hereby grant permission to use, copy, modify, distribute,

DOCDIR	= ../doc
TESTDIR = ../tests
PKGDIR	= ../../packages
MODULEDIR = ../../modules
IMAGEDIR = ./images
CODEDIR	= ../code

VERSION=1.1.6

vpath %.pdf $(DOCDIR)
vpath %.html $(DOCDIR)
vpath %.test $(TESTDIR)
vpath %.uxf $(IMAGEDIR)

DOCSRC 	=\
................................................................................
$(CODEDIR)/tcl/micca_main.tcl : $(DOCSRC) $(DOCPARTS)
	atangle $(ATANGLEOPTS) -root $(notdir $@) -output $@ $(DOCSRC)

$(DOCDIR)/%.pdf : %.aweb
	a2x $(A2XOPTS) --doctype=book  --format=pdf\
	    --destination-dir=$(DOCDIR)\
	    $(ASCIIDOC_OPTS) $(DBLATEX_OPTS) $<
	$(RM) $(DOCDIR)/*__[0-9].pdf

%.test : %.aweb
	atangle $(ATANGLEOPTS) -root $(notdir $@) -output $(TESTDIR)/$@ $<

$(IMAGEDIR)/platform-%.pdf : platform-%.uxf
	umlet -action=convert -format=pdf\


		-filename=$< -output=$(basename $@)-cvt
	pdftk $(basename $@)-cvt.pdf cat 1left output $@
	$(RM) $(basename $@)-cvt.pdf

$(IMAGEDIR)/%-translation.pdf : %-translation.uxf
	umlet -action=convert -format=pdf\


		-filename=$< -output=$(basename $@)-cvt
	pdftk $(basename $@)-cvt.pdf cat 1left output $@
	$(RM) $(basename $@)-cvt.pdf

$(IMAGEDIR)/%.pdf : %.uxf
	umlet -action=convert -format=pdf\
		-filename=$< -output=$(basename $@)

$(MANSRC) : $(DOCSRC)
	atangle $(ATANGLEOPTS) -root $(notdir $@) -output $@ $<

DOCDIR	= ../doc
TESTDIR = ../tests
PKGDIR	= ../../packages
MODULEDIR = ../../modules
IMAGEDIR = ./images
CODEDIR	= ../code

VERSION=1.1.7

vpath %.pdf $(DOCDIR)
vpath %.html $(DOCDIR)
vpath %.test $(TESTDIR)
vpath %.uxf $(IMAGEDIR)

DOCSRC 	=\
................................................................................
$(CODEDIR)/tcl/micca_main.tcl : $(DOCSRC) $(DOCPARTS)
	atangle $(ATANGLEOPTS) -root $(notdir $@) -output $@ $(DOCSRC)

$(DOCDIR)/%.pdf : %.aweb
	a2x $(A2XOPTS) --doctype=book  --format=pdf\
	    --destination-dir=$(DOCDIR)\
	    $(ASCIIDOC_OPTS) $(DBLATEX_OPTS) $<
	$(RM) $(DOCDIR)/*__[0-9].*

%.test : %.aweb
	atangle $(ATANGLEOPTS) -root $(notdir $@) -output $(TESTDIR)/$@ $<

$(IMAGEDIR)/platform-%.pdf : platform-%.uxf
	umlet -action=convert -format=pdf\
		-filename=$< -output=$(basename $@)
	#umlet -action=convert -format=pdf\
	#	-filename=$< -output=$(basename $@)-cvt
	#pdftk $(basename $@)-cvt.pdf cat 1left output $@
	#$(RM) $(basename $@)-cvt.pdf

$(IMAGEDIR)/%-translation.pdf : %-translation.uxf
	umlet -action=convert -format=pdf\
		-filename=$< -output=$(basename $@)
	#umlet -action=convert -format=pdf\
	#	-filename=$< -output=$(basename $@)-cvt
	#pdftk $(basename $@)-cvt.pdf cat 1left output $@
	#$(RM) $(basename $@)-cvt.pdf

$(IMAGEDIR)/%.pdf : %.uxf
	umlet -action=convert -format=pdf\
		-filename=$< -output=$(basename $@)

$(MANSRC) : $(DOCSRC)
	atangle $(ATANGLEOPTS) -root $(notdir $@) -output $@ $<

# terms specified in this license.
----

=== Version Information

----
<<version info>>=
Micca version: 1.1.6
----

=== Edit Warning

----
<<edit warning>>=
# DO NOT EDIT THIS FILE!
................................................................................
    domain micca {
        <<micca configuration>>
    }
}
rosea generate micca

namespace eval ::micca {
    variable version 1.1.6

    <<logger setup>>

    <<tclral imports>>
    namespace import ::ral::relvar

    <<micca constraints>>

# terms specified in this license.
----

=== Version Information

----
<<version info>>=
Micca version: 1.1.7
----

=== Edit Warning

----
<<edit warning>>=
# DO NOT EDIT THIS FILE!
................................................................................
    domain micca {
        <<micca configuration>>
    }
}
rosea generate micca

namespace eval ::micca {
    variable version 1.1.7

    <<logger setup>>

    <<tclral imports>>
    namespace import ::ral::relvar

    <<micca constraints>>

with those considerations here to focus on how the model is
translated into the implementation code using `micca`.

=== Translation Overview

To translate an XUML model using `micca`,
the model is encoded in a domain specific language.
You may draw the model in your favorite tool.
This example was done using http://www.umlet.com[UMLet]
as a drawing tool.
For this translation, we choose to keep the domain description
in one file and an initial instance population in another file.
This is a common way to be able to provide several different populations
to the same domain,
an important consideration for testing and deployment.

In the file for the domain,
we use the `domain` command to specify the details of the model.

[source,tcl]
----
<<wmctrl.micca>>=

with those considerations here to focus on how the model is
translated into the implementation code using `micca`.

=== Translation Overview

To translate an XUML model using `micca`,
the model is encoded in a domain specific language.
You may draw the model with your favorite UML drawing tool.
This example was done using http://www.umlet.com[UMLet]
as a drawing tool.
For this translation, we choose to keep the domain description
in one file and an initial instance population in another file.
This is a common way to be able to provide several different populations
to the same domain,
an important consideration for keeping testing and deployment separate.

In the file for the domain,
we use the `domain` command to specify the details of the model.

[source,tcl]
----
<<wmctrl.micca>>=

The counter is reset back to zero after each activity's code is generated
in order to have consistent symbol names in the generated code.

[source,tcl]
----
<<generation support data>>=
variable symcounter 0

----

Looking up a symbol returns a dictionary of the symbol attributes.

[source,tcl]
----
<<generation support commands>>=
................................................................................
}

proc CreateTempSymbol {args} {
    set name [CreateTempSymbolName]
    InsertSymbol Name $name {*}$args
    return $name
}





----

Again, we specialize the creation procedure for the variable types
commonly used in code generation.

[source,tcl]
----
................................................................................
            string map [list \" {}] ~ |
            join ~
        }] ; # <1>
        return "#error \"$msg\"\n" ; <2>
    } finally {
        relvar set Symbol [relation emptyof [relvar set Symbol]]
        variable symcounter 0

    }
}
----
<1> Preparing a message suitable for `#error` from the error result.
<2> We place a `#error` statement in the code to make sure it
will not compile.

................................................................................
[source,tcl]
----
<<generation support commands>>=
proc InstanceFindRelatedWhere {startref instref where args} {
    set startlevel [GetBlock]
    set where [string trim $where]
    set endref [CreateTempSymbolName]


    set chaincode [TraverseRelChain $startref $endref $args]
    set endsym [LookUpSymbol $endref]

    append chaincode [IndentToBlock [string cat\
        "$instref = $endref ;\n"\
        "if ($where) \{\n"\
    ]]
    PushBlock

    append chaincode [IndentToBlock "break ;\n"]
    PopBlock

    append chaincode [IndentToBlock "\} else \{\n"]
    PushBlock

    append chaincode [IndentToBlock "$instref = NULL ;\n"]

    set depth [expr {[GetBlock] - $startlevel}]
    for {set i 0} {$i < $depth} {incr i} {
        PopBlock
        append chaincode [IndentToBlock "\}\n"]
    }


    set result [IndentToBlock [string cat\
        [linecomment "instance $startref findRelatedWhere\
                $instref [list [string trim $where]] $args"]\
        [CreateInstRefSymbol [dict get $endsym Class] $instref]\
        "$instref = NULL ;\n"\
    ]]

    return [append result $chaincode]
}
----







ifdef::showtests[]
[source,tcl]
----
<<generate command tests>>=
test codegen-63.0 {
    Generated code file to select related instance
................................................................................
            t__T2 = t__T2->next ;
            struct Z *t__T4 = t__T3->R2__BACK ; // ~R2
            if (t__T4 != NULL) {
                struct Z *t__T1 ;
                t__T1 = t__T4 ;
                zref = t__T1 ;
                if (zref->pressure == 42) {
                    break ;
                } else {
                    zref = NULL ;
                }
            }
        }




















































































































































































    }
} -result {1}
----
endif::showtests[]

==== Finding a Single Related Instance

................................................................................
            mrt_InstSetInitialize(&zset, &codegen48__CLASSES[2]) ;
            for (MRT_LinkRef *t__T2 = mrtLinkRefBegin(&xref->R1__BACK) ; t__T2 != mrtLinkRefEnd(&xref->R1__BACK) ;) {
                struct Y *t__T3 = (struct Y *)((uintptr_t)t__T2 - offsetof(struct Y, R1__BLINKS)) ;
                t__T2 = t__T2->next ;
                struct Z *t__T4 = t__T3->R2__BACK ; // ~R2
                if (t__T4 != NULL) {
                    struct Z *t__T1 ;

































































                    t__T1 = t__T4 ;
                    mrt_InstSetAddInstance(&zset, t__T1) ;
                }
            }
        }]}
} -result {1}
----

The counter is reset back to zero after each activity's code is generated
in order to have consistent symbol names in the generated code.

[source,tcl]
----
<<generation support data>>=
variable symcounter 0
variable labelcounter 0
----

Looking up a symbol returns a dictionary of the symbol attributes.

[source,tcl]
----
<<generation support commands>>=
................................................................................
}

proc CreateTempSymbol {args} {
    set name [CreateTempSymbolName]
    InsertSymbol Name $name {*}$args
    return $name
}

proc CreateLabelName {} {
    variable labelcounter
    return l__L[incr labelcounter]
}
----

Again, we specialize the creation procedure for the variable types
commonly used in code generation.

[source,tcl]
----
................................................................................
            string map [list \" {}] ~ |
            join ~
        }] ; # <1>
        return "#error \"$msg\"\n" ; <2>
    } finally {
        relvar set Symbol [relation emptyof [relvar set Symbol]]
        variable symcounter 0
        variable labelcounter 0
    }
}
----
<1> Preparing a message suitable for `#error` from the error result.
<2> We place a `#error` statement in the code to make sure it
will not compile.

................................................................................
[source,tcl]
----
<<generation support commands>>=
proc InstanceFindRelatedWhere {startref instref where args} {
    set startlevel [GetBlock]
    set where [string trim $where]
    set endref [CreateTempSymbolName]
    set endlabel [CreateLabelName]

    set chaincode [TraverseRelChain $startref $endref $args]
    set endsym [LookUpSymbol $endref]

    append chaincode [IndentToBlock [string cat\
        "$instref = $endref ;\n"\
        "if ($where) \{\n"\
    ]]
    PushBlock

    append chaincode [IndentToBlock "goto $endlabel ;\n"] ; # <1>
    PopBlock

    append chaincode [IndentToBlock "\} else \{\n"]
    PushBlock

    append chaincode [IndentToBlock "$instref = NULL ;\n"]

    set depth [expr {[GetBlock] - $startlevel}]
    for {set i 0} {$i < $depth} {incr i} {
        PopBlock
        append chaincode [IndentToBlock "\}\n"]
    }
    append chaincode [IndentToBlock "${endlabel}: ;\n"] ;   # <2>

    set result [IndentToBlock [string cat\
        [linecomment "instance $startref findRelatedWhere\
                $instref [list [string trim $where]] $args"]\
        [CreateInstRefSymbol [dict get $endsym Class] $instref]\
        "$instref = NULL ;\n"\
    ]]

    return [append result $chaincode]
}
----
<1> We use a naked `goto` here because we may be many levels deep
in a loop to accomplish the relationships chain traversal.
Alternatively, we might be traversing a singular relationships.
The `goto` works for all the cases.
<2> The semi-colon is necessary because a `goto` must label
a statement.

ifdef::showtests[]
[source,tcl]
----
<<generate command tests>>=
test codegen-63.0 {
    Generated code file to select related instance
................................................................................
            t__T2 = t__T2->next ;
            struct Z *t__T4 = t__T3->R2__BACK ; // ~R2
            if (t__T4 != NULL) {
                struct Z *t__T1 ;
                t__T1 = t__T4 ;
                zref = t__T1 ;
                if (zref->pressure == 42) {
                    goto l__L1 ;
                } else {
                    zref = NULL ;
                }
            }
        }
        l__L1: ;
    }
} -result {1}
----
endif::showtests[]

ifdef::showtests[]
[source,tcl]
----
<<generate command tests>>=
test codegen-71.0 {
    find related where for a super to sub class traversal
} -setup {
    validateutils genMiccaFile codegen71 {
        domain codegen71 {
            class S {
                attribute size int -default 10
            }
            class A {
                attribute height int -default 5
            }
            class B {
                attribute width int -default 5
            }
            generalization R42 -union S A B
            domainop void findBs {} {
                <% S findByName s1 sref %>
                <% instance sref findRelatedWhere bref {bref->width == 5}\
                        {~R42 B} %>
            }
        }
        population codegen71 {
            class S {
                instance s1
            }
            class B {
                instance b1 R42 s1
            }
        }
    }
} -cleanup {
    micca clear
    validateutils forgetFiles
} -body {
    validateutils compileFiles codegen71.c
    validateutils matchLines codegen71.c {
        struct B *bref ;
        bref = NULL ;
        struct B *t__T2 = &sref->R42.B ; // ~R42 B
        if (t__T2->base__INST.classDesc == &codegen71__CLASSES[2]) {
            struct B *t__T1 ;
            t__T1 = t__T2 ;
            bref = t__T1 ;
            if (bref->width == 5) {
                goto l__L1 ;
            } else {
                bref = NULL ;
            }
        }
        l__L1: ;
    }
} -result {1}
----
endif::showtests[]

ifdef::showtests[]
[source,tcl]
----
<<generate command tests>>=
test codegen-72.0 {
    find related where for simple singular association
} -setup {
    validateutils genMiccaFile codegen72 {
        domain codegen72 {
            class A {
                attribute height int -default 5
            }
            class B {
                attribute width int -default 5
            }
            association R12 A 1--1 B
            domainop void findBs {} {
                <% A findByName a1 aref %>
                <% instance aref findRelatedWhere bref {bref->width == 5} R12 %>
            }
        }
        population codegen72 {
            class A {
                instance a1 R12 b1
            }
            class B {
                instance b1
            }
        }
    }
} -cleanup {
    micca clear
    validateutils forgetFiles
} -body {
    validateutils compileFiles codegen72.c
    validateutils matchLines codegen72.c {
        struct B *bref ;
        bref = NULL ;
        struct B *t__T2 = aref->R12 ; // R12
        struct B *t__T1 ;
        t__T1 = t__T2 ;
        bref = t__T1 ;
        if (bref->width == 5) {
            goto l__L1 ;
        } else {
            bref = NULL ;
        }
        l__L1: ;
    }
} -result {1}
----
endif::showtests[]

ifdef::showtests[]
[source,tcl]
----
<<generate command tests>>=
test codegen-73.0 {
    find related where for multiple and singular chain
} -setup {
    validateutils genMiccaFile codegen73 {
        domain codegen73 {
            class A {
                attribute height int -default 5
            }
            class B {
                attribute width int -default 7
            }
            class C {
                attribute area int -default 10
            }
            association R12 A 1..*--1 B
            association R13 B 1..*--1 C
            domainop void findBs {} {
                <% C findByName c1 cref %>
                <% instance cref findRelatedWhere aref {aref->height == 5} ~R13 ~R12 %>
            }
        }
        population codegen73 {
            class A {
                instance a1 R12 b1
            }
            class B {
                instance b1 R13 c1
            }
            class C {
                instance c1
            }
        }
    }
} -cleanup {
    micca clear
    validateutils forgetFiles
} -body {
    validateutils compileFiles codegen73.c
    validateutils matchLines codegen73.c {
        struct A *aref ;
        aref = NULL ;
        for (MRT_LinkRef *t__T2 = mrtLinkRefBegin(&cref->R13__BACK) ; t__T2 != mrtLinkRefEnd(&cref->R13__BACK) ;) {
            struct B *t__T3 = (struct B *)((uintptr_t)t__T2 - offsetof(struct B, R13__BLINKS)) ;
            t__T2 = t__T2->next ;
            for (MRT_LinkRef *t__T4 = mrtLinkRefBegin(&t__T3->R12__BACK) ; t__T4 != mrtLinkRefEnd(&t__T3->R12__BACK) ;) {
                struct A *t__T5 = (struct A *)((uintptr_t)t__T4 - offsetof(struct A, R12__BLINKS)) ;
                t__T4 = t__T4->next ;
                struct A *t__T1 ;
                t__T1 = t__T5 ;
                aref = t__T1 ;
                if (aref->height == 5) {
                    goto l__L1 ;
                } else {
                    aref = NULL ;
                }
            }
        }
        l__L1: ;
    }
} -result {1}
----
endif::showtests[]

==== Finding a Single Related Instance

................................................................................
            mrt_InstSetInitialize(&zset, &codegen48__CLASSES[2]) ;
            for (MRT_LinkRef *t__T2 = mrtLinkRefBegin(&xref->R1__BACK) ; t__T2 != mrtLinkRefEnd(&xref->R1__BACK) ;) {
                struct Y *t__T3 = (struct Y *)((uintptr_t)t__T2 - offsetof(struct Y, R1__BLINKS)) ;
                t__T2 = t__T2->next ;
                struct Z *t__T4 = t__T3->R2__BACK ; // ~R2
                if (t__T4 != NULL) {
                    struct Z *t__T1 ;
                    t__T1 = t__T4 ;
                    mrt_InstSetAddInstance(&zset, t__T1) ;
                }
            }
        }]}
} -result {1}
----
endif::showtests[]

ifdef::showtests[]
[source,tcl]
----
<<generate command tests>>=
test codegen-74.0 {
    Generated code file to select related instances
} -setup {
    validateutils genMiccaFile codegen74 {
        domain codegen74 {
            class S {
                attribute color int -default 20
            }
            class A {
                attribute temp int -default 30
            }
            class B {
            }
            generalization R1 -union S A B
            class Z {
                attribute pressure int -default 40
            }
            association R2 Z 1..*--1 B
            domainop void find {} {
                <%S findByName s1 sref%>
                <%instance sref selectRelated zset {~R1 B} ~R2%>
            }
        }
        population codegen74 {
            class S {
                instance s1
            }
            class B {
                instance b1 R1 s1
            }
            class Z {
                instance z1 R2 b1 pressure 41
                instance z2 R2 b1 pressure 42
                instance z3 R2 b1 pressure 43
            }
        }
    }
} -cleanup {
    micca clear
    validateutils forgetFiles
} -body {
    validateutils compileFiles codegen74.c
    testConditions\
        {[validateutils matchLines codegen74.c {
            MRT_InstSet zset ;
            mrt_InstSetInitialize(&zset, &codegen74__CLASSES[3]) ;
            struct B *t__T2 = &sref->R1.B ; // ~R1 B
            if (t__T2->base__INST.classDesc == &codegen74__CLASSES[2]) {
                for (MRT_LinkRef *t__T3 = mrtLinkRefBegin(&t__T2->R2__BACK) ; t__T3 != mrtLinkRefEnd(&t__T2->R2__BACK) ;) {
                    struct Z *t__T4 = (struct Z *)((uintptr_t)t__T3 - offsetof(struct Z, R2__BLINKS)) ;
                    t__T3 = t__T3->next ;
                    struct Z *t__T1 ;
                    t__T1 = t__T4 ;
                    mrt_InstSetAddInstance(&zset, t__T1) ;
                }
            }
        }]}
} -result {1}
----

    <authorinitials>GAM</authorinitials>
    <revremark>
        Corrected a problem with the declaration of the storage pool for
        multiple assigners.
        Minor improvements in man page documents.
    </revremark>
  </revision>












</revhistory>

    <authorinitials>GAM</authorinitials>
    <revremark>
        Corrected a problem with the declaration of the storage pool for
        multiple assigners.
        Minor improvements in man page documents.
    </revremark>
  </revision>
  <revision>
    <revnumber>1.1.7</revnumber>
    <date>December 5, 2019</date>
    <authorinitials>GAM</authorinitials>
    <revremark>
	Corrected an error in the generated code for conditional
	relationship traversal. The code assumed
	a loop control structure was generated and used a
	break statement. This was not the case for singular
	relationships.
    </revremark>
  </revision>
</revhistory>

Below is the UML class diagram for the domain subsystem of the platform model.

image::platform-classes.pdf[title="Classes Subsystem Class Diagram"]

A *Class* is composed of *ClassComponent* (*R20*).
There are two types of *ClassComponent* (*R25*).
*PopulatedComponent* are fundamental components whose values can be determine
by population.
*GeneratedComponent* are those that arise because of the design of how
reference information is held.
There are two types of *PopulatedComponent* (*R21).
An *Attribute* is a named, descriptive value of the *Class*.
Attributes come in two types (*R29*).
The value of an *IndependentAttribute* does not depend upon any other
aspect of the  domain and may have a *DefaultValue* (*R22*).
A *DependentAttribute* depends upon other aspects of the domain
and its value can be computed by a formula.
Consequently, you cannot update the value of a *DependentAttribute*.
Dependent attributes are, strictly speaking, redundant, but are used
by models to provide summary information in a more conveniently accessible form.
A *Reference* is used to specify class relationships.
There are three types of *Reference* (*R23*).
An *AssociationReference* is a reference a class makes to realize
a relationship.
................................................................................
references is realized by a *ComplementaryReference*.
A *ComplementaryReference* may also be one of three different types (*R26*).
The types of references fulfill different roles and types of relationships.
A *SingularReference* is used to store a pointer to a single class instance.
An *ArrayReference* holds the references for static associations of
multiplicity greater than one
and a *LinkReference* serves the same role for dynamic associations.
A *LinkReference uses a *LinkContainer* to store pointers for chaining
instances together (*R27*).
A *ComplementaryReference* may also be used in one of two ways (*R28*).
A *ForwardReference* is that reference set originated in a class based
association when traversing the forward direction.
A *BackwardReference* is that reference used when navigating any association
in the reverse direction.

................................................................................
place a pointer variable in the ``C'' structure of the class on the *many* side
and have the value of the pointer match that of a class instance on
the *one* side.

Now lets look at the computation required to navigate this relationship,
first from the many side to the one side and then from the one side to
the many side.
For this discussion we will assume the relationship is unconditional on
both sides.

From the many side,
given a pointer to an *A* instance
we can navigate to the related *B* instance by simply accessing the
structure member that points to the related *B* instance.
When navigating from the one side to the many side,
we will, in general, obtain more than one instance as a result of the
................................................................................
address of the one-side class instance.

Having to perform a search for the one-side to many-side navigation is
somewhat troubling.
If the number of instances of the many-side class is small,
then there is little concern.
If it is larger, then we might explore ways to avoid costs associated
with a straight linear search of the many-side instances.
The search code is also rather inconvenient since we target a statically
typed language.
The function to iterate across the many-side instances looking for
the one-side pointer value has to be specific to that particular relationship
if we are to be strictly type safe and don't want to resort to
extremes of type casting and pointer arithmetic.

Below is the UML class diagram for the domain subsystem of the platform model.

image::platform-classes.pdf[title="Classes Subsystem Class Diagram"]

A *Class* is composed of *ClassComponent* (*R20*).
There are two types of *ClassComponent* (*R25*).
*PopulatedComponent* are fundamental components whose values can be determined
by population.
*GeneratedComponent* are those that arise because of the design of how
reference information is held.
There are two types of *PopulatedComponent* (*R21*).
An *Attribute* is a named, descriptive value of the *Class*.
Attributes come in two types (*R29*).
The value of an *IndependentAttribute* does not depend upon any other
aspect of the  domain and may have a *DefaultValue* (*R22*).
A *DependentAttribute* depends upon other aspects of the domain
and its value is computed by a formula.
Consequently, you cannot update the value of a *DependentAttribute*.
Dependent attributes are, strictly speaking, redundant, but are used
by models to provide summary information in a more conveniently accessible form.
A *Reference* is used to specify class relationships.
There are three types of *Reference* (*R23*).
An *AssociationReference* is a reference a class makes to realize
a relationship.
................................................................................
references is realized by a *ComplementaryReference*.
A *ComplementaryReference* may also be one of three different types (*R26*).
The types of references fulfill different roles and types of relationships.
A *SingularReference* is used to store a pointer to a single class instance.
An *ArrayReference* holds the references for static associations of
multiplicity greater than one
and a *LinkReference* serves the same role for dynamic associations.
A *LinkReference* uses a *LinkContainer* to store pointers for chaining
instances together (*R27*).
A *ComplementaryReference* may also be used in one of two ways (*R28*).
A *ForwardReference* is that reference set originated in a class based
association when traversing the forward direction.
A *BackwardReference* is that reference used when navigating any association
in the reverse direction.

................................................................................
place a pointer variable in the ``C'' structure of the class on the *many* side
and have the value of the pointer match that of a class instance on
the *one* side.

Now lets look at the computation required to navigate this relationship,
first from the many side to the one side and then from the one side to
the many side.
For this discussion,
we will assume the relationship is unconditional on both sides.

From the many side,
given a pointer to an *A* instance
we can navigate to the related *B* instance by simply accessing the
structure member that points to the related *B* instance.
When navigating from the one side to the many side,
we will, in general, obtain more than one instance as a result of the
................................................................................
address of the one-side class instance.

Having to perform a search for the one-side to many-side navigation is
somewhat troubling.
If the number of instances of the many-side class is small,
then there is little concern.
If it is larger, then we might explore ways to avoid costs associated
with a straight sequential` search of the many-side instances.
The search code is also rather inconvenient since we target a statically
typed language.
The function to iterate across the many-side instances looking for
the one-side pointer value has to be specific to that particular relationship
if we are to be strictly type safe and don't want to resort to
extremes of type casting and pointer arithmetic.

Part V on the run-time code has some interesting aspects as to
how referential integrity is enforced.
For those more interested in how platform model data may be queried and
used to generate ``C'' code,
Part VI gives the details of how the embedded macro commands for
domain actions are translated into code.

This book is also a literate program.
See <<literal-programming>> for a description of the literate programming
syntax.
The syntax is not complicated, but you will need to know it
to make much sense of any code sequences in the book.
Being a literate program document means that all the source code for
`micca` is included here.
The `micca` program (and many other components) is built by extracting
the source from the document source.
Including the source code and all the design discussion makes the
text rather long
and skipping around when reading is encouraged.

The next part of the book presents a simple example.
This will give you a general sense of how model translation with
`micca` works.

After the example,
we consider the four major components of `micca`:

. The platform model. This is a complete model of the platform

Part V on the run-time code has some interesting aspects as to
how referential integrity is enforced.
For those more interested in how platform model data may be queried and
used to generate ``C'' code,
Part VI gives the details of how the embedded macro commands for
domain actions are translated into code.

This book is a literate program.
See <<literal-programming>> for a description of the literate programming
syntax.
The syntax is not complicated, but you will need to know it
to make much sense of any code sequences in the book.
Being a literate program document means that all the source code for
`micca` is included here.
The `micca` program (and many other components) is built by extracting
the source from the document source.
Including the source code and all the design discussion makes the
text rather long
and skipping around when reading is encouraged.

Part II of the book presents a simple example.
This will give you a general sense of how model translation with
`micca` works.

After the example,
we consider the four major components of `micca`:

. The platform model. This is a complete model of the platform

`mrtFindInstSlot` searchs for unused instance memory in the memory pool
described by `iab`.
It returns a pointer to the allocated memory if successful and
`NULL` if no memory is available in the class pool.
*****

The allocation algorithm is a simple linear search starting at the last
location that was allocated.

(((micca,Run Time Function,mrtFindInstSlot)))
[source,c]
----
<<mrt static functions>>=
static MRT_Instance *
................................................................................
the "source" instance reference must be one of the subclasses that
participates in the relationship.
The primary reference in a generalization is from subclass instance to
superclass instance.
<2> The "target" instance reference must then be to the superclass of the
generalization.

Finding the participating subclass of the generalization is a linear search
of the subclass roles in the relationship description.

(((micca,Run Time Function,mrtFindRefGenSubclassCode)))
[source,c]
----
<<mrt static functions>>=
static int
................................................................................
=== Reclassifying Subclasses

Generalization relationships represent a disjoint union of the
subclasses.
Because of this property,
we know that there is an unconditional relationship between a subclass
instance and a superclass instance and an unconditional relationship
between a superclass instance and a subclass instance from among all the
subclasses of the generalization.
This situation leads to the concept of a reclassify operation to allow
a related subclass instance to migrate from one subclass to another.
It is a powerful concept to model modal operations in a domain.
The run-time provides a function to accomplish the details.

*****

`mrtFindInstSlot` searchs for unused instance memory in the memory pool
described by `iab`.
It returns a pointer to the allocated memory if successful and
`NULL` if no memory is available in the class pool.
*****

The allocation algorithm is a simple sequential search starting at the last
location that was allocated.

(((micca,Run Time Function,mrtFindInstSlot)))
[source,c]
----
<<mrt static functions>>=
static MRT_Instance *
................................................................................
the "source" instance reference must be one of the subclasses that
participates in the relationship.
The primary reference in a generalization is from subclass instance to
superclass instance.
<2> The "target" instance reference must then be to the superclass of the
generalization.

Finding the participating subclass of the generalization is a sequential search
of the subclass roles in the relationship description.

(((micca,Run Time Function,mrtFindRefGenSubclassCode)))
[source,c]
----
<<mrt static functions>>=
static int
................................................................................
=== Reclassifying Subclasses

Generalization relationships represent a disjoint union of the
subclasses.
Because of this property,
we know that there is an unconditional relationship between a subclass
instance and a superclass instance and an unconditional relationship
between a superclass instance and exactly one subclass instance from among all the
subclasses of the generalization.
This situation leads to the concept of a reclassify operation to allow
a related subclass instance to migrate from one subclass to another.
It is a powerful concept to model modal operations in a domain.
The run-time provides a function to accomplish the details.

*****