Garbo

home *** CD-ROM | disk | FTP | other *** search

/ Garbo / Garbo.cdr / pc / science / atk1ibm.zoo / tutorial.txt < prev

Wrap

Text File | 1991-05-12 | 63.4 KB | 1,794 lines

----------------------------------- / A N A L Y S T T O O L K I T / ----------------------------------- || || \/ --------------------------------------------------------- / Copyright (C) Chinook Software Group 1986, 1988, 1991 / / all rights reserved / --------------------------------------------------------- || || || \/ ========================== / Chinook Software Group / / P.O. Box 24536 / / Denver, CO. 80224 / ========================== ======================================================== / This tool suite enables a user to perform top-down / / system specification using the Structured Analysis / / Methodology ( Data Flow Diagrams ). Diagrams are / / entered and manipulated graphically, but stored in / / textual form for easy access by other tools. Support / / is provided for data dictionary generation and / / analysis, as well as for analysis of the DFDs. / ======================================================== *** NOTICE: PLEASE READ *** This document is the companion to the SHAREWARE CHINOOK Software ATK product. This software has no artificial limitations on functionality or periodic reminder screens of any kind. The CHINOOK SOFTWARE GROUP address and registration fee request appear at the startup of certain tools only. This document and the attendant software is provided as-is and without warranty as to correctness or suitability for any specific application. The CHINOOK SOFTWARE GROUP disclaims any responsibility for the use or misuse of this software by any individual or entity, for any purpose whatever. This disk, with this document on it, may be copied and distributed in its entirety, freely, but may not be modified or sold. If you find ATK instructive and useful, registering your copy with us for $35 will go a long way toward allowing its authors to continue its development. In return, you will be placed on our mailing list to receive information about future releases and other products. In addition, you will be given special consideration with regard to future releases of ATK, and will be sent additional documentation including detailed file formats, evaluation rules, and reference pages for all functions. The asking price of $35 represents more than an order of magnitude price break when compared with similar products currently available. Your support is both needed and appreciated. Please send your contribution to: The Chinook Software Group P.O. Box 24536 Denver, CO. 80224 - ii - TABLE OF CONTENTS Introduction............................................1 This Document......................................1 Tool Synopsis......................................2 Installation............................................4 Hardware Requirements..............................4 Supplied Software..................................5 Procedures.........................................6 Floppy System.................................6 Hard Disk Systems.............................6 The Graphic Editor (GED)................................7 Command Overview...................................7 Controlling GED....................................8 Basic Operation....................................9 The Context Diagram...........................9 Prompts and messages.........................10 Description of a process.....................10 Redrawing a DFD..............................11 Deleting a DFD...............................11 Aborting a DFD...............................11 Saving a DFD.................................11 Naming a DFD.................................11 The Cursor...................................11 Creating Objects.............................12 Moving Objects...............................13 Erasing Objects..............................13 Naming Objects...............................13 Customizing GED...................................13 The Data Dictionary....................................15 Dictionary Syntax.................................15 Data Dictionary Builder (DDBUILD)......................18 Command Overview..................................18 Data Dictionary Evaluator (DDEVAL).....................19 Command Overview..................................19 The Analysis Tool (ANAL)...............................20 Command Overview..................................20 Report Generator.......................................22 Command Overview..................................22 Miscellaneous Tools....................................24 Attach............................................24 GEDPS.............................................24 PS................................................24 KB................................................25 Index..................................................26 - iii - Introduction Introduction The Structured Analysis methodology allows a user to perform a top-down specification of a system from a data viewpoint. The methodology is not limited to software development, but functions well at the requirements and system design levels also. The resulting set of diagrams and the data dictionary augments any documentation effort, and provides a concise, clear picture which may be dynamically maintained along with the system it describes. This Document This document is intended to acquaint those already knowledgeable in the Structured Analysis methodology with the ATK tool package and its use. For those unfamiliar with Structured Analysis techniques, Tom DeMarco's Structured Analysis and System Specification is strongly recommended. A rudimentary knowledge of IBM/PC operation is also assumed. This document provides basic functional information in a tutorial format. Each tool in the set is described, and some examples are provided to illustrate the most common usage. No attempt is made to cover every option or variation possible. It is hoped that a user will grasp the underlying principles of operation quickly, and be able to produce useful work before fully understanding every detail of every command. The document is not complete, but we believe it to contain as much information as the average user will need. If you believe some information should be added to this tutorial to make the toolset more useful, please let us know. Be sure to consult the README.TXT file to get any changes or additions made late in the production cycle. Analyst Tool Kit Shareware - 1 - Revision 041091 Introduction Tool Synopsis The ATK is a collection of application software designed to facilitate the development, analysis, and maintenance of a set of DFDs (data flow diagrams) and their associated data dictionary: + A GRAPHIC EDITOR, called GED, which allows DFDs to be interactively entered and manipulated. Unlike a generic graphics package, GED is specifically designed to work with standard DFD symbology and conventions. GED produces an ASCII format file as output, which can be read (and modified) by text editors as well as the other tools in the package. + A DATA DICTIONARY builder, called DDBUILD, which can read the output of the graphic editor and produce the skeleton Data Dictionary. The data dictionary is an ASCII formatted file which can be read and modified by text editors as well as the DFD EVALUATOR. + A DATA DICTIONARY EVALUATOR, called DDEVAL, which reads the completed data dictionary, parses it for errors, and produces an exception listing. + A DATA FLOW DIAGRAM EVALUATOR, called ANAL, which reads the data flow diagram files and the data dictionary, and reports on conformance to the Structured Analysis methodology guidelines. + A REPORT GENERATOR, called RG, which formats the output of the other tools. It has knowledge files produced by ATK, but may be used as general-purpose formatter. Other tools are also included: + A PostScript GENERATOR, called GEDPS, which converts DFD files into PostScript representations suitable for sending to PostScript printers or layout tools. + A DFD REUSE HELPER, called ATTACH, which copies entire DFD subtrees for reuse on other designs. This version of ATK was originally intended for classroom use and provides an environment in which to study the Structured Analysis method. It was discovered, however, to be practical for a range of small design efforts, and is being offered as SHAREWARE at a price to suit a market neglected by comparable products. The toolkit features: + 8 levels of decomposition below the context diagram. + Data dictionary evaluation limited only by available memory. Analyst Tool Kit Shareware - 2 - Revision 041091 Introduction + Flat ASCII data file formats easily accessible to other tools. + PostScript output from DFDs, suitable for printing or incorporation as EPS documents in publishing systems like Ventura Publisher. + Full function on vanilla PC hardware configurations, with no mouse or expensive graphics cards required. Analyst Tool Kit Shareware - 3 - Revision 041091 Installation Installation Hardware Requirements The toolset primarily targets an IBM PC computer with: + a minimum of 192K of main memory + a standard IBM color graphics adapter (CGA, EGA, VGA)* + a printer capable of doing graphic output (optional, if hardcopy not necessary)** + two 360K floppy drives, or one floppy and a hard drive. + DOS version 2.0 or higher (DOS 3.0 or higher is helpful) The product will run on most all IBM PC compatibles with an appropriate graphics card. The product will run on an IBM PC/AT with an appropriate graphics card. The product will run on an IBM PS2 with an appropriate graphics card. The product will generate conforming PostScript output for DFDs. The product does not require a mouse, but will support one if present*** . The product can be evaluated with a single low-density floppy, albeit with some annoyance. * In particular, Hercules graphic cards have not been tested at the present time (12/90), though they should work. An autodetection feature is used that requires register-level compatibility for a card to be recognized. ** Graphic output can be supported with the standard PrtSc function support (if provided), Epson 9-pin printers in any supported graphics mode, or Postscript. More integrated support is on the way. *** As a note to mouse users, many older mouse drivers did not understand and support EGA and VGA graphics modes. If loading your mouse driver and then running GED does not result in a visible mouse cursor, you should contact your mouse vendor for an updated driver. Analyst Tool Kit Shareware - 4 - Revision 041091 Installation Supplied Software The product is shipped on a single floppy disk containing the appropriate versions of the tool executables, a printable version of this manual, and some example material. At least the following files will be present on your distribution disk: + README.TXT A printable file containing errata, additions, or other noteworthy material. + GED.EXE The Graphics Editor program. + DDBUILD.EXE The Data Dictionary builder/updater program. + DDEVAL.EXE The Data Dictionary evaluator program. + ANAL.EXE The Data Flow Diagram Analyzer program. + CONFIG.ANA A sample configuration file for the analysis tool. This file is optional, and is consulted by ANAL if available. + CONFIG.GED A sample configuration file for the graphics editor. This file is optional, and is consulted by GED if available. + CONFIG.RG A sample configuration file for the report generator. This file is optional, and is consulted by RG if available. + RG.EXE The page formatting utility. + CONFIG.RG A sample configuration file for the report generator. This file is optional, and is consulted by RG if available. + DOC <DIR> A subdirectory containing this document in printable form. + SAMPLES <DIR> A subdirectory containing some pre-written DFDs for practice use, and an example of a data dictionary. + *.TXT Any other required up-to-date information Analyst Tool Kit Shareware - 5 - Revision 041091 Installation Procedures BEFORE YOU DO ANYTHING ELSE WITH THIS DISK, MAKE A BACKUP COPY! Use the diskcopy command as described in your operating system manual to make a copy of the disk. Put the original disk in a safe place and use the copy for the remainder of your work. Floppy System If you are using a dual floppy system the easiest way to use the toolset is to put the tool executables in drive A: and a disk to contain your work in drive B:. The sample material from the supplied disk may be copied to the B: drive for modification, if desired. In addition, you should have a copy of COMMAND.COM somewhere on the PATH, so that the DOS escape in GED, and the auto-execution features of RG will work. You should make the B: drive the default drive, and the directory holding your DFD files the current directory. (The files CONFIG.RG, CONFIG.ANA, and CONFIG.GED should also be here if you intend to use them.) The A: drive should be included in your PATH, so the operating system can find the tools. PATH with no arguments will display the current path setting. The path is usually set by the AUTOEXEC.BAT file when the machine is first booted. Hard Disk Systems Hard disk installations vary with individual user preference. Keep the following points in mind for your hard disk installation. + The tools are standard executables and use no overlays; the tools may reside together or separately, and are subject to the same rules which your operating system uses to locate any type .EXE file (e.g., PATH). + The DFDs being worked on are, by default, in the current directory. This implies that each set of DFDs (each project) should reside in a separate directory. + The files CONFIG.GED, CONFIG.ANA, and CONFIG.RG must reside either in the current directory, in the directory pointed to by environment variable "ATK", or in the directory containing the executable image (DOS 3.0 and above). Each set of DFDs (each project), may have its own set of setup files. Analyst Tool Kit Shareware - 6 - Revision 041091 The Graphic Editor (GED) The Graphic Editor (GED) The graphic editor, called GED, is the means by which graphic representations of DFDs are entered, viewed, and manipulated. The output of GED is a graphic rendition of the DFD on a CRT or graphic printer, and an ASCII file containing a formatted description of the DFD which the analysis tools can read. The DFD file may be created or manipulated with any text editor which doesn't put extraneous characters into the file. This would normally only be done in environments which can't support GED. (i.e. no graphics card) Command Overview The simplest invocation is to type GED at the system prompt. This would cause GED to consult the file CONFIG.GED in the current directory, if such a file exists, and to call the context diagram to the screen, if it exists. If no context diagram exists in the current directory, GED will provide a screen for its creation. This would be the proper beginning of a new project. The full command line syntax for GED is as follows: GED [-flags] [initial-diagram-number] where brackets [] indicate optional specifications possible flags are: -q loads diagrams "quietly", that is, without detailed error reporting. -Eeditor uses 'editor' as the minispec editor instead of EDLIN -ppath uses 'path' as the project directory instead of the current directory, if it exists. -m6 will set the graphics mode to mode 6 (B&W-600x200). This is useful if a user has an EGA or VGA card, but the only print screen utility available is GRAPHICS.COM (which is only for CGA mode). Such a user may create diagrams in the default mode, but should use the -m6 switch to prepare to print the diagrams. The initial-diagram-number is specified in standard DFD dot notation. Example: 0.2.3 is the diagram describing the third process in the diagram describing the second process in the diagram below context. Analyst Tool Kit Shareware - 7 - Revision 041091 The Graphic Editor (GED) Remember that if no diagram number is given, the context diagram will be called or created. The context diagram has the special number -1, and the diagram describing the context process is 0. Example: GED -q -pB:\MYPROJECT\ 0.2.5 will invoke GED, and silently load DFD number 0.2.5 from the directory B:\MYPROJECT\. Controlling GED The majority of commands within GED are given using the function keys located to the left of the main keyboard (on an IBM PC). The default mapping of GED commands to these keys is shown below. Use the cardboard overlay provided (or make one) until these keys become familiar. The file CONFIG.GED provides for remapping most of the keys, should our choices not be yours. In the list below, <shft> means to hold the shift key down before pressing the indicated function key, while <alt> means to do the same with the alt key. <F1> create process <shft><F1> visit DFD <F2> name object <shft><F2> name DFD <F3> create external <shft><F3> create text <F4> move object <shft><F4> unassigned <F5> create store <shft><F5> double <F6> save DFD <shft><F6> abort DFD <F7> create flow <shft><F7> route <F8> redraw DFD <shft><F8> exit GED <F9> visit child <shft><F9> visit parent <F10> delete object <shft><F10> delete DFD Most operations can also be done by holding down the Alt key and typing the mnemonic for the action. For example, a process can be created with Alt-P. Some additional special functions are provided by the following keys. COMMAND.COM must be available on the PATH for <A> and <S>. <esc> the escape key is used to cancel a partially completed operation. <^P> produces hardcopy of current DFD. You must have a printer capable of graphic rendition installed, and you must have a suitable graphic driver installed, as per the DOS User's Guide.* * For example, with an IBM PC, an IBM printer, and a CGA card, you must run GRAPHICS before invoking GED. If PostScript output is desired, GEDPS may be run after the GED session is completed. Epson 9-pin printer compatibles are supported in any graphics mode, through CONFIG.GED. Analyst Tool Kit Shareware - 8 - Revision 041091 The Graphic Editor (GED) <^A> calls the analysis tool (ANAL) from within GED. Only the current diagram is analyzed. <^S> performs a system escape. A DOS prompt appears and any DOS operation may be performed within the limits of available memory. The DOS command. The DOS command EXIT will return you to the graphic editor. <<> (less than key) will increase the size of the current object. <>> (greater than key) will decrease the size of the current object. A-F9 (The F9 key pressed with the Alt key) will visit (or create) the minispec of the current process. Ins The insert key will bring up a menu of objects that can be created Del The delete key will delete the current object C-PgUp (The PgUp key pressed with the Control key) will visit the parent of the current DFD C-PgDn (The PgDn key pressed with the Control key) will visit the child of the current process. Finally, GED can also be controlled using an optional mouse. Each mouse button can have an assigned action; for commands like Move and Create Flow, the mouse buttons get temporary new assignments. The default mouse actions are Visit Parent for the left button, Visit Child for the right button, and Move for the middle button (if any). Mouse buttons also have context- sensitive meanings. For instance, pressing the left button after starting a Flow identifies the endpoint, while the right button identifies a route point. Prompts requiring yes or no answers can be answered Yes by pressing the left button, and No by pressing the right button. Basic Operation Basic graphic concepts and operations for constructing and manipulating DFDs are summarized below. The manual provided to registered users contains a more complete description of each of the commands available. The Context Diagram DFDs are organized in the familiar inverted tree structure. The root node of every DFD tree is called the context diagram. If GED is called with no DFD number specified, the context diagram will be called. If the context diagram does not exist, it will be created. Analyst Tool Kit Shareware - 9 - Revision 041091 The Graphic Editor (GED) The context diagram, numbered -1, has only one process intended to show the scope of the project at hand. The process number is 0. (GED will draw this process for you in the context diagram, however, lower-level diagrams will contain nothing but text when they are first created.) The name of the context diagram is "CONTEXT" and cannot be changed. To try this on a real diagram, try the command line GED -p sample1 from your installed ATK directory (Use Shift-F8 to exit when you wish--other descriptions in this section assume the diagram is still available). Prompts and messages GED will prompt the user for information and confirmation in a number of circumstances. GED will also supply informational messages as appropriate times. These messages will always appear on the last two lines of the screen. User-entered input will always appear on the last line of the screen. User-entered input is always terminated by the <Enter> key, and is always cancelled through the <Esc> key. Any "yes" or "no" response can be answered with a y or n. The default is "yes". Description of a process The description of process 0 is DFD 0. A DFD inherits its number and name from the number and name of the process it decomposes. The names of DFDs below context are user selectable, however the analysis tool (ANAL) will complain if the name of a DFD does not match the name of the process it decomposes. A DFD must have at least one process, and should have no more than 8 (up to 50 are supported, however). DFDs in the tree are visited by using the 'visit child', 'visit parent', or 'visit DFD' keys. If the visited DFD does not exist, it will be created. If you press the F9 key while the cursor is located on the process in the center of diagram -1; you will see diagram 0 become visible. If a process is so well-defined that it can be described textually rather than being decomposed, use the 'visit minispec' key to edit the text description. If the minispec does not exist, it will be created. If you decide to decompose the process later, GED will prompt you to delete the minispec. Analyst Tool Kit Shareware - 10 - Revision 041091 The Graphic Editor (GED) Redrawing a DFD A DFD may be re-drawn by pressing the 'redraw DFD' key. This key is useful in eliminating occasional artifacts produced as a result of drawing and moving objects. You can get a feel for the speed of this operation by pressing F8 while a diagram is visible. Deleting a DFD A DFD may be deleted (removed from the disk) by pressing the 'delete DFD' key when the DFD is being displayed. In deleting a DFD, all children and minispecs of that DFD will be deleted as well. To experiment with this, please create a diagram or set of diagrams you are willing to lose first. Aborting a DFD Pressing the 'abort DFD' key will discard all work done since the last time the DFD was saved. The DFD is re-read from disk and displayed. Saving a DFD Pressing the 'save DFD' key will cause the DFD as currently displayed to be written to disk. A new DFD is not permanent until it is saved. Naming a DFD Pressing the 'name DFD' key will allow for naming or re-naming the current DFD, except for the context diagram. The Cursor When a DFD is on the screen, a graphic cursor will be visible. This cursor is used to point to graphic objects to be placed, erased, moved, named, or otherwise manipulated. The cursor is controlled by the cursor pad keys on the right side of the keyboard of an IBM-PC or compatible. On machines with separate cursor and numeric pads, the cursor control can be switched to the numeric pad by turning off the Num Lock key. There are two cursor speeds. The numeric keypad/cursor keys will provide coarse motion in any of the 8 directions. A 'fine' cursor is available as well. The fine cursor will move left, right, up, and down via the 'H', 'L', 'K', and 'J' keys respectively. The 'C' key will always jump to the center of the screen. Analyst Tool Kit Shareware - 11 - Revision 041091 The Graphic Editor (GED) For an object on the screen to be selected, the cursor should be somewhere inside its perimeter (for closed objects), or very near the object (in the case of flows, flow splitters, and boundary points. The object selected is displayed at the bottom of the screen. Creating Objects In general, objects are created by moving the cursor to the desired screen location of the object, and pressing the appropriate 'create' key, or by selecting from the menu-like selection of the 'create-any' key. This holds true for processes, externals, and stores. An opportunity to name the created object will be provided. Names should be alphanumerics, space, dash, and underscore characters. Boundary points are automatically created at the end of flows which don't terminate on any other known object. Boundary points are not named. Flows are created by positioning the cursor on the object at which the flow will originate, pressing 'create flow', moving the cursor to the object where the flow will terminate, and pressing 'create flow' again. GED will prompt for a flow name; if the flow did not terminate where you desired, the Cancel key (escape) will allow you to start again. The direction of the flow can be altered with the 'double' key after the flow is created. If one end of a flow rests on another flow, a flow splitter will be created with no arrow at the junction. Flow splitters are not named* . Flows may be maneuvered around other objects by creating route points on them. Route points can be added while creating a flow using the 'route' key. If you add an unwanted route point, you can cancel it by pressing the escape key. You may then continue with the flow. Stores come in single line and double line varieties. The 'create store' key initially draws a double line store. The 'double' key may then be used to toggle between the two representations. Descriptions are a single line of arbitrary text which can be placed anywhere on the diagram. Descriptions are not analyzed in the diagram, so their contents do not conform to other objects' naming conventions. * Flow splitters are implemented as route points in ATK. Analyst Tool Kit Shareware - 12 - Revision 041091 The Graphic Editor (GED) Moving Objects An object may be moved by selecting the object with the cursor and pressing 'move object'. The selected object will disappear, and the cursor will change to an icon of the moved object. The user then moves the cursor to the desired location for the object, and 'move object' pressed again. The operation is so designed that hitting the 'move object' key twice without moving the cursor will cause no change in the object's position. Flows may not be moved directly. They are automatically moved when objects they are connected to are moved. A flow name may be moved to any point on the diagram; the position is relative to the two endpoints of the flow. If 'move object' is pressed while the cursor is on a flow line a route point object is created and can be moved. The flow line passes through each of its route points before terminating. Erasing Objects When 'delete object' is pressed with the cursor selecting some object, the object will be deleted. Deletion will prompt for confirmation, unless the user has configured GED otherwise. Naming Objects Pressing the 'name' key allows for the naming or re-naming of an object. When renaming an object, the usual DOS command-line editing capabilities are available: F1 or right arrow copies one character from the old name, F4 or delete removes one, and F3 copies the remainder of the old name. Customizing GED GED can be customized by entering configuration lines in the CONFIG.GED file. A few of these lines are described below. A complete set can be found in the ATK reference manual. ERROR=X Sets the error file to be the file X. This setting is recommended (e.g., ERROR=GED.ERR). Otherwise, errors print to the screen (where they are quickly erased). MODE=n Sets the graphics mode to the given number. For the IBM PC, examples are 6=B&W 640x200; 16=Color 640x350 EGA; 17=B&W 640x480 VGA; 18=Color 640x480 VGA. PROCESS COLOR=n Sets the color of processes to the color index given. These indices are mode- and palette- dependent. (Similarly for EXTERNAL, STORE, FLOW, TEXT) PRINTER PORT=X Sets the printer port to the given device name. Default is LPT1. Analyst Tool Kit Shareware - 13 - Revision 041091 The Graphic Editor (GED) PRINTER MODE=n Sets the printer mode for Epson 9-pin and compatibles. Supported modes for the IBM PC are -2 Use Epson driver, preassigned modes -1 Use INT5 support (default if mode unspecified) 0 60 DPI 1 120 DPI 2 High speed 120 DPI (assigned modes 6,17,18) 3 240 DPI 4 80 DPI 5 72 DPI 6 90 DPI (assigned for other modes) EDITOR=X Sets the default editor for minispecs to path X. NOMOUSE Turns off mouse support, even if a mouse driver is loaded. Useful if running GED from an external application that wishes to retain control of the mouse. In all, more than 30 customization commands are supported. Analyst Tool Kit Shareware - 14 - Revision 041091 The Data Dictionary The Data Dictionary Flows and stores in a DFD are potentially decomposed into a series of more detailed flows and stores in the DFDs child. For instance, a flow named user-requests in a particular DFD would probably decompose into several flows in the child. The graphic representation of a DFD does not show the relationship between a flow and its decomposition. The Data Dictionary is an ASCII document specifying this and other relational information, and goes hand in hand with the set of data flows. Dictionary Syntax The Data Dictionary is an ASCII file, and consists of a list of sentences, each terminating with a period. A sentence consists of a left hand side followed by an equal sign followed by a right hand side. The left hand side consists of the name of the thing being described, such as the name of a flow or store. The right hand side consists of one of the following: + the term TBD meaning "To Be Defined". This is a place holder, indicating that a proper description will be supplied later. + the word PRIMITIVE, which defines an axiomatic entity not to be decomposed further. + a symbolic description of the item in terms of its component items. This description will include one or more other item names, and may use certain symbols to indicate sequences, repetition, choice, or optional components. The exact syntax of legal data dictionary statements is supplied in the manual, and is described in its own syntax. Persons familiar with formal language specification should have no trouble deciphering this description, but the beginning user will do better to study these prototype examples. Example: A = B + C + D. The item whose name is A is composed exactly of items B, C, and D. The plus sign thus denotes additive composition. Analyst Tool Kit Shareware - 15 - Revision 041091 The Data Dictionary Example: A = B + C + (D). The parentheses around item D indicate that it is optional. That is, an A must have a B and a C, and it may have a D in its composition. Example: A = B + C + {D}. The braces around item D indicate that zero or more iterations of D are required. A number may be used before the opening brace to indicate a lower limit on the number of iterations. Similarly, a number may be used after the closing brace to indicate an upper limit on the number of iterations. For instance, 1{digit}8 would specify a string of from one to eight digits. The absence of a number before the opening brace implies that a minimum of zero occurrences are permitted, while the absence of a number after the closing brace implies that a potentially infinite number of occurrences are possible. Notice, then, that A = B + (C) is the same as A = B + {C}1. Example: A = B + [ C | D ]. The bracket and the vertical bar together specify a list of choices. The example would be read, "A is composed of a B and either a C or a D". Notice that the choice is exclusive, that is, A may not contain both a C and a D. To make the choice itself an optional component, we could write, A = B + ([ C | D ]). which would be read "A is composed of a B, and may include either a C or a D". Whitespace (blanks, tabs, or newlines) may be freely included for readability. Since a single sentence may thus span more than one line, the period which ends the sentence is very important. A comment is a string of text bounded by asterisks. Comments are also terminated by new lines. Comments may be freely included virtually anywhere, even between items in a sentence. If a literal asterisk is needed, prefix it with a backslash. Example: A = B + * this is a comment * C + D. Example: * comments use the \* to identify themselves * To put some of the preceding information together, the following group of sentences specify the syntax of a FORTRAN style integer variable, which must start with one of the letters I thru N, and may contain one thru seven additional alphanumeric characters. Analyst Tool Kit Shareware - 16 - Revision 041091 The Data Dictionary integer_name = first_char + rest. first_char = [I|J|K|L|M|N]. rest = {[ALPHA|NUMBER]}7. ALPHA = letter_of_the_alphabet. NUMBER = DIGIT. letter_of_the_alphabet = PRIMITIVE. DIGIT = PRIMITIVE. Notice that the above description could have been written in a variety of ways, some of them being more concise. The sentence "NUMBER = DIGIT." may seem useless, since it does not decompose NUMBER. In fact, it specifies that NUMBER and DIGIT are aliases , which means that they may be used interchangeably. This feature is useful in a variety of scenarios, such as when portions of a project are specified by different individuals who choose different names for the same thing. Study the data dictionary file called SAMPLE.DCT provided in the SAMPLE subdirectory of the product disk for examples of data dictionary language usage and style. Analyst Tool Kit Shareware - 17 - Revision 041091 Data Dictionary Builder (DDBUILD) Data Dictionary Builder (DDBUILD) DDBUILD is a convenience tool which will scan one or all of the DFDs in a project and extract all the flow and store names used into a preliminary form in the data dictionary. Names appear only once, no matter how many times they are encountered, and are defined equal to TBD. While DDBUILD knows nothing about the intended relationships among the names, it does save the user a tremendous amount of initial typing. The user may then employ any text editor to fill in the necessary information as it becomes available. DDBUILD will create a new data dictionary if one does not exist, or it will append to an existing dictionary. Consider then, that if you change the name of an item in the DFD set and rerun DDBUILD, the new name will be added, but the old name will remain. Command Overview The simplest invocation is to type DDBUILD at the system prompt. In this case DDBUILD will build or add to a file called DATA.DCT in the current directory the names of all flows and stores found in all the DFDs on the primary chain. NOTE: The primary chain is the chain of all DFDs whose first number is 0, such as 0.2.3. It is possible to create DFDs with other digits in the first position, such as 3.4.2. These DFDs are considered to exist on side chains, and are normally invisible to the analysis tools. Side chains are a way of keeping DFDs around without having them enter into the analysis. Such DFDs may be renamed (DOS RENAME command) to make them "active". Notice that DFDs are given filenames which correspond to their dot specifications minus the dots, and file extensions of .DFD. The full command line syntax for DDBUILD is as follows: DDBUILD [-flags] [dfd dfd ... dfd] where brackets [] indicate optional specifications. possible flags are: -i suppress case sensitivity, e.g 'ABC' will be treated the same as 'abc'. -ppath path to use to find DFDs instead of the current directory Flags are optionally followed by a list of one or more DFDs to add to the dictionary. The default is to add all DFDs on the main path (-1 and 0*) Analyst Tool Kit Shareware - 18 - Revision 041091 Data Dictionary Evaluator (DDEVAL) Data Dictionary Evaluator (DDEVAL) DDEVAL will read a project's data dictionary and DFDs and report errors and omissions in the specifications. When invoked by its name alone, it will look for a file called DATA.DCT in the current directory, and will produce its report to the screen. DDEVAL will perform a somewhat detailed analysis of the dictionary, and is able to report such things as aliasing problems, items which are defined but never used, and items which are undefined. Command Overview The simplest invocation is to type DDEVAL at the system prompt. In this case DDEVAL will evaluate the data dictionary file DATA.DCT and give a report to the CRT. The full command line syntax for DDEVAL is as follows: DDEVAL [-flags] where brackets [] indicate optional specifications. possible flags are: -i ignore case in comparisons (Hello = HELLO) -v report version information -ppath use 'path' to locate the data dictionary to evaluate. Example: DDEVAL -PB:\MYSTUFF\ will evaluate the data dictionary and DFDs in directory B:\MYSTUFF. Analyst Tool Kit Shareware - 19 - Revision 041091 The Analysis Tool (ANAL) The Analysis Tool (ANAL) Just as DDEVAL performs an analysis from the standpoint of the data dictionary, the tool ANAL performs a similar analysis from the standpoint of the DFDs themselves. Each DFD is examined and a list of potential errors is produced. Most of the evaluation rules apply to a single diagram while a few require a DFD to be examined in context with its parent. In addition, ANAL uses the data dictionary, which it expects to be called DATA.DCT, to determine flow decomposition and aliasing, and can then look for consistency in the diagrams. Thus, it is wise to build as much of the data dictionary as possible before using ANAL, to avoid excessive numbers of errors concerning flows. Command Overview The simplest invocation is to type ANAL at the system prompt. In this case ANAL will examine all the DFDs it can find on the primary chain, and make its report to the standard output. The full command line syntax for ANAL is as follows: ANAL [-flags] [dfd] where brackets [] indicate optional specifications. possible flags are: -a load data dictionary (DATA.DCT) to resolve aliases for flows and stores -i ignore case in comparisons. (default is case sensitive) -ppath look for DFDs under the directory 'path' DFD is specified in standard dot notation. Example: ANAL -i -pB:\MYSTUF\ 0.2.3 Two major categories of errors are detected. + Object usage errors which include such things as processes with no flows, duplicate names, and data sources/sinks. + Boundary errors which catch problems occurring across the parent/child interface such as the sudden appearance of a single-line store, or the disappearance of a flow. A description of the customization of the analysis process is provided in full in the manual. The analysis configuration file is CONFIG.ANA. Each of the 9 tests can be set to ON or OFF (default is ON). The tests are: process flows store flows process child or minispec flow endpoints flow names duplicate names store double parent child name check parent child flows in parent child flows out Analyst Tool Kit Shareware - 20 - Revision 041091 The Analysis Tool (ANAL) The example in the SAMPLES1 directory is excellent for illustrating this tool. Invoking ANAL will give 30 odd lines of errors; half of them are because some processes do not have child diagrams or minispecs. If we decide we aren't ready to have that level of scrutiny yet, we add the line process child or minispec = OFF to our CONFIG.ANA file. Running ANAL again will give about half-a-dozen errors and warnings. As is typical, 4 of them have to do with naming conventions. A flow that is called 'source code' in one diagram is called 'source language' in another. The data dictionary is used to document and resolve these problems. A line in the data dictionary stating source code = source language. will assert this truth (the period is critical). Similarly, we enter a line process output = output. Running ANAL -a still has 4 error lines, because the diagram has Process Output (and we entered process output). Running ANAL -a -i now has only two warning lines. They indicate that in diagram 0.5, the flows in and out of a store are named, and the name is not an alias of the store. An explanation of why this is an error is that if you have a aluminum recycling bin, you want to make sure no one is putting paper into it. No one has told the data dictionary that a servicable process is a kind of awaiting process (one that can now be serviced). Analyst Tool Kit Shareware - 21 - Revision 041091 Report Generator Report Generator The Report Generator, called RG, is a pretty printer utility capable of paginating the output from the various tools and providing page header and/or footer capability. The utility will access a file, called CONFIG.RG, to obtain default formatting parameters, and can additionally be used to provide simple formatting for arbitrary user generated files. Command Overview The simplest invocation is to type RG {type} at the system prompt, where {type} is a single digit 1,2,or 3, designating the data dictionary, dictionary exceptions, or DFD tree exceptions respectively. The utility looks for the files DATA.DCT (data dictionary), DICT.ERR (data dictionary exceptions), or DFDS.ERR (DFD tree exceptions) and will automatically invoke DDBUILD, DDEVAL, or ANAL to produce them if they are not found. If the output of a tool has been directed to a file with a name other than that expected by RG, the filename should be specified after {type}. NOTE: For the automatic tool invocation to work, a copy of COMMAND.COM must be available on the PATH. A variety of command line options are available with RG, as well as some complex possibilities for CONFIG.RG. The full command line syntax for RG is as follows: RG [flags] report-type [report file] Possible flags are; -P Output the printer initialization string before printing any text, and output the printer term string after printing all text. -ok Use k as the page offset (left margin) -tk Use k as the top margin -bk Use k as the bottom margin -Rs Use string spec s as the report title -Hs Use string spec s as the page header -Fs Use string s as the page footer -If Use file f to initialize RG variables Analyst Tool Kit Shareware - 22 - Revision 041091 Report Generator -lk Use k as the page length in lines -wk Use k as the page width in characters -nk Use k as the page number of the first printed page report Meaning intermediate file type --------- ---------------- ------------- 1 data dictionary [DATA.DCT] 2 data dictionary exceptions [dict.err] 3 DFD-tree exceptions [dfds.err] 4 Generic print file report ---------- 5-9 User defined reports ---------- report file: A report file can be any legal MS-DOS file name The file name will support alternate drives and paths Each report will have a default name (see above). The default titles of user-defined reports can be stored in the preference file. String notation "..." is supported on the command line to collect a string including spaces, except for characters '<', '>', '|', '+', and '=' which may not be used within them (MS-DOS gets them!). Example: RG 2 will generate the data dictionary exception report to the screen Example: RG -P 3 >LPT1: will generate the DFD exception report, and print it to the default printer, using printer initialization strings. Example: RG 4 "-RCurrent Listings,nl,nl" list.txt > list.out will generate a user-defined report called Current Listings from a file called list.txt and put it in a file called list.out. Analyst Tool Kit Shareware - 23 - Revision 041091 Miscellaneous Tools Miscellaneous Tools Attach Data flow diagrams (and their associated minispecs) may need to be reused from one project to the next, or from one part of the project to the next. Also, sets of diagrams may need to be backed up from time to time. The tool provided for these jobs is attach. Attach syntax is ATTACH [-sSOURCE-DIR] [-dTARGET-DIR] From-DFD[*] To-DFD The source and target directories may contain drive and directory information. Use the optional asterisk (*) to copy the entire tree--without it a single DFD will be copied. GEDPS Postscript has become the page description language of choice for desktop publishing. When presenting DFDs, a neat diagram is essential. ATK provides encapsulated PostScript files as output from the GEDPS tool. GEDPS syntax is GEDPS [-r] [-foutput-file] DFD[*] The asterisk is used for wildcarding and is not useful if the documents are incorporated in a desktop publishing system. The output output is normally directed to the screen, so the -f flag is normally supplied. The -r flag is used to rotate the diagrams from their normal landscape orientation on 8-1/2" by 11" paper to portrait mode. The file GEDPS.PS is the Postscript prologue. PS Without a desktop publishing system, it can be difficult to print Postscript files. Traditional Postscript printers are controlled through the serial port, one of the weaker areas of the IBM PC design. A tool which supports simple flow-controlled serial port protocol is required--in the absence of other public domain offerings, we include PS. PS is a very simple program which uses the built in commands to communicate with the serial port. Because of this, PS may lose received characters sometimes. This tradeoff was made in the name of full portability. PS syntax is PS [-p[COM]<1,2,3,4>] [-w] [-b] filename ... The default port is COM2; COM3 and COM4 are only supported if the BIOS (INT14) recognizes them. The port characteristics should be set in advance (for IBM PCs, via the MODE command). The -w Analyst Tool Kit Shareware - 24 - Revision 041091 Miscellaneous Tools option is used to wait after all the files have been sent (in case of suspected error messages); pressing any key will exit. The -b option is rarely useful--it does a binary transfer of the file(s). The option is included for those occasional Postscript image files that contain 8-bit data. KB The CONFIG.GED file allows remapping of keys via lines of the form key-code=action Rather than supply a chart to look up key codes, the KB program prints those codes in the appropriate format. ASCII characters are represented by their codes. Sample actions include PROCESS EXTERNAL STORE DESCRIPTION FLOW CHILD PARENT ROUTE Analyst Tool Kit Shareware - 25 - Revision 041091 Index Index A process, 10 abort DFD, 11 prompt, 10 alias, 17 PS, 24 ANAL, 2,5,9,10,20,22 R ATTACH, 2,24 RG, 2,5,22 B route point, 12,13 boundary point, 12 S C save DFD, 11 chain, 18 side chain, 18 child, 10,11 T CONFIG.ANA, 20 TBD, 15 CONFIG.GED, 13,25 text editor, 7,14 CONFIG.RG, 22 U context diagram, 10 user input, 10 cursor, 11,12 D data dictionary, 2,15,18,19,20,23 DDBUILD, 2,18 DDEVAL, 2 delete, 13 delete DFD, 11 DeMarco, Tom, 1 description, 12 double, 12 E editor, 7,14 F floppy, 6 flow, 12,13 flow splitter, 12 G GED, 2,5,6 GEDPS, 2,24 GEDPS.PS, 24 graphic cursor, 11,12 H hard disk, 6 I input, 10 M minispec, 9,10,11,14 mouse, 9,14 move, 13 N name DFD, 11 name object, 13 P primary chain, 18 primitive, 15 print, 4,8,14,22,24 Analyst Tool Kit Shareware - 26 - Revision 041091