IBM
Contents Index Previous Next



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:

Accelerator Command / functionality
g

Select the Grammar section if the option is enabled and bring the separator into view

u

Similar to g but applies on Up.

t

Similar to g but applies on This.

d

Similar to g but applies on Down.

a

Similar to g but applies on All.

m

Similar to g but applies on MSC.

e

Similar to g but applies on External.

Ctrl+g

Toggles the Grammar option on / off (see Grammar). When the option is enabled, brings the Grammar separator into view and selects it.

Ctrl+u

Same as Ctrl+g, but applies on the Up option.

Ctrl+t

Same as Ctrl+g, but applies on the This option).

Ctrl+d

Same as Ctrl+g, but applies on the Down option.

Ctrl+a

Same as Ctrl+g, but applies on the All option.

Ctrl+m

Same as Ctrl+g, but applies on the MSC option.

Ctrl+e

Same as Ctrl+g, but applies on the External option.

Ctrl+f

Finds 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

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.

To request grammar help:

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":

  1. 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.

Figure 409 : The grammar for a task symbol

Figure 410 : The Assignment "use case"

  1. Click on the item of interest to select it.
  2. 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.
  3. 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.

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:

  1. Copy an existing grammar help file.
  2. 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:

To merge the current grammar template definitions with another one:

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.

Figure 411 : The symbol label

The symbol label reads "No single symbol selected" in the following circumstances:

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.

Figure 412 : The name field

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:

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).

Figure 413 : The grammar field

To copy and paste text from the template definition field to the text window, you can:

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.

Note:

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 symbol

The declaration is to be interpreted as:

editortype

editortype may currently be of one of the keywords:

Note:

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_BLOCK
ADDITIONAL_HEADING_BLOCK_TYPE
ADDITIONAL_HEADING_PROCEDURE
ADDITIONAL_HEADING_PROCESS
ADDITIONAL_HEADING_PROCESS_TYPE
ADDITIONAL_HEADING_P_AS_SERVICE
ADDITIONAL_HEADING_SERVICE
ADDITIONAL_HEADING_SERVICE_TYPE
ADDITIONAL_HEADING_SYSTEM
ADDITIONAL_HEADING_SYSTEM_TYPE
BLOCKSUBSTRUCTURE
BLOCK_REF
BLOCK_TYPE_REF
CALL
CHANNEL
CHANNELSUBSTRUCTURE
CONNECTION_POINT
CONNECTOR
CONTINUOUS_SIGNAL
CREATE
DECISION
ENABLING_CONDITION
GATE
INPUT
KERNEL_HEADING
KERNEL_HEADING_BLOCK
KERNEL_HEADING_BLOCK_TYPE
KERNEL_HEADING_PROCEDURE
KERNEL_HEADING_PROCESS
KERNEL_HEADING_PROCESS_TYPE
KERNEL_HEADING_SERVICE
KERNEL_HEADING_SERVICE_TYPE
KERNEL_HEADING_SYSTEM
KERNEL_HEADING_SYSTEM_TYPE
MACROCALL
OPERATOR_REF
OUTPUT
CLASS
PACKAGE_REF
PAGENUMBER
PRIORITY_INPUT
PRIORITY_OUTPUT
PROCEDURE_REF
PROCEDURE_START
PROCESS_REF
PROCESS_TYPE_REF
RETURN
SAVE
SERVICE_REF
SERVICE_TYPE_REF
SIGNALROUTE
START
STATE
STOP
TASK
TEXTSYMBOL_BLOCK_SUBSTR
TEXTSYMBOL_MACRO
TEXTSYMBOL_PROCEDURE
TEXTSYMBOL_PROCESS
TEXTSYMBOL_P_AS_SERVICE
TEXTSYMBOL_SERVICE
TEXTSYMBOL_SYSTEM
TRANSITION_OPTION

Note:

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>

Note:

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:

The syntax of a template definition is simply:

$<templatename>'Newline'
<multiple lines constituting the template 
definition>

Example 323 : The definition of a channel example

$GRAMMAR
Z100: 2.5.1 (p.45)
Z100: 2.5.5 (p.50) Signal list

<ChannelName> ::= <Name>
<SignalList> ::=
  ( <SignalName> / '(' <SignalListName> ')' )",'
$SignalList
SignalName, SignalName
$SignalList2
SignalName, SignalName, (SignalListName)

Note:

Neither leading nor trailing newlines will be added to the template definition. These can be added to the template simply by adding a leading empty line and/or a trailing empty line in the template definition.

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:

  1. The SDL Editor starts by fetching the preference value
    Editor*TemplateFile.
  2. If no value is specified for the preference parameter, it will use the default file name sdt.tpl.
  3. The directories where the SDL Editor will search for the file are:
    • The current directory
    • Your home directory ($HOME on UNIX and %HOME% in Windows)
    • The installation directory ($sdtrelease on UNIX)
  4. 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.
  5. 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.

Note:

The signal dictionary function requires a file with grammar help templates (sdt.tpl) in order to function properly. See The Grammar Help File.

Figure 414 : The Signal Dictionary window

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.

Note:

In order to extract signal information from a diagram, the SDL Suite requires the diagram to be syntactically correct in the sense that SDL/PR code can be generated from the SDL/GR diagram without encountering errors.

Opening the Signal Dictionary Window

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):

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.

To enable an option:

  1. Activate the Select menu.
  2. 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.

Note:

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.

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.

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.

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.

Note:

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.
    • As a consequence of this, you will not be able to look into the instance of a type that is defined in a package diagram and used in the current SDL system.
  • 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.

Figure 415 : The type is referred where instantiated

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):

  1. 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.
    • You may also use the keyboard accelerators <Ctrl+u>, <Ctrl+t>, <Ctrl+d>, <Ctrl+a>, <Ctrl+m> and
      <Ctrl+e>
      to toggle the respective option on and off.
    • Use the keyboard accelerators u, t, d, a, m and e to bring the respective section into view.
  2. 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.

  1. 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).
  2. Make sure the signal output, input, priority input or save symbol to be updated is selected in the target diagram.
  3. 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.
    • Alternatively, double-click the signal or timer.

Figure 416 : Selecting the signal Display

  1. Update the signal's formal parameter type with a current parameter.
Updating a Signal Conveyor
(Channel, Signal Route, Connection Point or Gate)
  1. 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.
  2. Make sure the signal list is selected in the target diagram.
  3. Select the signal conveyor. Use the Insert or Replace from the Edit menu to update the signal list contents.
    • Alternatively, double-click the signal or timer.

Figure 417 : Selecting the Channel cPanelToControl:int:int

  1. 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.

  1. You should make sure the Down and This options are selected.
  2. Remember to add a SIGNAL or TIMER keyword in the text symbol, before the enumeration of signals.
  3. 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.

Figure 418 : The symbol label

The symbol label reads "No single symbol selected" in the following circumstances:

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.

Figure 419 : The signal list (on UNIX)

Figure 420 : The signal list (in Windows)

The signal list is empty when:

The following objects are recognized as carrying signal information:

Object Usage

channel line
channel name
signal list in channel

Reference to signal

connection point

Reference to signal

gate
gate name
signal list in gate

Reference to signal

input

Reference to signal

output

Reference to signal

priority input

Reference to signal

save

Reference to signal

signal route line
signal route name
signal list in signal route

Reference to signal

text

Declaration of signal

Signal 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.

Figure 421 : A signal list separator (graphical notation on UNIX)

Figure 422 : A signal list separator (textual notation)

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:

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:

Figure 423 : Diagram type symbols (graphical notation on UNIX)

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:

Figure 424 : Gate symbols (graphical notation on UNIX)

The textual notation reads:

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):

Figure 425 : Channel symbols (graphical notation on UNIX)

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).

Figure 426 : Signal route symbols (graphical notation on UNIX)

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:

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).

Figure 427 : Signal definitions

Note:

Each signal appears only once within a diagram. If a signal is referenced at least once within the diagram, it is not listed in the signal definitions section for that diagram, only references are listed.

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).

Figure 428 : Signal references on a line

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):

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:

Figure 429 : Signal symbols (graphical notation on UNIX).

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.

Figure 430 : An undeclared signal which is input and output

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.

Figure 431 : Timer symbol (graphical notation on UNIX).

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.

Figure 432 : Errors were detected when extracting signals
(graphical notation on UNIX)

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

Figure 433 : Errors were detected when extracting signals

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:

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:

Figure 434 : Selection of a signal

The signal Display is selected. The signal definition shows the signal along with its parameters - one parameter of type Charstring in the example.

Figure 435 : Selection of a gate

The gate D, which is an in/out gate is selected. The signal definition shows one line with all in-signals (Door, Display) and one line with all out-signals (OpenDoor, DoorNo) in relation to the parent diagram (Controller)

1

The term signal conveyor denotes a communication path that conveys signals; a channel, signal route, a gate or connection point.

2

The term "available" means defined and / or referenced.

3

Save of signal is also considered as input by the Signal Dictionary function.

4

A signal list is identified with its name within parentheses, such as
(SignalListName)


http://www.ibm.com/rational
Contents Index Previous Next