Using the SDL Editor

Working with Pages

This section describes the more important aspects of page handling.

Each diagram page must have a unique name for identification purposes. This name must be correct in accordance with the naming convention for pages in SDL. Each diagram must contain at least one page, and there is no maximum amount of pages that a diagram may contain.

The autonumbering facility available for pages relates to automatically updating the sequential numbering when pages are added or deleted.

When diagrams are opened, the default way of presentation is that the first page of the requested diagram is shown (first in accordance to the order in which pages have been added). This default can be overruled, and you can go directly to a specific page that has been predetermined.

Most of the page managing functions are available through the menu choices on the Pages menu.

A number of functions are available through the Edit menu choice in this menu:

• Ordering Pages
• Naming Pages
• Adding a Page
• Renaming a Page
• Clearing (Deleting) a Page
• Pasting a Page
• Transferring to a Page
• Printing a Page
• Resizing a Page

Other page functions are also available in the SDL Editor:

• Applying Autonumbering on Page Names
• Removing Autonumbering on Page Names
• Designating the Page to Open
• Transferring to a Specific Page
• Transferring to the Referring Page
• Transferring to the Next or the Previous Page
• Transferring to the First Page
• Transferring to the Last Page

Ordering Pages

Within an SDL diagram, page locations are set according to the order in which they are added (see Adding a Page). This order is reflected in:

• The Organizer structure
• The listing order for pages in the Edit Pages dialog

To re-order pages, you use the Cut and Paste button.

Naming Pages

Whenever you name a page, the names that you use must strictly adhere to SDL naming conventions. If you use unacceptable notation (e.g. blank spaces or a semi-colon), you receive a message.

Applying Autonumbering on Page Names

If autonumbering is required, a feature can assign numeric names to the pages in the diagram. The page names will be assigned 1, 2, 3 and so forth.

1. Select Edit.
2. Select the page to autonumber in the page list.
3. Toggle the Autonumbered toggle button to on in the Edit Pages dialog. You are then prompted if you want to autonumber the selected page only or all pages in the dialog which is issued.

• If you click Yes, the SDL Editor assigns the page name the highest assigned numeric value + 1. You are then returned to the Edit Pages dialog.
• If you click All Pages, all pages will be assigned numeric names, starting with 1. The numbering will follow the listing order in the page list. You are then returned to the Edit Pages dialog.

Removing Autonumbering on Page Names

The autonumbering feature can be turned off . This must for instance be done if you want to assign a specific name to a page.

1. Select Edit.
2. In the page list, select the page to remove autonumbering on.
3. Toggle the Autonumbered toggle button to off in the Edit Pages dialog. You are then prompted to confirm the operation in the dialog which is issued.
• Clicking Yes transfers you to a Rename Page dialog where you assign the page a new name. Autonumbering is removed.

Adding a Page

To add a page to an existing diagram:

1. Select Edit.
2. In the list of existing pages, select the page to precede or succeed the new page to be added.
3. Click the Add button. The Add Page dialog is issued.

A faster way to add a page before or after the current page is to select the Add menu choice directly. In this case, the Add Page dialog is issued directly.

Figure 380 : Adding a page

In the Add Page dialog:

1. Enter the required page name in keeping with SDL conventions (the name must be unique within the diagram). Otherwise, select Autonumbered if you want the pages to be automatically renumbered to incorporate the new page.
2. Select the position of the new page -- before or after the current page.
3. Select the type of page required. The dialog box automatically shows the page options that are available to you under SDL rules.
4. Click OK. Control is returned to the Edit Pages dialog.
5. Click Done.

Designating the Page to Open

When a diagram is opened without specifying a particular page, the default is that it is opened at the first page that has been added to the diagram, showing the upper left part of the page.

You can however open a diagram at a specific page in the SDL Editor.

To specify the page to be opened first:

1. Bring up the Edit Pages dialog.

The Open this page first field, below the toggle button, reflects the page to be opened first (page 1 in Figure 381).

Figure 381  : Specifying what page to open first

2. To specify another page, select the page to be opened first in the Edit pages dialog.
3. Turn the Open this page first button on. The identification of the page to be opened is then placed under the Open this page first button.
4. Click Done.

Renaming a Page

1. Select Edit.
2. Select the page to rename.
• To rename an auto-numbered page, first click the Autonumbered button off. Autonumbering is removed on the selected page and the Rename Page dialog is issued. Go to step 4.
3. Click the Rename button. The Rename Page dialog is issued.
4. Fill in the required new name in keeping with SDL naming conventions. Page names must be unique within the diagram. For block and process diagrams, an option is available to also change the page type.
5. Click OK. Control is returned to the Edit Pages dialog.
6. Click Done.

Clearing (Deleting) a Page

If there is only page in a diagram, you cannot remove it. A message is then shown.

Caution!  Clear pages with caution as there is no Undo option available.

1. Select Edit.
2. Select the page to be deleted in the page list.
3. Click on the Clear option and then on Clear to delete the page.
4. Click Done.

Pasting a Page

1. Open the SDL diagram where to paste the page.
2. Select the Edit menu choice.
3. In the list of existing pages, select the page to precede or succeed the new page to be pasted. Click the Paste button. The Paste Page dialog is issued.

Figure 382 : Pasting a page

4. Enter the required page name in keeping with SDL conventions (the name must be unique within the diagram). Otherwise, select Autonumbered if you want the pages to be automatically renumbered to incorporate the page to be pasted.
5. Select where to paste the page - before or after the current page.
6. Click Paste. Control is returned to the Edit Pages dialog.

If there are reference symbols on the pasted page all the underlying substructure is also pasted. See Cutting, Copying and Pasting Reference Symbols.

7. Click Done.

Transferring to a Page

There are several ways to transfer to another page of the current diagram. When you transfer to a page, it will be placed on the top of the stack in the window if you are using one window only. Otherwise, that page will be displayed in a window of its own.

Transferring to a Specific Page

• Transfer to a page, located not further than two pages from the current page, by selecting that page in the Pages menu.
• In the Edit Pages dialog, transfer to a page by clicking on the required page and then click on the Edit button.
• Alternatively, double-click the page icon in the Organizer.

Transferring to the Referring Page

To transfer to the page where the current page is referenced from (i.e. where the SDL reference symbol referring to the current diagram is located):

Select Edit Reference Page from the Pages menu or the Reference Page quick-button.

Transferring to the Next or the Previous Page

You may transfer to the next or previous page in the diagram. The order is specified according to the listing order in the Edit Pages dialog.

To transfer to the next or previous page:

Use the quick-buttons for Previous Page or Next Page.

Transferring to the First Page

Select First from the Pages menu. You are transferred to the first page of the diagram.

Transferring to the Last Page

Select Last from the Pages menu. You are transferred to the last page of the diagram.

Printing a Page

SDT allows to print individual pages from the SDL Editor. You can also restrict the scope of printing to a part of the page. A number of options which affect the resulting printout are possible to specify.

Resizing a Page

1. Transfer to the page to resize.
2. Select Drawing Size from the Edit menu. A dialog is issued, showing the current width and height.
3. Type in the new values. Click OK.

Note:  If you enlarge a page so that the page size becomes wider or larger than the physical page size defined in the Print Options, your printouts will require more pages than before, if you use a fixed printout scale.

Working with Windows

Each SDL Editor window shows one SDL page. The SDL Editor is a multi-window tool, allowing you to open new windows on a page and close windows that are no longer needed.

A newly opened window is a mirror image of the window from which the selection to open a window was made. Multiple windows may be opened (one at a time) and they are all identical with the first one. Any subsequent modifications made will reflect the same in either the original window, or any of the newly opened window(s). This option affords the possibility of viewing in more than one window, and can ideally be used in conjunction with the scaling factor when looking at a detailed page.

For information on how you open:

• The Grammar Help Window, see Opening the Grammar Help Window.
• The Signal Dictionary Window, see Opening the Signal Dictionary Window.

Opening and Closing Windows

Standardized functions for opening and closing windows are provided in the Window menu: New Window and Close Window. If you close a window that is the last window opened by the MSC Editor, the editor will exit.

Hiding and Showing Parts of the SDL Editor Window

You can show and hide the various component parts of the SDL Editor window. On UNIX, if they are hidden, it increases the drawing area available to be used in the creation or modification of pages of a diagram.

You find all the available options for hiding and showing parts of the window in the dialog box accessed via the Window Options command on the View menu. You can set all of these options as preferences.

All of these options are turned on and off with a toggle button. Some of these options are available with quick-buttons:

The quick-button for text window on / off or symbol menu on / off.

• If you click All Windows it applies the values to all instances of the SDL Editor windows.

Editing Text

General

There are several ways of editing text in the SDL Editor, i.e.

• In the drawing area
• In the text window
• In an external text editor

Two support functions are provided, namely:

• Grammar Help, see Using Grammar Help.
• Signal Dictionary, see Using the Signal Dictionary.

Editing in the Drawing Area and Text Window

The SDL Editor allows you to edit textual objects directly in the drawing area.

If you select an object in the SDL Editor window, a text cursor is inserted directly in the text associated with the object, and the text window will be updated to contain the text. This is explained in Selecting a Symbol That Has Associated Objects and Selecting a Line That Has Associated Objects.

When you type text in the drawing area, all accelerator keys are interpreted as input to the text. As an example, the <Delete> key will in text editing mode delete a character, but in non-text editing mode it will remove (Clear) an entire symbol. This means that you can only use text editing keyboard accelerators like <Home>, <End>, <Ctrl+A> and <Ctrl+E> in text editing mode.

While useful for quickly editing small texts, direct editing in the drawing area suffers from some restrictions:

• While it is possible to position the insertion cursor in the text using the mouse or the arrow keys, it is not possible to make any selections in the text, for deletion or replacement.
• If the text becomes large enough to cross the drawing area boundary, parts of the text will no longer be visible.

To overcome these and other limitations, the Text Window can be used to edit the text. If you select more than one text object, the text window is not updated. Each line (except for the last line) in the text window is terminated by a carriage return, and may consist of any number of legal characters.

Regardless of whether you edit directly in the drawing area or in the text window, the SDL Editor makes sure that the contents of both displayed texts are consistent.

A context sensitive syntax check is performed on all texts being edited. If a syntax error is found a red bar underlining the text will appear where the first error occurs in the text. See also Syntax Rules when Editing.

You can also edit text in an external text editor by using the Connect to Text Editor command in the Tools menu. This allows you to use the Telelogic Tau Text Editor, the Emacs text editor (on UNIX) or MS Word (in Windows) to edit large pieces of text.

The SDL Editor also supports editing text outside the context of SDT, by transferring text to / from a file.

Text Window

On UNIX, the text window is a pane of the SDL Editor window.

In Windows, the text window is a floating, resizeable and moveable window that can be placed anywhere on the screen. A single text window is shared by all instances of the SDL Editor currently running.

The text window contains two menus described in:

• The File Menu of the Text Window
• Edit Menu

Hiding and Showing the Text Window

You can hide or show the text window with the Window Options command from the View menu, or by using a quick-button.

In Windows: When visible, the text window will always be placed on top of the SDL Editor window.

Basic Text Editing Functions

Delayed Updating of the Drawing Area

When you edit text in the text window, both the text window and corresponding text in the drawing area will be updated. The the drawing area will be updated after a slight time delay and this cay be set by an editor preference.

If you try to type an illegal character, you will be warned by a beep.

Standardized Text Editing Functions

When you edit text, you can:

• Position the cursor by clicking or by using the arrow keys.
• Insert characters after the current position of the text pointer.
• Delete one character backward by pressing <backspace>.
• Delete one character forward by pressing <delete>.
• Replace selected text by typing.
• Delete selected text by pressing <backspace> or <delete>.
• Select text by dragging or by clicking and <Shift>-clicking.
• Select a word by double-clicking it.
• Select a line by triple-clicking it.

Searching and Replacing Text

You can search for and replace text in a diagram or in a diagram structure that is managed by the Organizer.

Searching for Text in a Diagram

To search for text in the current page:

1. Select the diagram where to search in the Organizer.

Select Search from the Organizer's Tools menu or click the Organizer quick-button for Search. The Search dialog is issued.

3. Specify the text to be found in the Search for text field.
• Click the Consider case button on to search case sensitive.
• Turn the Search substructure button on to specify that the scope of search should comprise the diagrams included in the substructure (the SDL structure which root is designated by the current diagram). If you turn the button off, the scope of search will only comprise the current diagram.
4. Click the Search button. The object where the next occurrence of text is found will be selected and the text window updated accordingly.
• You may use the SDL Editor to edit the contents of a diagram while the Search dialog is active. The Organizer is however locked as long as the Search dialog is open.
• The diagram that the tool is currently processing is displayed to the right of the Search In field.
5. Click Close.

Searching and Replacing Text

1. Open the Search dialog as described in Searching for Text in a Diagram.
2. Specify the text to be found in the Search for text field.
3. Specify the text to be replaced with in the Replace with text field.
4. Click the Search button to find the first occurrence.
5. If the text is found, the object where the next occurrence of text is found will be selected and the text window updated accordingly. You may use any of the following options:
• Search further by clicking Search repeatedly
• Replace the text by clicking Replace
• Replace and continue search with the Replace & Search button.
• Replace all occurrences with the Replace All button.
6. Close the Search dialog by clicking Close.

Editing Text by Using an External Text Editor

Whenever a text object is selected and the text is visible in the text window, the command Connect to Text Editor in the Tools menu is available. This command opens an external text editor containing the text of the selected object. Which external text editor to start is defined by the preference SDT* TextEditor, which can be set either to the SDT Text Editor, to the Emacs text editor (on UNIX) or MS Word (in Windows).

From this point on, you can only edit the text by using the external text editor.

The text in the SDL Editor is updated every time the external text editor saves the text. When the text is no longer edited in the external text editor, the editing control returns to the SDL Editor.

Importing / Exporting Text

SDT allows you to import and export text from / to a file. You can, for instance, import text from files that contain SDL-PR into text symbols and export the contents of text symbols to files.

Importing Text from a File

Caution!  Importing text from a file replaces existing text as well. There is no Undo facility.

You can import the contents of a text file into an object managed by the SDL Editor in the following way:

1. Select the object where you want to import the contents of a file.
2. Select Import from the text window's File menu.
3. Specify the file to import.
4. Click OK. This replaces the contents of the text window with the contents of the file you have specified in the file selection dialog.

Exporting Text from a File

To export the contents of the text window into a file:

1. Select the object which text you want to export to a file.
2. Select Export from the text window's File menu.
3. Specify the file to export the text to.
4. Clicking OK possibly creates a new file and replaces the contents of the file with the contents of the text window.

Copying, Cutting and Pasting Text

In the text window, you can cut, copy and paste text between different symbols, lines and text attributes. You can also transfer text between different applications.

Programmable Function Keys (UNIX only)

On UNIX, SDT allows to tie a function key to a defined text string. When you type that defined function key, the programmed text string will be inserted at the current cursor location. You can customize your own programming of function keys.

Global SDT Resources

The function keys are set up as X resources. It is possible to set up both system default and user-defined X resources, allowing you to customize your environment. The X resources are defined in a file that is common for all SDT users, namely

/usr/lib/X11/app-defaults/SDT 

To program the function keys, insert following lines anywhere into the SDT file:

/* Any suitable comment */
SDT*XmText.translations: #override \n\
<Key>F1: insert-string("F1Text") \n\
<Key>F2: insert-string("F2Text") \n\
<Key>F3: insert-string("F3Text") \n\
<Key>F4: insert-string("F4Text") \n\
<Key>F5: insert-string("F5Text") \n\
<Key>F6: insert-string("F6Text") \n\
<Key>F7: insert-string("F7Text") \n\
<Key>F8: insert-string("F8Text") \n\
<Key>F9: insert-string("F9Text")
/* Note the absence of \n\ on line 9 */

Note:  Omitting to define some of the function keys is permissible.

User-Defined SDT Resources

You can define your own function keys. You do this by defining the X resources described above in a personal copy of the definition file and to store that file it into your home directory:

 ~username/SDT

Alternatively, any directory designated by the environment variable XAPPLRESDIR can be used.

Restrictions

• You can only define one line for each function key. If you attempt to define more than one line into one function key may cause an unpredictable result when you press that key.

For instance, it is not certain that the following line will produce the expected result:



<Key>F1: insert-string("F1Line1\nLine2") \n\ 
  

• You can define the keys F1--F9.

Changing Fonts on Text Objects

You may change the font faces and font sizes used in the textual objects displayed by the SDL Editor. All textual objects use the same font faces and font sizes, meaning that you can neither change them individually nor change them during an SDL Editor session.

There is one exception though -- it is possible to use a separate font for text symbols. This is useful in process diagrams where you may want a proportional font in most symbols to save space, while you may want a non-proportional font in text symbols to be able to align words on different lines.

The font faces available depend on the target system on which you are running SDT.

Defining What Font to Use

To modify the desired font size and font face, you must use the Preference Manager. See Managing Preferences.

Textual Objects Preferences

When the setting is in effect, SDT will use the font face names given by the preference settings

Editor* ScreenFontFamily

Editor* PrintFontFamily

to select font face names. Note that in this way you can select different font names for screen and for print.

On UNIX, if you leave the Editor* ScreenFontFamily preference setting empty, you will edit your documents using the SDT Draft font, but print them using the font you specified with the Editor* PrintFontFamily setting.

Text Symbol Preference

For text symbols, the preference Editor* TextSymbolFontFamily is used both for on-screen viewing and printing.

Supported Font Faces

On UNIX, the availability of font faces is determined by the version of the X Windows server which is running. With a revision 5 or higher (X11 R5), scalable fonts are supported. In that case, the available list of predefined font faces would be:

• Times
• Helvetica
• Courier
• SDT Draft (mapped to the Schumacher font)
• Other (mapped to a user-defined font)

In Windows, the availability of font faces is determined by the TrueType fonts that are currently installed on the computer (use for instance the Windows Control Panel to determine what is available).

Default Font Face

The default font face is Helvetica. On UNIX, if scalable fonts are not supported, the font face will be replaced by a Schumacher font (which can be used in all circumstances).

Default Font Sizes

The default font sizes are as follows:

Page Font Sizes (except overview pages)
Text Object:	Font Size
Kernel heading, texts in reference symbols, channel names, signal route names, gate names	12 points
Other text objects	9 points

Overview Page Font Sizes
Text Object:	Font Size:
All texts except signal lists	10 points
Signal list symbol	8 points

Setting Alignment

Normally the alignment of the text inside symbols are automatically set. However, you can use the preference setting Editor* TaskSymbolLeftAligned to set the alignment for the task symbol, procedure call symbol, macro call symbol, create request symbol and the save symbol. The default value is "off", meaning that the text will be centered, but if you set it to "on" the text in these symbols will be left aligned.

Determining Which Scalable Fonts Your Server Can Access (UNIX only)

On UNIX, use the xlsfonts command to list installed fonts. Font names containing 0 for width and height are scalable.

How to Determine what Fonts are Available

From the OS prompt, typing:

hostname% xlsfonts | grep "\-0\-O\-" | more

will return a list of accessible scalable fonts.

Scalable Fonts Under R5 Servers

To use scalable fonts under X11R5 you must normally first connect to a font server.

How to Start the Font Server

1. Start the font server on any local host:



hostname% fs

2. Connect the server to fs indicating which host the font server is running on (which can be the same host that the X server is running on):



hostname2% xset +fp tcp/<hostname>:7000

For further information see the X11R5 documentation or use man fs to read the manual page describing the font server you are running.

Disabling Font Scaling (UNIX only)

On UNIX, if the fonts look poor on the screen, a possible work-around is to disable the scaling option.

Note:  Disabling font scaling effectively disables WYSIWYG!

To do this, you should edit the SDT resource file.

1. Open the file SDT in a text editor.
2. Locate the line with the text: SDT*sdtUseScalableFonts
3. Change the line to SDT*sdtUseScalableFonts: false
4. Save the file and restart the SDT environment.

Grammar Help and Signal Dictionary

General

Besides the context sensitive syntax check performed on the texts, there is a grammar help supportfunction. 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

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

• Select the Grammar Help menu choice from the Windows menu.

The grammar help window is issued (see Figure 383).

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:

• Select the object of interest. The grammar help window contents are automatically updated to list the following:
• The nature of the selected object
• The grammar for that object
• The various "use cases".

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 383  : The grammar for a task symbol

• The next items contains a number of "use cases". As an example, if you select a task symbol, the first "use case" reads Assignment, while the second reads Assignment2. This is to be interpreted as:
  An assignment statement,
  Multiple assignment statements in a task symbol.

Figure 384 : The Assignment "use case"

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

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

Figure 385 : The symbol label

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.

Figure 386 : 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:

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

Figure 387 : The grammar field

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.

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.

@SDL@CHANNEL@Channel symbol

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

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

• 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>

$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 SDT 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, see Figure 412) for files with the standard suffix .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 388  : The Signal Dictionary window (on UNIX)

Figure 389  : The Signal Dictionary window (in Windows)

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 SDT 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, SDT 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

• Select Signal Dictionary from the SDL Editor Windows menu. The signal dictionary window is issued (see Figure 388 and Figure 389).

Setting the Mode to Graphical or Textual (UNIX only)

On UNIX, the signal dictionary window can take advantage of your computer's font capabilities to present the information in a graphical way, using SDL-like notation. This is the default mode.

If the information is presented using strange characters, your terminal does not support the font family used by the signal dictionary window. You should use the textual mode.

To turn the mode to textual:

1. Set the environment variable SDLENOGRAPHICS
• If you are to run several Signal Dictionary sessions in this mode, you may want to set the environment variable in a file that you will automatically source (e.g. .cshrc)
2. Exit all SDT tools.
3. Restart SDT to have the environment variable affect the behavior.

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 conveyors¹ 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, a bug symbol (on UNIX), or an error message (in Windows) 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.

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

• You may also type <Ctrl+t> to toggle the option. Typing t brings the This option into view (if enabled).
• To find the definition of the signal in the This section, you may select an object in the drawing area that uses the signal and type <Ctrl+f>.

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 SDT Message Sequence Chart 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 SDT 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 390 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 390  : 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 398) 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 by clicking on it. 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.

Figure 391 : Selecting the signal Display

• Alternatively, double-click the signal or timer.

4. 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 399, Figure 400 and Figure 401).
• 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 by clicking on it. Use the Insert or Replace from the Edit menu to update the signal list contents.

Figure 392  : Selecting the gate B

• Alternatively, double-click the signal or timer.

4. 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 392, 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 393 : The symbol label

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.

Figure 394 : The signal list (on UNIX)

Figure 395 : The signal list (in Windows)

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:

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.

In Windows, this notation is purely textual.

On UNIX, the notation that is adopted is an SDL-like graphical notation. It is also possible to select a textual notation if the font face used in the graphical notation is not supported by the computer. You select the textual notation by setting the environment variable SDLENOGRAPHICS before you start SDT.

Each item in the signal list is one of the following:

• Separator
• Diagram Identifier
• Gate
• Channel
• Signal Route
• Signal and Signal List
• Timer

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 396 : A signal list separator (graphical notation on UNIX)

Figure 397 : 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:

• Grammar

SDL Grammar Help section. See Using Grammar Help for more information about this topic.

• Up

A list of all SDL signals that are available² 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

All SDL signals that are available by looking at the current diagram, i.e. this diagram.

• Down

All SDL signals that are available by looking at all diagrams one level down in the SDL hierarchy. The Down section is empty if the current diagram has no diagrams below it in the hierarchy.

• All

All defined SDL signals that are visible for the current diagram according to the SDL scope rules.

• 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 SDT's public PostMaster interface. 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:

Figure 398  : 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 399  : 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 400  : 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 401  : 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:

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

Figure 402  : 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 403).

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

• Input³
• 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:

Figure 404  : 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 405.

Figure 405  : 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 406 : Timer symbol (graphical notation on UNIX).

In the textual notation, a `T' appears as the rightmost attribute.

Timers can appear in the following contexts:

• Definitions of timers
• Set statements
• Reset statements
• Active statements.

Error Notification

If SDT 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 407 : Errors were detected when extracting signals
(graphical notation on UNIX)
SDT 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 408 : Errors were detected when extracting signals
The current diagram (This diagram) is process type Door. SDT could not convert this diagram to SDL-PR.

These error situations are either caused by:

• Syntactically incorrect SDL which causes SDT 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 409).

Figure 409  : 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.

• 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 410).
• The first line contains the signal list to the parent diagram
• The second line contains the signal list from the parent diagram.

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

• If a signal list⁴ 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,...,SignalN