![]() |
![]() |
![]() |
![]() |
![]() |
Grammar Help and Signal Dictionary
General
Besides the context sensitive syntax check performed on the texts, there is a grammar help support function. It assists you in entering the correct text, according to the SDL grammar, in the selected text attribute to an object.
Designing using SDL implies to large extent defining, sending and receiving signals. A signal dictionary assists you in reducing the time it takes to find out names and parameters for a signal that you already have used somewhere in a diagram. The signal dictionary also incorporates timers.
Keyboard Accelerators (UNIX only)
In addition to the standard keyboard accelerators, described in Keyboard Accelerators, the Grammar Help and Signal Dictionary window features the following:
gSelect the Grammar section if the option is enabled and bring the separator into view
uSimilar to g but applies on Up.
tSimilar to g but applies on This.
dSimilar to g but applies on Down.
aSimilar to g but applies on All.
mSimilar to g but applies on MSC.
eSimilar to g but applies on External.
Ctrl+gToggles the Grammar option on / off (see Grammar). When the option is enabled, brings the Grammar separator into view and selects it.
Ctrl+uSame as Ctrl+g, but applies on the Up option.
Ctrl+tSame as Ctrl+g, but applies on the This option).
Ctrl+dSame as Ctrl+g, but applies on the Down option.
Ctrl+aSame as Ctrl+g, but applies on the All option.
Ctrl+mSame as Ctrl+g, but applies on the MSC option.
Ctrl+eSame as Ctrl+g, but applies on the External option.
Ctrl+fFinds the last occurrence of the first word in the currently selected object in the SDL Editor drawing area and selects it in the This section.
The first word is defined as the text string from the start of the object's text and until one of the following characters:` ' (space) `,' (comma) `(` (left parenthesis) <TAB> `\n' (newline)
Using Grammar Help
The Grammar Help window is a multi-functionality window; it can also provide signal dictionary capabilities. These functions are further described in Using the Signal Dictionary. What functionality is provided depends on the options defined in the Select menu.
Each SDL Editor window has its associated Grammar Help window.
Opening the Grammar Help Window
- Select the Grammar Help menu choice from the Windows menu.
- The grammar help window is issued (see Figure 409).
Requesting Grammar Help
If you select the object you need assistance on, you will see the keywords and options available for use in given situations, and the corresponding reference to sections of the ITU Z.100 SDL Definition, followed by the grammar syntax of the meta language.
- Select the object of interest. The grammar help window contents are automatically updated to list the following:
Inserting Text
This operation inserts the contents of the grammar help window into the SDL Editor text window.
To insert the text related to a given "use case":
- Locate the "use case" of interest. The left part of the window provides a list of situations, named using some abbreviation that associates to the situation.
- The first item(s) in the list reads GRAMMAR, possibly with a suffix that informs you about the grammar context. You can take advantage of the GRAMMAR items either as using the references to Z.100 if you need more detailed information about the selected sort of object, or if you need to read more about the concrete grammar.
- Click on the item of interest to select it.
- Select Insert from the Edit menu or double-click the item in the list. The contents of the right part of the window are inserted into the SDL Editor text window, at the current I-beam cursor position.
- Finally, replace the formal notation with the appropriate values, variables, signals, etc. used in your diagram.
Replacing Text
This operation signifies replacing the contents of the SDL Editor text window with the contents of the grammar help window.
- Proceed as described in Inserting Text, but select Replace from the Edit menu.
Customizing the Grammar Help
With the SDL Suite, a standard grammar help template file is provided. In addition to this, the SDL Editor allows you to use your own templates and to merge these with the standard templates.
To create grammar help definitions:
- Copy an existing grammar help file.
- Edit the file using any text editor (the grammar help file is an ASCII file). See The Grammar Help File for a description of the contents and syntax of the file.
To use another grammar template definitions:
- Select Load from the File menu. In a File Selection Dialog you then specify what template definitions to load.
To merge the current grammar template definitions with another one:
- Select Load from the File menu. In a File Selection Dialog, you then specify what template definitions to merge with the current.
The Symbol Label
The symbol label field is a non-editable text field that displays the type of symbol that is currently selected in the SDL Editor.
The symbol label reads "No single symbol selected" in the following circumstances:
- No symbol or line is currently selected in the SDL Editor
- More than one symbol is selected
- The symbol type is not defined in the Grammar Help file.
The Name Field
The name field consists of a scrollable list that contains a list of names of templates associated with the currently selected symbol.
The list is updated automatically each time an object in the SDL Editor's drawing area is selected, to reflect the templates that are currently available for that object. By default, the first item in the list is selected.
The name field is empty in the following circumstances:
- The symbol label reads "No single symbol selected"
- The symbol type information is missing in the Grammar Help file.
When selecting an item in the list, the corresponding template definition appears in the grammar field, allowing to check its contents before inserting it into the text window (see Insert and Replace).
The Grammar Field
The grammar field is a scrollable field from which text can be copied. Its contents are updated to reflect the definition for the currently selected item in the name field.
The grammar field is empty if no item is selected in the name field (or if the name field is empty).
To copy and paste text from the template definition field to the text window, you can:
- Use the Insert command, described in Insert.
- Use the Replace command, described in Replace.
- Copy and paste by using the graphical environment clipboard functions.
The Grammar Help File
This section is a reference for the format of the files that contain SDL Grammar Help definitions.
The template definition file format is line-oriented, and uses two separator characters chosen so as to not interfere with the possible contents of templates appearing in the file.
The characters `@' and `$' are separator characters. They are reserved for that purpose.
The template definition file is divided into sections defining templates for a particular symbol type. A section begins with a Grammar Help Declaration part and ends with a Grammar Help Definition part.
The grammar help declaration of a new section has the following syntax:
@<editortype>@<symboltype>[@[<symbolcomment>]]<editortype>, <symboltype> and <symbolcomment> are to be replaced with the adequate text strings.
Comments in Grammar Help files are also permissible.
Example 322 : The Declaration of a Channel Template
@SDL@CHANNEL@Channel symbolThe declaration is to be interpreted as:
- SDL
Valid for the SDL Editor only- CHANNEL
A channel line- Channel Symbol
An informative text that will be displayed to you (see The Symbol Label).editortype
editortype may currently be of one of the keywords:
- - The section contains templates relevant for the SDL Editor.
- - The section contains templates for the Message Sequence Chart Editor.
Grammar Help is currently not supported by the MSC Editor. The MSC keyword is reserved for future functionality extensions.
symboltype
symboltype is defined per editor and the allowed names are the following:
ADDITIONAL_HEADING_BLOCKADDITIONAL_HEADING_BLOCK_TYPEADDITIONAL_HEADING_PROCEDUREADDITIONAL_HEADING_PROCESSADDITIONAL_HEADING_PROCESS_TYPEADDITIONAL_HEADING_P_AS_SERVICEADDITIONAL_HEADING_SERVICEADDITIONAL_HEADING_SERVICE_TYPEADDITIONAL_HEADING_SYSTEMADDITIONAL_HEADING_SYSTEM_TYPEBLOCKSUBSTRUCTUREBLOCK_REFBLOCK_TYPE_REFCALLCHANNELCHANNELSUBSTRUCTURECONNECTION_POINTCONNECTORCONTINUOUS_SIGNALCREATEDECISIONENABLING_CONDITIONGATEINPUTKERNEL_HEADINGKERNEL_HEADING_BLOCKKERNEL_HEADING_BLOCK_TYPEKERNEL_HEADING_PROCEDUREKERNEL_HEADING_PROCESSKERNEL_HEADING_PROCESS_TYPEKERNEL_HEADING_SERVICEKERNEL_HEADING_SERVICE_TYPEKERNEL_HEADING_SYSTEMKERNEL_HEADING_SYSTEM_TYPEMACROCALLOPERATOR_REFOUTPUTCLASSPACKAGE_REFPAGENUMBERPRIORITY_INPUTPRIORITY_OUTPUTPROCEDURE_REFPROCEDURE_STARTPROCESS_REFPROCESS_TYPE_REFRETURNSAVESERVICE_REFSERVICE_TYPE_REFSIGNALROUTESTARTSTATESTOPTASKTEXTSYMBOL_BLOCK_SUBSTRTEXTSYMBOL_MACROTEXTSYMBOL_PROCEDURETEXTSYMBOL_PROCESSTEXTSYMBOL_P_AS_SERVICETEXTSYMBOL_SERVICETEXTSYMBOL_SYSTEMTRANSITION_OPTION
If the same section appears more than once, all template definitions under those sections will be available.
symbolcomment
symbolcomment is an optional feature, which allows specification of a text to be associated with each symboltype. The text for a specific symboltype appears in the symbol type field of the Grammar Help window whenever a symbol of that type is selected in the editor.
Comments
Also, comments may appear in the file using the following syntax:
@COMMENT@<commenttext>
Such a comment signals the end of the previous section and should only be used before another section.
Grammar Help Definition
A SDL grammar template has significance only if it is located after a valid declaration. The template will be added to the list of templates for that section.
A template definition is started with a line beginning with a `$' sign and continues until either:
- A line beginning with a `$' sign is read.
- A line beginning with a `@' sign is read.
- End of file is encountered.
The syntax of a template definition is simply:
$<templatename>'Newline'<multiple lines constituting the template definition>Example 323 : The definition of a channel example
$GRAMMARZ100: 2.5.1 (p.45)Z100: 2.5.5 (p.50) Signal list<ChannelName> ::= <Name><SignalList> ::=( <SignalName> / '(' <SignalListName> ')' )",'$SignalListSignalName, SignalName$SignalList2SignalName, SignalName, (SignalListName)
File Handling
When a Grammar Help window is opened, the SDL Editor will try to locate a SDL grammar help file and to load it, if found. The search order is as follows:
- The SDL Editor starts by fetching the preference value
Editor*TemplateFile.- If no value is specified for the preference parameter, it will use the default file name sdt.tpl.
- The directories where the SDL Editor will search for the file are:
- If no file can be located, either with a specified name or the default name, you get the option of searching manually (i.e. from a File Selection Dialog) for files with the standard file name extension .tpl.
- If you decline by clicking Cancel, the Grammar Help window will appear without contents. You can now locate a grammar help file by choosing Load (or Merge, which will have the same effect in this case).
Using the Signal Dictionary
Messages from a Message Sequence Chart and signals from an external signal dictionary may be included into the SDL Editor's signal dictionary.
All functionality is provided in the signal dictionary window. Each SDL Editor window has its associated Signal Dictionary window.
The signal dictionary function requires a file with grammar help templates (sdt.tpl) in order to function properly. See The Grammar Help File.
Signal Dictionary Update
The signal dictionary function stores information about signals in an information server. The information server updates its contents each time an SDL diagram is saved. When the diagram is saved by the SDL Editor, the SDL Analyzer is invoked and produces a mirrored image which is an SDL/PR description of the SDL/GR diagram. That information is then loaded into the information server which serves the SDL Editor with information upon request. All of this is done automatically.
Opening the Signal Dictionary Window
- Select Signal Dictionary from the SDL Editor Windows menu. The signal dictionary window is issued (see Figure 414).
Requesting Signal Dictionary Services
When you select an object where a reference or definition of a signal makes sense, the signal dictionary window is automatically updated to reflect the signals and signal conveyors1 that are available according to what options you have selected.
The signal dictionary function responds when selecting the following objects (see Object for more details):
- channel
- signal route
- connection point
- gate
- signal input
- signal output
- priority input
- save of signal
- text symbol
Updating the Signal Dictionary
The signal dictionary is automatically updated each time you save an SDL diagram or an MSC that is referred to in the Organizer's SDL System Structure chapter.
When modifying an SDL diagram, you may have unintentionally introduced SDL constructs that are incomplete and thus cause the signal dictionary to fail in providing signal information for that diagram.
Where the signal dictionary fails on a diagram, an error message will appear after the diagram name in the signal list. Correct the source of error and save the diagram again. For a reference on signal dictionary errors, see Error Notification.
Specifying the Signal Dictionary Options
You can customize the signal dictionary to fit your needs, by restricting or extending the amount of information that is presented through a set of options that you can activate or deactivate.
Depending on the method you are following when designing with SDL, you should activate the required options.
Next follows a guide for when to use the available options.
- Activate the Select menu.
- Toggle the appropriate option on by selecting it (an option which is enabled is indicated with an asterisk preceding the option name). Selecting the option once again disables it.
- Alternatively, select the Options menu choice and toggle the buttons on or off. When satisfied, click OK.
The more options are enabled, the more information is computed by the SDL Editor and the more time it takes.
Bellow follows a few general guidelines for enabling the various options, depending on the approach you are following when designing with SDL.
Working Top-Down
This expression means starting by designing the root diagram (e.g. the system diagram) and continuing with the block diagrams, next the process diagrams and so forth.
If you follow this approach, selecting the Up option will enable access to signals used one level up in the SDL hierarchy. This option is enabled by default.
- You may also type <Ctrl+u> to toggle the option. Typing u brings the Up option into view (if enabled).
Working Bottom-Up
Following this method means starting with the diagrams at a deeper level (e.g. procedures) and working upwardly in the SDL hierarchy.
If you work bottom-up, select the Down option to enable access to signals used one level down in the SDL hierarchy. This option is enabled by default.
- You may also type <Ctrl+d> to toggle the option. Typing d brings the Down option into view (if enabled).
Working with Local Signals
If you look for entities that are used locally in a diagram, select the This option. Remember, a diagram needs to be saved in order to update the signal dictionary.
Listing all Signals
You can list all signals that are visible according to the SDL scope rules by turning the All option on. For instance, a signal that you declare on the system level will be available in all diagrams in the SDL hierarchy.
- You may also type <Ctrl+a> to toggle the option. Typing a brings the All option into view (if enabled).
Using Packages
If you want to gain access to signals that you have declared in a package, you should enable the All option.
Using Diagram Types
If you use the diagram type concept, you should enable the All option to gain access to the signals that are defined in the diagram types.
Listing MSC Messages
If you describe the dynamic behavior of an SDL diagram using the MSC Editor, you may take advantage of this by turning the MSC option on.
Messages used in an MSC will be available in the signal dictionary only if it is associated with an SDL diagram, i.e. linked into the SDL diagram structure.
Importing an External Signal Dictionary
You may import an external signal dictionary into the SDL Suite through the Postmaster interface. This is described in Load External Signal Definitions into the Information Server.
Locating the Source Diagram
Note: Signal Dictionary and OO
If you are looking for a source diagram that is an SDL-92 type (system type, block type, process type or service type) and that you access through an instance of the type, the following conditions must be respected in order to have the signal dictionary window list the diagram and list all of the signals and signal conveyors that are used in the diagram:
- The type diagram must be referred in the same diagram as where it is instantiated. In the signal dictionary window, only the type will be listed, not the instance. Figure 415 shows an example of this.
- In the case the type is inherited from a supertype, the entities that you are looking for must be defined in the child type.
The main cause of this limitation is that channels and signal routes are connected to the instance, not to the type.
The process type Controller is instantiated as Cl. The process instance Cl will be visualized as the process type Controller, and you can list signals conveyed on the gates A, B, C, D and E.
To locate the source diagram (i.e. the diagram where the signal is used or where the signal conveyor is available):
- Locate the section (Up, This, Down, All, MSC and External) by scrolling up or down. The sections are listed in that order and the start of each section is identified with a separator with the corresponding name.
- Identify the source diagram by its type and name. Diagrams are listed alphabetically by their name. The diagram type is identified either by a graphical SDL-like symbol (see Figure 423) in the left margin (UNIX only), or by a text string that consists of the diagram type.
Updating the Text in the Target Diagram
Once you have located the source diagram your next task is to insert the text belonging to the object you have selected in the target diagram (the diagram where the change is to be done).
Updating a Signal / Timer Output, Input, Priority Input or Save
This operation makes sense only on pages where the implementation is described, i.e. the flow pages.
- Locate the matching signal or timer in the signal list.
- Signals are identified graphically with the SDL signal input and/or signal output symbol (UNIX only), or with the characters `I', `O' or `?' (see Signal and Signal List.
- Timers are identified with the MSC timer symbol (UNIX only), or the character `T' (see Timer).
- Make sure the signal output, input, priority input or save symbol to be updated is selected in the target diagram.
- Select the signal or timer item in the signal list. Use Insert or Replace from the Edit menu to update the symbol contents. The target symbol is updated with the signal name and its formal parameters.
Updating a Signal Conveyor
(Channel, Signal Route, Connection Point or Gate)
- Locate the signal conveyor that constitutes the corresponding item that interfaces to the channel, signal route or gate that you are to update in the current diagram.
- In graphical notation on UNIX, these entities are identified graphically by a symbol which has the appearance of the corresponding SDL concept (see Figure 424, Figure 425 and Figure 426).
- Channels, signal routes and gates are identified textually with the abbreviations CH, SR and GA, respectively.
- Make sure the signal list is selected in the target diagram.
- Select the signal conveyor. Use the Insert or Replace from the Edit menu to update the signal list contents.
- In the case of a bidirectional conveyor, you will see lines of text in the right window, each one corresponding to a signal list (as in Figure 417, above). You should copy each line of text to the corresponding signal list. Select the signal list in the SDL Editor and a line, then use Insert or Replace to update the signal list.
Updating a Text Symbol
When updating a text symbol, you are likely to declare signals and timers that you have referred to in the current diagram or referred to in the SDL hierarchy descending from the current diagram.
- You should make sure the Down and This options are selected.
- Remember to add a SIGNAL or TIMER keyword in the text symbol, before the enumeration of signals.
- Locate all diagrams of interest. Look for signals / timers that you want to declare. Double-click each signal, and insert the necessary commas to create a syntactically correct declaration. Terminate the operation by inserting a semicolon.
Finding a Definition
When you select an object in the SDL Editor's drawing area and then type <Ctrl+f> the first occurrence of the first word in the object is looked for and selected in the This section.
Closing the Signal Dictionary Window
You close the signal dictionary window by selecting Close from the signal dictionary File menu.
The Symbol Label
The symbol label field is a non-editable text field that displays the type of object that is currently selected in the SDL Editor.
The symbol label reads "No single symbol selected" in the following circumstances:
- No object is currently selected in the SDL Editor
- More than one object is selected.
- The symbol type is not defined in the Grammar Help file.
The Signal List
The signal list is a selectable list where all occurrences of signals that are found according to the current selection criteria are listed.
The signal list is empty when:
- The symbol label reads "No single symbol selected"
- The signal dictionary function does not make any sense on the selected object. i.e. the selected object does not refer/define a signal.
The following objects are recognized as carrying signal information:
signal route line
signal route name
signal list in signal routeSignal List Notation and Syntax
Each line in the signal list follows a notation that informs about the various diagrams and symbols where signals are used and also about the context.
Each item in the signal list is one of the following:
Separator
The signal list is divided into several sections. The top of each section is clearly marked with a separator, having the appearance of a thick line (graphical notation on UNIX) or a number of hashes ("###...###") preceding and following a text that identifies the section.
Each of these sections corresponds to an option that is enabled in the Select menu (see Select Menu). Their meaning and order of appearance in the signal list is as follows:
- Grammar
- SDL Grammar Help section. See Using Grammar Help for more information about this topic.
- Up
- A list of all SDL signals that are available2 by looking one level up in the SDL hierarchy. The Up section is empty when working on the top diagram (e.g. a system diagram).
- This
- Down
- All
- MSC
- Signals that have been exported from a Message Sequence Chart into the SDL Editor signal dictionary facility. An MSC must be Associated with an SDL diagram in the Organizer's diagram structure in order to include its signals into the Signal Dictionary (see Associate).
- External
- Signals that have been imported from an external signal dictionary. An external signal dictionary is imported through the public PostMaster interface of the SDL Suite. See Load Definition File.
Diagram Identifier
In the graphical notation on UNIX, diagrams are identified with an SDL Reference symbol in the left margin which identifies the diagram type, followed by the diagram name:
The textual notation reads <diagramtype diagramname>
All information that is listed after a diagram identifier is related to that diagram, until the next diagram identifier or separator.
Gate
In the graphical notation on UNIX, gates are identified by an arrow pointing into or out from the frame, followed by the name of the gate:
GA <Gatename>:<In>|<Out>|<In:Out>Signals on a gate are the lines that appear after the gate and before the next gate, channel, signal route or diagram identifier. The lines consist of all signals or signal lists that are conveyed on the gate, the signals sent to the diagram appearing first and the signals sent from the diagram appearing last.
Signals are listed according to the order of appearance in the respective signal lists.
If you select a gate in the list, one or two lines is displayed in the signal definition list. In the case of a bidirectional gate, the first line holds the signals sent to the diagram while the second line holds the signals sent from the diagram.
Channel
In the graphical notation on UNIX, channels are identified by an arrow between the frame and a block symbol (in the case of a channel to/from the environment), alternatively with an arrow between two block symbols (an internal channel):
The textual notation of a channel is:
CH <Channelname>:<In>|<Out>|<In:Out>|<Int>|<Int:Int>Channels are present on package, system, block, block substructure and system type diagrams only.
The lines of information that follow a channel consist of the signals that are conveyed on it. The appearance is similar to listing signals on a gate. See Gate for information about listing order.
Signal Route
In the graphical notation on UNIX, signal routes are identified by an arrow between the frame and a process symbol (a channel to/from the environment), alternatively with an arrow between two process symbols (an internal signal route).
The textual notation of a signal route looks like this:
SR <Signalroutename>:\<In>|<Out]>|<In:Out>|<Int>|<Int:Int>Signal routes are present on block and block type diagrams only.
The lines of information that follow a signal route consist of the signals that are conveyed on it. The appearance is similar to listing signals on a gate. See Gate for information about listing order.
Signal and Signal List
Signals and signal lists can appear in the following contexts:
- Signal Definitions (i.e. declarations in text symbols)
- Signal References on Lines (i.e. references in gates, channels and signal routes)
- Signal References in Flow Diagrams (i.e. references in flow diagrams; processes, process types and procedures).
The notation that is adopted differs slightly depending on the context.
A signal definition appears directly after the diagram identifier where the signal is declared. The signal is identified by its name and its location to distinguish it from other items.
The indentation is filled with blank space (see Figure 427).
A signal reference on a line uses a similar notation as for signal definitions. The indentation consist of an arrow that identifies the direction of the signals (see Figure 428).
Signal references in flow diagrams are listed along with the context the signal is used. This is indicated by the following attributes (multiple attributes can be set):
- Input3
- Output
- Reference to an undefined signal.
In the graphical notation on UNIX, these attributes are shown using SDL input and SDL output symbols, and a question mark for showing that the signal is not declared:
The textual notation uses the characters:
[I][O][?]These characters appear at fixed positions. Where an attribute is not set, this is indicated with a hyphen (`-'). See Figure 430.
Timer
A timer is handled identically as described in Signal and Signal List. To indicate that the item is a timer, the graphical notation on UNIX uses the MSC symbol for timer.
In the textual notation, a `T' appears as the rightmost attribute.
Timers can appear in the following contexts:
Error Notification
If the SDL Suite fails in extracting signal information from some SDL diagrams, the information contained in that diagram is not available to the signal dictionary function.
In the graphical notation on UNIX, this is indicated in the signal list by a "bug" symbol located to the right of the diagram names.
The SDL Suite failed in extracting signal information from the process type diagrams Door, DoorLock and the block type diagram Doors (one level down in the SDL hierarchy)
In the textual notation, this is indicated by an error message following the diagram name:
<diagramtype diagramname> :GrPrError
The current diagram (This diagram) is process type Door. The SDL Suite could not convert this diagram to SDL/PR.
These error situations are either caused by:
- Syntactically incorrect SDL which causes the SDL Suite to fail when converting the SDL/GR diagram to SDL/PR.
- Syntactically incorrect SDL which causes the information server to fail when parsing the contents of the SDL/PR file. When possible, the signal definition field will contain a graphical reference to the source of error. Double-clicking that graphical reference will display the source of error in an SDL Editor window.
The error reports are listed in the Organizer low window. See also Signal Dictionary Update.
The Signal Definition
The signal definition contains the following information:
- If a signal or timer is selected in the signal list, the signal or timer is listed with its parameters (see Figure 434).
The signal Display is selected. The signal definition shows the signal along with its parameters - one parameter of type Charstring in the example.
- If a channel, signal route or gate is selected, the signal definition holds one or two lines of information. Each line contains a list of all signals that are conveyed (see Figure 435).
1
- If a signal list4 is selected, the signal definition holds one line of information containing a list of all signals contained in the signal list. The syntax is
SignalListName = Signal1, Signal2,...,SignalNThe term signal conveyor denotes a communication path that conveys signals; a channel, signal route, a gate or connection point.
2The term "available" means defined and / or referenced.
3Save of signal is also considered as input by the Signal Dictionary function.
4A signal list is identified with its name within parentheses, such as
(SignalListName)
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |