11 - Textual representation

The storage format for SDL-RT diagrams follows the XML (eXtensible Markup Language standard from W3C available at http://www.w3.org) standard. There are 3 quite different kind of diagrams that are actually represented differently in the XML:

• "Standard" diagrams, consisting in symbols that can have links between them, with no particular structure associated to them. These diagrams include for example system or block diagrams, deployement diagrams, and so on.
• Behavioral diagrams, which have a specific structure in terms on state blocks and transitions. These diagrams include for example process and procedure diagrams.
• MSC diagrams that have a very specific structure which is very different from all other diagrams.

The following paragraphs describe how each diagram kind is represented, starting with the XML definitions that are common to all diagram kinds.

11.1 - Common XML definitions

<!-- Entity for booleans -->
<!-- =================== -->

<!ENTITY % boolean "(TRUE|FALSE)">


<!-- Entity for language -->
<!-- =================== -->

<!ENTITY % Language "(sdl|sdl-rt|none)">


<!-- Entities for symbol types -->
<!-- ========================= -->

<!ENTITY % sdlSymbolTypes1 "sdlSysDgmFrm|sdlSysTypeDgmFrm|sdlBlkDgmFrm|sdlBlkTypeDgmFrm|sdlBlkType|sdlBlk|sdlBlkTypeInst|sdlPrcsType|sdlPrcs|sdlPrcsTypeInst">
<!ENTITY % sdlSymbolTypes2 "sdlInherits|sdlPrcsTypeDgmFrm|sdlPrcsDgmFrm|sdlPrcdDgmFrm|sdlStart|sdlState|sdlInputSig|sdlSendSig|sdlSaveSig|sdlContSig">
<!ENTITY % sdlSymbolTypes3 "sdlTask|sdlDecision|sdlTransOpt|sdlAnswer|sdlJoin|sdlText|sdlComment|sdlTextExt|sdlCnctrOut|sdlCnctrIn|sdlPrcsCreation|sdlStop|sdlObjCre">
<!ENTITY % sdlSymbolTypes4 "sdlInitTimer|sdlResetTimer|sdlSemDecl|sdlSemTake|sdlSemGive|sdlPrcdProto|sdlPrcdDecl|sdlPrcdCall|sdlPrcdStart|sdlPrcdReturn">
<!ENTITY % sdlSymbolTypes5 "sdlMacroDecl|sdlMacroCall|sdlMacroDgmFrm|sdlMacroInlet|sdlMacroOutlet|sdlPrioInputSig|sdlPrioSendSig|sdlCompState">
<!ENTITY % sdlSymbolTypes6 "sdlCompStateDef|sdlService|sdlCompStateDgmFrm|sdlServDgmFrm|sdlSuperTransitionCall|sdlSuperNextstateCall">
<!ENTITY % sdlSymbolTypes "%sdlSymbolTypes1;|%sdlSymbolTypes2;|%sdlSymbolTypes3;|%sdlSymbolTypes4;|%sdlSymbolTypes5;|%sdlSymbolTypes6;">

<!ENTITY % hmscSymbolTypes "hmscDgmFrm|hmscParallel|hmscStart|hmscEnd|hmscCondition|hmscMscRef|hmscAlternativePoint">

<!ENTITY % umlClassSymbolTypes "umlClassDgmFrm|umlPckg|umlClass|umlComment|umlSys|umlBlkCls|umlBlk|umlPrcsCls|umlPrcs">
<!ENTITY % umlDeplSymbolTypes "umlDeplDgmFrm|umlNode|umlComp|umlFile">
<!ENTITY % umlUCSymbolTypes "umlUCDgmFrm|umlUseCase|umlActor">

<!ENTITY % SymbolType "(%sdlSymbolTypes;|%hmscSymbolTypes;|%umlClassSymbolTypes;|%umlDeplSymbolTypes;|%umlUCSymbolTypes;)">


<!-- Entity for connector types -->
<!-- ========================== -->

<!ENTITY % ConnectorType "(void|chnl|chnlgate|sdlarrow|mscvoid|mscgate|mscarrowgate|hmscarrow|umlcvoid|umlassoc|umlrole|umldvoid)">


<!-- Entity for side for connectors -->
<!-- ============================== -->

<!ENTITY % Side "(n|s|w|e|x|y)">


<!-- Entity for end types for connectors -->
<!-- =================================== -->

<!ENTITY % ConnectorEndType "(voidend|arrow|midarrow|fullarrow|outltri|outldiam|filldiam|outldiamarw|filldiamarw)">


<!-- Entity for link segment orientation -->
<!-- =================================== -->

<!ENTITY % Orientation "(h|v)">


<!-- Entity for link types -->
<!-- ===================== -->

<!ENTITY % LinkType "(sbvoid|dbvoid|ssvoid|dsvoid|chnl|dec|transopt|msg|meth|rtn|instcre|assoc|spec|aggr|comp|cnx|dep)">


<!-- Entity for diagram types -->
<!-- ======================== -->

<!ENTITY % DiagramType "(sys|systype|blk|blktype|prcs|prcstype|prcd|macro|msc|hmsc|mscdoc|class|usec|depl|compstate|service|ifobs)">


<!-- Entity for message parameters visibility -->
<!-- ======================================== -->

<!ENTITY % MsgParamVis "(no|abbr|full)">

11.2 - XML elements for standard diagrams

11.2.1 Principles

The file describes the whole diagram in terms of symbols, links and connectors. A link is subdivided into link segments. Each of these elements have one or several texts.
Here is an example of this organization with a UML class diagram:

11.2.2 XML elements

<!-- Element for text in symbols/links/... -->
<!-- ===================================== -->
<!-- The "hidden" attribute is only used for attributes and operation boxes in UML class diagrams -->

<!ELEMENT Text (#PCDATA)>
<!ATTLIST Text
id CDATA "0"
hidden %boolean; "FALSE"
>


<!-- Element for symbols -->
<!-- =================== -->
<!-- The "Symbol*" component is for contained symbols -->

<!ELEMENT Symbol (Text+, Symbol*)>
<!ATTLIST Symbol
symbolId ID #REQUIRED
type %SymbolType; #REQUIRED
xCenter CDATA #REQUIRED
yCenter CDATA #REQUIRED
fixedDimensions %boolean; "FALSE"
width CDATA "10"
height CDATA "10"
color CDATA "#000000"
fillColor CDATA "#ffffff"
>


<!-- Element for connectors -->
<!-- ====================== -->

<!ELEMENT Connector (Text, Text)>
<!ATTLIST Connector
connectorId CDATA ""
attachedSymbolId IDREF #REQUIRED
type %ConnectorType; #REQUIRED
isOutside %boolean; #REQUIRED
side %Side; #REQUIRED
position CDATA #REQUIRED
endType %ConnectorEndType; #REQUIRED
>


<!-- Element for link segments -->
<!-- ========================= -->

<!ELEMENT LinkSegment EMPTY>
<!ATTLIST LinkSegment
orientation %Orientation; #REQUIRED
length CDATA #REQUIRED
>


<!-- Element for links -->
<!-- ================= -->

<!ELEMENT Link (Text, Connector, Connector, LinkSegment*)>
<!ATTLIST Link
linkId CDATA ""
type %LinkType; #REQUIRED
textSegmentNum CDATA #REQUIRED
color CDATA "#000000"
reverseRead %boolean; "FALSE"
>


<!-- Element PageSpecification -->
<!-- ========================= -->
<!-- Attributes for diagram pages; all dimensions are centimetres -->
<!ELEMENT PageSpecification EMPTY>
<!ATTLIST PageSpecification
pageWidth CDATA "21"
pageHeight CDATA "29.7"
topMargin CDATA "1.5"
bottomMargin CDATA "1.5"
leftMargin CDATA "1.5"
rightMargin CDATA "1.5"
pageFooter %boolean; "TRUE"
scaleFactor CDATA "1.0"
>


<!-- Element DiagramPartition -->
<!-- ======================== -->
<!-- A partition in a diagram -->
<!ELEMENT DiagramPartition (PageSpecification, Symbol, Link*, UnifiedPublication*)>
<!ATTLIST DiagramPartition
name CDATA ""
nbPagesH CDATA "1"
nbPagesV CDATA "1"
>


<!-- Element for diagrams -->
<!-- ==================== -->

<!ELEMENT Diagram (DiagramPartition+)>
<!-- Warning: attributes pageWidth, pageHeight, nbPagesH & nbPagesV are obsolete -->
<!ATTLIST Diagram
language %Language; "none"
type %DiagramType; #REQUIRED
name CDATA ""
cellWidthMm CDATA "5"
>

11.2.3 Explanations

The main XML element is <Diagram>. It is split in several partitions, each being a rectangular set of pages having the same page size and margins within a partition (XML element <PageSpecification>). A partition always has an external frame, which is a symbol, containing all the symbols in it. Attributes for a symbol are all the required information to display it. In addition to its display attributes, a link also knows the index of the segment bearing its text (textSegmentNum) and a special indicator for association links giving the reading order of the association (reverseRead). The position for connectors is given by the side of the symbol to which they attach, the relative position along the symbol's border and a boolean saying if the connector is outside the symbol (normal case) or inside it (links connecting to a frame border):
A connector also has an endType specifying the symbol that appears at the link end, which may vary for a given connector type (e.g connectors for association links may end with a filled or outlined diamond to indication the association is actually a composition or aggregation).

11.3 - Behavioral diagrams

11.3.1 Principles

Behavioral diagrams are not described in terms of symbols with links between them, but in terms of logical elements:

• State blocks, which are blocks of symbols starting with a state symbol with transitions attached to it, each starting either with a message input symbol, a continuous signal symbol or a save symbol.
• "Standalone" transitions, such as the start transition, or a sequence of symbols starting with a label. These are also called "non-state transitions", as they do not appear in a state block.
• Symbols alone that are not attached to any other, such as declaration symbols.

Some specific constructions are used for state blocks starting on a state symbol that is also a next state in another transition, and for symbols that are attached to other ones, such as comment symbols.

11.3.2 XML elements

<!-- =================================== -->
<!-- ELEMENTS FOR STATE MACHINE DIAGRAMS -->
<!-- =================================== -->


<!-- Element SdlFSMDiagram -->
<!-- ~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Element for the whole state machine diagram. The symbols are the declaration symbols in the diagram. -->

<!ELEMENT SdlFSMDiagram (%SdlFSMPartition*)>
<!-- NB: entities and elements not defined in this file are in rtdsDiagram.dtd, where this DTD is included -->
<!ATTLIST SdlFSMDiagram
language %Language; "-"
type %DiagramType; "prcs"
>


<!-- Element SdlFSMPartition -->
<!-- ~~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Element for a partition in the state machine diagram. The symbols are the declaration symbols in the partition. -->

<!ELEMENT SdlFSMPartition (SdlFSMSymbol*, (NonStateTransition | StateTransitionBlock)*, PageSpecification?)>
<!ATTLIST SdlFSMPartition
name CDATA ""
>


<!-- Element StateTransitionBlock -->
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Element for a set of transitions attached to a state symbol. The symbol is the state. -->

<!ELEMENT StateTransitionBlock ((SdlFSMSymbol|SdlFSMSymbolReference), (SaveTransition|NormalStateTransition)*)>
<!ATTLIST StateTransitionBlock
top_left_coordinates CDATA ""
>


<!-- Element SdlFSMSymbolReference -->
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Element for a reference on a symbol. Used to connect state transition blocks to nextstate symbols -->

<!ELEMENT SdlFSMSymbolReference EMPTY>
<!ATTLIST SdlFSMSymbolReference
identifier IDREF #REQUIRED
>


<!-- Element NonStateTransition -->
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Element for a transition not attached to a state symbol, such as a start transition or an "in" connector transition. The symbol is the starting one (start or connector). -->

<!ELEMENT NonStateTransition (SdlFSMSymbol, Transition)>
<!ATTLIST StateTransitionBlock
top_left_coordinates CDATA ""
>


<!-- Element NormalStateTransition -->
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Element for a "normal" transition in a state block, i.e starting with an input or a continuous signal. The symbol is the input or continuous signal. -->

<!ELEMENT NormalStateTransition (SdlFSMSymbol, Transition)>


<!-- Element SaveTransition -->
<!-- ~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Element for a transition in a state block that is only a save symbol. The symbol is the save. -->

<!ELEMENT SaveTransition (SdlFSMSymbol)>


<!-- Element Transition -->
<!-- ~~~~~~~~~~~~~~~~~~ -->
<!-- Element for the behavioral part of a transition (not including the header symbol such as the input or the start). -->

<!ELEMENT Transition ((SdlFSMSymbol | DecisionBlock)*)>


<!-- Element DecisionBlock -->
<!-- ~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Element for a decision block in a transition. The symbol is the decision, or transition option. -->

<!ELEMENT DecisionBlock (SdlFSMSymbol, DecisionBranch*)>


<!-- Element DecisionBranch -->
<!-- ~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Element for a branch in a decision. The symbol is the answer. -->

<!ELEMENT DecisionBranch (SdlFSMSymbol, Transition)>


<!-- Element SdlFSMSymbol -->
<!-- ~~~~~~~~~~~~~~~~~~~~ -->
<!-- Element for a single symbol. The default value "-" for the colors means they should use the default color. -->

<!ELEMENT SdlFSMSymbol EMPTY>
<!ATTLIST SdlFSMSymbol
identifier ID #REQUIRED
type %SymbolType; #REQUIRED
text CDATA ""
outline_color CDATA "-"
background_color CDATA "-"
center_coordinates CDATA ""
dimensions CDATA ""
attached_symbol_id CDATA ""
>

11.3.3 Explanations

The top-level XML element for a behavioral diagram is <SdlFSMDiagram>. Just as for standard diagrams, each diagram is split into partitions described via the <SdlFSMPartition> element. A partition has a page specification, just like partitions in standard diagrams, but their contents is specific:

• Each of the top-level symbols appearing in it (e.g, a declaration symbol) is described via a <SdlFSMSymbol> element;
• Each state transition block appearing in it is described via a <StateTransitionBlock> element;
• Each non-state transition appearing in it (e.g, the start transition) is described via a <NonStateTransition> element.

More precisely, here is what each XML element represents and how it is structured:

• <StateTransitionBlock>:
• <NormalStateTransition>:
• <SaveTransition>:
• <NonStateTransition>:
• <Transition>:
• <DecisionBlock>:
• <DecisionBranch>:

There are no explicit links described for this kind of diagram: all displayed links are deduced from the position of the symbols they link.
State transition blocks that start on a next state symbol in a transition will have the <SdlFSMSymbol> representing the state replaced by a <SdlFSMSymbolReference>, with its identifier attribute being the identifier for the next state symbol in the other transition. Note that in this case, the state transition block's top_left_coordinates attribute is irrelevant and ignored, since its position can be computed from its state symbol.
Symbols attached to other ones such as comment symbols will appear as top-level symbols in their parent partition, but will have their attached_symbol_id attribute set to the identifier of the symbol they are attached to. The link is made both ways: the symbol they are attached to will also have its attached_symbol_id attribute set to the identifier of the attached symbol.

11.4 - MSC diagram DTD

11.4.1 Principles

A MSC diagram is described mainly as a series of events happening on lifelines (instances). More precisely, it has 3 main parts:

• The first part gives the sequence of lifelines in the diagram, ordered as they should be displayed. All lifelines are listed, including collapsed ones.
• The second part lists the collapsed lifelines and the lifelines they "contain".
• The third part gives the events actually happening in the diagram. Each event has a type and a set of attributes connecting it to lifelines or other events, or giving information about how it should be displayed.

11.4.2 DTD text

<!ENTITY % MscEventType1 "MESSAGE_SEND|MESSAGE_RECEIVE|MESSAGE_SAVE|OPERATION_CALL|OPERATION_RETURN">
<!ENTITY % MscEventType2 "TIMER_START|TIMER_CANCEL|TIMER_TIMEOUT|TIME_CONSTRAINT_START|TIME_CONSTRAINT_END">
<!ENTITY % MscEventType3 "PROCESS_CREATION|PROCESS_START|PROCESS_END">
<!ENTITY % MscEventType4 "SEMAPHORE_CREATION|SEMAPHORE_START|SEMAPHORE_END|SEMAPHORE_DELETION">
<!ENTITY % MscEventType5 "SEMAPHORE_TAKE|SEMAPHORE_TAKE_SUCCEEDED|SEMAPHORE_TAKE_TIMEOUT|SEMAPHORE_GIVE">
<!ENTITY % MscEventType6 "SEGMENT_START|SEGMENT_END|ACTION_SYMBOL_START|ACTION_SYMBOL_SPACER|ACTION_SYMBOL_END">
<!ENTITY % MscEventType7 "MSC_REFERENCE_START|MSC_REFERENCE_END|INLINE_EXPRESSION_START|INLINE_EXPRESSION_SEP|INLINE_EXPRESSION_END|CONDITION_START|CONDITION_END">
<!ENTITY % MscEventType8 "TEXT_SYMBOL|UNATTACHED_COMMENT|ATTACHED_COMMENT|ABSOLUTE_TIME">
<!ENTITY % MscEventType "(%MscEventType1;|%MscEventType2;|%MscEventType3;|%MscEventType4;|%MscEventType5;|%MscEventType6;|%MscEventType7;|%MscEventType8;)">

<!ELEMENT MscDiagram (LifelineOrdering, CollapsedLifeline*, MscEventRow*, PageSpecification?)>
<!ATTLIST MscDiagram
message_params_visibility %MsgParamVis; "full"
>

<!ELEMENT LifelineOrdering EMPTY>
<!ATTLIST LifelineOrdering identifiers CDATA "">

<!ELEMENT CollapsedLifeline EMPTY>
<!ATTLIST CollapsedLifeline
identifier CDATA #REQUIRED
collapsed_lifelines_ids CDATA #REQUIRED
>

<!ELEMENT MscEventRow (MscEvent+)>

<!ELEMENT MscEvent EMPTY>
<!ATTLIST MscEvent
event_type %MscEventType; #REQUIRED
lifeline_ids CDATA ""
color CDATA "#000000"
background CDATA "#ffffff"
identifier CDATA ""
type CDATA ""
text CDATA ""
text_size CDATA ""
>

11.4.3 Explanations

The main XML element is <MscDiagram>.
The first part in the diagram is given in the <LifelineOrdering> XML element: its identifiers attribute contains a space-separated list of lifeline identifiers.
The second part is given in the <CollapsedLifeline> XML elements, each associating an identifier for the collapsed lifeline to the space-separated list of identifiers for lifelines they contain (collapsed_lifelines_ids).
The third part is the sequence of <MscEvent> XML elements. Each of these elements is a description of an event happening in the diagram. The attributes for an event are:

• event_type: type for the event.
• lifeline_ids: space-separated list of identifiers for lifelines involved in the event.
• color: text and outline color for the event.
• background: background color for the event if applicable.
• identifier: identifier for the event itself if one is needed. This identifier is used to link 2 related events, such as a couple MESSAGE_SEND / MESSAGE_RECEIVE or a couple TIME_CONSTRAINT_START / TIME_CONSTRAINT_END.
• type: type for object described by the event.
• text: text for the object described by the event if any.
• text_size: size for the text for the object described by the event, giving its width and its height, separated by a space, both of which can be a '-' if it's missing or not significant.

All attributes do not apply to all event types, and may not contain the same inforamtion. Here is the compatibility matrix:

Table 2: Event attributes

Event type	lifeline_ids	color	identifier	type	text	text_size
MESSAGE_SEND	X	X	X	.	X	.
MESSAGE_RECEIVE	X	X	X	.	X	.
MESSAGE_SAVE	X(1)	X	.	.	.	.
OPERATION_CALL	X(2)	X	.	.	X	.
OPERATION_RETURN	X(2)	X	.	.	X	.
TIMER_START	X(1)	X	.	.	X	.
TIMER_CANCEL	X(1)	X	.	.	X	.
TIMER_TIMEOUT	X(1)	X	.	.	X	.
TIME_CONSTRAINT_START	X(1)	X	X	.	X	.
TIME_CONSTRAINT_END	X(1)	X	X	.	X	.
PROCESS_CREATION	X(2)	X	.	.	.	.
PROCESS_START	X(1)	X	.	.	X	X(6)
PROCESS_END	X(1)	X	.	.	.	.
SEMAPHORE_CREATION	X(2)	X	.	.	.	.
SEMAPHORE_START	X(1)	X	.	.	X	.
SEMAPHORE_END	X(1)	X	.	.	.	.
SEMAPHORE_DELETION	X(1)	X	.	.	.	.
SEMAPHORE_TAKE	X(1)	X	.	.	X	.
SEMAPHORE_TAKE_SUCCEEDED	X(1)	X	.	.	.	.
SEMAPHORE_TAKE_TIMEOUT	X(1)	X	.	.	.	.
SEMAPHORE_GIVE	X(1)	X	.	.	.	.
SEGMENT_START	X(1)	X	X	X(4)	.	.
SEGMENT_END	X(1)	X	X	X(4)	.	.
ACTION_SYMBOL_START	X(1)	X	.	.	X	.
ACTION_SYMBOL_SPACER	X(1)	X	.	.	X	.
ACTION_SYMBOL_END	X(1)	X	.	.	X	.
MSC_REFERENCE_START	X(3)	X	X	.	X	.
MSC_REFERENCE_END	X(3)	X	X	.	X	.
INLINE_EXPRESSION_START	X(3)	X	X	X(5)	.	X(7)
INLINE_EXPRESSION_SEP	X(3)	X	X	X(5)	.	.
INLINE_EXPRESSION_END	X(3)	X	X	X(5)	.	.
CONDITION_START	X(3)	X	X	.	X	.
CONDITION_END	X(3)	X	X	.	X	.
TEXT_SYMBOL	.	X	.	.	X	.
UNATTACHED_COMMENT	.	X	.	.	X	.
ATTACHED_COMMENT	.	X	.	.	X	.
ABSOLUTE_TIME	.	X	.	.	X	.

1. Only one lifeline identifier is allowed, which is the one on which the event happens.
2. Two lifelines must be specified. The first is the one onto which the event happens (called one, created one, etc...); the second one is the causing the action (caller, creator, etc...).
3. Several lifelines can be specified, listing all those spanned by the symbol.
4. The type is the type for the segment: suspended, method, co-region, etc...
5. The type is the type for the inline expression: opt, alt, par, etc...
6. The text size only specifies the width for the text, allowing to size the lifeline head correctly.
7. The text size allows to give the proper dimensions to the tag border in the inline expression.

http://www.sdl-rt.org info@sdl-rt.org