Next: 2. Document Editing Up: Toolkit for Conceptual Modeling Previous: List of Figures
Subsections

- 1.1 An Overview of TCM
  - 1.1.1 The Purpose of TCM
  - 1.1.2 What is Included in TCM
  - 1.1.3 Using TCM in Software Specification
- 1.2 How to Read this Manual
- 1.3 How to Obtain the Latest Version of TCM
- 1.4 Installation and Getting Started
  - 1.4.1 Unix tar-files with binaries
  - 1.4.2 RPM distributions with binaries
  - 1.4.3 Source code distributions
  - 1.4.4 Starting up
  - 1.4.5 Unix options, files and variables
  - 1.4.6 Graphical User Interface
- 1.5 Questions and Comments

# 1. Introduction

#
1.1 An Overview of TCM

## 1.1.1 The Purpose of TCM

The Toolkit for Conceptual Modeling (TCM) is a collection of software tools to represent conceptual models of software systems in the form of diagrams, tables, trees, etc. A conceptual model of a system is a structure used to represent the requirements or architecture of the system. TCM is meant to be used for specifying and maintaining requirements for desired systems, in which a number of techniques and heuristics for problem analysis, function refinement, behavior specification, and architecture specification are used. TCM takes the form of a suite of graphical editors that can be used in these design tasks.

During software development, a number of stakeholders must reach a common understanding of the behavior and structure of the software. These are for example users and sponsors (or their representatives), analysts, designers and programmers. An important function of conceptual models is to facilitate this understanding.

The notations for software specifications that are supported by TCM are explained in appendix A. A more detailed analysis of the nature and use of some of these techniques and heuristics in various existing methods for software specification is presented in the book [22]. The UML diagram techniques are discussed in [23]. Bibliographic references can be found on page .

##
1.1.2 What is Included in TCM

This manual is the successor of [5] and [7]. This version of the TCM software (henceforth called ``TCM'') is a collection of document editors, i.e. diagram, table and tree editors, each for a different graphical notation system. Currently, TCM has the following editors:

- Generic Editors.

  - TGD: Tool for Generic Diagrams. This tool is for arbitrary graphs, it does not perform semantic checks.

  - TGT: Tool for Generic Tables. This tool is intended for arbitrary tables, it does not perform semantic checks.

  - TGTT: Tool for Generic Textual Trees. This tool is intended for generic trees in which all nodes are text labels. It does not perform semantic checks.

- Structured Analysis Editors.

  - TESD: Tool for Entity Relationship Diagrams.

    Entity-relationship diagrams are used in structured analysis and an extension of them, class diagrams (static structure diagrams), are used in the UML. This tool is intended for entity relationship diagrams (ERDs) that are used in Entity Relationship (ER) modeling based on the subset of the UML static structure diagrams. The ERD part of the UML class diagram technique is explained in [17,18,19]. The ER notation that TCM supports is explained in appendix A.3.1.

  - TEFD: Tool for Data and Event Flow Diagrams. This tool is intended for data and event flow diagrams (EFDs), that are used in the method of Structured Analysis for Real Time Systems (SA/RT) [20] and in the Yourdon Systems Method [31]. The technique is explained in appendix A.1.2.

  - TSTD: Tool for State Transition Diagrams (Mealy). This tool is intended for state transition diagrams (STDs) according to the Mealy notational convention. This technique is explained in appendix A.1.3.

  - TTUT: Tool for Transaction-Use Tables. This tool is intended for transaction-use tables. These tables are used in some of the methods presented in [22]. The technique is explained in appendix A.1.4.

  - TFET: Tool for Function-Entity type Tables. This tool is intended for function-entity type tables. These tables are used in some of the methods presented in [22]. The technique is explained in appendix A.1.5.

  - TFRT: Tool for Function Refinement Trees. This tool is intended for function refinement trees, also called function decomposition trees. Function refinement trees of this type are used and discussed in [22]. See also appendix A.1.6.

- UML Editors.

  The Unified Modeling Language (UML) is an object oriented modeling language. The notation and semantics of UML diagrams can be found in [17,18,19].

  - TUCD: Tool for Use Case Diagrams. This tool is intended for Use Case Diagrams that are used in UML for specifying interactions between a user and a computer system.

  - TSSD: Tool for Static Structure Diagrams. This tool is intended for Static Structure Diagrams that are used in UML for specifying class and object diagrams.

  - TATD: Tool for Activity Diagrams. This tool is intended for Activity Diagrams that are used in UML for specifying interactions between a user and a computer system.

  - TSCD: Tool for Statechart Diagrams. This tool is intended for Statechart Diagrams that are used in UML for specifying the sequences of states that an object of a given class goes through during its life in response to received stimuli, together with its responses and actions.

  - TSQD: Tool for Sequence Diagrams. This tool is intended for Sequence Diagrams that are used in UML for specifying an interaction arranged in time sequences.

  - TCBD: Tool for Collaboration Diagrams. This tool is intended for Collaboration Diagrams that are used in UML for specifying an interaction between an object and its related objects.

  - TCPD: Tool for Component Diagrams. This tool is intended for Component Diagrams that are used in UML as an implementation diagram for specifying the dependencies among software components.

  - TDPD: Tool for Deployment Diagrams. This tool is intended for Deployment Diagrams that are used in UML as an implementation diagram for specifying the structure of the run-time system.

- Miscellaneous Editors.

  - TERD: Tool for Entity Relationship Diagrams (classic). This tool is intended for classic entity relationship diagrams (ERDs) that are used in Entity Relationship (ER) modeling [3]. The ER method is explained in [22].

  - TCRD: Tool for Class-Relationship Diagrams. This tool is intended for class-relationship diagrams (CRDs) that are used in object oriented modeling. The CRD notation variant that TCM supports is explained in appendix A.3.2. TCRD is similar to TSSD and is actually the predecessor of TSSD.

  - TDFD: Tool for Data Flow Diagrams. This tool is intended for data flow diagrams (DFDs) that are used in the method of Structured Analysis (SA) [8,30]. This method is discussed in [22]. The technique is explained in appendix A.3.3. The notation of TDFD is a subset of the TEFD editor; i.e. TDFD only edits diagrams without control processes and event flows.

  - TPSD: Tool for Process Structure Diagrams (JSD). This tool is intended for process structure diagrams (PSDs) that are used in the Jackson System Development method (JSD) [11]. The JSD method is discussed in [22]. This technique is explained in appendix A.3.4.

  - TSND: Tool for System Network Diagrams (JSD). This tool is intended for system network diagrams (SNDs) that are used in the Jackson System Development (JSD) method [11]. The JSD method is discussed in [22]. The technique is explained in appendix A.3.5.

  - TRPG: Tool for Recursive Process Graphs. This tool is intended for recursive process graphs (RPGs), also known as life cycle diagrams. This technique is explained in appendix A.3.6.

  - TTDT: Tool for Transaction Decomposition Tables. This tool is intended for transaction decomposition tables. These tables are used in some of the methods presented in [22]. The technique is explained in appendix A.3.7.

All editors look very similar and have many operations in common. All diagram editors have almost the same set of edit commands and all table editors have almost the same set of edit commands. TCM supports constraint checking for single documents (e.g. name duplication, cycles in is-a relationships). TCM distinguishes built-in constraints (of which a violation cannot even be attempted) from immediate constraints (of which an attempted violation is immediately prevented) and soft constraints (against which the editor provides a warning when it checks the drawing). TCM is planned to support hierarchic graphs, so that it can handle for example hierarchic statecharts. Features to be added later include constraint checking across documents and executable models.

## 1.1.3 Using TCM in Software Specification

Figure 1.1 gives an overview of how the different document editors in TCM can be used in various methods for software specification. Each of these methods uses a subset of the notations available in TCM and defines a number of consistency rules across notations. Thus, each method allows the specification of a model of the required software product and uses different notations to specify different views upon this model. The consistency rules guarantee that there is a model that is being specified. Views that are inconsistent according to these rules, do not represent a model. The consistency rules of ER, DF and JSD are defined in [22] and the consistency rules of YSM are defined in [31]. The current TCM version does not yet implement all the consistency rules of these methods. The implementation of consistency rules of these methods is planned for TCM version 3.0 as is described in [6].

The same applies to object oriented (OO) methods, in particular those using UML. TCM currently contains a number of tools for drawing diagrams for OO models, albeit sometimes incomplete or in a bit different notation than the standard. However, in the future we want to build support for integrated OO modeling with UML into TCM as well.

In TCM there is and will be no consistency checking for other methods such as the ISAC [12] and Information Engineering [13] methods. But tools for TCM can be used to draw the diagrams.

Figure 1.1: Using TCM in several software specification methods.

# 1.2 How to Read this Manual

If you want to try TCM for the very first time, you first have the read section 1.4 to get started. You probably do not have to read much more of this manual for carrying on. The user interface is designed to be as intuitive as possible and to be proof against users who are trying things at random. The most important commands that you need are explained in the on-line help windows.

This manual is intended to be a reference manual for the user in the first place, hence the amount of details. You certainly need not read it all to be able to use TCM. Chapter 2 describes the common features between all TCM editors, such as saving documents, loading documents, printing documents etc. Chapter 3 describes how you edit a diagram abstracting from a particular diagram editor. In chapters 4, 5 and 6 you find all the material specific to the different diagram editors, grouped by data view editors, behavior view editors and function view editors, respectively. These chapters are organized in the same order as the list of diagram editors in section 1.1.2. Chapter 7 describes how you can edit tables in general and it explains the (small) differences between the four table editors. Chapter 8 describes how to edit a tree document in general and it explains the differences between the two tree editors. In appendix A a mini tutorial is given to the notations and methods supported by the TCM tools. In appendix B, there is a list of frequently asked questions (FAQ). In appendix C there is a specification and explanation of the TCM file format.

You can search for information in this manual either top down, via the table of contents, or bottom up, via the index pages at the end.

# 1.3 How to Obtain the Latest Version of TCM

There is an ftp site ftp://ftp.cs.utwente.nl/pub/tcm from which you can download distributions with binaries for different Unix platforms. A mirror of the TCM ftp site can be found at
ftp://ftp.cs.vu.nl/pub/tcm. See the file `README` on the ftp site for more details.

Currently, TCM runs on Solaris 2.x (Sparc and x86), SunOS 4.x (Sparc), Linux (x86), OSF/1 (Digital Unix on DEC Alpha), IRIX 6.x (SGI), AIX 4.x (RS6000) and HP-UX 10.x. There is also a distribution with the source code. Each distribution contains binaries of the TCM software and recent user documentation. The source code distribution contains no binaries but the source code, the user manual and technical documentation (developer's guide, source code documentation, specifications etc.). Solaris Sparc and Linux x.86 are the platforms on which we develop and for which the most recent binaries are available. The source code of TCM is publically available, under the GNU public license. See the file COPYING in the TCM ftp distribution directory.

TCM has as home page http://www.cs.utwente.nl/~tcm. This page contains supplementary information about TCM. It is possible to download the TCM software via the page
http://www.cs.utwente.nl/~tcm/software.html. You can find a HTML version of the recent version of the user manual in http://www.cs.utwente.nl/~tcm/usersguide/index.html. The user manual is also contained as PostScript file in the `doc` subdirectory of each software distribution. There you can also find the manual as a set of HTML files. If you plan to upgrade TCM, see the file `CHANGELOG` on the ftp site for the most important changes between the consecutive versions.

#
1.4 Installation and Getting Started

TCM runs on Unix systems with X Windows version 11 release 5 or higher and uses the Motif library release 1.2 or higher for the graphical user interface. Instead of the official Motif it is also possible to use the free Motif-clone Lesstif. For Linux we have made some distributions in which the Motif library is already linked with the TCM executables. These statically linked distributions carry the name `statmotif` as part of their name. For using these distributions you don't need Motif or Lesstif at all.

For up-to-date system specific information see http://www.cs.utwente.nl/~tcm/software.html and read also the file `INSTALL` in one of the software distributions before you install and use TCM.

## 1.4.1 Unix tar-files with binaries

Most TCM distributions are in the form of a Unix `tar` file compressed with the `gzip` program 1.1. To install a binary distribution (a tar.gz file) unzip and untar the TCM distribution by for instance: `tar xzvfp 'distribution'.tar.gz`. If your tar-program does not know the `z`(unzip) option then unzip the file explicitly by e.g. `gunzip`. A new directory named tcm-'version'/ will be created in the current directory containing the TCM binaries and documentation in subdirectories.

Every user of TCM should set the `TCM_HOME` environment variable to the directory where TCM is installed. It is recommended that they add `$TCM_HOME/bin` to their `PATH` and add `$TCM_HOME/man` to their `MANPATH` environment variable. TCM will not work when `TCM_HOME` is not set. Do not forget to export these variables. It is a good idea to set the variables in your `.profile` or `.login` startup script of your Unix shell.

The distributions for Solaris contain shared object libraries. If you have one of these distributions and you have TCM installed in a directory other than `/opt/tcm`, each user should include this directory in the `LD_LIBRARY_PATH` variable by for instance: `LD_LIBRARY_PATH=$TCM_HOME/lib:$LD_LIBRARY_PATH`. Users of Linux do not need to set `LD_LIBRARY_PATH`. To configure amongst others the path names of some external Unix programs that are used by TCM you can modify the `$TCM_HOME/lib/tcm.conf` file.

## 1.4.2 RPM distributions with binaries

For Linux we have also provided the software in the form of RPM packages. These distributions work with Redhat 6.0 and Redhat 6.1 and almost certainly with any other Linux system that has support for RPM. Install the distribution by:

    rpm --install tcm-<version>.i386.rpm

Or upgrade an existing distribution by:

    rpm --upgrade tcm-<version>.i386.rpm

By default TCM is installed in `/opt/tcm`. With the rpm option `-prefix` <`dir`> you can install it in a different directory. Some of the documentation will be installed by default in
`/usr/doc/tcm-`<`version`>. There are two sorts of binary RPMs. One contains the name `statmotif` and the other `dynmotif`. The first sort have Motif statically linked into the executables. The `dynmotif' RPMs are dynamically linked against Motif 1.2. It uses the libXm.so (version 1.2) of Motif or Lesstif on your system. The RPM installation creates some initialization scripts for TCM in `/etc/profile.d`. It is therefore not necessary to set yourself environment variables like for the tar.gz distribution. You only have to login again before you start using TCM.

## 1.4.3 Source code distributions

This is not treated in this document. See the file `INSTALL` contained in the source distribution for how you can compile TCM quick and easy. The source code also contains an extensive developer's guide that explains all ins and outs of compiling and porting TCM on your system.

## 1.4.4 Starting up

You can start a particular tool in two ways:

Figure 1.2: The TCM startup window.

1.
  Call it from the program `tcm`. `tcm` displays a window containing a push button for each available editor (see figure 1.2). To start an editor, click the corresponding button. The diagram and tree editors are started up immediately. When a table editor is chosen, first a dialog is displayed in which you can change some options. Be careful, because each time you click a button a new editor is started.

  To kill the `tcm` startup program issue `Quit` from the File menu. The processes of the running editors are independent from the running startup program, so when you quit a startup program, all other programs continue to run.

2.
  Call the editor directly from the shell, e.g. `tesd`, `tefd`, `tssd`. Perhaps you want to end the command with an ampersand (like `terd&`) to run it in the background. You can supply a single document name as command line argument. If this argument is the name of an existing file then the editor tries to load a document from it. If the document does not exist, a new document is created in the editor having the argument as document name. In section 1.4.5 we give an overview of the flags that can be given in the command line and the Unix environment variables that are used by TCM.

##
1.4.5 Unix options, files and variables

The Unix manual pages in the TCM distribution give an up-to-date overview of all arguments, environment variables and files that are used by TCM. Here we will give some explanation of the most important ones. TCM has the following command line arguments:

- Filename. This will be the document name when the editor is started, instead of `untitled`. If the file exists and contains a valid document for the concerning editor, the document is loaded while starting up. If the file does not exist, only the document name in the editor will be modified.

- `-drawing` Width `x` Height. Specifies the size of the drawing area in pixels. The default size is 1330x1330 pixels 1.2. Increasing the values makes it possible to draw larger documents, but it can slow down the editor significantly. Smaller values make it possible to run TCM faster on a machine with little memory. You can change the default size also in the configuration file `$TCM_HOME/lib/tcm.conf`.

- `-help`. Write all allowed command line arguments to standard output and exit.

- `-maxdrawing` Width `x` Height. The drawing area can not be larger than width pixels wide and height pixels high. The default maximum values are 3000x3000 pixels. When the drawing is larger than the current drawing area, the drawing area is made larger up to this maximum. However, when the drawing area is extremely large, the editor becomes slower and may eventually crash because there were insufficient resources to allocate the background pixmap.

- `-priv_cmap`. Start the editor with a private color map. Normally editors use the default color map. When there are not enough colors available in the default color map for the main window on startup, the editor is always started with a private color map, whether this option is given or not. It is possible to set in `$TCM_HOME/lib/tcm.conf` that you always want to start editors with a private colormap.

- `-projdir` directory. Set the project directory (working directory) to this directory. Files are loaded from and saved in this directory.
- `-version`. Write the TCM version to standard output and exit.

- In addition to these options, the standard X11 toolkit options such as `-bg` and `-display` are accepted as command line arguments (see the X window man page, X(1) or X11(7)).

All editors additionally have some optional command line arguments to generate printable output directly from an existing document file. When these options are given, no windows are created, but the X display is used however, so you should run X Windows with an opened display. These options are:

- `-toEPS [`<`outputfile`>`.eps]`. Generate Encapsulated PostScript from existing document and write it to the optional `<outputfile>.eps` or standard output and exit.

- `-toFig [`<`outputfile`>`.fig] [-latex]`. Generate Fig format from existing document and write it to the optional <`outputfile`>`.fig` or standard output, when no file name is given, and exit. When the `[-latex]` option is given, LATEX fonts are generated, otherwise normal Postscript fonts are generated. For more information about Xfig and its file format see http://www.xfig.org/userman.

- `-toPNG [`<`outputfile`>`.png]`. Generate PNG graphics format from an existing document and write it to optional <`outputfile`>`.ps` or standard output and exit. PNG is a format that is understood by most web browsers and by MS-Word. PNG is similar to the GIF-format but less controversial (see this article and http://burnallgifs.org). Generation of PNG format is done with the `fig2dev` command that processes a temporal fig file. fig2dev is part of the Transfig package that can be downloaded from ftp://www-epb.lbl.gov/xfig.

- `-toPS [`<`outputfile`>`.ps]`. Generate PostScript from existing document and write it to optional<`outputfile`>`.ps` or standard output and exit.

Table editors additionally have the following optional command line arguments:

- `-cell` Width `x` Height. Sets the default cell size of the table editor to width pixels wide and height pixels high.

- `-table` Rows `x` Columns. The table editor will be initialized with a table having rows rows and columns columns.

The TCM tools depend on the following files and programs:

- `$TCM_HOME/bin/psf`. A Perl script that is used to filter PostScript output written by TCM. It assumes that the Perl interpreter is in `/usr/bin/perl`. Otherwise, you have to edit the first line of `$TCM_HOME/bin/psf` to make it call your local interpreter 1.3. Psf is supplied with TCM and can be used stand alone as well, see `man psf`.

- `$TCM_HOME/bin/text2ps`. A small program that converts ASCII text files to PostScript. It is used by TCM for printing text, for instance the on-line help pages. Text2ps is supplied with TCM and can also be used stand alone, see `man text2ps`.

- `$TCM_HOME/lib/tcm.conf`. This is the TCM configuration file. This file contains initialization values for the tools, like the default export format, the various print banner options, the default page size, the scale and grid settings etc. Each tool reads this file upon startup. The menu entries of the editor are initialized with the values from the configuration file. The settings in `tcm.conf` are already set to default values, but, when you have installed TCM, feel free to adjust them to your favorite settings. In the configuration file itself you find directions for how to modify it.

  Some settings in `tcm.conf` are commented out such as the name of the printer, the Unix commands to print a file, to view or remove a print request. The reason is that TCM normally determines these settings itself but in case the commands are not found or the wrong ones are chosen then they can be set explicitly in `tcm.conf`.

- `$HOME/.tcmrc`. Each user of TCM can override any setting in `tcm.conf` by his own configuration file, which has to be installed in `$HOME/.tcmrc`. The file syntax should be the same as of the TCM configuration file `tcm.conf`, i.e. of the form `{` option value `}`.

- `$TCM_HOME/lib/TCM`. This file contains some X Resources. These X resources are already built-in in the tools, so this file is not read in by TCM. But you can customize with this file the fonts and colors of the Motif widgets that TCM uses, by setting these resources with different values in your X defaults database. Each string of the form ``TCM.resource:definition'' sets a resource. See question B.18 in the FAQ for how exactly you can set X resources.

- `$TCM_HOME/lib/banner.ps`. PostScript banner page that can be used when you explicitly want to print a banner page. To use this banner by default you have to edit `tcm.conf` or ``.tcmrc``.
- `$TCM_HOME/lib/colorrgb.txt`. This is a text file with the names of the colors that can be used in TCM, together their associated RGB (red, green, blue) values.

- `$TCM_HOME/lib/help/`. This is a directory that contains a collection of plain text files for the on-line help windows that are issued via the entries of the Help menu. If you have installed TCM, make sure that these help files are readable for all users.

The TCM editors depend on the following Unix environment variables.

- `LD_LIBRARY_PATH`. If TCM is installed in a directory other than `/opt/tcm` and the TCM distribution has shared object libraries 1.4, it is necessary to append `$TCM_HOME/lib` to this variable. Otherwise the shared libraries can't be found by TCM. In the FAQ in appendix B you will find more information about shared libraries and this variable. Also, if your X- or Motif libraries are in a non-default place then it can be necessary to set this variable.

- `MANPATH`. You are advised to add `$TCM_HOME/man` to your MANPATH. Each tool has a short Unix manual page. E.g. `man terd` will show the man page of the ER diagramming tool TERD.

- `PATH`. You are advised to add `$TCM_HOME/bin` to your PATH.

- `PRINTER`. The name of the default printer for printing documents. This variable can be overridden by the `PrinterName` option in the TCM configuration files.

- `TCM_HOME`. The parent directory of the directories where the TCM binaries, libraries and manual pages are expected to reside. The tools will not start when `TCM_HOME` is not set. When `TCM_HOME` is set to the wrong directory, the configuration and help files can not be read, which will be reported upon start up.

##
1.4.6 Graphical User Interface

The user interface of TCM complies for a large part with the OSF/Motif Style Guide [15]. The user interface is built from the OSF/Motif widget set [14]. The result is that user interaction through menus, dialogs, buttons, scroll bars and text areas work in the same way as other Motif applications and environments such as for instance Netscape for X Windows and CDE (common desktop environment). Only the drawing of diagrams and tables itself is quite different and this part does not make use of Motif. In any case, the TCM editors should be well-behaved under all popular X Window managers, e.g. kde, gnome, fvwm, mwm, etc. In [16] you find the specification of the user interaction with Motif applications in general, so it is not necessary to repeat that in this manual. TCM looks optimal on a full color display and a resolution of at least an XVGA screen (1024x756). It should still be usable though on a black and white display and/or an SVGA screen (800x600). For more detailed information about the other system requirements of TCM regarding Motif, X Windows and Unix see appendix B.

# 1.5 Questions and Comments

Questions and comments about the TCM software and about this manual are welcome and can be sent by e-mail to the TCM mailing list tcm-users@cs.utwente.nl. You can subscribe by sending an empty message to: tcm-users-request@cs.utwente.nl. Mail that is only intended for us (the authors) can be sent to tcm@cs.utwente.nl.

Before you ask questions that were already asked and answered before: Appendix B contains a collection of frequently asked questions (FAQ).

#### Footnotes

... program 1.1
  gzip (GNU zip) is a compression utility designed to be a replacement for ``compress''. It can be downloaded from ftp://ftp.gnu.org or from one of the many mirror sites that are mentioned inhttp://www.gnu.org/order/ftp.html.
... pixels 1.2
  one pixel is 1/83 inch, which is about 0.306 millimeter.
... interpreter 1.3
  When your system does not have Perl at all, this is not an major problem. Only the Print duplex and tumbled page options do not work.
... libraries 1.4
  This is the case when the directory `$TCM_HOME/lib` contains files ending on `.so`.

Next: 2. Document Editing Up: Toolkit for Conceptual Modeling Previous: List of Figures