MULTI: Editing Files and Configuring the IDE

Transcription

1 MULTI: Editing Files and Configuring the IDE Green Hills Software, Inc. 30 West Sola Street Santa Barbara, California USA Tel: Fax:

2 DISCLAIMER GREEN HILLS SOFTWARE, INC., MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. Further, Green Hills Software, Inc., reserves the right to revise this publication and to make changes from time to time in the content hereof without obligation of Green Hills Software, Inc., to notify any person of such revision or changes. Copyright by Green Hills Software, Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission from Green Hills Software, Inc. Green Hills, the Green Hills logo, CodeBalance, GMART, GSTART, INTEGRITY, and MULTI are registered trademarks of Green Hills Software, Inc. AdaMULTI, EventAnalyzer, G-Cover, GHnet, GHnetLite, Green Hills Probe, Integrate, ISIM, PathAnalyzer, Quick Start, ResourceAnalyzer, Safety Critical Products, Slingshot, SuperTrace Probe, TimeMachine, and TotalDeveloper are trademarks of Green Hills Software, Inc. All other company, product, or service names mentioned in this book may be trademarks or service marks of their respective owners. PubID: May 20, 2004

3 Contents 1 Introduction 1 The MULTI Integrated Development Environment 2 The MULTI Launcher 4 MULTI Workspaces 5 The MULTI 4.0 Document Set 6 About This Manual 7 Online Help 8 ViewingHelponWindowsSystems 8 ViewingHelponUNIXSystems 9 Conventions Used in This Book 10 Part I MULTI Editing Tools 2 The MULTI Editor 15 The Editor GUI 17 Editor Toolbar 17 File and and Procedure Fields 18 Shortcut Menu 18 Status Bar 19 Getting Started with the Editor 20 Starting the Editor 20 Overview of Editor Features 21 Navigating in Files 22 Using References and Prototypes 22 Searching in the Editor 25 Incremental Searching 25 Interactive Searching Using the Search Dialog Box 26 Searching in Files 30 Using the GoTo Dialog Box 32 Working with Code 34 Indenting Code 34 Working with Comments 36 Highlighting the Boundaries of the Current Block of Code 37 Green Hills Software, Inc. i

4 Part II Contents Working with Columns 37 Working with Multiple Files 39 Merging Files 39 Comparing Files 43 Configuring the Editor 44 Customizing the Editor GUI 44 Configuring the Editor for a Programming Language 44 The index.gsc Configuration File 45 The language.gsc Syntax Definition Files 47 Configuring Auto-Complete 49 3 Editor GUI Reference 53 The File Menu 54 The Edit Menu 57 The View Menu 59 The Per File Settings Dialog Box 61 The Block Menu 63 The Tools Menu 65 The Version Menu 68 The Config Menu 70 The Windows Menu 71 The Help Menu 71 UNIX Dialog Boxes 72 File Chooser Dialog Box (UNIX) 72 The Print Setup Dialog Box 74 4 The MULTI Hex Editor 77 Using the Hex Editor 78 Hex Editor Menus and Keyboard Shortcuts 79 Search and Goto in the Hex Editor 80 Managing Files 5 Using MULTI Workspaces and Shortcuts 83 Creating a Workspace 85 Copying and Moving Workspaces 86 ii MULTI: Editing Files and Configuring the IDE

5 Contents Running Actions and Action Sequences 86 Creating or Modifying an Action Sequence 87 Creating or Modifying an Action 88 Creating MULTI Shortcuts 90 Managing Processes 90 The Launcher GUI 90 Opening Workspaces 91 The Launcher Toolbar 92 The Detail Pane 95 Miscellaneous Dialogs and the Progress Window 96 The Launcher Menus 98 6 Using Version Control with MULTI 105 Configuring Version Control in MULTI 106 Using Version Control with the MULTI Editor and Builder 109 Version Control Options from the Editor 109 Version Control Options from the Builder 110 Automatic Checkout 111 Show Last Edit 111 Revert to a Previous Version of a File 112 Integrating with MULTI Version Control (MVC) 112 Using MVC 114 Entering MVC Commands 114 Version Numbers and Branching 116 MVC Date Format 117 Integrating with ClearCase 118 Working with Views 118 Integrating with CVS 118 Integrating with RCS 119 Integrating with SourceSafe 119 VSS Database Structure Assumptions 120 Required Setup Steps 120 Using the Integration 121 Integrating with PVCS 122 Assumptions 122 Required Setup Steps 123 Using the Integration 123 Green Hills Software, Inc. iii

6 Contents Integrating with a Custom Version Control System Version Control Tools 127 The Checkout Browser 128 Starting the Checkout Browser 129 Using the Checkout Browser 129 Features and Issues Specific to CVS 135 Using the Checkout Editor 136 The History Browser 138 Using the History Browser 138 History Browser File Menu 139 History Browser Shortcut Menu 140 The Diff Viewer 141 Opening the Diff Viewer from the Command Line 141 Using the Diff Viewer 142 Part III Configuring the MULTI IDE 8 Configuring and Customizing MULTI 149 Setting Configuration Options 150 Using the Options Dialog Box 151 Using the configure Command 151 Using Configuration Files 152 Saving Configuration Settings 153 Loading Configuration Files 154 Clearing Configuration Settings 155 Creating Custom Functionality Using Scripts and Macros 155 Using Startup Files 155 Customizing the Graphical User Interface (GUI) 158 Configuring and Customizing Toolbar Buttons 160 Creating and Working with Icons 161 Configuring and Customizing Menus 162 Opening and Accessing Menus 164 Customizing Keys and Mouse Clicks 165 Key and Mouse Locations 167 Key and Mouse Command Special Sequences 168 Inserting a Character Blocked By a Custom Key Binding 170 iv MULTI: Editing Files and Configuring the IDE

7 Contents Configuring Window Docking 171 UNIX Docking Limitations 171 Configuring File Extensions 173 Extension Mapping Files 173 File Format 173 Using a Custom Web Browser with UNIX Configuration Options 177 General Configuration Options 179 General Options Tab 179 Other General Configuration Options 192 Builder Configuration Options 195 Debugger Configuration Options 197 Debugger Options Tab 197 Other Debugger Configuration Options 207 MULTI Editor Configuration Options 215 MULTI Editor Options Tab 216 Other MULTI Editor Options 222 Session Configuration Options 224 Colors Configuration Options 228 More Color Options Dialog Box 232 Color Chooser 232 Deprecated Configuration Options 233 Part IV License Administration 10 Licensing Overview 237 License Types 238 Green Hills License Manager Device 239 Licensing Procedures 240 Important Considerations for License Servers 241 License Server Compatibility 242 Server Codes 243 Using a Dongle 245 Dongle Installation 245 Troubleshooting Dongle Problems 246 Green Hills Software, Inc. v

8 Contents 11 License Administration with the MULTI License Administrator 247 Opening the MULTI License Administrator 248 The MULTI Licensing Wizard 248 Install or Configure License Server 250 Server Settings Dialog Box 251 Requesting Licenses 252 The MULTI License Administrator Window 253 File Menu 255 License Menu 255 Legacy Tools Menu 256 Shortcut Menus 257 Configure Dialog Box 259 Configuration Tools Menu 260 Logging Menu 260 Environment Variables 261 GHSlm Environment Variables 262 ElanLM Environment Variables Green Hills License Manager Device 265 Connecting the License Manager Device to the Network 266 Accessing MULTI License Administrator 267 License Manager Device Web Interface 267 Status Page 268 Configuration Page 271 License Page 277 Help Page 282 Client Configuration 283 Client TCP Port 283 Specifying a License Manager Device 283 Specifying the License Manager Type 285 Redundant License Manager Devices 285 Redundant Server Theory of Operation GHSlm: Green Hills License Manager 287 GHSlm License Server Installation for Windows 289 Installing GHSlm License Server Software 289 vi MULTI: Editing Files and Configuring the IDE

9 Contents GHSlm License Server Startup and Shutdown for Windows 290 GHSlm License Server Installation for UNIX 291 Installing GHSlm License Manager Software on UNIX 291 GHSlm License Server Startup for UNIX and Linux 291 Configuring the GHSlm License Manager Software 291 GHSlm License Administration Utilities 292 Controlling the License Server with wrap_svc 292 Listing Licenses with find_ghs_licenses 294 Log Summary with lic_log_summary 295 Installing Licenses with update ElanLM: Legacy License Manager 299 Important Notes on Using ElanLM 300 ElanLM License Server Installation for Windows 301 Installing ElanLM License Server Software 301 ElanLM License Server Startup for Windows 301 Startup Settings 302 ElanLM License Administration with Windows Utilities 304 Find Available Licenses 305 License Manager Reports with WlmRpt 307 ElanLM License Server Installation for UNIX 309 Installing ElanLM License Manager Software 309 ElanLM License Server Startup for UNIX 309 UNIX Options for ghs_elmd 310 License Administration with Command Line Utilities 314 Administrative Control with elmadmin 315 License Manager Alerts with elmalert 318 License Manager Reports with elmrpt 320 License Activity Report with elmusage 323 Version Information with elmver 323 Log Summary with lic_log_summary 324 Resource Files 325 Restricting the Domain 326 Reserving, Excluding, and Holding Licenses 327 Troubleshooting 330 Green Hills Software, Inc. vii

10 Contents License Server Not Responding ( Unable to Get License for... ) 330 If You Experience License Server Delays 336 Part V Appendices A Editor Commands 343 Navigation Commands 344 Continue Selection Commands 349 File Commands 351 Undo/Redo Commands 354 Clipboard Commands 355 Text Deletion Commands 358 Search Commands 359 Block Commands 360 Indentation Commands 361 Insert Commands 362 Tools Commands 363 Tag Commands 365 Auto-Completion Commands 367 Version Control Commands 369 Help Commands 371 Selection Commands 372 Drag-and-Drop Commands 374 Configuration Commands 376 Mode Commands 377 if Conditional Commands 378 Miscellaneous Commands 380 Deprecated Commands 381 B MVC Command Reference 383 C Third-Party Tools 389 Third-Party Version Control Systems 390 Third-Party Editors 390 viii MULTI: Editing Files and Configuring the IDE

11 Contents Third-Party Editor Settings 391 Using the Editor with Third-Party Tools 392 D Default Key and Mouse Bindings 395 Default Keyboard Shortcuts 396 Cursor Movement 396 Selecting Text 398 Searching 399 Deleting Text 400 Indenting Text 401 Copying, Cutting, and Pasting 401 Undo / Redo 403 Opening, Closing, and Saving 403 Version Control 404 Auto-Completion Keyboard Shortcuts 405 Miscellaneous 406 Default Mouse Bindings 407 First (Left) Mouse Button 407 Second (Middle) Mouse Button 408 Third (Right) Mouse Button 408 Index 409 Green Hills Software, Inc. ix

12 Contents x MULTI: Editing Files and Configuring the IDE

13 Chapter 1 Introduction This Chapter Contains: The MULTI Integrated Development Environment The MULTI Launcher The MULTI 4.0 Document Set About This Manual Online Help Conventions Used in This Book

14 1. Introduction This chapter provides an overview of the MULTI Integrated Development Environment and its documentation set, and then gives a brief introduction to this book, which describes the MULTI tools that are used to edit files and manage projects. The MULTI Integrated Development Environment MULTI is a complete Integrated Development Environment (IDE) designed especially for embedded systems engineers to assist them in analyzing, editing, compiling, optimizing, and debugging embedded applications. The MULTI IDE includes graphical tools for each part of the software development process. The following tools can be launched from within the IDE or as separate standalone programs: IDE launcher MULTI Launcher (mstart) The gateway to the MULTI IDE, which allows you to quickly launch any of the primary MULTI tools, access open windows, and manage MULTI workspaces Editing tools MULTI Editor (me) A graphical editor for modifying text files Checkout Browser (mcobrowse) A graphical viewer for files managed under a version control system Diff Viewer (diffview) A graphical viewer that displays differences between two text files Hex Editor (mhexedit) A graphical editor for modifying binary files Building tools MULTI Builder (mbuild) A graphical interface for managing and building projects CodeBalance (codebalance) A graphical interface for automating the process of optimizing an executable for size or speed INTEGRATE (integrate) A graphical utility for configuring tasks, connections, and kernel objects across multiple address spaces when using the INTEGRITY RTOS 2 MULTI: Editing Files and Configuring the IDE

15 The MULTI Integrated Development Environment Linker Directives File Editor (mldedit) A graphical editor for creating and modifying linker directives files Debugging tools MULTI Debugger (multi) A graphical source-level debugger EventAnalyzer (mevgui) A graphical viewer for monitoring the complex real-time interactions of an embedded RTOS such as INTEGRITY or ThreadX ResourceAnalyzer (wperf) A graphical viewer for monitoring the CPU and memory usage of an embedded system running the INTEGRITY RTOS Script Debugger (mscriptdbg) A graphical debugger for writing, recording, and debugging scripts containing MULTI commands Serial Terminal (mterminal) A serial terminal emulator for connecting to serial ports on embedded devices Miscellaneous and administrative tools Bug Report (gbugrpt) A utility for providing system configuration and tool version information to the Green Hills support staff Green Hills Probe Administrator (gpadmin) A graphical interface for configuring and managing Green Hills Debug Probes (Slingshots, Green Hills Probes, and/or SuperTrace Probes) Graphical Utilities (wgutils) A collection of utilities for analyzing and performing various operations on object files, libraries, and executables produced with the Green Hills toolchain MULTI License Administrator (mlmadmin) A graphical utility for managing Green Hills tools licenses Green Hills Software, Inc. 3

16 1. Introduction The MULTI Launcher The MULTI Launcher (mstart) provides a convenient way to launch frequently used tools, to create new or access recently used files and projects, and to manage MULTI workspaces. All of the main MULTI components can be accessed using the following buttons: Runs a shortcut or an action sequence in the current workspace. Also allows you to create a new workspace or create or edit a shortcut. Opens the Builder on a recent or new project. Opens the Debugger on a recent or new executable. Opens the Editor on a recent or new file. Opens the Checkout Browser on a recent or new checkout. Opens the Connection Organizer or a recent or new target connection. Opens a Serial Terminal using a recent or new connection. Opens the EventAnalyzer (licensed separately). Opens the ResourceAnalyzer (licensed separately). Closes the MULTI Launcher (UNIX only by default). Shows/hides the detail pane of the Launcher. You can also launch the Green Hills License Administrator and (if installed) the Green Hills Probe Administrator from the Utilities menu. During development, you can use the MULTI Launcher as a convenient centralized window manager. You can access any of your open MULTI windows from the Windows menu of the Launcher. 4 MULTI: Editing Files and Configuring the IDE

17 The MULTI Launcher MULTI Workspaces The MULTI Launcher allows you to create and use workspaces. AMULTI workspace is a virtual area where the tools, files, and actions required for a particular project can be organized, accessed, and executed. A workspace is typically created for each top-level project and includes a working directory and a group of related actions for example, opening a project in the MULTI Builder, connecting to a target, or performing a shell command. Actions are grouped into action sequences, so that a single mouse click can perform all the actions in the specified action sequence. For more information, see Chapter 5, Using MULTI Workspaces and Shortcuts. Green Hills Software, Inc. 5

18 1. Introduction The MULTI 4.0 Document Set The primary documentation for using MULTI is provided in the following books: MULTI: Getting Started Describes how to install MULTI and obtain a license, and takes you through creating, building, and debugging an example project. MULTI: Editing Files and Configuring the IDE Describes how to use the MULTI Editor, how to use a version control system with MULTI, how to use the MULTI Launcher, and how to configure and license the MULTI IDE. MULTI: Building Applications Describes how to use the MULTI Builder and compiler drivers and the tools that compile, assemble, and link your code. Also describes the Green Hills implementation of supported high-level languages. MULTI: Configuring Connections Describes how to set up your target debugging interface for use with MULTI and how to configure connections to your target. MULTI: Debugging Describes how to use the MULTI Debugger and its associated tools. These books, and any others you may have received (for example, for the INTEGRITY or ThreadX operating system, or for the Green Hills Debug Probes) are available in the following formats: A printed book Online help, accessible from most MULTI windows via the Help Manuals menu (see Online Help on page 8) An electronic PDF, available in the manuals subdirectory of your installation Note New or updated information may have become available while this book was in production. For additional material that was not available at press time, or for revisions that may have become necessary since this book was printed, please check your CD-ROM for Release Notes, README files, and other supplementary documentation. 6 MULTI: Editing Files and Configuring the IDE

19 About This Manual About This Manual This manual contains four parts: Part I: MULTI Editing Tools Contains information about using the MULTI Editor, a graphical interface for editing source code, and the MULTI Hex Editor, which is used for editing binary files. Includes descriptions of all Editor menus and their equivalent commands, and instructions about configuring the Editor for your programming language. Part II: Managing Files Contains information about using the MULTI Launcher, and configuring and using version control to track changes to your files. Includes instructions for using MULTI Version Control (MVC) or integrating your existing version control system. Also provides information about the following version control tools included with MULTI: the History Browser, Checkout Browser, anddiff Viewer. Part III: Configuring the MULTI IDE Contains information about configuring the integrated development environment to help you work more efficiently. You can customize the appearance and functionality of many GUI buttons, menus, keyboard shortcuts and mouse bindings. Part IV: License Administration Contains information about installing and administering Green Hills licenses, including how to use the Green Hills Licensing Device. Green Hills Software, Inc. 7

20 1. Introduction Online Help The MULTI online help system provides three different types of online help: Full online manuals You can access an indexed hypertext version of any MULTI manual by selecting it from the list that appears in the Help Manuals menu. Context-sensitive help Many MULTI windows and dialog boxes are linked to specific sections of the online manuals. To view the page in online help that documents an active window or dialog box: (Windows) Press F1. (UNIX) Press F1 or Help. If you are using the MULTI Editor, you can also open context-sensitive help about a button or a menu item by selecting Help Identify and then clicking the button or selecting the menu item. Debugger command help You can obtain help information about a specific MULTI Debugger command by typing help command_name in the Debugger command pane. This will open the online version of the MULTI: Debugging book on the section that documents the specified command. You can also type usage command_name to print to the command pane the basic syntax of the specified command. Viewing Help on Windows Systems Windows systems display online help via the Microsoft HTML Help viewer. You can view only one manual at a time with the HTML Help viewer. There are two panes in the HTML Help viewer. The right-hand pane displays the contents of a selected help page. You can click any underlined link that appears in right-hand pane to jump to pages about other related topics. The left-hand pane provides the following three navigation tabs: Contents Displays the chapter and section headings for the manual being viewed. Click a plus or minus icon to show or hide headings for embedded sections. Click a heading to display the associated help page in the right-hand pane. Index Displays index entries for the manual. Double-click an index entry to display its help page in the right-hand pane. 8 MULTI: Editing Files and Configuring the IDE

21 Online Help Search Provides an interface that allows you to search for specific words in the manual. Enter a word or phrase in the text box and click List Topics to display a list of pages related to your search string. Double-click any entry in the list to display the entry s help page in the right-hand pane. Viewing Help on UNIX Systems Depending on your specific UNIX system, MULTI will automatically choose one of the following two methods for viewing online help: Oracle Help for Java Displays hypertext version of manuals, including tables of contents and index entries, and provides full text searching across multiple manuals, with the ability to sort and rank search results. This viewer may take up to 30 seconds to initialize and is only available on systems running Red Hat Linux 7.1 or higher, Solaris 2.6 or higher, or HP-UX or 11.x. Other UNIX systems must use browser-based online help. If problems occur when MULTI is attempting to start the Oracle Help for Java application, you will see a message prompting you to use browser-based help (see below). The Java Runtime Environment that is included with MULTI has been configured to use fonts common to most X Window servers. However, some X Window servers may not display Oracle Help for Java properly. To configure fonts for the Java Runtime Environment, edit the font.properties file that is located in the jre/lib directory of your MULTI installation (for more information, see the Sun Microsystems Java web site). Web Browser Help Displays hypertext version of manuals, including tables of contents and index entries. In GUI mode, netscape is the default browser. If netscape is installed on your system and the executable is in your path, no further configuration should be necessary. In non-gui mode, a copy of lynx running inside of an xterm will be used as the default browser. If you have xterm in your path, no further configuration should be necessary. For information about using an alternate web browser, see Using a Custom Web Browser with UNIX on page 176. Note To change your online help settings, choose Config Options General tab, then click Help. Green Hills Software, Inc. 9

22 1. Introduction Conventions Used in This Book All Green Hills documentation assumes that you have a working knowledge of your host operating system and its conventions, including its command line and graphical user interface (GUI) modes. For example, you should know how to use basic commands, how to open, save, and close files, and how to use a mouse and standard menus. Green Hills documentation uses a variety of notational conventions to present information and describe procedures. These conventions are described below. Convention Meaning Examples bold type italic type ellipsis (...) (in command line instructions) greater than sign ( > ) Indicates a: Filename or pathname Command Option Window title Button name Menu name or menu choice Indicates that the user should replace the text in italics with an appropriate argument, command, filename, or other value. Indicates that the preceding argument or option can be repeated zero or more times. Represents a prompt. Your actual prompt may be a different symbol or string. The > prompt helps to distinguish input from output in examples of screen displays. C:\MyProjects setup command -G option the Task window the Browse button the File menu -o filename debugbutton [name] > print Test Test 10 MULTI: Editing Files and Configuring the IDE

23 Conventions Used in This Book Convention Meaning Examples pipe ( ) (in command line instructions) square brackets ( [ ] ) (in command line instructions) Indicates that one (and only one) of the parameters or options separated by the pipe or pipes should be specified. Indicate optional arguments, commands, options, and so on. You can either include or omit the enclosed elements. The square brackets should not appear in your actual command. help [command group] (The square brackets indicate that an argument is optional. If an argument is specified, however, it must be either a command or a group.).macro name [list] The following command description demonstrates the use of some of these typographical conventions. gxyz [-option] filename The formatting of this command indicates that: The command gxyz should be entered as shown. The option -option should either be replaced with one or more appropriate options or be omitted. The word filename should be replaced with the actual filename of an appropriate file. The square brackets and the ellipsis should not appear in the actual command you enter. Green Hills Software, Inc. 11

24 1. Introduction 12 MULTI: Editing Files and Configuring the IDE

25 Part I MULTI Editing Tools

26

27 Chapter 2 The MULTI Editor This Chapter Contains: The Editor GUI Getting Started with the Editor Navigating in Files Working with Code Working with Multiple Files Configuring the Editor

28 2. The MULTI Editor This chapter provides an introduction to the MULTI Editor, which you can use to create and modify text files. To open the Editor from the Launcher, do one of the following: Click the Edit button ( ). Select File Open Editor. The main components of the Editor graphical user interface (GUI) are: Title Bar Contains the path and filename of the file displayed in the current Editor window. Menu Bar Contains menus to access Editor functions. All menus and menu items are described in detail in Chapter 3, Editor GUI Reference. Editor Toolbar Contains buttons for some of the most common Editor actions. For more information, see Editor Toolbar on page 17. File and Procedure Fields Contains fields that provide quick access to files, procedures and line numbers. For more information, see File and and Procedure Fields on page MULTI: Editing Files and Configuring the IDE

29 The Editor GUI Source Pane Displays the text of the active document. Status Bar Displays information about document status and cursor position. For more information, see Status Bar on page 19. The Editor GUI In addition to the menu system described in Chapter 3, Editor GUI Reference, the following items in the Editor GUI provide easy access to important menu items and common Editor actions. Editor Toolbar The Editor Toolbar contains the following buttons that provide access to some of the most common Editor actions: (Open) OpenstheEdit File dialog box, which is used to select a file to open in the Editor. (Save) Saves the current file. (Cut) Deletes the current selection and places it on the clipboard. (Copy) Copies the current selection to the clipboard. (Paste) Pastes the contents of the clipboard. (Undo) Undoes the last edit. (Redo) Re-implements the last edit that was undone. (Search) OpenstheSearch dialog box, which is used to conduct an interactive search (see Interactive Searching Using the Search Dialog Box on page 26). (Goto) OpenstheGoTo dialog box, which is used to go to a file, line or procedure (see Using the GoTo Dialog Box on page 32). (Previous File) Switches to the previous open file in the Editor s stack. (Next File) Switches to the next open file in the Editor s stack. Green Hills Software, Inc. 17

30 2. The MULTI Editor (Save and Close) Saves files without prompting, then quits the Editor. (Close File) Closes the current file. (Quit) Quits the Editor. The presence or absence of this button on the toolbar is a configurable option (see the configuration option Display close (x) buttons in General Options Tab on page 179). File and and Procedure Fields Below the toolbar are three fields you can use to navigate within and between files. File This field displays the name and path of the file you are currently editing. You can type another filename in the field to open it in the Editor window. The drop-down menu provides access to your most recently used files. Files opened in the current Editor session appear at the top, and other recently used files appear below. Procedure The drop-down menu displays all procedures defined in the file. You can use this box to go to a procedure in the file. Select a procedure from the drop-down menu, or type a procedure name in the field. This field only appears when you are editing C or C++ files. As you type characters in this field, the Editor will auto-complete with procedures that match the characters you type. You can type part of a procedure name, then select the drop-down menu to view a list of all procedures that match the string you have entered. If you are uncertain about a procedure s name, you can use * and? wildcard characters. Line Number This box displays the line number the cursor is on. To go to a specific line in the file, type the line number in this field, and press Enter. Shortcut Menu You can right-click anywhere in the Editor source pane to open a Shortcut Menu of common editing operations. The shortcut menu includes some or all of the following items, depending on the cursor s position and the type of file that is being edited. 18 MULTI: Editing Files and Configuring the IDE

31 The Editor GUI Cut, Copy, Paste and Undo For information, see The Edit Menu on page 57. Go To Definition For information, see Go To a Definition on page 23. Go To Declaration For information, see Go To a Declaration on page 23 Browse References For information, see Browse References on page 24. Generate Cross References For information, see Generate or Regenerate Cross References on page 24. Regenerate Cross References For information, see Generate or Regenerate Cross References on page 24. Show Last Edit For information, see The Version Menu on page 68. Open New Editor Window For information, see The File Menu on page 54. Comment, Uncomment and Indent For information, see The Block Menu on page 63. Properties For information, see The View Menu on page 59. Status Bar The Status Bar is located at the very bottom of the Editor window. It displays the following information: Status box The left corner of the status bar displays status, usage, and error messages. For example, when you press Ctrl + F (see Incremental Searching on page 25), the left corner of the Status Bar displays the search text as you type it. Cursor position indicator Displays the current line and column position of the cursor. Read-only indicator A stop sign appears near the right corner of the status bar if the current file is read-only. Change dot A small red star appears near the right corner of the status bar if changes have been made to the file since the last time it was saved. Green Hills Software, Inc. 19

32 2. The MULTI Editor Version control status The letters VC appear in the right corner of the status bar if the current file is under version control. The letters will be red if the file has been modified. Otherwise they will be black. Getting Started with the Editor This section describes how to start the Editor and provides information about Editor features. Starting the Editor There are a number of ways to start the Editor, either as a standalone editing program, or from other MULTI tools. Starting the Editor from the Launcher To start the Editor from the Launcher, do one of the following: Click the Edit button ( ). Select File Open Editor. Starting the Editor as a Standalone Program To start the Editor as a standalone program, run the following executables from a command line prompt. A filename can be used as a command line argument to open a specific file. Windows The executable is me.exe, which is located in the Green Hills directory. The default directory for a Green Hills installation is: c:\ghs\target_release_number. For example, c:\ghs\ppc40 is the default directory for 4.0 release for the Power PC. UNIX Theexecutableisme, which is located in the Green Hills directory. The default directory for a Green Hills installation is: /usr/green/host. For example, /usr/green/solaris2. 20 MULTI: Editing Files and Configuring the IDE

33 Getting Started with the Editor Starting the Editor from the Builder To start the Editor while using the Builder, do one of the following: Select a file, then click the Edit button ( )toopenitintheeditor. Select one or more files in the source pane, then select Edit Edit Selected Files, or right-click and select Edit from the shortcut menu. Double-click a text filename in the source pane. Double-click an error or warning in the Progress window to open the source file in the Editor with the cursor placed on the line with the error. Starting the Editor from the Debugger To start the Editor while using the Debugger, do one of the following: Click the Edit button ( ). Right-click in the Source pane and select Edit. Use edit commands in the Debugger command pane. For more information about edit command options that open files in the Editor, see the MULTI: Debugging book. When you start the Editor from the Debugger, the Debugger creates temporary copies of the source files so you can continue to debug your program while looking at the original source code. Changes that you make in the Editor affect the actual files and not these temporary files which are deleted when you exit the Debugger. Overview of Editor Features The Editor provides powerful features to help you work with your files. Details about the following advanced features are provided in this book: Navigating in Files The Editor can automatically obtain function prototypes and cross reference information, and provides a number of search options. For more information, see Navigating in Files on page 22. Working with Code The Editor provides tools and keyboard shortcuts that are helpful when editing source code. For more information, see Working withcode onpage34. Green Hills Software, Inc. 21

34 2. The MULTI Editor Working with Multiple Files The Editor contains tools to merge or compare multiple files. For more information, see Working with Multiple Files on page 39. Configuring the Editor The look and functionality of Editor can be customized to help you work more efficiently. see Configuring the Editor on page 44. The Editor automatically configures itself based on the programming language of the source file that is currently being edited. You can create definition files for new languages, for example to add support for a proprietary scripting language (see Adding Support for New Languages on page 49). Version Control The Editor is fully aware of several version control systems, and allows you to perform many version control operations without leaving the Editor. For more information, see The Version Menu on page 68. Version control configuration options for the Editor can be set through the Config Options menu (see General Options Tab on page 179). For information about version control and configuring MULTI to work with your version control system, see Chapter 6, Using Version Control with MULTI. Navigating in Files This section provides details about Editor functions that help you navigate within a single file, and across multiple files. Using References and Prototypes Whenever the MULTI Editor loads a C or C++ file, it attempts to obtain information about the file, including the following information: The operating system for which the code was written The source file s include files The cross reference information When this information is obtained, the Editor automatically grabs the function prototypes from the include files; loads information for the operating system 22 MULTI: Editing Files and Configuring the IDE

35 Navigating in Files such as APIs, constants and types; and uses this information for syntax coloring and auto-completion (see The language.gsc Syntax Definition Files on page 47). The prototype information also allows you to quickly jump to the function s definition or declaration from the shortcut menu. If cross reference information is available, it is automatically loaded (see Generate or Regenerate Cross References on page 24). The Editor will attempt to obtain cross references from the following sources: MULTI Debugger The Editor can obtain cross reference information from the Debugger when the Editor was launched from the Debugger and the current file in the Editor is contained in the program being debugged. Cross reference (.dbo) files These files are generated using the project information from a Builder window. Cross reference information for a source file may be incomplete. To obtain complete cross reference information for the source file s enclosing project, you can right-click and select Generate Cross References from the shortcut menu (see Generate or Regenerate Cross References on page 24). Go To a Definition To go to the definition of an item: 1. Right-click an object, function, variable, type or other text in the source pane and select Go To Definition from the shortcut menu. 2. The Editor will use the function prototype or cross reference information to find the definition of the clicked item and move the cursor to that position. Go To a Declaration To go to a declaration of an item: 1. Right-click an object, function, variable, type or other text in the source pane and select Go To Declaration from the shortcut menu. 2. The Editor will use the function prototype or cross reference information to find the declaration of the clicked item and move the cursor to that position. Green Hills Software, Inc. 23

36 2. The MULTI Editor Browse References To browse reference information: 1. Right-click an object, function, variable, type, or other text in the source pane and select Browse References from the shortcut menu. 2. The Editor will attempt to obtain the item s cross references and display them in a Browse window. The Browse window for cross references in Editor is very similar to the Browse window in the Debugger, without the Debugger-related functions (see Browsing Cross References in Chapter 10, Browsing Program Elements in the MULTI: Debugging book for details). The status box of the Browse window will display the source from which the cross references are obtained: Basedondebugger the source is the symbol table of the program in the corresponding Debugger. Based on progress: N/A the source is the single.dbo file of the current source file. Basedonprogress: 70% the source is multiple.dbo files of the enclosing project. The percentage displayed represents the number of currently loaded.dbo files out of the total number in the enclosing project. Cross reference Browse windows are accessible in the Editor through the Windows menu. Cross reference Browse windows can be deleted by selecting View Close Dependent Windows. Generate or Regenerate Cross References To obtain complete cross reference information based on the project to which the source file belongs: 1. Right-click in the source pane and select Generate Cross References from the shortcut menu.. Note This menu item is unavailable if the Editor obtained cross reference information from the corresponding MULTI Debugger. 24 MULTI: Editing Files and Configuring the IDE

37 Navigating in Files 2. The Editor will search for the enclosing project and generate cross reference information for the whole project. Once cross reference information for the enclosing project is generated, the shortcut menu item will change to Regenerate Cross References. If any of the source files in the project have changed, the cross references for the enclosing project must be regenerated for the information to be accurate. Searching in the Editor The MULTI Editor provides three ways to search for text: Incremental searching Performs a quick search of the active file. This type of searching uses keyboard shortcuts rather than a dialog box, so there are fewer options. However, the search is incremental, so it searches for a string as you type it. This means that you do not always have to type the whole text you are looking for. For more information, see Incremental Searching on page 25. Interactive searching UsestheSearch dialog to perform a variety of searching tasks on the file in the active Editor window. Interactive searching allows search-and-replace and regular expression matching. For more information, see Interactive Searching Using the Search Dialog Box on page 26. Searching files Performs full-text searching in all open files using the grep utility. For more information, see Searching in Files on page 30. Incremental Searching You can perform a quick incremental search in the active Editor window, without opening the Search dialog box, by performing the following steps: 1. Press Ctrl + F (to search forward in the file) or Ctrl + B (to search backwards in the file). This will cause the status box in the lower left corner of the status bar to display the prompt: Srch. 2. Type the string for which you are searching. As you type characters, the Editor highlights the first occurrence of that string pattern. You can use the Backspace key to remove characters from the search string. As you type additional characters or Backspace, the search string is displayed in the Green Hills Software, Inc. 25

38 2. The MULTI Editor status bar to the right of the Srch prompt and the next occurrence of the new string is highlighted in the Editor source pane. 3. If a match has been found, press Ctrl + F again to view the next match or press Ctrl + B to view the previous match. If there is no other match, the status bar will indicate that the search failed to find another match. 4. Press Esc at any time to clear the current search. (The Srch prompt will disappear.) Note If you are not in search mode (that is, if the Srch prompt is not showing in the status bar), you can press Ctrl + F two times to repeat your most recent search. Search criteria that you have previously set in the Search dialog box (see Interactive Searching Using the Search Dialog Box on page 26) will affect incremental searches. If you used the Search dialog box for your most recent search, you can press Ctrl + F twice to repeat that search. Other options set in the Search dialog box, such as Case and Search Type will be applied to all subsequent incremental searches until they are cleared. Use the Search dialog box to clear or change these options. To make all incremental searches case-sensitive, select Config Options, select the General tab, and enable Match exact case in searches. Beaware that this setting affects incremental searches in all MULTI tools, not just the Editor. See Chapter 9, Configuration Options for more information about configuring MULTI. Interactive Searching Using the Search Dialog Box The Search dialog box allows you to specify search criteria for interactive searches. To open the Search dialog box, do one of the following: Select Edit Find. Click the Search button ( ). Press Ctrl + Shift + F. 26 MULTI: Editing Files and Configuring the IDE

39 Navigating in Files The Search dialog box can be used to search for and to search-and-replace text in the file open in the active Editor window. The fields and options in the Search dialog box are described in the following table. Item Find Replace Replace Then Find Find Then Replace Replace All Undo Forward Backward Meaning Searches for and highlights the next occurrence of the string entered in this field. To search for the next occurrence, click the Find button again, or press Enter. Replaces the current selection with the string entered in this field. Replaces the current selection and then searches again. Searches for the next occurrence of the search string, and replaces it with the replacement string. Starts at the beginning of the file and replaces all occurrences of the search string with the replacement string. Undoes the last Editor command. Note that this button will Undo all Editor commands, not just commands entered in the Search dialog box. Determines whether the search proceeds forward or backward from the current location. (The default is Forward.) The Editor searches from the current location in the file toward the end of the file for a forward search, and toward the beginning of the file for a backward search. If the search string is not found before it reaches the end or the beginning, the search stops and an error message is displayed in the status bar. If you start the search again, it resumes from the beginning or end of the file. Green Hills Software, Inc. 27

40 2. The MULTI Editor Item Case Search Type StartsWord EndsWord StartsLine EndsLine Meaning Determines whether or not the search is case-sensitive. Select one of the following: Exact Selects a case-sensitive search. For example, Fly matches Fly, but not fly or FLY. Either Selects a case-insensitive search. For example, Fly matches both fly and FLY. (This is the default.) Determines the type of search to be conducted. Select one of the following: Normal No special characters in the search; that is, characters only match themselves. (This is the default.) Wildcard The following characters have a special meaning in the search string:? (question mark) Matches any single character except a newline character. * (asterisk) Matches any number of characters except newline characters. RegExpr The characters listed in Searching for Regular Expressions on page 29 can be used in the search string. Specifies whether the search string must appear at the beginning or end of a word. If StartsWord is checked, the search string must appear at the beginning of a word. For example, fly matches fly or flybat, but not batfly. If EndsWord is checked, the search string must appear at the end of a word. For example, fly matches fly or batfly, but not flybat. If both are checked, the string string must form a complete word. For example, fly matches fly, but not flybat or batfly. If neither box is checked, any occurrence of the string is found. Specifies whether the search string must appear at the beginning or end of a line. These options function similarly to StartsWord and EndsWord, described above, except that they apply to the beginning and end of a line. Selecting both of these boxes specifies that the entire line must match the search text. 28 MULTI: Editing Files and Configuring the IDE

41 Navigating in Files Note The settings in this dialog box set the defaults for the next incremental search (see Incremental Searching on page 25). Searching for Regular Expressions The following table lists acceptable formats for entering regular expressions as search strings when the RegExpr button has been selected in the Search dialog box.. (A period) Matches any single character except a new line. [string] [^string] ^ Matches any single character appearing in string. For example, [abc] matches an a, b, orc. You can specify character ranges by separating the start and end of the range with a dash (-). For example, [b-e] matches b, c, d and e. To include aclose bracket (]) aspartofthestring, make it either the first character of string, or the last character of a range. For example, []abc]. If the first character of the string is a caret (^), it matches any character that is not in string. Place at the start of the search string to match the beginning of a line. Same as the StarsLine option. $ Place at the end of the search string to match the end of a line. Same as the EndsLine option. < Place at the start of the search string to require that the rest of the search string matches the beginning of a word. Same as the StartsWord option. > Place at the end of the search string to require that the rest of the search string matches the end of a word. Same as the EndsWord option. (regexp) regexp* regexp1 regexp2 Matches the regular expression regexp enclosed in parentheses. Matches zero or more occurrences in succession of the regular expression regexp. Matches regular expression regexp1 or regular expression regexp2. The following table gives some examples of regular expressions that can be used in searches. a.d a.*d <and Matches and, ad, and aud. Matches ad, are d, and abd. Matches and, but not stand. Green Hills Software, Inc. 29

42 2. The MULTI Editor are is (are is)* bad Matches either are or is. Matches are bad, is bad, areisare bad, andbad. Searching in Files The MULTI Editor supports full-text searching of all open files with the Search in Files feature. To search all open files, do one of the following: Select Tools Search in Files. Enter the Grep command in the Execute Editor Commands dialog, as described in Tools Commands on page 363. This opens the Search in Files dialog box. Enter the search string in the text box (or use the drop-down list to select recent search strings) and select any of the following searching options, if desired: Case sensitive The search will only find text that matches the case of the search string exactly. If this box is not selected, the search will ignore case when searching for a match. This box is selected by default. Whole word The search will only find text that matches as a whole word. For example, if this box is selected, a search for word would not match sword. This box is cleared by default. Use Regular Expressions The search treats the text you enter in the text box as a regular expression. If this box is not selected, the search treats the text you enter as a fixed string. This box is selected by default. After you have entered the search string and set your searching options, click Search to perform the search. A Search in Files Results window will open and display all matches as they are found. See the next section for a description of this window. 30 MULTI: Editing Files and Configuring the IDE

43 Navigating in Files Note The Search in Files capability works by running the GNU grep utility. A copy of GNU grep is installed along with MULTI. However, GNU grep is not part of MULTI and is not distributed under the same license as MULTI. For more information about the GNU General Public License, under which GNU grep is distributed, refer to the file gnugrep.readme, which is located in the directory where MULTI is installed. Viewing Search in Files Results The results of a Search in Files operation are displayed in the Search in Files Results window. The main components of this window include: Results pane Contains three columns that display information about the matching lines in the files searched. File column Displays the filename of the matching line. Place your mouse pointer over this field to display the path to the file, if available, in a tooltip. Line column Displays the line number of the matching line. Text column Displays the text of the matching line. Text pane Contains a description of the search and displays any errors printed by the GNU grep utility. Stop Search button Stops the current search. This does not dismiss the results window; the results collected before the search was stopped will Green Hills Software, Inc. 31

44 2. The MULTI Editor continue to be displayed. This button becomes unavailable when the search is complete. Close button Dismisses the results window. Status bar Displays the progress of the search. Located at the bottom of the window, this bar will display Searching, Search completed, orsearch stopped. You can double-click any line in the search results window to open an Editor on the specified file and line. Note Although Search in Files is available from the Editor, the Debugger, and the Builder, the functionality differs slightly across these tools. The descriptions above apply to searches performed from the Editor. See the MULTI: Building Applications book for your target and the MULTI: Debugging book for more information about searching from the Builder and the Debugger. Using the GoTo Dialog Box You can use the GoTo dialog box to go to a file, line number or function. To open the GoTo dialog box, do one of the following: Select Edit Goto. Click the Goto button ( ). Press Ctrl + Shift + G. Goto a File To open a file in the current Editor: 1. Type a filename in the Goto box. 2. Select the Filename radio button. 3. Click Go. 32 MULTI: Editing Files and Configuring the IDE

45 Navigating in Files Goto a Line Number To go to a specific line number in the current file: 1. Type the line number in the Goto box. 2. Select the Line Number radio button. 3. Click Go. Quickly Go To a Line You can quickly go to a line without using the GoTo dialog box: 1. Type Ctrl + G. The status box in the lower left corner of the status bar will display the prompt Goto Line:. 2. Enter the line number to go to. 3. Press Enter. Goto a Function To go to a specific function in either the current file, or in another file: 1. Type a function name into the Goto box. 2. Select the Function radio button. If the Function button is not available, then the Editor could not find a tag file. 3. Click Go. 4. If the function is in the current file, the Editor moves the cursor to the beginning of the function. If the function is in a different file, the Editor opens that file and moves the cursor to the beginning of the function. Note This option is only available if the corresponding language is C/C++ (for which the Editor can automatically grab function prototypes from the edited file) or: A ctags style tag file named tags resides in the current directory. See Using Tags in Your Files on page 34 for more information. A tags file has been specified with the Tools Append TagFile menu item. Green Hills Software, Inc. 33

46 2. The MULTI Editor You use the AppendTagFile Editor command. Using Tags in Your Files If you use the ctags utility to create a tag file, the Editor uses the information to open files and move the cursor based on the name of a function. See Tag Commands on page 365 for additional tag commands. Manually Loading a Tag File in an Editor Session When the Editor starts, it looks for a file called tags. If the tag file has a different name or is in an unexpected location, the Editor may not find it. To manually load a tag file into an Editor session: 1. Select Tools Append TagFile. 2. The Select Tag File dialog box appears. Select the tag file, or enter the path and filename of the tag file. 3. Click Load. Removing a Tag File from an Editor Session To unload a tag file from an Editor session: 1. Select Tools Reset Tags. 2. Once you have unloaded a tag file, the Editor no longer uses that file to navigate to functions. WorkingwithCode The Editor provides tools and keyboard shortcuts that you will find helpful when editing source code. Indenting Code Indentation is whitespace at the beginning of each line, used to denote the hierarchical structure of your code and make it more readable. As you write code, you can manually insert an indent, or you can let the Editor indent your code based on common coding standards. 34 MULTI: Editing Files and Configuring the IDE

47 Working with Code Manually Inserting or Removing an Indent To manually insert or remove an indent: 1. Move the cursor to the appropriate line, or highlight multiple lines. 2. Select Block Indent to insert an indent. 3. Select Block Unindent to remove an indent. For more information about working with indents, see The Block Menu on page 63. Auto-Indenting Code The Editor has an auto-indent feature that will indent your code according to common coding standards. Auto-indent is only available for certain languages. At present, MULTI supports auto-indenting for C, C++, Java, and ADA only. 1. If you want to auto-indent a single line of code, move the cursor to that line. If you want to auto-indent multiple lines of code, highlight those lines. 2. Select Block Auto Indent, or press Ctrl + 2 or Ctrl + ; (semicolon). Pressing the Tab key also automatically indents everything to the right of the cursor. Note You can make a one time change in how far the Editor auto-indents the lines of a lexical block of code, by indenting the first line of code the way you want the entire block to look, then highlighting the rest of the block and starting the auto-indent. This prevents the Editor from breaking the conventions of a pre-existing block. Configuring Indents You can configure the default size of indents and how they affect your code. To change the configuration of indents for all files, select Config Options and make changes on the MULTI Editor tab (see MULTI Editor Options Tab on page 216). To change the size of indents for the current file and current session only, use the Per File Settings dialog box. See The PerFileSettingsDialog Box on page 61 for more information. Green Hills Software, Inc. 35

48 2. The MULTI Editor Auto-Indent Characters By default, the Editor automatically makes indenting adjustments when you type the following characters: # number sign * asterisk ; semi-colon : colon { left curly brace } right curly brace You can disable characters from auto-indenting both your code and comments by disabling Implicit auto indent. If you want special characters to auto-indent your code, but want to disable them if you use them within a comment, disable Implicit auto indent in comments (see MULTI Editor Options Tab on page 216 in Chapter 9, Configuration Options ). Working with Comments This section describes how you can use the Editor to easily insert and manipulate comments in your code. Inserting or Removing a Comment The Editor uses the proper syntax for comments based on your selected programming language. Block comment operations are available to C, C++, Pascal, Java, and all languages that support line comments. To insert a new comment, place the cursor on a blank line where you want the comment to start and select Block Comment. To comment out existing code, select the appropriate text, then select Block Comment. The selection is implicitly extended to line boundaries; the entire line the selected text is in will be commented out. To uncomment a comment block, highlight the block and select Block UnComment. For more information about working with comments, see The Block Menu on page MULTI: Editing Files and Configuring the IDE

49 Working with Code For information about configuring comments, see MULTI Editor Options Tab on page 216 in Chapter 9, Configuration Options. Note If the Editor is not using the correct syntax for comments, select View Language to make sure it is configured for the correct language. Highlighting the Boundaries of the Current Block of Code To identify the beginning and end of the current block of code, select View Match. When you perform this operation, the Editor: 1. Searches backward from the cursor and finds the first enclosing instance of a left parenthesis (, left curly brace {, or a left bracket [. 2. Searches forward from the cursor to find the matching ending mark. 3. Selects the code in between. For more information, see The View Menu on page 59. Working with Columns You can cut, copy and paste columns of text in the Editor. For more information, see The Block Menu on page 63. Copying a Column of Text You can copy a column of data from a file, excluding data on either side of the column. For example, suppose you have a tab delimited file that lists date, time, file size, and filename. You can copy just the column that lists time without affecting any of the other data. 1. On the first line that contains data you want to copy, start the selection at the first character you want copy. 2. Extend the selection to include all of the data in the column. The last character selected should be the last character of the column. 3. Select Block Rect Copy. Green Hills Software, Inc. 37

50 2. The MULTI Editor 4. The region of text to be copied is the rectangle with the diagonal defined by the first character and the last character of the selection. Example 1. Using Rect Copy Highlight the following selection, then select Block Rect Copy. When you paste the contents of the clipboard, the following is inserted in your file: 09:21a 09:22a 09:23a 09:36a 09:23a 09:33a Cutting a Column of Text To cut a column of text out of a file, highlight the column and select Block Rect Cut. Pasting a Column of Text After you have cut or copied a column of text from a file, you can: Select Block Rect Paste to paste the column without inserting line breaks. Select Edit Paste to paste the contents of the clipboard into the file with line breaks. 38 MULTI: Editing Files and Configuring the IDE

51 Working with Multiple Files Working with Multiple Files This section provides information about the MULTI Editor tools you can use to merge and compare multiple files. Merging Files You can use the Editor to merge two or three files into a single file. The initial files can be completely different files, or different versions of the same file. To begin merging files, select Tools Merge Files to open the EditMerge dialog box. The EditMerge dialog box contains the following fields and buttons: File1 File2 Base Type the name of the first file you want to merge, or click (Browse) to select a file. If you are using a version control system and want to merge a different version of a file from disk, enter the filename in the File1 field and the version of that file to be merged in the adjacent Version field. Type the name of the second file you want to merge, or click to select a file. If you specify the same file in the File1 and File2 fields without specifying a version, then File1 refers to the copy currently open in the Editor, while File2 refers to the file on disk. Type the name of the file from which the other two files, File1 and File2, are derived, or click to select a file. If you are only merging two files, leave this field blank. Green Hills Software, Inc. 39

52 2. The MULTI Editor Automatic Merge Check this box if you want the Editor to try to resolve merges without prompting you. Clear this box if you want to manually review every proposed merge. Click Merge to begin the merge: The two-file Merge dialog box will open (see Merging Two Files on page 40). IfafileisspecifiedinBase, the three-file Merge dialog box will open (see Merging Three Files on page 41). Merging Two Files To merge two files: 1. Select merge criteria in the EditMerge dialog box (see Merging Files on page 39) and click Merge. An Editor window appears for each of the two files you specified, as well as an extra Result window that displays results of the merge. The Status box in the lower left corner of each window identifies which file is in each window. In addition to the Editor windows, the two-file Merge dialog box will open: The Editor will pause at each difference between the files and highlight the text that is different. 2. Use the following buttons in the two-file Merge dialog box to control the merge results: File1 File2 Both Copies the selected text from File1 into the Result window. Copies the selected text from File2 into the Result window. The first time you click this button, a dialog box appears asking you how you want to merge the two selections (in what order, with change bars around them, with comments in front, between, or after them, and so forth). The next time you click this button, the last values entered are used. 40 MULTI: Editing Files and Configuring the IDE

53 Working with Multiple Files Skip Automatic Help Edit Change Bars Cancel Finds the next difference without adding the current difference to the file. Enables or disables the automatic merge feature. If the box is checked, the Editor will try to make merge changes without prompting you. If the box is cleared, you manually control every merge change. Opens MULTI s online help for the Merge dialog box. Performs the same action as the Both button, except that you can modify the changes in a temporary window before merging them into the new file. Changes the settings for the Both button. When you click this button, it opens the same dialog box that appears the first time you click the Both button. Aborts the merge, closing all merge windows. The results of each merge selection will be copied to the Result window. You can also manually cut and paste text into the Result window. 3. When the merge is complete, a Save dialog box opens so you can save the Result file. After you save the results, the other Editor windows close. If you save the Result file with the same name as one of the original files, any Editor windows still open on that file will be updated with the merged results. Merging Three Files When you merge three files, one file is considered the Base file from which the other two are derived. With this assumption, the Editor is usually able to merge without asking you for information, using the following rules: If a difference exists between the two source files, and one is the same as the Base file, then the Editor uses the one that is different from the Base file. If both source files differ from the Base file, but are the same as each other, then the Editor uses the new text from either source file. If all three files are different, a conflicting change was made and the Editor has to ask which change to use. In this case, it is likely that you will have to merge the change manually. To merge three files: Green Hills Software, Inc. 41

54 2. The MULTI Editor 1. Select merge criteria in the EditMerge dialog box (see Merging Files on page 39) and click Merge. An Editor window appears for each of the three files you specified, as well as an extra Result window that displays results of the merge. The Status box in the lower left corner of each window identifies which file is in each window. In addition to the Editor windows, the three-file Merge dialog box will open: The Editor will pause at each difference between the files and highlight the text that is different. 2. Use the following buttons in the three-file Merge dialog box to control the merge results: Button File1 File2 All Meaning Copies the selected text from File1 into the Result window. Copies the selected text from File2 into the Result window. Copies the selected text from all three files. The first time you click this, a dialog box appears asking you how to merge the selection (in what order, with change bars around them, with comments in front, between, or after them, and so forth). The next time you click this button, the last values entered will be used. 1,2 Merges the selections from File1 and File2. The first time you click this, a dialog box appears asking you how to merge the two selections from File1 and File2 (in what order, with change bars around them, with comments in front, between, or after them, and so forth). The next time you click this button, the last values entered will be used. 1,Base 2,Base Functions the same as the 1,2 button, except it merges the selections from File1 and the Base file. Functions the same as the 1,2 button, except it merges the selections from File2 and the Base file. 42 MULTI: Editing Files and Configuring the IDE

55 Working with Multiple Files Button Skip Automatic Help Edit Change Bars Cancel Meaning Finds the next difference without adding the current difference to the results file. Enables or disables the automatic merge feature. If the box is checked, the Editor will try to make merge changes without prompting you. If the box is cleared, you manually control every merge change. Opens MULTI s online help for the Merge dialog box. Performsthesameactionasthe1,2 button, except that you can modify the changes in a temporary file before merging them into the new file. Changes the way the 1,2, 1,Base, 2,Base, and All buttons work. This button opens the same dialog box as the one that appears the first time you click any of those buttons. Aborts the merge, closing all merge windows. Comparing Files You can compare files without merging them. To compare two files, do the following: 1. Select Tools Diff Files. TheDiff Files dialog box will open: 2. In the Left field, specify the filename and version of the first file you want to compare. If you do not specify a version, the Editor assumes you mean the current version. 3. In the Right field, specify the filename and version you want to compare to the first file. Click the up or down arrows to increment or decrement the version number. 4. Click Diff. The Editor opens a Diff Viewer that shows the differences between the two specified versions. For more information, see The Diff Viewer on page 141. Green Hills Software, Inc. 43

56 2. The MULTI Editor Configuring the Editor You can change how the Editor looks and functions to help you work more efficiently. Many of the options that control how the Editor appears and handles your code are accessible by selecting Config Options, then the MULTI Editor tab. For more information about configuring MULTI, see Chapter 8, Configuring and Customizing MULTI and Chapter 9, Configuration Options. Customizing the Editor GUI You can customize the Editor to perform actions in new ways. You can replicate any of the actions available in the standard Editor window by assigning commands to new menu items, buttons, key bindings, or mouse click combinations. For example, if you prefer not to use the mouse when you are editing, you can assign commands to keystrokes; or if there is a menu item that you access frequently, you can assign the equivalent commands to a button. For information about how you assign commands to menus, key bindings, mouse bindings, and buttons, see Customizing the Graphical User Interface (GUI) on page 158 in Chapter 8, Configuring and Customizing MULTI. For information about Editor commands, see Chapter 3, Editor GUI Reference, which lists the equivalent commands for GUI menu items; and Appendix A, which provides a complete list of Editor commands. For a complete list of the default key and mouse bindings, see Appendix D. Configuring the Editor for a Programming Language The Editor automatically configures itself based on the programming language of the source file that is currently being edited. For example, if you open a file foo.c, the Editor automatically identifies text enclosed in double quotes ("") as a string, completes certain words (such as language-specific keywords) as they are typed into the file, and automatically colors the code to make it more readable. Two files are used to identify the programming language in a source file, color the programming language, and enable auto-completion: index.gsc The index configuration file that the Editor uses to match the source file with the appropriate syntax definition file. 44 MULTI: Editing Files and Configuring the IDE

57 Configuring the Editor language.gsc The syntax definition file for a specific programming language. This file defines how the Editor should color the language and whether the Editor should auto-complete certain words as they are typed. The index.gsc Configuration File When the Editor opens a file, it searches the index.gsc configuration file for the file s extension and uses it to locate the corresponding language syntax definition file. The index.gsc configuration file is located in the defaults/syntax_coloring directory of your MULTI installation. Each entry defines the basic information about a language. The definition order determines how they will be displayed in the Editor s View Language menu or submenu. For each language, the index.gsc file defines the following: Identifier A unique identifier for the name of the language. This identifier must correspond to the name in the language s syntax definition file (see The language.gsc Syntax Definition Files on page 47). If the language s identifier contains any non-alphanumeric characters, enclose the entire identifier in quotes, for example: "C++". extension Lists the file extensions of files that contain the language. To force the Editor to automatically use a language that is not consistent with a file s extension, insert -*-language-*- on the first line of the file (include this syntax within a comment). For example, to force the Editor to view a file as C++, regardless of its extension, enter: // -*- c++ -*- on the first line of the file. description The name of the language as it will appear in the Editor s View Language menu. The & symbol indicates that the following key is a hot key for the menu item. For example, if you specify description = "Per&l", the letter l becomes the hot key. definition_file The language s syntax definition file. If an absolute path is not specified, the Editor will look for the syntax definition file in the syntax_coloring directory of your local or site-wide MULTI configuration directory. For more information, see The language.gsc Syntax Definition Files on page 47. Green Hills Software, Inc. 45

58 2. The MULTI Editor hide You can determine whether the language appears in the Editor s View Language menu. To hide a language, enter hide = true. The default is false. Although a hidden language will not appear in the menu, the Editor will still use it to color files written in the corresponding language. submenu To group languages into a submenu within the View Language menu, enter: submenu = submenu_name first_line_pattern The regular expressions that identify the language by the source file s first non-blank line. If the Editor cannot match a language based on the source file s extension, or if the extension matches more than one entry in index.gsc, the Editor will use these regular expressions to select the correct language. Be sure to use a double escape character sequence (\\) when defining the regular expressions. Regular expression support is provided by the PCRE library package, which is open source software, written by Philip Hazel, and copyrighted by the University of Cambridge, England. It can be downloaded from the University of Cambridge FTP server (ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/). Example 1. index.gsc Entry The entry in the index configuration file for the Perl language might look like: Perl { extension = {"pl"} description = "Per&l" definition_file = "perl.gsc" first_line_pattern = {"^[\\s]*#![\\w /\\\\]*[/\\\\]perl"} } To visually separate languages when they are listed in the View Language menu, define a unique identifier with a description of "\x01". For example: "GHS-Sep1" { description = "\x01" } Each separator should be given a unique name. 46 MULTI: Editing Files and Configuring the IDE

59 Configuring the Editor The language.gsc Syntax Definition Files The MULTI Editor uses language.gsc syntax definition files to determine items such as the display color of language elements, case-sensitivity, and auto-completion. Each language has its own syntax definition file located in the syntax_coloring directory. The definitions for some languages are split into multiple files, in which case the language.gsc file can use %include "filename.gsc" statements to include definitions from other syntax definition files. Each of the following elements can be defined in the syntax definition file. For each element that can be defined, you can use the default color or specify your own. general The following entries define general settings for the language: name = The identifier for the language. This identifier must match the Identifier listed in the index.gsc file (see The index.gsc Configuration File on page 45). description = The name of the language as it will appear in the Editor s View Language menu. extension = File extensions associated with this language. case_sensitive = Defines whether the language is case-sensitive. For a case-insensitive language, enter case_sensitive = false. The default is true. pascal_style_priority = (boolean). In languages such as C/C++, comments, strings and characters receive higher priority than preprocessor statements; while other languages, such as Pascal, give higher priority to preprocessor statements. To assign priority to preprocessor statements, enter pascal_style_priority = true. The default is false. separator = Separators used to delimit syntax tokens. escape = Escape sequence leader. For example: name = "Pascal" description = "Pascal" extension = {"p", "pas", "h"} case_sensitive = false separator = "\\\"+-*/<=>:,; \t()[]^%!~ & {}.@?" escape = "\\" Green Hills Software, Inc. 47

60 2. The MULTI Editor keyword You can define a list of keywords, the display color for keywords, and whether keywords are auto-completed. line_comment Specify line comment characters. Multiple line comment leaders can be defined, so an index number is used for each. For example: 1 = "//" comment Specify comment characters. Multiple comment characters can be defined, so an index number is used for each. For example: 1 { begin = "(*"; end = "*)" } 2 { begin = "{"; end = "}" } string Specify string characters. Multiple string characters can be defined, so an index number is used for each. For example: 1 { begin = " "; end = " " } character Specify constant characters. Multiple characters can be defined, so an index number is used for each. For example: 1 { begin = "\ "; end = "\ " } integer The following entries can be made to define integers: hex = Specifies support for hex integers. To support hex integers, enter hex = true. The default is false. case_sensitive = Specifies case sensitivity in integer suffixes. To make integer suffixes case insensitive, enter: case_sensitive = false. The default is true. decimal_suffix = Specifies a list of suffixes for decimal integers. hex_suffix = Specifies a list of suffixes for hex integers. 48 MULTI: Editing Files and Configuring the IDE

61 Configuring the Editor float The following entries can be made to define the display of numbers in floating point form. scientific = Specifies whether scientific format is supported. To use scientific format, enter scientific = true. The default is false. case_sensitive = Specifies case-sensitivity for float suffix. The default is true. To override, enter case_sensitive = false suffix = Specifies a list of suffixes for float. customized You can define a list of customized items (wildcards can be used in them), and whether those customized buttons not containing wildcards are auto-completed. autocomplete Defines the auto-complete behavior. For information, see Configuring Auto-Complete on page 49. Adding Support for New Languages You can create new syntax definition files for any language, for example you can add support for a proprietary scripting language. To implement support, you must create a syntax definition file for the language (for example, my_language.gsc),andthencreateanentryintheindex.gsc file for the new language. Tip MULTI s default index configuration file and syntax definition files include detailed comments. The easiest way to add a new language is to look at the default files, which are located in the defaults\syntax_coloring (Windows) or defaults/syntax_coloring (UNIX) directory of your MULTI installation. Configuring Auto-Complete A language syntax definition file determines whether keywords, preprocessor statements, and customized items will be automatically completed by the Editor as they are typed. Most of the language syntax definition files included with MULTI have auto-complete enabled for both keywords and preprocessor statements. Auto-complete can also be enabled for function prototypes. Auto-completion does not work for customized items that contain wildcard characters. Green Hills Software, Inc. 49

62 2. The MULTI Editor You can turn auto-complete on or off for an entire language, or for a specific category of items in the syntax definition file by specifying autocomplete = false or autocomplete = true. The following sections provide details about auto-complete that can be modified by editing the autocomplete section of the syntax definition file. Note Even when auto-completion is disabled, you can use the keyboard shortcuts listed in Auto-Completion Keyboard Shortcuts on page 405 to perform auto-completion functions based on the characters located at the cursor. First Match vs. Best Match Auto-Complete Auto-completion uses either first match logic or best match logic to complete words based on the letters that have been typed: autocomplete = "first" Completes the first word that begins with the letter that has been typed. autocomplete = "best" Does not complete a word until it can uniquely identify the letters that have been typed. This is the default setting. For example, assume auto-completion has been enabled for the keywords: main, mailman and mist. When the letter m is typed, first match logic auto-completes the item into main, but best match logic does not perform any auto-completion. When the letters ma have been typed, first match logic still auto-completes the item into main, while best match logic auto-completes the item to mai because it still cannot determine whether the item should be main or mailman. Minimum String Length You can control the minimum number of characters in a string before auto-complete attempts to match the sting. The default value is 1. To change this setting, enter: min_string_length = num where num is the number of characters in the string. 50 MULTI: Editing Files and Configuring the IDE

63 Configuring the Editor Auto-Completion of Function Prototypes Auto-complete entries also control the use of function prototypes. Function prototypes are often defined in included files. Whenever the Editor loads a C or C++ file, it automatically grabs the include files for function prototypes if it can find the include files. grab_prototype = Specifies whether function prototypes are dynamically grabbed as you type in the Editor. The default setting is false. To dynamically grab function prototypes as you type, enter grab_protoype = true. Automatically grabbing function prototypes is only supported for C and C++. show_prototype = Specifies whether function prototypes are displayed as you type. To automatically display function prototypes, enter show_prototype = true. When when you type a function name in the Editor followed by a ( (open parentheses), a tooltip containing prototype information will appear to guide you through the function s arguments. The default setting is false. These two options are explicitly enabled in the syntax definition files for C and C++. Green Hills Software, Inc. 51

64 2. The MULTI Editor 52 MULTI: Editing Files and Configuring the IDE

65 Chapter 3 Editor GUI Reference This Chapter Contains: The File Menu The Edit Menu The View Menu The Block Menu The Tools Menu The Version Menu The Config Menu The Windows Menu The Help Menu UNIX Dialog Boxes

66 3. Editor GUI Reference The MULTI Editor graphical user interface (GUI) contains menus, toolbar buttons and keyboard shortcuts for editing files. All of the Editor GUI menus are described in the tables that follow. The tables also include the equivalent toolbar buttons and keyboard shortcuts, where applicable. Most of the menu items also have equivalent commands, which may be entered by using the GUI menu item Tools Execute Editor Commands (see The Tools Menu on page 65). Advanced users can also use these commands to configure their keyboard or mouse shortcuts (see Customizing Keys and Mouse Clicks on page 165). For a complete list of Editor commands, see Appendix A. The File Menu The File menu contains the following items: New Editor (Ctrl + N) Opens a file in a new Editor window. Select a file from the Edit File dialog box and click Edit; or to create a new file, enter the new filename and click Edit. This menu item is bound to the LoadFileWithNewEditor command (see File Commands on page 351). Open (Ctrl + O) Opens a file in the current Editor window. Select a file from the Edit File dialog box and click Edit; or to create a new file, enter the new filename and click Edit. The selected file is pushed to the top of the context stack for the current window. This menu item is bound to the OpenFile command (see File Commands on page 351). Save (Ctrl + S) Saves the current file. This menu item is bound to the Save command (see File Commands on page 351). 54 MULTI: Editing Files and Configuring the IDE

67 The File Menu Save As (Ctrl + Shift + S) Saves the current file with a new name. Specify the new path and filename in the Save As dialog box. This menu item is bound to the SaveAs command (see File Commands on page 351). Save All Opens the Save All dialog box. All open files with changes that have not been saved will be listed. Select the check boxes next to the files you want to save, then click Save Selected. Tosaveallofthelistedfiles, click Save All. This menu item is bound to the QuerySaveAll command (see File Commands on page 351). Revert to Saved Undoes all changes made to the current file since the last time it was saved. This menu item is bound to the Revert command (see File Commands on page 351). Revert to Backup Undoes all changes made to the current file since the last time it was backed up. See the configuration option Create backup file when saving in MULTI Editor Options Tab on page 216 for backup file. This menu item is bound to the RevertToBackup command (see File Commands on page 351). Page Setup Windows only Opens the Page Setup dialog box, which allows you to set printing options for the current file. This menu item is bound to the PageSetup command (see File Commands on page 351). Print Opens the Print dialog box, which allows you to print the current file to a printer or to a file. For UNIX, see The Print Setup Dialog Box on page 74. This menu item is bound to the Print command (see File Commands on page 351). 1, 2, 3, 4, 5, 6, 7, 8 Up to eight previously viewed files may be listed. Select any of the files to open it in the current Editor window. Green Hills Software, Inc. 55

68 3. Editor GUI Reference Close File (Ctrl + Shift + P) Closes the current file and prompts you to save any unsaved changes. If the file was checked out of version control during this session, you will be prompted to check it back in. This menu item is bound to the Close command (see File Commands on page 351). Save and Close (Ctrl + Shift + Q) Closes and saves changes to open files without prompting, then exits the Editor. This function is accessed with the Save and Close button on theeditor Toolbar. It is not available in the GUI menus. This menu item is bound to the Done command (see File Commands on page 351). Close Editor (Ctrl + Q) Prompts you to save the changes made to open files, then exits the Editor. This menu item is bound to the Close command (see File Commands on page 351). Exit All Prompts you to save the changes made to all open files, then quits all MULTI tools (including the Legacy Builder and Debugger windows) that are currently running and from which the Editor is launched. This menu item is bound to the Quit command (see File Commands on page 351). 56 MULTI: Editing Files and Configuring the IDE

69 The Edit Menu The Edit Menu The Edit menu contains the following items: Undo (Ctrl + Z) Reverts the last change made to the current file. Each Undo reverts one more change. This process can be repeated until all changes made since the file was opened are undone. This menu item is bound to the Undo command (see Undo/Redo Commands on page 354). Redo (Ctrl + Y) Restores the last edit that was removed by Undo. YoucanRedo multiple Undos, until you make new changes to the file. This menu item is bound to the Redo command (see Undo/Redo Commands on page 354). Repeat Last Edit (Ctrl +.). Repeats the last edit you made to the file. You can only use this feature with certain types of edits: text input or replacement. For example, if you just selected text and replaced it with new text, then Repeat Last Edit will delete a similar selection contiguous to the cursor and insert the new text. For example, your file contains the text: This is a block of text. You select the word block and type string, to change the text to: This is a string of text. If you move the cursor to the beginning of the word text (you do not have to highlight the word) and select Edit Repeat Last Edit, the text will change to: This is a string of string. This menu item is bound to the RepeatLast command (see Undo/Redo Commands on page 354). Cut (Ctrl + X) Deletes the current selection and places it on the clipboard. This menu item is bound to the Cut commands (see Clipboard Commands on page 355). Green Hills Software, Inc. 57

70 3. Editor GUI Reference Copy (Ctrl + C) Copies the current selection to the clipboard. This menu item is bound to the Copy commands (see Clipboard Commands on page 355). Paste (Ctrl + V) Pastes the clipboard contents to the current location. This menu item is bound to the Paste commands (see Clipboard Commands on page 355). Delete (Ctrl + D) Deletes the current selection. If there is no current selection, deletes the character after the insertion point. This menu item is bound to the Delete command (see Text Deletion Commands on page 358). Select All (Ctrl + A) Selects the entire contents of the current file and moves the cursor to the end of the file. This menu item is bound to the SelectAll command (see Selection Commands on page 372). Find (Ctrl + Shift + F) Opens the Search dialog box which allows you to set criteria for an interactive search. For more information, see Interactive Searching Using the Search Dialog Box on page 26. Alternately, use Ctrl + F to perform an incremental search for a string without using the dialog box. For more information, see Incremental Searching on page 25. These items are bound to the Search and ISearch commands (see Search Commands on page 359). Goto (Ctrl + Shift + G) Opens the GoTo dialog box, which allows you to go to a file, line number or function. For more information, see Using the GoTo Dialog Box on page 32. UseCtrl+Gtoquicklygotoalinenumber without using the dialog box. For more information, see Quickly Go To a Line on page 33. These items are bound to the Goto and EditLine commands (see Navigation Commands on page 344). 58 MULTI: Editing Files and Configuring the IDE

71 The View Menu The View Menu The View menu contains the following items: Language Specifies the programming language used in the current source file. The Editor uses this setting for syntax coloring, commenting, and auto-indenting features. This menu item is bound to the SelectLanguage command (see Miscellaneous Commands on page 380). Per Language Settings Opens the Language Settings dialog box which lists settings for the selected language. The items in this dialog box are: Auto-Complete Indicates whether auto-completion is active for the selected language. For more information, see Configuring Auto-Complete on page 49. Auto-completion Match Algorithm Select Best Match or First Match Min. String Length for Auto-completion The number of characters to be entered before auto-completion attempts to match the string. Max Number of Objects to Show for Auto-completion The number of matched objects to display when you enter Ctrl + / or Ctrl + to show the matched object names or function prototypes. The default is specified in the corresponding language s configuration file (see The language.gsc Syntax Definition Files on page 47). Dynamically Grab Function Prototype The Editor can automatically grab the function prototypes in the edited files for C and C++ code. The default is specified in the corresponding language s configuration file (see The language.gsc Syntax Definition Files on page 47). Show Function Prototype Whenyoutypeinafunctionnamefollowed by (, the Editor will display the function s prototype to help you enter the arguments. The default is specified in language s configuration file (see The language.gsc Syntax Definition Files on page 47). This menu item is bound to the LanguageOptions command (see Miscellaneous Commands on page 380). Per File Settings Opens the Per File Settings dialog box which lists variables that can be set for an individual file. These settings are used only for the current session only. See The Per File Settings Dialog Box on page 61 for details. This menu item is bound to the EditorFlags command (see File Commands on page 351). Green Hills Software, Inc. 59

72 3. Editor GUI Reference File Properties Displays information the Editor is able to obtain about the file, including: Language. Number of include files. Cross reference file. Extra syntax information. Enclosing project name. Progress information about the cross reference files for the enclosing project. This menu item is bound to the FileProperties command (see File Commands on page 351). Next File (Ctrl + Shift + Tab) Switches to the next open file in the Editor stack. This menu item is bound to the CyclePushBack command (see File Commands on page 351). Previous File (Ctrl + Tab) Switches to the previous open file in the Editor stack. This menu item is bound to the CyclePush command (see File Commands on page 351). Flash Cursor (Esc) Scrolls to and flashes the line containing the cursor. This menu item is bound to the FlashCursor command (see Navigation Commands on page 344). Match (Shift + Right-click) Searches backward from the cursor for the first paired character (parenthesis, square bracket, or curly brace) at the same nesting level as the cursor, and selects the paired characters and all text enclosed by them. This menu item is bound to the SelecToMatch command (see Selection Commands on page 372). Column Opens the Column dialog box, which allows you to enter a specified column on the current line, if applicable. This menu item is bound to the Column command (see Navigation Commands on page 344). 60 MULTI: Editing Files and Configuring the IDE

73 The View Menu Read Only Toggles the file between read-only and writable modes, if possible. A check next to this menu item indicates that the file is currently read-only. This menu item is bound to the ToggleReadOnly command. Generate Cross References / Regenerate Cross References For C and C++ files, obtains complete cross reference information based on the project to which the source file belongs. When you select this menu item, the Editor will search for the enclosing project and generate cross reference information for the whole project. Once cross reference information for the enclosing project is generated, the menu item will change to Regenerate Cross References. If any of the source files in the project have changed, the cross references for the enclosing project must be regenerated for the information to be accurate. These menu items are bound to the GenerateXrefInfo and RegenerateXrefInfo commands. Close Dependent Windows Deletes all cross reference Browse windows. This menu item is bound to the CloseDependentWindows command (see Miscellaneous Commands on page 380). The Per File Settings Dialog Box This dialog box lists a number of indenting and text wrapping options that you can set for the current file and current session only. To open this dialog box, select View Per File Settings. Note These settings default to the Editor options in Config Options. For more information about these settings, see MULTI Editor Options Tab on page 216 and More Editor Options Dialog Box on page 220. The Per File Settings dialog box contains the following fields: Indent size Controls the number of spaces the Editor inserts when you press the Tab key. The default is 4 spaces. If you enter 0 to disable tabs, pressing Tab will insert a single space. Green Hills Software, Inc. 61

74 3. Editor GUI Reference Ada indent size For Ada language file types only. Sets the indentation size. The default is 3 spaces. For more information, see MULTI Editor Options Tab on page 216. Ada continuation size For Ada language file types only. Determines how far a line of Ada source code is indented if it continues on multiple lines. Wrap column If Word wrap is enabled, this setting specifies the column at which word wrap takes affect. If a line grows to longer than this number of columnsasyouare typing, the Editor will insert a line break at the first whitespace before the column. It will indent the newly formed line by the same amount as the line above it, plus the wrap indent offset, described below. Wrap indent offset If Word wrap is enabled, this setting determines how much the wrapped line will be indented past the indentation of the line above it. Word wrap Check this box to enable word wrap, or clear it to disable word wrap. If Word wrap is enabled, the Editor will wrap lines automatically as you type, but will not wrap long lines while loading a file. Disk format Determines whether the file will be saved in UNIX format or DOS format (with carriage returns). It will default to the appropriate setting. Procedure Order Selects the order in which procedures will display in the Procedure drop-down menu (see File and and Procedure Fields on page 18). Permitted settings for this option are: Base Name Displays procedures sorted by the procedure s base name. Full Name Displays procedures sorted by their class name, then procedure name. Position Displays procedures in the order they appear in the file. 62 MULTI: Editing Files and Configuring the IDE

75 The Block Menu The Block Menu The Block menu contains the following items: Indent (Ctrl + i) Indents at the beginning of the current line or selected lines. The default size is four spaces. To change the indent size, select Config Options, then select the MULTI Editor tab and edit the Indent size field. This menu item is bound to the Indent command (see Indentation Commands on page 361). Unindent (Ctrl + Shift + i) Deletes a number of spaces equal to or less than the size of an indent from the beginning of the current line. This menu item is bound to the Unindent command (see Indentation Commands on page 361). Auto Indent (Ctrl + 2) Indents the current line or block of lines to the position indicated by the syntax of the code. This option is only available for the C, C++, Java, and Ada languages. For more information, see Auto-Indenting Code on page 35. This menu item is bound to the AutoIndent command (see Indentation Commands on page 361). Comment (Ctrl + *) Inserts language specific characters to signify that the selected text is a comment, and not code. This menu item is bound to the CommentBlock command (see Block Commands on page 360). UnComment (Ctrl + Shift + U) Removes comment characters from the selected text to make it active code. This menu item is bound to the UnCommentBlock command (see Block Commands on page 360). UpperCase (Ctrl + +) Changes all the characters in the current selection to upper case. This operation is not supported for FORTRAN, Pascal, and Green Hills Script. This menu item is bound to the UpperCaseBlock command (see Block Commands on page 360). Green Hills Software, Inc. 63

76 3. Editor GUI Reference LowerCase (Ctrl + ) Changes all the characters in the current selection to lower case. This operation is not supported for FORTRAN, Pascal, and Green Hills Script. This menu item is bound to the LowerCaseBlock command (see Block Commands on page 360). Rect Copy Copies a rectangular subsection of the current selection to the clipboard. For more information, see Working with Columns on page 37. This menu item is bound to the RectCopy1 command (see Clipboard Commands on page 355). Rect Cut Deletes a rectangular subsection of the current selection, and copies it to the clipboard. For more information, see Working with Columns on page 37. This menu item is bound to the RectCut1 command (see Clipboard Commands on page 355). RectPaste Pastes a clipboard selection created with Rect Copy or Rect Cut to the current location without line breaks. If you use Edit Paste (Ctrl + V) to paste a rectangular selection, line breaks will be added. For more information, see Working with Columns on page 37. This menu item is bound to the RectPaste1 command (see Clipboard Commands on page 355). Cut Lines (Ctrl + M) Extends the current selection to the closest line boundaries, deletes the selection, and places it on clipboard number two. This menu item is bound to the SelectLine; Cut2 command combination (see Selection Commands on page 372 and Clipboard Commands on page 355). Join Lines (Ctrl + P) Joins two lines of text by replacing the new line character from the end of the current line and all initial whitespace on the next line with a single space. This menu item is bound to the JoinLines command (see Block Commands on page 360). Insert File Opens the Insert dialog box, which allows you to select a file to be inserted. The contents of the inserted file are placed on the line above the cursor. This menu item is bound to the InsertFile command (see Insert Commands on page 362). 64 MULTI: Editing Files and Configuring the IDE

77 The Tools Menu The Tools Menu The Tools menu contains the following items: Insert Date (Ctrl + Shift + D) Inserts the current date, as a formatted string, at the current location. This menu item is bound to the Date command (see Insert Commands on page 362). Search in Files Opens the Search in Files dialog box, which allows you to search for an expression in all open files. See Searching in Files on page 30 for a description of this window and how to use it. This menu item is bound to the Grep command (see Tools Commands on page 363). Start Launcher Opens the MULTI Launcher, which provides easy access to all the primary MULTI components. The Launcher Bar provides a convenient way to create new files and projects, to access recent ones, and to manage your currently open windows. This menu item is bound to the MultiBar command (see Miscellaneous Commands on page 380). For more information about Launcher, see The Launcher GUI on page 90. Make UNIX only Opens the Thing to make? dialog box. Changes made in the Editor are saved before Make starts. To examine erroneous lines, click error messages that appear in the output window. This menu item is bound to the Make command (see Tools Commands on page 363). Green Hills Software, Inc. 65

78 3. Editor GUI Reference Execute Shell Command UNIX only Opens the Shell Command to exe dialog box, which allows you to execute a command in the shell, then inserts the output into the open file. The command uses the current selection in the Editor as stdin, and replaces that selection with stdout. If nothing is selected, the output from the command is inserted into the open file after the cursor s current position. The following macro sequences are recognized in the command: %FILE Replaced with the name of the current open file. %SEL Replaced with the current selection. %LINE Replaced with the current line number. %COMMENTS Replaced with text from a dialog box that prompts for input. This menu item is bound to the ExecuteCmd command (see Tools Commands on page 363). Command to Window UNIX only Opens the Command to Window dialog box, which allows you to execute a command in the shell. Output will appear in a new temporary Editor window. This command does not modify the open file. The following macro sequences are recognized in the command: %FILE Replaced with the name of the current open file. %SEL Replaced with the current selection. %LINE Replaced with the current line number. %COMMENTS Replaced with text from a dialog box that prompts for input. This menu item is bound to the CommandToWindow command (see Tools Commands on page 363). Hex Editor Opens the Hex Editor. For information, see Chapter 4, The MULTI Hex Editor. Notepad Opens a small Editor window in a scratch file. Thescratchfileusedis: (Windows) multipad.txt in your current working directory. (UNIX) ~/.Notes. This menu item is bound to the Notepad command (see Tools Commands on page 363). 66 MULTI: Editing Files and Configuring the IDE

79 The Tools Menu Launch Utility Programs Opens the Utility Program Launcher dialog box, which allows you to launch one of the Green Hills utility programs. This menu item is bound to the WGUtils command (see Tools Commands on page 363). Execute Editor Commands Opens the Execute Editor Commands dialog box, which allows you to enter Editor commands. This menu item is bound to the Minibuffer command (see Tools Commands on page 363). Append TagFile Opens a dialog box where you can specify a tag file (in the format determined by the ctag utility) that the Editor can use to find procedures in files. By default, the Editor looks for a file called tags. For more information, see Using Tags in Your Files on page 34. This menu item is bound to the AppendTagFile command (see Tag Commands on page 365). Reset Tags Resets the tag file to the default, tags. This menu item is bound to the ResetTags command (see Tools Commands on page 363). Merge Files Opens the Merge dialog box, which allows you to merge two or three files. For more information, see Merging Files on page 39. This menu item is bound to the MergeFiles command ( Tools Commands on page 363). Diff Files Opens the Diff Files dialog box, which allows you to find and display the differences between two files. For more information, see Comparing Files on page 43. This menu item is bound to the DiffFiles command (see Tools Commands on page 363). Green Hills Software, Inc. 67

80 3. Editor GUI Reference The Version Menu Most of the items in the Version menu are enabled only if the current file uses version control. The availability of the items listed in the table varies according to which version control system is being used. For more information, see Chapter 6, Using Version Control with MULTI. Check Out Retrieves a writable copy of the latest version and locks the file so that other users cannot change the file while you work on it. Checks out the current file from version control for editing. (Files cannot be edited unless they are checked out.) This action is not relevant if you are using CVS. This menu item is bound to the CheckOut command (see Version Control Commands on page 369). Check In Saves any changes you have made to the current file, makes the file read only in MULTI, and removes the lock from the file. You will be asked for comments to be saved in the log file along with your changes. This menu item is bound to the CheckIn command (see Version Control Commands on page 369). Check In All Saves the changes you have made to all the files you have checked out, makes the files read only in MULTI, and removes the lock from the files. You will be asked for comments to be saved in the log file along with your changes. This menu item is bound to the QuerySaveCheckinAll command (see Version Control Commands on page 369). Discard Changes Undoes all changes made to the file since it was checked out from version control, removes the lock from the file, and reverts to the latest version. This function updates the timestamp on a file in case the modified version was used in a previous build. Use this to undo a checkout without making any changes. (This will make the file read only.) This menu item is bound to the Discard command (see Version Control Commands on page 369). 68 MULTI: Editing Files and Configuring the IDE

81 The Version Menu Place Under VC Puts the current file under version control, prompting you to insert comments (if desired). After you have performed this action, the file must be checked out before changes can be made. If using MVC, this is equivalent to the create command, which creates a log file. For more information, see the create in Appendix B. This menu item is bound to the PlaceUnderVC command (see Version Control Commands on page 369). Auto Checkout Enables or disables Auto Checkout mode. If Auto Checkout is not selected, you must manually check out a file that uses version control before you can edit the file. If Auto Checkout is enabled, files will be automatically checked out from the version control system when you initiate an editing action. This option functions on a per-file basis and defaults to the value of the Automatic Checkout configuration option. For more information, see Chapter 8, Configuring and Customizing MULTI. This menu item is bound to the AllowAutoCheckout and PreventAutoCheckout commands (see Version Control Commands on page 369). Show History Opens the History Browser, which displays information about all versions of the current file. This window displays the check-in comment, who checked the file in, and the date of the check-in. You can double-click any entry in the history to open the Editor on a temporary copy of that version. See The History Browser on page 138 for more information. (If you are using ClearCase, this command opens the ClearCase history browser rather than the MULTI History Browser.) This menu item is bound to the ShowHistory command (see Version Control Commands on page 369). Show Last Edit Finds the version of the current file that changed the selected text, or if no text is selected, the current line. A Diff Viewer window opens and displays the version that changed the text. (For more information about using this window, see The Diff Viewer on page 141.) This menu item is bound to the ShowLastEdit command (see Version Control Commands on page 369). Revert To History Opens the History Browser, which lists all versions of the current file, and from which you can select a version to load into the Editor. (This is not supported for all version control systems.) This menu item is bound to the RevertHistory command (see Version Control Commands on page 369). Green Hills Software, Inc. 69

82 3. Editor GUI Reference Revert To Date Opens a dialog box in which you can enter a revision date. The Editor will load the version that was current on the date you specify. This menu item is bound to the RevertDate command (see Version Control Commands on page 369). Revert To Version Opens a dialog box in which you can enter a version number of the current file to load into the Editor. (This is not supported for all version control systems.) This menu item is bound to the RevertVersion command (see Version Control Commands on page 369). The Config Menu The Config menu contains the following items: Options Opens the Options dialog box to change options that affect the appearance and behavior of the Editor and other MULTI tools. This dialog box contains is covered in detail in Chapter 9, Configuration Options. This menu item is bound to the ConfigOptions command (see Configuration Commands on page 376). Save Configuration as Default Saves the current configuration options in a file in the default location. For more information, see Chapter 9, Configuration Options. This menu item is bound to the SaveConfig command (see Configuration Commands on page 376). Clear Default Configuration Prompts before clearing the default configuration file. This menu item is bound to the ClearConfig command (see Configuration Commands on page 376). Save Configuration Opens the Save Configuration to what file? dialog box, which allows you to specify the filename and location for the configuration file. This menu item is bound to the SaveConfigToFile command (see Configuration Commands on page 376). 70 MULTI: Editing Files and Configuring the IDE

83 The Windows Menu Load Configuration Opens the Load Configuration from what file? dialog box, which allows you to specify the filename and location of the configuration file you want to load. This menu item is bound to the LoadConfigFromFile command (see Configuration Commands on page 376). The Windows Menu The Windows menu is used to jump between any of the windows created by MULTI. If you choose an entry in the Windows menu, the corresponding window is brought to the front of the Editor stack. The following are menu items that may appear in the Windows menu: application_name Opens a submenu listing of all Debugger-related windows created in the same program execution. The main Debugger window for the application is listed first and Data Explorers are listed in a submenu. Select one of the entries to bring the corresponding window to the front. standalone_window_type Lists other standalone windows (created in the same execution, or from other executions), with submenu entries under the corresponding category names. Others Lists other windows, such as Browse Windows launched from the Editor. Misc Lists other windows types that do not fall into any of the above categories. The Help Menu The Help menu contains the following items: Editor Help (F1) Opens MULTI s online help system. This menu item is bound to the Help command (see Help Commands on page 371). Green Hills Software, Inc. 71

84 3. Editor GUI Reference Manuals Opens the Manuals submenu, which displays a list of manuals appropriate to your version of MULTI. Select one of these manuals to open the online help to the first page of that manual. This option is only available through the Editor GUI. Identify Waits until the next key or mouse click sequence, and displays help for that command instead of executing the command. This menu item is bound to the Identify command (see Help Commands on page 371). About MULTI Opens the About banner. This menu item is bound to the About command (see Help Commands on page 371). UNIX Dialog Boxes The following sections describe dialog boxes that only appear in the Editor on UNIX systems. File Chooser Dialog Box (UNIX) A file chooser dialog box opens if you initiate an action (using a menu, button, command, or shortcut) for which a file must be specified, but you have not yet specified a file. A chooser also opens if you click a Browse or button on a dialog box. A sample UNIX file chooser is shown below. (For information about Windows file choosers, see your Windows documentation.) 72 MULTI: Editing Files and Configuring the IDE

85 UNIX Dialog Boxes The title bar of the file chooser will vary depending on the action you are performing. The table below describes the main elements of the file chooser. Directory Displays the directory whose contents are shown in the File List. Type in a new directory name and press Enter to display a different directory. Directory Buttons With this set of buttons, you can quickly go to different important directories. The buttons that appear are: File List Up One Directory from the current directory. Jumps to the current Working Directory. Jumps to the MULTI Run Directory. Jumps to the User Home Directory. Below the directory text field is the file list. To enter a directory, double-click the directory. To choose a file, single-click the filename. You can click any column header to sort the list in ascending or descending order. If multiple files are allowed for the present operation (for example, Open is selected in the editor menu), use the Shift key to select a consecutive list of files; use the Ctrl key to select non-consecutive files. Filename Type a filename or directory name into this text field. As you type in this field, the selection in the file list will change to reflect the closest match. If you type a directory name and press Enter, or follow the directory name by a slash (/), the file list will change to the specified directory. Green Hills Software, Inc. 73

86 3. Editor GUI Reference File type If you select a file type, the File List will only display files with suffixes that match the selected file type. Action buttons There are two buttons in the lower right corner of the file chooser window. The upper button displays the action that will occur, such as Open (in the example above), OK, oredit. The lower button is the Cancel button, which closes the window without taking any action. The Print Setup Dialog Box On Windows, selecting a printing operation from the File menu opens a standard Print dialog box with settings and options appropriate for your version of Windows and your printer and printer driver. See your Windows and printer documentation for details about the settings on this dialog. On UNIX systems, selecting a printing operation from the File menu opens the following Print Setup dialog box: The settings of the Print Setup dialog box are described in the table below. Print To Specifies where to send the print output. Select either Printer (the default) or File (to write to a postscript file). 74 MULTI: Editing Files and Configuring the IDE

87 UNIX Dialog Boxes Print Command Specifies the print command that will be run when you click Print. Enter the appropriate command and options for printing a file on your specific system (for example, lpr on UNIX). This field is only available if you have chosen the Printer radio button above. Filename Specifies the output post-script file for print to file operations. This field is only available if you have selected the File radio button above. Enter the file to write to,orclickbrowse to open a chooser and navigate to an existing file. (See File Chooser Dialog Box (UNIX) on page 72 for a description of the chooser.) Font Name Specifies the font for your printing operations. Select your desired font from the drop-down list, which contains a list of available fonts on your system. You can also type a font name into this field if it is not in the list. Font Size Specifies the font size used for printing. Select your desired size from the drop-down list. The default font size is 8 point. Paper Size Specifies your paper size. Select Letter, Legal, Executive, ora4. The default setting is Letter. Orientation Specifies the layout for your printed document. Select Portrait or Landscape. The default setting is Portrait. Columns Specifies whether to print the output in one or two columns. The default setting is 1. Print Executes the print request. Cancel Cancels the print request and discards any settings you have changed. Green Hills Software, Inc. 75

88 3. Editor GUI Reference 76 MULTI: Editing Files and Configuring the IDE

89 Chapter 4 The MULTI Hex Editor This Chapter Contains: Using the Hex Editor

90 4. The MULTI Hex Editor MULTI contains a Hex Editor for editing binary files. When you open binary files, MULTI may open them in the Hex Editor by default, or you may be prompted to open them in the Hex Editor. The Hex Editor is a standalone program that can be opened from a command line. UNIX The executable is mhexedit Windows The executable is mhexedit.exe Using the Hex Editor To open a file in the Hex Editor: 1. Select File Open, or enter Ctrl + O. 2. A file chooser will open. Select the file you want to edit, then click Edit. 3. The selected file will open in the Hex Editor. The Hex Editor contains three panes: The left-hand pane displays the offset into the file. The center pane displays the binary hex code. The right-hand pane displays the associated ASCII text. The cursor changes from gray to black to indicate which pane is active. As you make changes to text in the right-hand pane, the associated binary hex code in 78 MULTI: Editing Files and Configuring the IDE

91 Using the Hex Editor the center pane will change. Modified characters will turn red in both panes. Similarly, changes made to the binary hex code in the center pane will change the associated ASCII text in the right-hand pane. The Status Bar displays the byte offset into the file where the cursor is currently located and the total number of bytes in the file. Hex Editor Menus and Keyboard Shortcuts The following menus and keyboard shortcuts are available in the Hex Editor. File Menu The following items are accessible through the Hex Editor s File menu or by using the associated Keyboard Shortcuts: Open Ctrl + O Opens the Edit File? dialog box, which you can use to select a file to edit. If you are currently editing a file with outstanding modifications, you will be prompted to save changes. New Window Opens a new Hex Editor window. Close Ctrl + N Ctrl + W Closes the current file in the Hex Editor. You will be prompted to save changes. Save Saves changes to the current file. Print Window Prints the visible contents of the window. Quit Quits the Hex Editor. You will be prompted to save any changes. Ctrl + S Ctrl + P Ctrl + Q Green Hills Software, Inc. 79

92 4. The MULTI Hex Editor Edit and View Menus The following items are accessible through the Hex Editor s Edit and View menus or by using the associated Keyboard Shortcuts: Copy Copies the selection to the clipboard. (Copy is in the Hex Editor s Edit menu.) Paste Replaces data with the clipboard contents at the cursor s location. (Paste is in the Hex Editor s Edit menu.) Bytes Per Row Enter the number of bytes per row to display in the Hex Editor. The default is 16 bytes per row. (Bytes Per Row is in the Hex Editor s View menu.) Ctrl + C Ctrl + V Search and Goto in the Hex Editor You can find data or a line number in the Hex Editor with the following Keyboard Shortcuts: Ctrl + F Search forward in the file. First select either the ASCII text or the hex data pane. Type the search string after pressing Ctrl + F. Ctrl + B Search backward in the file. First select either the ASCII text or the hex data pane. Type the search string after pressing Ctrl + B. Ctrl+G Gotoanaddresswithinthefile. For more information, see Incremental Searching on page 25 and Quickly Go To a Line on page MULTI: Editing Files and Configuring the IDE

93 Part II Managing Files

94

95 Chapter 5 Using MULTI Workspaces and Shortcuts This Chapter Contains: Creating a Workspace Running Actions and Action Sequences Creating or Modifying an Action Sequence Creating or Modifying an Action Creating MULTI Shortcuts Managing Processes The Launcher GUI

96 5. Using MULTI Workspaces and Shortcuts The Launcher provides an easy method for launching all the primary IDE components and managing user-defined workspaces. A workspace is typically created for each top-level project and includes a working directory and a group of related action sequences. The working directory for the workspace is the directory from which the action sequences will be started and it is typically the directory containing the executable program associated with the project. An action sequence consists of one or more actions that are performed in the listed order. The actions in an action sequences could include: Building a program with MULTI, and then debugging it. Launching the Checkout Browser and opening several frequently-used files for editing Connecting to a Debugger hardware target and opening a serial terminal connection. Running a script or batch file or executing a Debugger command. Invoking an external tool. A shortcut is an action sequence that is not associated with a particular workspace. Shortcuts can be run from within any workspace and execute in the working directory of the currently selected workspace. 84 MULTI: Editing Files and Configuring the IDE

97 Creating a Workspace In the example above, a user has defined a workspace called STP Dev Area with a working directory of c:\my Projects\STP. TheStartup, View Bug List, and Run Client/Server Test action sequences are defined. The Startup action sequence contains the following actions: Open the MULTI Builder on the default.gpj project. Open the Checkout Browser on the src directory. The Run Client/Server Test action sequence contains the following actions: Build the projects stp_server and stp_client. Open the MULTI Debugger on stp_server with arguments set to -port Open the MULTI Debuggeronstp_client with arguments set to -port Creating a Workspace To create a workspace: 1. Select File Create Workspace. TheSelect Workspace Type window will be displayed. 2. Specify a name for your workspace and choose one of the following options, depending on how you want to create the workspace: New Project Select this option if you want to create a workspace containing a new project. The Launcher will start the New Project Wizard to allow you to create the project. For more information, see Creating a New Project: The New Project Wizard in Chapter 2, The MULTI Builder in the MULTI: Building Applications book. Existing Project Select this option if you already have a top-level project and you want to create a workspace to provide you with easier access to that project. The Launcher will prompt you to specify the location of your existing top-level project. Blank Select this option if you want to create an empty workspace. You can customize the workspace later. Enter a path to your desired working directory in the Working Directory field or click to navigate to the desired working directory. Green Hills Software, Inc. 85

98 5. Using MULTI Workspaces and Shortcuts When you create a workspace for a new project or existing project, an action sequence called Startup is created. The Startup action sequence launches the Builder on the project. Creating or Modifying an Action Sequence on page 87 explains how to customize this action sequence or add other action sequences to the workspace. Copying and Moving Workspaces The Launcher saves definitions of workspaces, shortcuts and other Launcher items in the file config.gmb, which is located in your local configuration directory. To find the path, make a change to your current workspace or a shortcut and select File Save Changes. A dialog box will open that displays the full path. If you want to move the workspaces and global shortcuts you created on one computer to another, copy the config.gmb file to the proper directory. Workspaces and global shortcuts can also be made available to other users by copying the corresponding file to their configuration directory, or merging your definitions into their Launcher configuration file. For example, to export a workspace definition to another user, copy the workspace s definition into the workspace scope in their Launcher configuration file. The Launcher configuration file is a text file in the general Green Hills Software odb (object data base) format, with straightforward syntax. Running Actions and Action Sequences Before running an action sequence or an action, you must select the desired workspace from the drop-down list at the top left of the Launcher. Torunanactionsequence: 1. Click the Shortcut button ( ). 2. Select the appropriate action sequence from the list. The action sequences contained in the current workspace are listed first, followed by any shortcuts. When you run an action sequence, all the actions associated with the action sequence will be performed in order. 86 MULTI: Editing Files and Configuring the IDE

99 Creating or Modifying an Action Sequence To run one or more actions, do one of the following: Select the desired actions, then click the Run button. Right-click the selected actions and select Run from the shortcut menu. If the actions or action sequences being executed contain a blocking command action, a build action, a wait action or any utility action, a progress window opens. The progress window s title indicates the currently executing action or the last executed action if execution is finished. For more information about the progress window, see Miscellaneous Dialogs and the Progress Window on page 96. Creating or Modifying an Action Sequence To create an action sequence: Click the Add button. If the button is not visible, you may have the detail pane hidden. To reveal the detail pane, click. To delete an action sequence, do one of the following: Select the action sequence and click the Delete action. Right-click the action sequence and select Delete from the shortcut menu. To edit an action sequence, do one of the following: Select the action sequence and click the Edit button. Right-click the action sequence and select Edit from the shortcut menu. Double-click an action sequence. To reorder action sequences: 1. Select an action sequence. 2. PressCtrl + UpArrow or Ctrl + DownArrow to move the action sequence up or down. Action sequences are edited from the Edit Action Sequence dialog. You can perform the following operations by right-clicking an action. Green Hills Software, Inc. 87

100 5. Using MULTI Workspaces and Shortcuts Edit Displays the Edit Action dialog. For more information, see Creating or Modifying an Action on page 88. Disable or Enable Disables or enables the selected action. Disabled actions appear dimmed and do not run when the action sequence is run. Cut, Copy, Paste, ordelete Performs the requested editing operation on the selected action. The Paste button inserts actions above the current selection; it does not overwrite the current selection. Move Up or Move Down Moves the selected action or actions one position up (earlier) or down (later) in thelistofactions. Creating or Modifying an Action To create an action, display the Edit Action dialog in one of the following ways: From the Launcher, right-click the action sequence and select Add Action. From the Edit Action Sequence dialog click Add Action. To modify an action, perform one of the following: From the Launcher, double-click the action or right-click the action and choose Edit. From the Edit Action Sequence dialog, either right-click the action and choose Edit or highlight the action and click Edit Action. The Edit Action dialog contains two fields. The first field, called Action, specifies the type of action. The second field contains the arguments for the action. The name of the second field depends on which Action is selected. You should first select the type of action from the Action list, then customize the second field. The available action types and example arguments are as follows: Builder Opens the MULTI Builder on the specified project. For example: MyProjects/Project1/default.gpj 88 MULTI: Editing Files and Configuring the IDE

101 Creating or Modifying an Action Build Project Builds the specified project. For example: MyProjects/Project1/default.gpj Debug Program Opens the MULTI Debugger on the specified executable. For example: MyProjects/Project1/prog Debugger Command Performs the specified Debugger command. For a list of commands, see Chapter 30, Debugger Commands in the MULTI: Debugging book. For example: cb Editor Opens the MULTI Editor on the specified file. For example: MyProjects/Project1/readme.txt Checkout Browser Opens the Checkout Browser on the specified directory. For example: MyProjects/Project1 Connection Connects to the specified target. For example: simppc Serial Terminal Connects via a Serial Terminal to the specified target. For example: (for Windows) com1 (for Linux) ttys0 EventAnalyzer Opens the EventAnalyzer on the specified event source file. For example: evlog.mes. ResourceAnalyzer Connects the ResourceAnalyzer to the specified target. For example: Nonblocking Command Runs the specified shell command. The command output is not displayed. A nonblocking command is particularly good for launching graphical programs. For example: gmemfile program Blocking Command Runs the specified shell command. Subsequent actions must wait until the Blocking Command has completed before running. The command output is displayed in an editor window. A blocking command is particularly good for command line programs or batch-processing applications. For example: gsize program Wait Causes the Launcher to wait the specified number of milliseconds before executing the next action. For example: (waits for 10 seconds). Utility Actions Runs one of the Green Hills utility programs. When you choose this action in the Edit Action dialog, the Launcher displays a list of utility actions and allows you to choose one. For example: gstrip program If the chosen action type requires a filename or directory to be specified, the drop-down list will also contain a Select File or Select Directory option to launch a file or directory chooser. Green Hills Software, Inc. 89

102 5. Using MULTI Workspaces and Shortcuts Creating MULTI Shortcuts MULTI shortcuts are like action sequences, except that they are not associated with any particular workspace. To create a shortcut: Click the Shortcut button ( ). Select Create or Change Shortcut. The MULTI Launcher Shortcuts pane will appear. The Working Dir: field is empty to indicate that shortcuts do not have a working directory associated with them. Shortcuts execute in the working directory of the currently selected workspace. You can create or modify shortcuts just as you would action sequences for a workspace (see Creating or Modifying an Action Sequence on page 87). Managing Processes Each time a workspace action launches another program, that program appears in the Launcher Processes menu. If necessary, you can terminate the program by choosing it from the list in the Processes menu. The following actions cause the corresponding program to appear in the Launcher Processes menu: Build Project, Nonblocking Command, Blocking Command, Wait, andutility Actions. This menu does not list components of the MULTI IDE that were launched by Launcher actions. Note The Processes menu only lists workspace actions. This menu is not related to programs being debugged by the MULTI Debugger. The Launcher GUI The Launcher provides the ability to easily launch all major IDE components and manage user-defined workspaces that can be customized to your common working environments. The Launcher provides the following two display modes, depending on whether you need to create or modify workspaces and action sequences. 90 MULTI: Editing Files and Configuring the IDE

103 The Launcher GUI Concise mode (as shown below), which uses less screen space. This can be useful if you do not need to access or modify individual actions. Detailed mode (as shown below), which shows more information and allows you to modify workspace action sequences. You can switch between the two modes by clicking the or button. The current mode is maintained across Launcher sessions. Opening Workspaces You can create as many workspaces as necessary, but only one workspace can be the current workspace, and you can only run the actions from the current workspace. You can change current workspaces in the following ways: Open the workspace pulldown menu and select the desired workspace (see The Launcher Toolbar on page 92). Green Hills Software, Inc. 91

104 5. Using MULTI Workspaces and Shortcuts Select File Recent Workspaces, and select the desired workspace in the submenu. The Launcher Toolbar On the left side of the Launcher Toolbar, the pulldown shows the current workspace. The full list of existing workspaces can be viewed by clicking the pulldown. In the menu, you can select a workspace, which will become the current workspace. The Launcher has the following buttons in its toolbar: (Shortcut) Lists the following items: Action sequences In the order they were defined in the current workspace. When an action sequence is selected, it will be executed. Shortcuts In the order they were used. The most recently used shortcut is at the beginning. When a shortcut is selected, it will be executed. Create Workspace See Creating a Workspace on page 85 for details. Create or Change Shortcut See Creating MULTI Shortcuts on page 90 for details. (Builder) Lists the following items: Projects Thatwere used as arguments in the Builder actions in the current workspace. When a project is selected, it will open in a Builder. Most recently used projects When a project is selected, it will open in a Builder. Open Project Builder See the corresponding menu item in The File Menu on page 98. Create Project See the corresponding menu item in The File Menu on page 98. (Debugger) Lists the following items: Programs Used as arguments in the Debug Program actions in the current workspace. When a program is selected, it will open in a MULTI Debugger. Most recently used programs When a program is selected, it will open in a MULTI Debugger. 92 MULTI: Editing Files and Configuring the IDE

105 The Launcher GUI Open Debugger See the corresponding menu item in The File Menu on page 98. Lists the following items: Files Used as arguments in the Editor actions in the current workspace. When a file is selected, it will open in an Editor. Most recently used Editor files When a file is selected, it will open in an Editor. Open Editor See the corresponding menu item in The File Menu on page 98. (Checkout Browser) Lists the following items: Directories Used as arguments in the Checkout Browser actions in the current workspace. When a directory is selected, it will be used as the argument to launch a Checkout Browser. Most recently used Checkout Browser directories When a directory is selected, it will be used as the argument to launch a Checkout Browser. Open Checkout Browser See the corresponding menu item in The File Menu on page 98. (Connect) Lists the following items: Targets Used as arguments in the Connection actions in the current workspace. When a target is selected, a connection will be established to the corresponding target. Most recently used targets When a target is selected, a connection will be established to the corresponding target. Existing connections in the system (preceded by Disconnect:) When an entry is selected, the corresponding connection will be closed. Connect See the corresponding menu item in The File Menu on page 98. Open Connection Organizer See the corresponding menu item in The File Menu onpage98. (Serial Terminal) Lists the following items: Green Hills Software, Inc. 93

106 5. Using MULTI Workspaces and Shortcuts Serial Terminal Targets Used as arguments in the Serial Terminal actions in the current workspace. When a serial target is selected, a serial terminal connection will be established to the corresponding target. Most recently used Serial Terminal Targets When a serial target is selected, a serial terminal connection will be established to the corresponding target. Open Terminal See the corresponding menu item in The File Menu on page 98. (EventAnalyzer) This button will not be present if the MULTI EventAnalyzer is not licensed or if the executable does not exist in your distribution. Lists the following items: Event Stream Files Used as arguments in the EventAnalyzer actions in the current workspace. When an event stream file is selected, it will open in a MULTI EventAnalyzer. Most recently used Event Stream Files When an event stream file is selected, it will open in a MULTI EventAnalyzer. Open EventAnalyzer See the corresponding menu item in The File Menu on page 98. (ResourceAnalyzer) This button will not be present if the MULTI ResourceAnalyzer is not licensed or if the executable does not exist in your distribution. Lists the following items: ResourceAnalyzer Targets Used as arguments in the ResourceAnalyzer actions in the current workspace. When an item is selected, a MULTI ResourceAnalyzer.will be launched to try to connect to the target. Most recently used ResourceAnalyzer targets When an item is selected, a MULTI ResourceAnalyzer will be launched to try to connect to the target. Open ResourceAnalyzer See the corresponding menu item in The File Menu on page 98. (Close) Closes the Launcher. (more) or (less) Expands or shrinks the Launcher window to show or hide the detail pane. 94 MULTI: Editing Files and Configuring the IDE

107 The Launcher GUI The Detail Pane The detail pane is located below the toolbar. It is displayed when the Launcher is in detailed mode. The detail pane can display the brief help information about the Launcher or it can display the current workspace s information. When you create a new workspace or select a workspace as the current workspace in the detailed display mode, the detail pane will show the workspace s information, even if it was previously displaying the brief help information. When the detail pane displays help information, it contains the following elements: Help information pane Shows brief information about the Launcher. Don t show this message again Select this check box to instruct the Launcher to hide the help information when it starts up next time. Start with MULTI Launcher Select this check box to start the Launcher when the multi command is run with no arguments. See the corresponding menu entry in The Config Menu on page 102. When the detail pane shows the current workspace information, it contains the following elements: Name The workspace name. Working Dir The workspace working directory. Properties Opens a dialog box that allows you to change the current workspace s basic information (in the Current tab) and certain global settings (in the Global tab). Buttons Change the current workspace s action sequences and actions. Add adds a new action sequence. The other buttons operate on the objects selected in the action tree. Action tree Lists the action sequences and actions in the current workspace. The following keyboard commands can be used to manipulate the action tree: Green Hills Software, Inc. 95

108 5. Using MULTI Workspaces and Shortcuts Key Action Ctrl + UpArrow Ctrl + DownArrow Ctrl + X Ctrl + C Ctrl + V Ctrl + D Delete Meaning Moves the selected objects up by one row (see the note below). Moves the selected objects down by one row (see the note below). Deletes the selected objects and copies the selected actions into an internal buffer. Copies the selected actions into an internal buffer. Pastes the actions in the internal buffer before the selected action or at the end of the selected action sequence. Deletes the selected objects, including actions and action sequences. Deletes the selected objects, including actions and action sequences. Note When one of the operations Run, Move Up or Move Down (from the right-click shortcut menu or the equivalent keyboard command) is applied to the selected objects in the action tree, the operation will be applied as follows: If any action is selected, the operations will be applied only to those selected actions and not to entire action sequences. Otherwise, the operations will be applied to the selected action sequences. When the Run operation is applied to an object: If the object is an action, the action will be executed even if the action is disabled. If the object is an action sequence, only enabled actions of the action sequence will be executed. The Delete operation is applied to all selected objects in the action tree; both actions and action sequences. Miscellaneous Dialogs and the Progress Window The Launcher opens various dialog boxes for: Creating a workspace Changing workspace properties and global settings 96 MULTI: Editing Files and Configuring the IDE

109 The Launcher GUI Editing an action sequence Editing an action These dialog boxes are not described here, although some are described earlier in this chapter. A progress window (a MULTI Editor) will be displayed when you execute actions or action sequences that contain any of the following: Blocking Command action Build Project action Wait action Any utility action. The progress window s title indicates the currently executing action or the last executed action if execution is finished. In the progress window, the output from actions is displayed in the normal text color, and each action s output is separated by some progress lines which are put in by the Launcher and are displayed in a special color. If the execution is not finished yet and you try to close the progress window, you will be asked if you want to terminate the execution. If you choose yes, the corresponding execution will be terminated. You can also terminate an execution in progress at any time by selecting the corresponding entry in the Processes menu. Green Hills Software, Inc. 97

110 5. Using MULTI Workspaces and Shortcuts The Launcher Menus This section describes the choices and commands available in the Launcher menus. The File Menu The File menu has the following entries: Create Workspace Creates a new workspace. Delete Current Workspace Deletes the current workspace, and automatically selects the next workspace (if any) as the current workspace. Recent Workspaces Lists the most-recently-accessed workspaces so you can select one as the current workspace. Create or Change Shortcuts Creates a new shortcut or changes an existing shortcut. A shortcut is an action sequence that is not associated with a particular workspace. Open Project Builder Opens an existing project. The project will be opened in either the Project Builder or the Legacy Builder, depending on the project type (.gpj or.bld) and the setting of the Convert Legacy Projects option (see The Config Menu on page 102 for more information). Create New Project Creates a new project using the New Project Wizard, and loads the created project in a Builder. The new project will be created in either the.gpj format supported by the Project Builder or the.bld format supported by the Legacy Builder, depending on the setting of the Create Legacy Projects option. (see The Config Menu on page 102 for more information). Open Debugger Debugs an existing program. This launches a file chooser to allow you to select the program to debug. Open Editor Edits an existing file. This launches a file chooser to allow you to select the file to edit. 98 MULTI: Editing Files and Configuring the IDE

111 The Launcher GUI Open Checkout Browser Launches the Checkout Browser from the current working directory. Connect Launches the connection dialog so that you can establish a connection. Open Connection Organizer Launches the Connection Organizer for you to manipulate your connections. Open Serial Terminal Launches the Serial Terminal. Open EventAnalyzer Launches the MULTI EventAnalyzer. This entry will not be present if the MULTI EventAnalyzer is not licensed or if the executable does not exist in your distribution. Open ResourceAnalyzer Launches the MULTI ResourceAnalyzer GUI. This entry will not be present if the MULTI ResourceAnalyzer is not licensed or if the executable does not exist in your distribution Save Changes Saves the changes you made to workspaces or the Launcher properties into the Launcher s configuration file. After the changes are saved, a dialog box will open, showing the path of the Launcher s configuration file. Close Launcher Closes the Launcher. Any unsaved changes to workspaces or the Launcher properties will be saved automatically. Exit All Closes all MULTI windows, including the Launcher. Green Hills Software, Inc. 99

112 5. Using MULTI Workspaces and Shortcuts The Utilities Menu The Utilities menu has the following entries: License Administrator Opens the Green Hills Licensing Tool to perform software license management actions. Probe Administrator Launches the Green Hills Probe Administrator to manage the Green Hills probes on your local network. This entry will not be present if the Green Hills Probe Administrator is not licensed or if the executable does not exist in your distribution Launch Utility Programs Allows you to run one of the utility programs. The Windows Menu The Windows menu list all the top-level windows from various MULTI components in the system. Selecting an item for a MULTI window (in the second level menus) will cause the corresponding window to be shown at the top. The Windows menu lists only window types that are actually open. The menu may contain the following entries: Debugger Lists all open MULTI Debugger windows. Editor Lists all open MULTI Editor windows. Task Manager Lists all open Task Manager windows. Connection Organizer Lists all open Connection Organizer windows. Builder Lists all open MULTI Builder windows (both Project Builder and Legacy Builder). Checkout Browser Lists all open Checkout Browser windows. 100 MULTI: Editing Files and Configuring the IDE

113 The Launcher GUI OSA Explorer Lists all open OSA Explorer windows. EventAnalyzer Lists all open MULTI EventAnalyzer windows. ResourceAnalyzer Lists all open MULTI ResourceAnalyzer windows. Misc Lists all other open MULTI windows in the system. If there is no other MULTI window in the system, the item will not be displayed. Minimize All Windows Minimizes all MULTI windows except the Launcher. If there are no MULTI windows open, this item will not be displayed. Show All Windows Restores all MULTI windows to their normal sizes. If there are no MULTI windows open, this item will not be displayed. Close All Windows Closes all windows listed in the menu. When certain windows are closed, you may be prompted first. For example: When a Debugger is closed, you may be asked whether to kill the program being debugged; When an Editor is closed, you may be asked whether to save outstanding changes. If there are no MULTI windows open, this item will not be displayed. No Windows Indicates that no MULTI windows (except for the Launcher itself) are open. If any MULTI windows are open, this item will not be displayed. Green Hills Software, Inc. 101

114 5. Using MULTI Workspaces and Shortcuts The Processes Menu The Launcher executes a non-standard action in non-blocking mode by spawning a separate process for the corresponding executable or shell script. The Launcher keeps track of such spawned processes and lists all of the currently executing processes in its Processes menu. The menu has the following entries: Kill process_info: pid Kills the corresponding process that was spawned from the Launcher. No Processes Indicates that no currently executing processes were spawned from the Launcher. If any currently executing processes were spawned from the Launcher, this item will not be displayed. The Config Menu The Config menu has the following entries: Show/Hide Detail Pane Specifies whether the Detail Pane (see The Detail Pane on page 95) is visible in the Launcher. Click this menu item to toggle between showing or hiding the Detail Pane. Start with MULTI Launcher Specifies the effect of entering the multi command on the command line. If a check mark appears next to this menu item, issuing the multi command with no arguments will run the Launcher. This is the default behavior. If no check mark appears next to this menu item, issuing the multi command with no arguments will run the Legacy Builder. To toggle between these settings, click the menu item. Create Legacy Projects Specifies the build format to be used when creating new projects from the Launcher. If a check mark appears next to this menu item, new projects will be created in the.bld format supported by the Legacy Builder. If no check mark appears next to this menu item, new projects will be created in the.gpj format supported by the Project Builder. This is the default setting. To toggle between these settings, click the menu item. 102 MULTI: Editing Files and Configuring the IDE

115 The Launcher GUI Convert Legacy Projects Specifies how MULTI will behave when you open.bld format projects. If a check mark appears next to this menu item,.bld format legacy projects will be automatically converted into the.gpj format and then opened in the Project Builder. After the translation, the top legacy.bld file will be archived with the extension.bak. This is the default setting. If no check mark appears next to this menu item,.bld format legacy projects will be opened with the Legacy Builder. To toggle between these settings, click the menu item. In all cases, the Project Builder will be used for projects in the.gpj format. Options Opens the MULTI options dialog (see Chapter 9, Configuration Options for more details). Save Configuration as Default Saves the current configuration options in the default location. For more information, see Chapter 9, Configuration Options. Clear Default Configuration Clears the default configuration file. The Launcher prompts before performing this action. Save Configuration Opens the Save Configuration to what file? dialog box, which allows you to specify the filename and location in which to save the configuration. Load Configuration Opens the Load Configuration from what file? dialog box, which allows you to specify the filename and location of the configuration file to load. The Help Menu The Help menu has the following entries: Show Information Shows the Launcher information in the Detail Pane. This information includes a brief description about how to use the Launcher. Help Opens MULTI s online help system. Green Hills Software, Inc. 103

116 5. Using MULTI Workspaces and Shortcuts Manuals Opens the Manuals submenu, which displays a list of manuals appropriate to your version of MULTI. Select one of these manuals to open the online help to the first page of that manual. About MULTI Shows basic information about MULTI, including the version number and revision date. Troubleshooting Info Gathers information about your MULTI distribution, including your system information, environment information and your MULTI installation information, and displays it in a dialog box. You can save the information to a file or send it to others, such as Green Hills support or your product support contact. 104 MULTI: Editing Files and Configuring the IDE

117 Chapter 6 Using Version Control with MULTI This Chapter Contains: Configuring Version Control in MULTI Using Version Control with the MULTI Editor and Builder Integrating with MULTI Version Control (MVC) Integrating with ClearCase Integrating with CVS Integrating with RCS Integrating with SourceSafe Integrating with PVCS Integrating with a Custom Version Control System

118 6. Using Version Control with MULTI The MULTI IDE can be integrated with a number of different version control systems such as ClearCase, CVS, RCS, PVCS and SourceSafe. MULTI also includes its own version control system, MULTI Version Control (MVC). Additionally you can configure a custom version control integration to support other version control systems. The first portion of this chapter describes general procedures for enabling, configuring, and using a version control system with MULTI. The later sections provide specific instructions relating to each of the supported version control systems. Configuring Version Control in MULTI MULTI supports the following version control systems: MULTI Version Control (MVC) ClearCase CVS PVCS RCS SourceSafe Note You can also configure MULTI to integrate with other version control systems by setting custom version control options. For more information, see Integrating with a Custom Version Control System on page 124. MULTI s support for version control is enabled by default and will attempt to automatically detect which version control system is being used. To configure MULTI s version control support, perform the following steps: 1. Open the Options window: In the Editor, Checkout Browser, Debugger or Launcher, select Config Options; or In the Builder, select Tools Options. 106 MULTI: Editing Files and Configuring the IDE

119 Configuring Version Control in MULTI 2. Select the General tab of Options window. 3. In the Version Control field, select a version control system from the drop-down list. The available options are: Auto Detect Causes MULTI to automatically detect the version control system being used. This is the default setting, and should only be changed if MULTI appears not to be integrating correctly with your version control system, or you are using a custom version control integration. Disable Disables MULTI s version control integration. CVS Configures MULTI to integrate with CVS (Concurrent Version Systems). See the CVS ( web site for more information. For detailed information, see Integrating with CVS on page 118. MVC Configures MULTI to integrate with MULTI Version Control (MVC), the version control system provided by MULTI. For detailed Green Hills Software, Inc. 107

120 6. Using Version Control with MULTI information, see Integrating with MULTI Version Control (MVC) on page 112. RCS Configures MULTI to integrate with the RCS version control system. For detailed information, see Integrating with RCS on page 119. ClearCase Configures MULTI to integrate with Rational s ClearCase version control system. For detailed information, see Integrating with ClearCase on page 118. PVCS (Windows only) Configures MULTI to use MERANT s PVCS version control system. For detailed information, see Integrating with PVCS onpage122. SourceSafe (Windows only) Configures MULTI to integrate with Microsoft s SourceSafe version control system. For detailed information, see Integrating with SourceSafe on page 119. Custom Configures MULTI to integrate with a version control system other than those listed above. To use MULTI with a custom version control system, you will need to customize various version control options, as described in Integrating with a Custom Version Control System on page Click the Configure Version Control button to open a dialog box that will prompt you to enter settings that are specific to the version control system you have selected. After you have entered the applicable settings, click OK in the dialog box. 5. Click OK to apply your settings to the current session and close the Options window. If you want to save these settings to be used in future MULTI sessions, select Config Save Configuration as Default. Note You may need to restart any Editors or Builders that you have open for the version control configuration changes to take effect. 108 MULTI: Editing Files and Configuring the IDE

121 Using Version Control with the MULTI Editor and Builder Using Version Control with the MULTI Editor and Builder The MULTI Editor and MULTI Builder contain menus that provide access to common version control actions, such as checking files in and out and viewing version history. In the Editor, version control actions are available from the Version menu. In the Builder, version control actions are available from the Tools Version Control submenu. The options on these menus vary slightly and are described below. Version Control Options from the Editor The following menu items are available in the MULTI Editor. Their availability is determined by the version control system used. Check the section corresponding to the version control system you are using to determine which items are available and any special notes on the item specific to your version control system. Check Out Update Check In/Commit Check In All Discard Changes Place Under VC Auto Checkout Check a file out of the version control system to allow for editing. If the file is not checked out, no edits will be allowed. This is not meaningful for CVS. Issue an update command. If the repository version corresponding to the version of the local file has changed, the changes are merged into the local file. This is only available for CVS. Check a file into a version control system. Commit is used for CVS and Check In is used for other version control systems. Check in all checked out files at once. Discard current changes and release the file if it was checked out. Place a file under a version control system. If a version control system was not specified, it will be automatically detected based on the version control system used for other files in the same directory. When an edit operation is desired and this option is checked, the file will automatically be checked out. This is not meaningful for CVS. Green Hills Software, Inc. 109

122 6. Using Version Control with MULTI Show History Show Last Edit Revert to History Revert to Date Revert to Version Show View Starts the history browser on the file, see The History Browser on page 138. For ClearCase this will start the ClearCase history browser. Shows the last edit in the selected region. Starts the history browser. The file is reverted to a specific version chosen through the history browser. See The History Browser on page 138. Prompts for a date and reverts the file to that date. Prompts for a version and reverts the file to that version. Show both the working directory and the set ClearCase view. This is only available for ClearCase on non-windows hosts. The working directory used is the directory of the current file being edited. Version Control Options from the Builder These are the items that can be accessed through the Tools Version Control menu in the Builder. Check Out Check In/Commit Check In + Out Retrieve Discard Changes Place Under VC Show History Check the selected files out of a version control system to allow for edit. If the file is not checked out, no edits will be allowed. This is not meaningful for CVS. Check the selected files into a version control system. Commit is used for CVS and Check In is used for other systems. Perform the Check In operation and then the Check Out operation. Retrieves read-only copies of the selected files. Discard current changes for the files selected and release any selected files that are checked out. Place the selected files under a version control system. If a version control system was not specified, it will be automatically detected. Starts the history browser on the selected files. For ClearCase this will start the ClearCase history browser. See The History Browser on page MULTI: Editing Files and Configuring the IDE

123 Using Version Control with the MULTI Editor and Builder Checkout Browser Other VC Command Starts the checkout browser. See The Checkout Browser on page 128. Opens a dialog which allows a version control command to be called. Automatic Checkout If you enable the Automatic Checkout option, the MULTI Editor will automatically check out a file when you start editing it. In most version control systems files that have not been checked out are read-only, which prevents you from making changes to them. CVS is an exception to this rule because it allows multiple users to edit the same file simultaneously and then makes a best effort to merge the changes. To configure the Editor to automatically check out files when you modify them: 1. In the Editor, select the Config Options. In the Builder, select Tools Options. 2. Select the General tab. 3. Click the Configure Version Control button and check the Automatic Checkout option if available (see Version Control Configuration Options on page 185). This box may not be available for certain version control systems. For example, in CVS a file is always checked out so there is no option to enable or disable Automatic Checkout. Note To control Automatic Checkout on a per-file basis, select Version Auto Checkout in the Editor. Show Last Edit To show the last edit made to a specific portion of a file: 1. In the Editor, select the portion of the file you want to examine. 2. Select Version Show Last Edit. This finds the last version of the current file in which the selected text changed (or the current line, if no text is selected) and displays the difference in the Diff Viewer. For information about the Diff Viewer, see Green Hills Software, Inc. 111

124 6. Using Version Control with MULTI The Diff Viewer on page 141. If the selection has never changed, a dialog explaining stating this will be displayed. This command is only available if the file is under a version control system that supports this feature (such as MVC, CVS, ClearCase and SourceSafe). This command is also available if the file has been locally modified, in which case the Diff Viewer will display the difference between the local file and the repository version of the file. Revert to a Previous Version of a File There are three ways to specify the version of a file to which you want to revert: To select the version to revert to from a list of all versions of the file: 1. Select Version Revert to History. 2. A History Browser will open. You can right click a version in the browser window and select Revert to Version (see The History Browser on page 138). To revert to a version checked in on a specific date: 1. Select Version Revert to Date. 2. A dialog box will open where you can enter the date of the appropriate version. To revert to a specific version number: 1. Select Version Revert to Version. 2. A dialog box will open where you can enter the appropriate version number. Integrating with MULTI Version Control (MVC) MULTI Version Control (MVC) provides a proprietary version control system for text files. By default, MULTI is configured to automatically detect which version control system to use, and will default to MVC when no other system can be detected. If you do not have a version control system, it is easy to begin using MVC. 112 MULTI: Editing Files and Configuring the IDE

125 Integrating with MULTI Version Control (MVC) Note MVC works on text files only. If you attempt to check in any binary files and then check them out, they may become corrupted. MVC keeps track of all changes to your text files in separate log files. When you edit a file, you first check out the file from version control. After you finish editing a file, you check in your changes. This creates a new version in the log file. The log file preserves the entire version history, allowing you to revert back to a previous version or restore previous versions for comparison. If you are using the Editor to edit a file and have Automatic Checkout enabled (see Automatic Checkout on page 111), the file is automatically checked out when you make changes. When you close the file, it is automatically checked in. During the check in process, a dialog box prompts you for comments. These comments are saved in the log file along with the new version. To prevent changes from being made to files without MVC s knowledge, all files under MVC are read-only. Files become writable when they are checked out and return to read-only status when they are checked in. (UNIX) Files become writable only to the user who checked out the files. This prevents multiple users from editing the same file at the same time. When a file is under MVC, the following directories are created in the same directory as the file: mvc.log This directory contains the MVC log files: (Windows) If the file C:\a\john\fly.c is placed under MVC, then the log file is C:\a\john\mvc.log\fly.c. (UNIX) If the file /a/john/fly.c is placed under MVC, then the log file is /a/john/mvc.log/fly.c. These log files must not be modified by hand, as all version history may be lost if the file becomes corrupted. mvc.lok This is a subdirectory of mvc.log. This directory contains the lock files that display who has checked out the file. MVC only allows one user to check out a file at a time: (Windows) The lock file for C:\a\john\fly.c is C:\a\john\mvc.log\mvc.lok\fly.c. (UNIX) The lock file for /a/john/fly.c is /a/john/mvc.log/mvc.lok/fly.c. Green Hills Software, Inc. 113

126 6. Using Version Control with MULTI mvc.sem This is a subdirectory of mvc.log. This directory contains temporary files used as semaphores to prevent two different MULTI sessions from writing to the same MVC log file at the same time. Using MVC There are several ways to access MVC options and commands: Select menu items in the Version menu of the Editor, or the Version Control submenu of the Builder (see Using Version Control with the MULTI Editor and Builder on page 109). Enter a full MVC command line (see Entering MVC Commands on page 114). MVC commands can be passed on the command line to the mvc executable included with MULTI, or by selecting Tools Version Control Other VC Command in the Builder. Use the Editor to edit a text file that is under version control. Files will be checked in and out automatically. Files must be placed under version control manually. To place files under MVC, do one of the following: From the Editor, choose Version Place Under VC. From the command line, run mvc with the create option (see create in Appendix B). Entering MVC Commands You can enter a full MVC command in two different places: There is an mvc executable included with MULTI that can be executed from a DOS window or from a UNIX shell. In the Builder, choose Version Other VC Command. Many MVC actions are also available from the Version menu of the Editor, or the Version Control submenu of the Builder (see Using Version Control with the MULTI Editor and Builder on page 109). All of the commands in Appendix B, take at least one filename as an argument. Multiple filenames are separated by spaces. 114 MULTI: Editing Files and Configuring the IDE

127 Integrating with MULTI Version Control (MVC) In all MVC commands, version refers to the MVC version number of the file on which the command operates. If no version number is specified, the current version is assumed. For a check out, the current version is the latest version on the main version sequence. For a check in, the current version is the same but with the minor version number incremented by one. For more information about specifying version numbers in MVC, see Version Numbers and Branching on page 116. Some MVC commands use a -d date option instead of a version number to refer to a given version. For more information about entering dates in MVC commands, see MVC Date Format on page 117. You can add the -c option to any MVC command that checks in a file to force MVC to prompt for comments. MVC Directory Options To use MVC with directories other than the current one, use: -L logdir Specifies the directory that contains the mvc.log directory. -S sourcedir Specifies the directory that contains the source files. For Windows: If the source files are in C:\usr\john and the log files are in C:\usr\george\mvc.log, then the command: mvc ci fly.c bat.c -S \usr\john -L C:\usr\george takes the files C:\usr\john\fly.c and C:\usr\john\bat.c and checks them into the log files C:\usr\george\mvc.log\fly.c and C:\usr\george\mvc.log\bat.c. For UNIX: If the source files are in /usr/john and the log files are in /usr/george/mvc.log, then the command: mvc ci fly.c bat.c -S /usr/john -L /usr/george takes the files /usr/john/fly.c and /usr/john/bat.c and checks them into the log files /usr/george/mvc.log/fly.c and /usr/george/mvc.log/bat.c. Green Hills Software, Inc. 115

128 6. Using Version Control with MULTI Version Numbers and Branching Version numbers are created when new files are added to a branch or version, allowing you to revert to previous versions if necessary. Version numbers have the form: major_version.minor_version As you create new versions, the minor version number is incremented by one for each new version. You can manually set the version number for a new version (for instance if you want to increment the major version number) by using the -v command line option of the various check in commands. This is done from an MVC command line. For example, the command: mvc ci foo.c -v 3.2 checks in the file foo.c with version number 3.2. Version numbers are never allowed to decrease. For example, a version number sequence can go from 1.4 to 1.5, or from 1.5 to 2.1, but version numbers cannot go from 2.5 to 2.4 or from 2.5 to 1.6. Creating a Branch You can create a branch in the version for a file by adding two more dots (..) to the version number. For example, a version sequence might be 1.1, 1.2, 1.3, 1.4. If you create a version with the number , that version is a branch off the main sequence. The version sequence for that branch would be 1.1, 1.2, 1.3, The next version for that branch after would be To create a branch, use the -v command line option of the various check in commands. The version must be entered in the form of a branch version (with four numbers). This must to be done from the MVC command line. For example, the command: mvc ci foo.c -v creates a branch off of version 1.5. When you work on a branch, you should always use the -v version option. If you omit the -v version option, MVC assumes that you are working on the main 116 MULTI: Editing Files and Configuring the IDE

129 Integrating with MULTI Version Control (MVC) version sequence. This creates a version on the main sequence instead of on the branch. For example, this command: mvc co foo.c -v edits foo.c. Then, this command: mvc ci foo.c -v checks it in on the branch. Compare that with the command: mvc ci foo.c which creates a version on the main branch (for example, version 1.6). MVC Date Format Some MVC commands accept a date (for example, -d date) instead of a version number to refer to a given version. The date needs to be in the form: MMDDYYhhmmss where MM = month; DD =day;yy = year; hh = hour; mm = minutes; ss = seconds. The individual components of the date can be separated with non-digit characters (except for whitespace). For example, you can specify the date as or Do not put spaces in the date. If any part of the date is omitted, then the maximum value for that part is used. For example, implies (August 25, 1997 at 11:59:59 pm). Two-digit years between 50 and 99 are assumed to describe years from 1950 to 1999, while years from 00 to 49 are used to refer to years from 2000 to You can use four-digit years by using the -D date option which takes a date in the form: YYYYMMDDhhmmss Green Hills Software, Inc. 117

130 6. Using Version Control with MULTI Integrating with ClearCase If you use ClearCase, the program cleartool should exist in your path. If it does not, or if your ClearCase program uses a filename other than cleartool you should configure your ClearCase options to set the path to the ClearCase executable (see Configuring Version Control in MULTI on page 106). The default location is /usr/atria/bin/cleartool on UNIX hosts and C:\Program Files\Rational\ClearCase\bin\cleartool on windows. The following features and issues are specific to ClearCase: Show History starts the ClearCase history browser. Revert To History and Revert To Date are not available. The Show View item is added to the Editor Version menu. (see Working with Views on page 118). The Show Last Edit command does not detect deletions. That is if a range of lines is selected in a file, the Show Last Edit command will not show the most recent change if it was a deletion in that range. There is no Checkout Browser support for ClearCase. WorkingwithViews If you are going to set a view, it must be set before MULTI is started. There is no way to set or change the view once MULTI has been started. To see your current view, choose Version Show View from the Editor. This will display the working directory view and the set view. The working directory view is also displayed next to the filename being edited at the top of the editor pane. If it is necessary to work with two different views then set a view, start the Editor, and then set the next view and start another Editor. Integrating with CVS If you use CVS, the program cvs should exist in your path. If it does not, or if your CVS program uses a filename other than cvs you should configure your CVS options to set the path to the CVS executable (see Configuring Version Control in MULTI on page 106). 118 MULTI: Editing Files and Configuring the IDE

131 Integrating with RCS The following features and issues are specific to CVS: Show Last Edit will not detect deletions. That is, if a range of lines is selected in a file, the Show Last Edit command will not show the most recent change if it was a deletion in that range. The Checkout Browser is supported with CVS. See The Checkout Browser on page 128 for more information about the Checkout Browser. The History Browser is supported with CVS. See The History Browser on page 138 for more information about the History Browser. Integrating with RCS If the RCS integration with MULTI is used, then the programs ci, co,and rlog must exist in your path. As with the MVC integration, a file is read-only until it is checked out. Usually a file is checked out (Check Out), modified, and checked back in (Check In). If the Auto Checkout option is enabled, the file is automatically checked out when an edit is attempted (see Automatic Checkout on page 111). The following features and issues are specific to RCS: Show Last Edit is not available with RCS. The Checkout Browser is not supported with RCS. Integrating with SourceSafe Note The SourceSafe integration is only available on Windows hosts. If the SourceSafe integration with MULTI is used, then the program ss.exe should exist in your path. If it does not, or if your SourceSafe program uses a filename other than ss.exe you should configure your SourceSafe options to set the path to the SourceSafe executable (see Configuring Version Control in MULTI on page 106). The default location used is C:\Program Files\Microsoft Visual Studio\VSS\win32\ss.exe. One advantage of this integration is that several different databases can be used simultaneously. The user can edit files from two different databases at the same time. The integration requires some setup steps to indicate what database is being used. Green Hills Software, Inc. 119

132 6. Using Version Control with MULTI The following features and issues are specific to SourceSafe: Show Last Edit will not detect deletions. That is, if a range of lines is selected in a file, the Show Last Edit command will not show the most recent change if it was a deletion in that range. The Checkout Browser is supported with SourceSafe. See The Checkout Browser on page 128 for more information about the Checkout Browser. The History Browser is supported with SourceSafe. See The History Browser on page 138 for more information about the History Browser. VSS Database Structure Assumptions The following assumptions are made about the structure of the Visual Source Safe (VSS) database. A working directory is defined. This should be defined using the Visual SourceSafe Explorer, which comes with the installation of VSS. The directory structure in the working directory mirrors the directory structure of the database. For example: If there is a database with the following structure: $/ _hello _hello.c andiftheworkingdirectoryof$/ is C:\ssafedir, thentheworkingdirectoryof the hello project is assumed to be C:\ssafedir\hello. Most of the MULTI version control operations (such as Check Out, Place Under VC) assume read/write access permissions. However, you can view files read only. Required Setup Steps 1. It is necessary to specify the database working folder location, otherwise known as the root of the checkout. It is also necessary to specify what database is going to be used. The are two ways to specify these parameters. a. The fist way to configure these parameters is through the GUI. i. Select the Config Options available in most MULTI GUI s. 120 MULTI: Editing Files and Configuring the IDE

133 Integrating with SourceSafe ii. Select the General tab and then choose SourceSafe from the Version Control pull-down. iii. Click the Configure Version Control button and enter the path to the root of the checkout and the directory path of the srcsafe.ini file for the database being used. Ask your administrator for the location of this file. b. The second way to configure these parameters is to create a.ssdir file at the root of each database checkout. This file should contain a single line with the directory path to the srcsafe.ini file for that particular database. For the example in the previous section it would be necessary to place a.ssdir file in the directory C:\ssafedir. The contents of the file would look similar to: C:\Program Files\Microsoft Visual Studio\VSS Ask your administrator for the location or determine the location by using the Open SourceSafe Database option in the Visual SourceSafe Explorer. This is a one time setup step required for each database checkout you want to use the MULTI version control integration with. It is necessary to use this method if the auto detection option is enabled. Auto detection works by locating and reading the.ssdir file. 2. Set the SSUSER environment variable. Set SSUSER to your SourceSafe username. This is necessary to avoid queries for your username. 3. Set the SSPWD environment variable. Set SSPWD to the SourceSafe password that corresponds to the SSUSER environment variable. This is necessary to avoid queries for your password. Using the Integration To create a new project in the database, simply create a new directory in the appropriate place in the working directory and start checking in files. With the first checked in file, a new project will be created by that name. Green Hills Software, Inc. 121

134 6. Using Version Control with MULTI Integrating with PVCS Note The PVCS integration is only available on Windows hosts with PVCS version 8. The integration requires some setup steps to indicate what project database is being used. The following features and issues are specific to PVCS: Show Last Edit is not available. The Checkout Browser is supported with PVCS. See The Checkout Browser on page 128 for more information about the Checkout Browser. The History Browser is supported with PVCS. See The History Browser on page 138 for more information about the History Browser. Assumptions The following assumptions are made. It is assumed that the workfile location for a project database is set at the root level and that all they subprojects are assigned default workfile locations. For example, if the workfile location for a project database is C:\project1, then the subproject subproject1 is assigned C:\project1\subproject1 as its workfile location. It is assumed that there is a local copy of the project database files located at the project database workfile location, including it s subprojects. The integration with the Checkout Browser relies on comparing the directory structure of the project database workfile location and the project database. It is assumed the login source is either VCSID or HOME for the project database. Most of the version control operations (such as Check Out, Place Under VC) assume read/write access permissions. These permissions are assumed both for the workfile location and for the archive directory. However, you can view files read only. 122 MULTI: Editing Files and Configuring the IDE

135 Integrating with PVCS Required Setup Steps It is necessary to specify the project database workfile location, otherwise known as the root of the checkout. It is also necessary to specify what project database is going to be used. The are two ways to specify these parameters. 1. The fist way to configure these parameters is through the GUI. a. Select the Config Options available in most MULTI GUI s. b. Select the General tab and then choose PVCS from the Version Control pull-down. c. Click the Configure Version Control button and enter the path to the root of the checkout and the full path of the master configuration file for the project database being used. Ask your administrator for the location of this file. 2. The second way to configure these parameters is to create a.pvcsdir file at the root of each project database checkout. In other words, this file has to be located in the project database workfile location. This file should contain a single line with the full pathname of the master configuration file for the project database being used. Ask your administrator for the location of this file. The location of the file specifies the root of the checkout and the content of the file specifies what project database is going to be used. It is necessary to use this method if the auto detection option is enabled. Auto detection works by locating and reading the.pvcsdir file. Using the Integration To create a new subproject in the project database, simply create a new directory in the appropriate place in the workfile location and start checking in files. With the first checked in file, a new subproject will be created by that name. Green Hills Software, Inc. 123

136 6. Using Version Control with MULTI Integrating with a Custom Version Control System You can also configure MULTI to integrate with a custom version control system. To do this, you must use the Custom Configuration dialog to specify which commands perform the basic version control operations, such as checking in a file and checking out a file. Each of the commands requires a filename as an argument and should return output in a form acceptable to MULTI. For a full description of the commands that must be specified and the acceptable output for each, see Custom Version Contol Options on page 186. Minimal preprocessing is performed on the commands specified in the Custom Configuration dialog. If %c is specified as part of a command and comments are available, the %c is substituted with the comment string before the command is run. The following example shows the custom version control configuration settings for the SCSS version control system. (To open the Custom Configuration dialog, select Config Options from the Launcher, Debugger, or Editor, or Tools Options from the Builder, then select the General tab, set the Version Control field to Custom, and then click the Configure Version Control button.) 124 MULTI: Editing Files and Configuring the IDE

137 Integrating with a Custom Version Control System Example 1. Custom Configuration for SCSS Version Control The settings shown below configure MULTI for use with the SCSS version control system. ThefulltextfortheUnder VC field in this example is: perl -e \ use File::Basename; exit not -r (dirname($argv[0]). -> \"/SCCS/s.\". basename($argv[0]))\ The full text for the Who field is in this example is: perl -e \ use File::Basename; $d = dirname($argv[0]); $b= basename($argv[0]); ->open F, \"sccs info $d \"; [.0-9]+([-_A-Za-z0-9]+)/;}\ Green Hills Software, Inc. 125

138 6. Using Version Control with MULTI 126 MULTI: Editing Files and Configuring the IDE

139 Chapter 7 Version Control Tools This Chapter Contains: The Checkout Browser The History Browser The Diff Viewer

140 7. Version Control Tools MULTI provides three tools that provide graphical interfaces for viewing information about files under version control: Checkout Browser Provides a graphical view of the files in your checkout and easy access to version control operations, such as checking files in and out and viewing revision history. For more information, see The Checkout Browser on page 128. History Browser Displays the complete revision history of any file under version control. For more information, see The History Browser on page 138. Diff Viewer Compares two ASCII files (typically different revisions of the same file) and highlights differences between them. For more information, see The Diff Viewer on page 141. Each of these tools is described in detail below. The Checkout Browser The Checkout Browser is designed to be used with CVS, PVCS or SourceSafe to give you a graphical view of your checkout and the status of files in the repository. While the History Browser (see The History Browser on page 138) is designed to give you detailed version information about a specific file, the Checkout Browser gives you general information about every file in your checkout, and provides access to more detailed information about any file within the checkout. The Checkout Browser also allows you to manipulate the files in your checkout. For example, you can select files in the Checkout Browser that have been modified, compare those files using the Diff Viewer, then commit those files to the repository. Note The term repository is used throughout this chapter to mean the central store of version control information for the version control system in use. Different version control systems may use different terms, for example, in SourceSafe the repository is called a database. 128 MULTI: Editing Files and Configuring the IDE

141 The Checkout Browser Starting the Checkout Browser You can start the Checkout Browser any of the following ways: From the Launcher, click the Checkout Browser button ( ), or select File Open Checkout Browser. (For more information about the Launcher, see TheMULTILauncher onpage4). (UNIX) From a shell with the Green Hills MULTI tools directory in the PATH, entermcobrowse. From MULTI, use the checkoutbrowser command. From the History Browser, select File Checkout Browser. Using the Checkout Browser There are basic modes of operation for the Checkout Browser. They are: Scanning a preexisting checkout Modifying an existing checkout Creating a new checkout This section explains how to scan a preexisting checkout. For information about modifying an existing checkout or creating a new checkout, see Using the Checkout Editor on page 136. To scan a preexisting checkout: 1. Set the Roots field. The Roots field indicates what directories will be scanned and displayed in the browser. You can use any of the following methods to select what will be displayed: Enter a directory in Roots. When using CVS it is possible to supply a comma separated list of directories. Use the Roots drop-down list to select from directories that have previously been displayed in the Checkout Browser. Click to browse for the correct folder. 2. Once you have selected the directories to be displayed, use the File menu to select one of the following two types of scans: Green Hills Software, Inc. 129

142 7. Version Control Tools Local Rescan provides local information, such as which files have been locally modified. Local scans do not contact the remote repository, and as a result are usually faster and do not tax the remote repository, which may have many users. Only available for CVS. Full Rescan gathers information from the remote repository and provides information about local and remote changes to files. Full scans usually take longer than local scans. Pressing Enter after entering or selecting a directory in the Roots field will also perform a full scan. 3. The Checkout Browser will scan the selected directories and display the results of the scan. 130 MULTI: Editing Files and Configuring the IDE

143 The Checkout Browser The following information is displayed in the Checkout Browser: Filename Names of files in the folder you selected. You can click the and buttons to expand or contract the file list. Status Current version control status of the file. The possible values for the status are: No changes The file has not been changed. Locally Modified Changes have been made to the file in your checkout that do not exist in the remote repository. There is a chance that updating the file will result in conflicts if changes have been made to the repository since your last scan. Locally Added The file exists in your checkout and has been marked to be added to the remote repository when committed. Locally Removed The file has been marked to be removed from the remote repository when committed. The file no longer exists in your checkout. Remotely Modified The version in the repository is newer than the version in your checkout, perhaps because another user has checked in a new version of the file. Remotely Added The file exists in the remote repository, but is not in your checkout. This is most likely because someone else has added the file to the repository. Remotely Removed The file has been removed from the repository, but is still in your checkout. Not under VC The file is not recognized by the version control system. This identifies files that have been created inside your checkout, but have not been added or marked to be added to the repository. Needs Merge The file has been modified in your checkout, but a newer version exists in the repository than the version you started with. You must update your checkout to merge the changes between your local version and the repository version before you can commit your changes to the repository. There is a chance that the process of updating the file will result in conflicts if changes have been made to the repository since your last scan. Will Conflict SimilartoNeeds Merge, except when you update your checkout, the merge will create conflicts that must be resolved before you will be able to commit the file to the remote repository. Has Conflict The file in your checkout contains conflicts that must be resolved before you will be able to commit it to the remote repository. Green Hills Software, Inc. 131

144 7. Version Control Tools Local Version Version of the file as it currently exists in the local checkout. Tag The branch tag, if applicable. Locked By A list of user names that have the file locked. Only available for SourceSafe and PVCS. Checkout Browser Menus The following menus and menu items are available from the Checkout Browser: File menu Contains the following items: Start MULTI Launcher Opens the Launcher. Full Rescan Gathers information from the remote repository and provides information about modified files. After this scan the Checkout Browser will show the status of each file in your checkout and corresponding repository at the time it was scanned. Local Rescan Provides local information, such as which files have been locally modified. After this scan the Checkout Browser will show as much status information for each file in your checkout as it can determine without contacting the repository. Only available for CVS. Update Checkout Brings the specified local checkout up to date with the remote repository, performs a scan for local changes, and displays the results in the Checkout Browser. Halt Scan / Update Stops any Rescan or Update in progress. Checkout Editor Open the Checkout Editor. This feature is only supported when using CVS. It is used to create a new checkout, or to modify the contents of an entire checkout or portion of a checkout, such as reverting a checkout to a certain date. For more information, see Using the Checkout Editor on page 136. Close ClosestheCheckout Browser. 132 MULTI: Editing Files and Configuring the IDE

145 The Checkout Browser Show menu This menu is used to select what type of files are displayed in the Checkout Browser. A check mark appears next to items that are currently selected for display. Selecting a menu item toggles the display on or off for that particular type of file. You can choose to display any combination of file types from the menu. The menu items you can select from are: No changes Displays files with no changes. Conflicts Displays files with conflicts that must be resolved before you can commit your local version to the repository (files with Status listed as Needs Merge, Will Conflict, orhas Conflict). Local Changes Displays files that have been changed locally. Remote Changes Displays files that have been changed remotely. Not under VC Displays files that are not currently under Version Control. Config menu This is the same Config menu that appears in other MULTI GUIs. You can use it to modify configuration options for MULTI. For more information, see Chapter 9, Configuration Options. File Operations Shortcut Menu When you right-click one or more filenames or directories in the Checkout Browser, thefile Operations shortcut menu displays. The menu will display some or all of the following options, depending on which version control system you use: Diff with Local Version Opens a Diff Viewer that shows differences between the local file and the version of the file that was originally checked out. See The Diff Viewer on page 141. Diff with Remote Version Opens a Diff Viewer that shows differences between the latest version in the repository and your local version. This menu item is only available for files that have been remotely modified (files with Status listed as Remotely Modified, Needs Merge, orwill Conflict). Edit Opens an editor on the selected files. Green Hills Software, Inc. 133

146 7. Version Control Tools Show History Opens a History Browser that displays information about all versions of the file (see The History Browser on page 138). If you select multiple files, a separate History Browser will open for each file. Rescan Updates the status of the selected files or directory. Useful for determining whether either the repository or local versions have been modified since the last full scan. Update Brings the selected files or directory in your checkout up to date with the versions in the repository. Commit / Check In Checks in local changes of the files or directory selected, creating new versions in the repository. Check Out Checks out the selected files from the repository locking them. Only available for SourceSafe and PVCS. Unlock Releases the lock on the selected files. Only available for SourceSafe and PVCS. Place Under VC Adds the selected files to the repository, creates an initial version, and checks that version out. Only available for SourceSafe and PVCS. Revert to Repository Removes any local changes and reverts files in your local checkout to the version in the repository. Add Marks files to be added to the version control system. Files will not be added to the remote repository until you Commit them. Delete Marks files to be deleted from the version control system. If the files selected are not under version control they will be deleted from your checkout. If the files exist in the repository they will be removed from your checkout and marked for deletion. They will not be removed from the repository until you Commit them. The menu options available in the File Operations shortcut menu will depend on the files or directories you have selected. For example, if you select a directory, the Show History and Diff menu options will be unavailable. Similarly, you cannot Commit a file if no changes have been made, Add a 134 MULTI: Editing Files and Configuring the IDE

147 The Checkout Browser file that already exists in the repository, or Update a file that does not have any remote changes. Status Bar and Status Window The Checkout Browser performs many operations that can take a long time. Information about the operation the Checkout Browser is performing at any given time is displayed in two places, both towards the bottom of the window. While performing a scan, modify or create operation, the Status Window displays a continuously updating stream of text. For CVS this information includes the number of directories which have been scanned and the current output from the CVS executable. Other version control systems may display different information. While performing operations such as committing files, the Status Bar displays the current activity. For example, it will report that it is committing files and once they are committed, the display will change to report which file it is currently rescanning to determine the file s new status. Features and Issues Specific to CVS There are some limitations in the Checkout Browser when using it with CVS. Most of these limitations are imposed by the nature of CVS. The following trade-offs have been made in order to maintain access to common CVS actions: Updating the entire checkout (or a subdirectory) automatically uses the -Pd option to pull in new directories from the repository and prune empty directories from the checkout. Directories that have been added to the repository do not display after a Rescan although they will be displayed after an Update. Thisisbecause the Checkout Browser cannot determine whether the new directories are empty, and will be pruned with the next update. Green Hills Software, Inc. 135

148 7. Version Control Tools Using the Checkout Editor The Checkout Browser provides the capability to create or modify an entire CVS checkout with the Checkout Editor. Note This feature is only supported when using CVS. To start the Checkout Editor select File Checkout Editor from the Checkout Browser. The Checkout Editor has two modes of operation, one for creating a checkout and one for modifying a checkout. To create a checkout: 1. Select the Create Checkout tab. 2. Fill in the required fields: Create Checkout In Directory Enter the destination directory, which is where the checkout will be created. If this directory does not exist but its parent does, the directory will be created automatically. Modules to Checkout Enter a space separated list that specifies what should be checked out. You can enter filenames, directories, and/or modules as defined on the CVS server. Tag to Checkout Enter the tag to use when creating the checkout. Repository Location Enter the location of the repository. By default it is set to whatever is in the $CVSROOT environment variable. 3. Click OK to start creating the checkout. 136 MULTI: Editing Files and Configuring the IDE

149 The Checkout Browser To modify a checkout: 1. Select the Modify Checkout tab. 2. Enter the directory of the checkout to be modified in the Checkout Location. This may be a subdirectory of the root of the checkout. 3. Select either Revert to HEAD or one or both of Revert to Tag and Revert to Date: Revert to HEAD Select to reset all sticky tags. This will clear the selection of Revert to Tag and Revert to Date if either was selected. Revert to Tag Select the check box, then enter the tag of the checkout to revert to in the text field. This will clear the selection of Revert to HEAD if it was selected. Revert to Date Select the check box, then enter the date of the checkout to revert to in the text field. This will clear the selection of Revert to HEAD if it was selected. Note If both a tag and a date are specified CVS will set the sticky tag, and will set the version back to the specified date in that tagged branch, but will not set the sticky date. 4. Click OK to start modifying the checkout. Green Hills Software, Inc. 137

150 7. Version Control Tools The History Browser The History Browser allows you to examine the versions of a file that exist in your version control system. As you scroll through the versions of the file, you can view the check in comments associated with those versions. You can also use the History Browser to compare versions or revert to a previous version. Using the History Browser To start the History Browser, do one of the following: Select Version Show History in the Editor. Select Tools Version Control Show History in the Builder. Select Show History in the Checkout Browser (see The Checkout Browser on page 128), You can open the History Browser as a standalone application by starting the MULTI Editor with the -historybrowser filename option. For example, to start a History Browser that lists the version history of the source files sample.cc, enter: me -historybrowser sample.cc Any of these actions will open the History Browser: 138 MULTI: Editing Files and Configuring the IDE

151 The History Browser The History Browser displays the following information: Status Current version control status of the file. Current Tag Identifying label that was last used to update your local machine. A version might have several labels associated with it in the version control system, but only the label used to update the file on your local machine will appear. Version List The top half of the History Browser window displays the following information about all versions logged in version control: Date Lists the date and time versions were checked in. Version Lists the version numbers assigned to files. If possible, version numbers are grouped by branches with the +/- construct as seen in the previous figure. User Lists the user who saved the specified version. Tag Lists the tags corresponding to the specified version. This is only available for CVS. Information is displayed sorted by Version. You can change the sort criteria by clicking any of the column headings. Comment area The bottom half of the History Browser window displays comments associated with the version selected in the top half of the window. It also lists tags associated with this version. Note To view version changes that occurred after the History Browser was opened, select File Refresh History. History Browser File Menu The History Browser has one menu, the File menu, which contains the following items: Diff with Local Version Opens a Diff Viewer that shows the differences between the selected version of the file and your local version of the file. See The Diff Viewer on page 141. Green Hills Software, Inc. 139

152 7. Version Control Tools Diff 2 Versions Opens a Diff Viewer that shows the differences between two selected versions of the file. If you select a range of versions, Diff 2 Versions will perform a diff between the upper and lower bounds of the range. See The Diff Viewer on page 141. View Selected Version Opens the selected version of the file in an editor. Revert to Selected Version Overwrites the local copy of the file with the selected version. Edit Local Version Opens the local copy of the file in an editor. Refresh History Updates the information in the History Browser. Checkout Browser Opens the Checkout Browser. See The Checkout Browser on page 128. Close Closes the History Browser. History Browser Shortcut Menu The following shortcut menu can be accessed by right-clicking a version in the History Browser: Diff with Local Version Opens a Diff Viewer that shows differences between the selected version of the file and your local version of the file. See The Diff Viewer on page 141. Diff 2 Versions Opens a Diff Viewer that shows difference between the two selected versions of the file. If you select a range of versions, Diff 2 Versions will performs a diff on the upper and lower bounds of range. See The Diff Viewer on page 141. View Opens the selected version of the file in an editor. Revert to Overwrites the local copy of the file with the selected version. 140 MULTI: Editing Files and Configuring the IDE

153 The Diff Viewer The Diff Viewer The Diff Viewer graphically displays differences between two ASCII files, whether they are different files or different versions of the same file. To open the Diff Viewer, do one of the following: MULTI automatically opens the Diff Viewer whenever you choose to compare two files in the History Browser or Checkout Browser (see The History Browser on page 138 and The Checkout Browser on page 128). The Diff Viewer is a standalone executable that can be opened from a command line. For UNIX, the executable is diffview For Windows, the executable is diffview.exe For more information and command line options, see Opening the Diff Viewer from the Command Line on page 141. In the Debugger, use the Diff command. In the Editor, select Tools Diff Files (see The Tools Menu on page 65). If you have not already specified which files to open in the Diff Viewer, the Choose two files dialog box will open: Select filenames and version to compare, then click Diff. TheDiff Viewer will open with the two files that are being compared. For more information, see Using the Diff Viewer on page 142. Opening the Diff Viewer from the Command Line The Diff Viewer accepts command line arguments. You can control the files and versions being compared in the viewer by setting these options. Green Hills Software, Inc. 141

154 7. Version Control Tools The MVC-style syntax is: diffview [options] file1 [-v vers1] [file2 [-v vers2]] The CVS-style syntax is: diffview [options] [-r rev1 -D date1] [-r rev2 -D date2] file1 [file2] The Diff Viewer options include: -h, --help (UNIX only) Displays information about the options. -reuse ReuseanexistingDiff Viewer window (default). -new, -noreuse Open a new Diff Viewer window. Note Whitespace represents space and tab characters. It does not represent newline characters. Using the Diff Viewer The Diff Viewer contains the following features: The main panes of the Diff Viewer display the two files that are being compared. Differences between the files are highlighted in the control area 142 MULTI: Editing Files and Configuring the IDE

155 The Diff Viewer color, while the current selection is highlighted in the highlight color. Lines that are identical have a background whose color is the foreground color. The Status Bar displays the current diff number and total number of diffs. The pane in the lower-right corner displays the version control comments associated with the file displayed in the right-hand pane. It is empty if the file is not under version control. The pane in the lower left corner is the Diff List. It contains a list of all Diff Views that have been opened in the current Diff Viewer session. The columns in this pane represent the following (from left to right): The first column displays a blue dot next to the current Diff. TheReload ( ) button can be used to reload the current diff from the files on disk. The second column shows the filename of the file that will be displayed in the left hand pane when the row is selected, and the third column shows the version of that file. If the file is on disk, this field will display disk, if the file has been locally modified, it will display local (version number) to indicate the version of the file that it is based on. The fourth column shows the filename of the file that will be displayed in the right hand pane when the row is selected, and the fifth column shows the version of that file. If the file is on disk, this field will display disk,if the file has been locally modified, it will display local (version number) to indicate the version of the file that it is based on. The last column displays the total number of differences. A question mark (?) in this column means that to improve performance, the number of differences has not been calculated yet. You can right-click in this box to access the Diff List Commands shortcut menu, which contains the following items: Show Diff Displays the highlighted diff in the main panes of the Diff VIewer. The blue dot will appear next to the diff that is being displayed. Remove Diff Removes the highlighted diff from the Diff List, and from the main panes of the Diff Viewer, if it is currently displayed. Green Hills Software, Inc. 143

156 7. Version Control Tools Navigating the Diff Viewer The Diff Viewer provides a number of ways to navigate through the files: The Next ( )andprevious ( ) buttons scroll through differences between the two displayed versions. The plus (+) and minus (-) keys scroll up and down through the differences, and the asterisk (*) re-positions the pane to display the current difference. You can use the Editor keyboard shortcuts Ctrl + F and Ctrl + B to incrementally search forward or backward through the files (see Incremental Searching on page 25). If there is no current selection, the Diff Viewer begins its search at the top left corner of the visible pane. You can use the Editor keyboard shortcut Ctrl + G to go to a line number (see Quickly Go To a Line on page 33). The line numbers displayed along the left margin of the files can be used as selection bars. Diff Viewer Menus The following Diff Viewer actions can be accessed through the File menu or the Keyboard Shortcuts listed here. Open Diff Ctrl + O Opens a diff file selection dialog box which will add a new diff to the current Diff View window. Open New Diff Ctrl + Shift + O Opens a new diff file selection dialog box which will show the new diff in a new Diff Viewer window. Show Current Diff Ctrl + * Re-positions the Diff Viewer panes to the current diff (highlighted in the highlight color). Close Closes the Diff Viewer. Ctrl + Q 144 MULTI: Editing Files and Configuring the IDE

157 The Diff Viewer The Diff Viewer can be put in several different modes to alter what types of differences it shows to the user. The following Diff Viewer modes can be set through the View menu. Ignore Whitespace Amount Differences in the amounts of whitespace between two otherwise identical lines are ignored. If one line uses ten spaces while its counterpart uses only one then this difference will not be shown. However, if the second line uses no whitespace then a difference will be shown. For instance: void func(int a); and void func(int a); would be considered the same when in this mode. When this mode is selected it will override either of the other whitespace modes if they were selected. Ignore Whitespace for C Ignore whitespace using heuristic C tokenization of a file. The intent of this mode is that whitespace differences within a line which would not affect compilation would not show up as differences. The C tokenization uses a heuristic parser which cannot perfectly account for all cases because it does not have enough information available to do a true compilation of the file. For instance: void func(int a); and void func ( int a ) ; would be considered the same when in this mode. When this mode is selected it will override either of the other whitespace modes if they were selected. Ignore All Whitespace Ignore all whitespace differences between files. For instance: voidfunc(inta); and void func (int a); would be considered the same in this mode. When this mode is selected it will override either of the other whitespace modes if they were selected. Green Hills Software, Inc. 145

158 7. Version Control Tools Case Insensitive Ignore all differences which are caused by differences in capitalization between lines. For instance: void func(int a); and void Func(int A); would be considered the same in this mode. Note that this mode can be selected regardless of the state of the other whitespace modes. Diff Viewer Shortcut Menu When you right click in one of the files being compared, the shortcut menu provides the following options: Edit File on Disk Opens the selected file in a text editor. Show Last Edit in File Opens a diff of the versions of the file in which the selected section changed. Both panes will update as needed to display the applicable versions. This is only applicable to files which are under version control. Show History Opens a History Browser for the selected file. See The History Browser on page 138. This is only applicable to files which are under version control. Set to Current Diff Selects the diff that the cursor is on as the current diff (highlighted in the highlight color). 146 MULTI: Editing Files and Configuring the IDE

159 Part III Configuring the MULTI IDE

160

161 Chapter 8 Configuring and Customizing MULTI This Chapter Contains: Setting Configuration Options Creating Custom Functionality Using Scripts and Macros Using Startup Files Customizing the Graphical User Interface (GUI) Configuring and Customizing Toolbar Buttons Configuring and Customizing Menus Customizing Keys and Mouse Clicks Configuring Window Docking Configuring File Extensions Using a Custom Web Browser with UNIX

162 8. Configuring and Customizing MULTI MULTI provides the ability to configure and customize your Integrated Development Environment (IDE) to fit the way you work most efficiently. This chapter explains how to: Set configuration options that affect how the various components of the MULTI IDE function (see Setting Configuration Options on page 150). Use scripts and/or macros to automate tasks and create custom functionality (see Creating Custom Functionality Using Scripts and Macros on page 155). Use startup files to configure a MULTI session using specific configuration settings (see Using Startup Files on page 155). Customize the appearance and behavior of MULTI s graphical components (see Customizing the Graphical User Interface (GUI) on page 158). Setting Configuration Options MULTI contains a large number of standard configuration options that control how the various components of the MULTI IDE function. These options can be changed according to your specific needs and preferences. Your configuration settings can be saved in a configuration file (*.cfg), which MULTI can use to reconfigure itself at startup. Alternatively, you can manually load a configuration file during a session to reconfigure your current environment. You can edit MULTI s configuration options with the Options dialog box or by issuing the configure command from the Debugger command pane. Configuration settings entered with the configure command are automatically reflected in the Options dialog box. The following sections explain how to use the Options dialog box, the configure command, or a configuration file to configure your MULTI environment. Note Changes to configuration settings are not automatically saved for future MULTI sessions. You must manually save configuration if you want them available in the future (see Saving Configuration Settings on page 153). 150 MULTI: Editing Files and Configuring the IDE

163 Setting Configuration Options Using the Options Dialog Box To make changes to MULTI s configuration options using the GUI, do one of the following: Select Config Options from the Launcher, Debugger, or Editor. Select Tools Options from the Builder. The Options dialog box will open, which allows you to set most of the configuration settings that affect MULTI. For more information about each configuration option and its available settings, see Chapter 9, Configuration Options. Using the configure Command You can set or edit configuration options from the MULTI Debugger by issuing the configure command in the command pane. The syntax for using the configure command can be one of the following: configure config_item=value configure config_item:value configure config_item value where config_item identifies which option you are setting and value is an appropriate setting for that options. For example: configure tabsize=9 configure background #ffffff configure moon: On configure linenumbermode: Both Numbers configure prompt: "> " configure status.stopped STOPPED configure key: "Up"@Command=backhistory For a complete description of every configuration option and the available settings for each, see Chapter 9, Configuration Options. Tip You can enter the command: configure? in the Debugger command pane to display a list of all the items that can be configured with the configure command. Green Hills Software, Inc. 151

164 8. Configuring and Customizing MULTI Using Configuration Files As an alternative to setting configuration options using the Options dialog box or the configure command, you can create configuration files manually using the MULTI Editor or any text editor. Configuration File Format Each line in a configuration file should either: Begin with a pound sign (#) as the first non-whitespace character and contain a comment (these lines are ignored) Be in the format config_item:value where config_item identifies which option you are setting and value is an appropriate setting for that option. Appropriate values for config_item and value are the same as those used with the configure command, but you do not need to include the configure command in.cfg files. For a complete description of every configuration option and the available settings for each, see Chapter 9, Configuration Options. Example 1. Configuration File Contents # This is a comment which is ignored tabsize: 8 background: #ffffff moon: On linenumbermode: Both Numbers prompt: "> " # The following blank line is ignored as well: status.stopped: STOPPED key: "Up"@Command=backhistory 152 MULTI: Editing Files and Configuring the IDE

165 Setting Configuration Options Saving Configuration Settings If you change your configuration settings using the Options dialog box or the configure command, you must save your changes if you want to preserve them for future MULTI sessions. When you save configuration settings, a.cfg file is created. Note MULTI does not prompt you to save changes to configuration files when you quit, so be sure to save any settings that you want to persist across sessions. After you save your configuration options to a.cfg file, you can use that file to configure MULTI automatically every time it starts up, or you can use the file to manually configure new or existing MULTI sessions. The following list describes the different ways that you can save your configuration settings and apply them to future sessions. To save your current settings so that they are automatically loaded every time you start MULTI, do one of the following: Select Config Save Configuration as Default (from the Builder, Tools Configuration Save Configuration as Default). Use the saveconfig command. The current settings will be saved in the user configuration file, which MULTI reads each time it starts. For more information about the user configuration file, see Using Startup Files on page 155. To save your current settings, but not load them automatically every time you start MULTI: Select Config Save Configuration (from the Builder, Tools Configuration Save Configuration). The Save Configuration to what file? dialog box will open, where you can enter the filename and path for this configuration file. This save your settings to a *.cfg file. This saved configuration file will not be automatically loaded at start up, but can be manually loaded in future sessions (see Loading Configuration Files on page 154). Green Hills Software, Inc. 153

166 8. Configuring and Customizing MULTI To save your current settings as the global configuration file, sothattheyare always loaded for every user of the installation: Select Config Save Configuration (from the Builder, Tools Configuration Save Configuration). The Save Configuration to what file? dialog box will open. Save the file as: (Windows) install_dir\config\ghs.cfg (UNIX) install_dir/config/ghs.cfg For more information about the global configuration file, see Using Startup Files on page 155. Loading Configuration Files When MULTI starts a session, it automatically initializes its configuration options from the following configuration (*.cfg) files, if they exist, in the following order: Global configuration file. User configuration file. The configuration file, if any, specified on the command line with the -config option. Settings in a configuration file specified on the command line can override global or user options. Script files can also affect configuration options. For more information about loading configuration settings upon startup, see Using Startup Files on page 155. To load a predefined configuration file during a MULTI session, do one of the following: Choose Config Load Configuration (from the Builder, Tools Configuration Load Configuration), then select the configuration file you want to load. In the Debugger command pane, use the configurefile command (see configurefile in Other General Configuration Options on page 192). 154 MULTI: Editing Files and Configuring the IDE

167 Creating Custom Functionality Using Scripts and Macros Clearing Configuration Settings To permanently delete your user configuration file, which contains configuration options you have saved to be used as your default settings: Select Config Clear Default Configuration (from the Builder, Tools Configuration Clear Default Configuration). Future sessions will use MULTI s default settings unless you create a new user configuration file, or specify another configuration file for the session. See Using Startup Files on page 155 for more information about the user configuration file. Creating Custom Functionality Using Scripts and Macros You can use scripts and/or macros to customize MULTI to simplify and automate tasks. A script is a list of commands and expressions in a file that MULTI reads and executes as if they were entered individually in the Debugger command pane. Scripts are powerful tools for automating both common tasks and regression testing. A script file could, for example, compare a program variable to a constant value and then perform some action based on that result. Scripts are also useful for configuring your target board. You could also write a command script that executes parts of your program and then checks to see whether your program is running correctly. Such a script would be useful for verifying that your program still runs as expected after you make changes. For complete details on how to write, use, and debug scripts, see Chapter 8, Using MULTI Scripts in the MULTI: Debugging book. Using Startup Files When MULTI starts up, certain configuration files are loaded automatically to set up the environment, and when the Debugger loads a program, certain additional script files may be executed. Because the same configuration items can exist in multiple files, the order which these files are loaded is important. A configuration change in a later file will override the effects of a previous change. Green Hills Software, Inc. 155

168 8. Configuring and Customizing MULTI On startup, MULTI loads the configuration files in the following order (if a file does not exist, it is skipped): 1. Global configuration file 2. User configuration file 3. Command Line configuration file After the MULTI Debugger has loaded these configuration files it then runs scripts in the following order (if a file does not exist, it is skipped): 1. Global script file 2. User script file 3. Command Line script file 4. Program script file The global configuration file, user configuration file, and command line configuration file are parsed on MULTI startup, irrespective of which MULTI component is launched. The global script file, user script file, and command line script file are executed when MULTI s first Debugger window first appears (i.e., the first time you start a Debugger on a program from an invocation of MULTI). All Debugger windows launched in a debugging session share the same Debugger environment. If you launch multiple Debugger windows from the same MULTI program (for example, the Builder), all of the script files for the corresponding programs being debugged will be executed, resulting in the final Debugger environment. Global configuration file (Windows) install_dir\config\ghs.cfg (UNIX) install_dir/config/ghs.cfg This file is useful in setting up a common environment, required by whole user groups when debugging any program. If ghs.cfg is not found, multi.cfg will be used, if it exists (me.cfg if using MULTI Editor as a standalone executable). To always override the configuration file for a particular application, create a configuration file in the override directory, which should exist in the directory containing ghs.cfg. The override configuration file should be named application_name.cfg, where application_name is the name of the application to override. 156 MULTI: Editing Files and Configuring the IDE

169 Using Startup Files User configuration file Windows NT, 2000 and XP user_dir\application Data\GHS\ghs.cfg Windows 98/ME either install_dir\users\user_name\ghs\ghs.cfg or install_dir\users\default\ghs\ghs.cfg, depending on whether MULTI is able to obtain the user s name. UNIX user_dir/.ghs/ghs.cfg This file is useful in setting up a common environment, required by a single user when debugging any program. If ghs.cfg is not found, multi.cfg will be used, if it exists (me.cfg if using MULTI Editor as a standalone executable). To always override the configuration file for a particular application, create a configuration file in the override directory, which can be created in the directory containing ghs.cfg. The override configuration file should be named application_name.cfg, where application_name is the name of the application to override. Command line configuration file You can specify a configuration file on the MULTI command line with -config filename or -configure filename. This feature is not available when running the MULTI Editor as a separate executable. Global script file (Windows) install_dir\config\multi.rc (UNIX) install_dir/config/multi.rc This file is useful for commands that need to run once when any person in a user group starts the Debugger for the first time in a debugging session. User script file (Windows) user_dir\ghs\multi.rc (For more information about user_dir see User configuration file, above.) (UNIX) user_dir/.ghs/multi.rc This file is useful for commands that need to run once when debugging any program by a single user. Command line script file You can specify a script file in the command to run MULTI with the -rc option, such as: multi my_prog -rc your_script Green Hills Software, Inc. 157

170 8. Configuring and Customizing MULTI Program script file (Windows) executable_dir\executable_name.rc (UNIX) executable_dir/executable_name.rc The program script file is executed every time that program is loaded into a Debugger window, that is, on every new Debugger opened window on that program, on every program reload (debug command with no arguments), but not on every program restart. If you load a new program into an existing Debugger window, MULTI will automatically execute the commands in the script file of the new program (if any), but it does not clean up the effects of the script file of the old program (if any). For more information about writing scripts to include in your startup files, see Chapter 8, Using MULTI Scripts in the MULTI: Debugging book. Customizing the Graphical User Interface (GUI) MULTI allows you to customize buttons, menus, keystroke combinations, and mouse clicks in the Debugger, Builder, and Editor. You can remove these GUI elements, add new GUI elements, or change the commands that are executed when the GUI element is used. You can define customized GUI elements using the following methods: Use configuration commands in the Debugger command pane. Use the Config Options dialog box to access and change configuration options. You will need to refer to the corresponding commands that appear in the following sections for proper syntax. Write a script file that contains customization commands. The table below lists the commands you need to execute for each GUI element. Be aware that the script files that MULTI loads automatically (global, user, and program script files) are loaded only when the Debugger is launched, so do not put customizations that apply to the Builder and Editor into these startup script files; use a configuration file instead. For more information about writing a script, see Chapter 8, Using MULTI Scripts in the MULTI: Debugging book. Changes must be be saved in a configuration file if you want the configuration available for later use (see Saving Configuration Settings on page 153). Once you have defined a configuration file or script file that customizes the GUI, you 158 MULTI: Editing Files and Configuring the IDE

171 Customizing the Graphical User Interface (GUI) can have MULTI load that file. For more information about these and other files that MULTI uses at startup, see Using Startup Files on page 155. To customize a particular GUI element, use the following as a guide: Debugger buttons Debugger command pane Use the debugbutton command (see Configuring and Customizing Toolbar Buttons on page 160). GUI Select Config Options Debugger Configure Debugger Buttons (see Debugger Options Tab on page 197). Editor buttons Debugger command pane Use the editbutton command (see Configuring and Customizing Toolbar Buttons on page 160). GUI Select Config Options Editor Configure Editor Buttons (see MULTI Editor Options Tab on page 216 GUI menus Debugger command pane Use the menus command (see Configuring and Customizing Menus on page 162). GUI Select Config Options General tab Menus (see General Options Tab on page 179). Keyboard shortcuts Debugger command pane Use the keybind command (see Customizing Keys and Mouse Clicks on page 165). GUI Select Config Options General tab Keys (see General Options Tab on page 179). Mouse actions Debugger command pane Use the mouse command (see Customizing Keys and Mouse Clicks on page 165). GUI Select Config Options General tab Mouse (see General Options Tab on page 179). Green Hills Software, Inc. 159

172 8. Configuring and Customizing MULTI Configuring and Customizing Toolbar Buttons You can customize Toolbar buttons that appear in the Debugger or Editor using the following commands: debugbutton [num] [name] [c=command] [i=iconname] [h=helpstring] [t=tooltip] editbutton [num] [name] [c=command] [i=iconname] [h=helpstring] [t=tooltip] The arguments name, command, iconname, helpstring, and tooltip must be entered as either single words or quoted strings of the form: "This is a quoted string." "These are quotes \" \" within a quoted string." Arguments entered in button configuration commands have the following meanings: num is the number which MULTI assigns to the button. name is the name of the button. command is the command executed when the button is pressed. Youmayuse semicolons in the command to execute multiple commands. For example: > debugbutton printxy c="print x;print y" creates a button named printxy that prints the values of the variables x and y in the current context. iconname is the name of the button s icon. This may be: One of MULTI s built-in icons. To obtain a list of the built-in icon names along with what they look like, select Configure Debugger Buttons (see Debugger Options Tab on page 197). The filename of a bitmap you have created (see Creating and Working with Icons on page 161). If only a partial path is given, it is assumed to be relative to the MULTI installation directory. If iconname is not specified, the first letter of the command name will be used as the icon for the button. helpstring is the help text that appears in the Status Bar at the bottom of the Debugger or Editor window when the cursor moves over the button. tooltip is the text that appears when the cursor hovers over the button for a short interval. If no tooltip is specified, the name of the button is used for the tooltip text. 160 MULTI: Editing Files and Configuring the IDE

173 Configuring and Customizing Toolbar Buttons The following special forms of debugbutton can be used in the Debugger command pane: debugbutton Lists all the defined Debugger buttons, except the Quit button and the separator before it (which are special and cannot be modified or deleted). debugbutton 0 Deletes all buttons except the Quit button and its separator. debugbutton [num] Deletes the button numbered num. debugbutton [name] Deletes the button named name. debugbutton [num] [name][...] Replaces the button numbered num with a new button named name. debugbutton [name][...] If a button named name exists, the button is replaced. Otherwise a new button named name is added to the end of the Debugger toolbar. The following special forms of editbutton can be used in the Debugger command pane: editbutton Lists all the defined Editor buttons. editbutton 0 Deletes all Editor buttons. editbutton [num] Deletes the button numbered num. Creating and Working with Icons In addition to numerous built-in icons, MULTI can use graphic files you provide for icons. If you create your own graphic file, then it must end in a.bmp extension and must be in the uncompressed 16-color Windows Bitmap format. Other color depths are not supported, and compressed bitmaps are not supported. An easy way to create such bitmaps is to use the Paint accessory in Microsoft Windows. Select 16 Color Bitmap for the Save as type in the Save As dialog box. The built-in icons in MULTI are 20 pixels wide by 20 pixels tall, so your buttons will look best if you also use this size for your custom bitmaps. By default, the color light gray in your custom icons will become transparent. (UNIX) You can specify color translations for your custom icon by appending a string of the form "oldcolor1=newcolor1&oldcolor2=newcolor2" with a question mark to the end of your bitmap filename. Green Hills Software, Inc. 161

174 8. Configuring and Customizing MULTI For example: > debugbutton Hello c="echo hello" \ continued> i="/home/user/hello.bmp?black=fg&dkgray=shadow&white=highlight" \ continued> h="say hello" The above example would replace black pixels in hello.bmp with the current foreground color, dark gray pixels with the current shadow color, and white pixels with the current highlight color. You can use the following values for oldcolor and newcolor: Oldcolor (RGB values) white (255,255,255) ltgray (192,192,192) dkgray (128,128,128) black (0,0,0) Possible values for newcolor white [default] highlight transparent [default] ltgray dkgray [default] shadow black [default] fg Configuring and Customizing Menus MULTI comes with a set of predefined menus for the Debugger window and the Editor. You can create new menus or edit existing menus using any the following methods: Edit a configuration file. Use the configure command in the Debugger command pane. Click Menus on the Config Options, General tab, to open the Menus dialog box (see General Options Tab on page 179). You can use this dialog box to add, edit, or delete menus. Note Menu names are case-sensitive. 162 MULTI: Editing Files and Configuring the IDE

175 Configuring and Customizing Menus The MULTI Debugger provides the menu command to view and manipulate menus: menu Prints a list of all the currently defined menus. menu name Displays the body of the menu named name. menu name {{label cmd } } Defines a menu that can be inserted into a menu bar or displayed by a MULTI button, mouse button, or key binding. The arguments in this command have the following meanings: name is the menu name that appears on the menu bar or at the top of the menu when it is opened. label is an entry in the menu. cmd is a command that executes when the associated label is selected. Menus can contain other menus by using the -> command. For example, the menu Main defined below contains RunCmds as a submenu: menu Main {{RunCmds -> RunCmds}{Up {E 1}}{Down {E -1}}{ToPC E} Note: To replace an existing menu, define a new menu with the same name. To create a menu: 1. Enter the command menu followedbythename for the menu. 2. Create menu items by entering a label and an associated cmd enclosed in curly braces {}. If one of the characters in a menu label is preceded with an ampersand (&), that character becomes a hotkey and will be underlined when the menu is displayed. The user can type that character to execute the associated command, just as if they clicked the label. The cmd portion can contain its own subset of curly braces for commands that require them (such as if), but they must be paired correctly. If cmd is a single command and that command is associated with a key binding that key binding will be displayed to the right of label when the menu is displayed. 3. Enclose the entire body of the menu in curly braces {}. Green Hills Software, Inc. 163

176 8. Configuring and Customizing MULTI The following example creates a menu named RunCmds: menu RunCmds {{Step s}{next S}{Run r}{go c}{return cu}} Opening and Accessing Menus You can access new menus in the following ways: -> name Opens a menu named name. For example, to open the Main menu from the Debugger command pane, enter: ->Main debugbutton [name]-> [menu] Binds a menu named menu to the Debugger button named name. For example, the following command will create a button named View on the Debugger toolbar, which opens the View menu when it is clicked: debugbutton View ->ViewMenu This command is most useful when used in conjunction with the menu command to define your own menus. mouse [button_num] [*click_num] [@location] =-> [menu] Binds a menu to a mouse click. For example, the following command displays the RunCmds menu when the third mouse button is clicked: mouse mouse3*press1@all=->runcmds For more information about binding mouse clicks to commands, see Customizing Keys and Mouse Clicks on page MULTI: Editing Files and Configuring the IDE

177 Customizing Keys and Mouse Clicks Customizing Keys and Mouse Clicks You can customize key bindings and the behavior of mouse clicks in the Debugger and Editor with the following methods: Use the configure command in the Debugger command pane. On the Config Options, General tab, click Keys to open the Keyboard Commands dialog box, or Mouse to open the Mouse Commands dialog box. keybind Displays key bindings that have location specified as All. keybind location Prints the current key bindings for a particular location. keybind key [ modifiers] [@location] [=command] Assigns an action to take when a key is pressed in the specified context. The arguments in this command mean the following: key is an identifier that specifies the keyboard key for which the binding is active. This identifier may be either a single ASCII (or ISO8859) character or a quoted string containing the name of one of the keys on the keyboard, such as BACKSPACE or F3. Characters needing more than one key press (besides the Shift, Ctrl, Alt, and Meta keys) cannot be used. To obtain a list of all of the acceptable key names, type keybind "????". The BACKSPACE key is different from h Control even though their ASCII representations are the same. To specify the double-quote key, use a sequence of three double-quotes """ in a row. modifiers are other keys (Shift, Ctrl, Alt, and Meta) that may be used in combination with key. If a modifier is specified, the command runs only if that modifier is pressed at the same time as the key. If more than one modifier is specified, they should be separated from each other and from key by vertical bars ( ). location is the area of the window the cursor must be in for the key binding to be matched. If location is omitted, the default is Command. For more information, see Key and Mouse Locations on page 167. command is the command that will be executed upon the key press. For more information, see Key and Mouse Command Special Sequences on page 168. mouse location Prints the current mouse bindings for a particular location. Green Hills Software, Inc. 165

178 8. Configuring and Customizing MULTI mouse button_num [*Clickclick_num[(AtOnce)]] [ modifiers] [@location] [=command] Assigns an action to a mouse button click. The arguments in this command mean the following: button_num represents the mouse button to be assigned. This can be the keyword Any, which matches any mouse button, or the word mouse, followedby a combination of digits between 1 and 5 which match the specified mouse button. For example, mouse2 matches the second (usually the middle) mouse button, while mouse13 matches both the first (usually the left) and the third (usually the right) buttons. Not all mice have five buttons. Commands assigned to non-existent buttons will never be matched. click_num specifies the number of times the mouse button must be released before the command is executed. This may be a number between 1 and 5. A binding that contains *Click3 would be executed upon the release of the specified button on a triple click. If the *Clickclick_num option is be omitted, the binding matches the first release of the specified mouse button. The keyword Click may be replaced by Press, which executes the command on the button press rather than the release, or by Either, which executes the command on both the press and release. A binding that contains *Either1 is executed twice, once for the press of the mouse button, and once for the release. The keyword Click maybefollowedbythekeyword (AtOnce). This keyword causes the command assigned to execute immediately rather than pausing to see if it is part of a click sequence. A binding that contains *Press2 is executed only after the second press of a mouse button in a double-click, while *Press2(AtOnce) would be executed for the second mouse button press in a double-click, triple-click, quadruple-click, etc. This is acceptable behavior for many options, such as the standard selection clicks: one click sets the insertion point, two clicks selects the current word, three the line, and so forth. If (AtOnce) is not used, there is a slight delay when invoking single-click commands. This delay is specified by the ClickPause configuration option. modifiers are other keys that must be held down at the same time the button is clicked. Valid modifiers are Shift and Ctrl (plus Meta for UNIX). Modifiers are preceded by a vertical bar ( ), which separates them from each other and from the previous arguments. If more than one modifier is specified, all of the modifiers listed must be pressed simultaneously with the mouse click for the binding to be matched. location indicates the place within MULTI s windows the mouse must be for the binding to be matched. If location is omitted, the default is Source. For more information, see Key and Mouse Locations on page 167. command is the MULTI command that will be executed when the binding is matched. For more information, see Key and Mouse Command Special Sequences on page MULTI: Editing Files and Configuring the IDE

179 Customizing Keys and Mouse Clicks Key and Mouse Locations The location argument for the keyboard and mouse commands can be one of the following: All InputWindow OutputWindow View Title Command Remote Source Monitor Labels Values Name Type Freeze Close Pop Menu ScrollBar UpArrow DownArrow ScrollArea (keybind) Any MULTI windows except the Editor. (mouse) Any MULTI windows. Any MULTI input window, such as the command pane, a target window, or an I/O window. Any output only window, such as the source pane or a monitor window. Anywhere in a Data Explorer window, except the title bar. Anywhere in the title bar of a Data Explorer or monitor window. (keybind) The command pane or source pane. (mouse) The command pane. A target or I/O window. (mouse only) The source pane. Anywhere in a monitor window except the title bar. The field names column in a Data Explorer. The field values column in a Data Explorer. Anywhere in the region of the title bar that displays the name of the expression being viewed in a Data Explorer or the command of a monitor window. Anywhere in the region of the title bar that displays the type of expression being viewed in a Data Explorer. Anywhere in the region indicating whether or not the window is frozen. The close button in the title bar. The Pop button of a Data Explorer. Anywhere in the portion of the title bar that displays the format menu in a Data Explorer. Anywhere within a scroll bar. (keybind only) Arrow pointing up at the top of a scroll bar. (keybind only) Arrow pointing down at the bottom of a scroll bar. (keybind only) Region between the direction arrows of a scroll bar. Green Hills Software, Inc. 167

180 8. Configuring and Customizing MULTI Thumb AboveThumb BelowThumb Edit (keybind only) The control in the middle of a scroll bar that can be dragged to change the viewable contents of the associated window. (keybind only) Area between the Thumb and the UpArrow. (keybind only) Area between the Thumb and the DownArrow. Anywhere within an Editor. Some of these locations implicitly include other locations. These locations are: All InputWindow OutputWindow View Title ScrollBar ScrollArea InputWindow, OutputWindow, View, and Title. Command and Remote. Source and Monitor. Labels and Values. Name, Type, Freeze, Close, and Pop. (keybind only) UpArrow, DownArrow, and ScrollArea. (keybind only) Thumb, AboveThumb, and BelowThumb. Key and Mouse Command Special Sequences The command isanymulticommandtobeexecutedwhenthekeyormouse binding is matched. Several special sequences of characters in the command will be replaced with information about MULTI s state when the action is performed. These sequences are not valid for key or mouse bindings in the Editor. The following are the special sequences for command: %s Replaced by the current selection. %p Replaced by the current selection if it exists, otherwise MULTI prompts for input. %P Always prompts for input. %w Replaced by a special number identifying the window to MULTI. In command synopses and MULTI documentation, this number is referred to as a window identification number or wid. %x Replaced by the x location in the window when pressing the button or mouse. %y Replaced by the y location in the window when pressing the button or mouse. 168 MULTI: Editing Files and Configuring the IDE

181 Customizing Keys and Mouse Clicks %k (keybind) Replaced by the ASCII expansion of the key. For the key labeled a, this is replaced with "a". (mouse) Replaced by the null string. %m (keybind) Replaced by Press to indicate a key press triggered the action. (mouse) Replaced by Press or Release, depending on whether the command was executed as a result of a mouse button press or a mouse button release. %% Replaced by %. If the key[ modifier]@location portion of a keybind command matches a previously defined binding, then the new definition replaces the old binding. If no command is specified in the new definition, then the old binding is deleted. When a key is depressed in a window, MULTI searches for key bindings that match. There may be more than one, in which case MULTI chooses the one whose location is the most specific. If there are still several, then MULTI chooses one arbitrarily. If the button_num[*clickclick_num][ modifiers][@location] portion of a mouse binding matches a previously defined mouse binding, then the new binding replaces the old one. If no command is specified, then the old mouse binding is deleted. When the mouse is clicked in a window, MULTI searches its list of mouse actions for a matching binding. If there is more than one that might match the event, then MULTI uses the one whose location is the most specific. If there are multiple bindings that match the most specific location, then MULTI chooses the one which is bound to the fewest number of different mouse buttons. If there are still several bindings, then MULTI chooses one of the bindings arbitrarily. Example 1. Keybind Command With this command, MULTI evaluates and prints the selection when the first function key (F1) is pressed in the source pane or command pane: keybind "F1"=print %s With this command, the Debugger opens a Data Explorer that displays the current selection when key combination Ctrl + F1 is pressed: keybind "F1" Control@All=view %s Green Hills Software, Inc. 169

182 8. Configuring and Customizing MULTI With these commands, MULTI scrolls the window when the up or down arrow is depressed: keybind scrollcommand 1l keybind scrollcommand -1l With this command, MULTI single steps the program when Ctrl + S is pressed in the source window: keybind s Control=S Example 2. Mouse Command mouse mouse1=print %s With this binding, the Debugger evaluates and prints the selection when you click the left mouse button once in the source window. mouse mouse1*click2@all=view %s With this binding, the Debugger opens a Data Explorer displaying the current selection when you double-click the left mouse button in any window. Inserting a Character Blocked By a Custom Key Binding If you customize the Editor to run a command based on a single keystroke, you will not be able to directly insert the literal character of that keystroke into a file. For example, if you customize the key binding so that every time you press d the cursor moves down one line, then you will not be able to type the literal letter d in a file. To enter the literal character d in your file, you would have to: 1. Press Ctrl + \ (the Ctrl key with the backslash \ key). 2. Press the key for the character that you want to enter into the file. 170 MULTI: Editing Files and Configuring the IDE

183 Configuring Window Docking Configuring Window Docking MULTI includes configurable window docking options, which allow you to customize how multiple windows interact and are displayed on the screen. Window docking is supported in both Windows and UNIX environments (see UNIX Docking Limitations on page 171 for more information that is specific to UNIX environments). Window docking supports the following two types of behaviors: Window alignment Windows brought near other windows will automatically snap together, and windows brought near the edge of your screen will automatically snap to the edge of the screen. You can configure how sensitive this form of window docking is by adjusting the proximity at which a window will snap to another window or screen border. Window grouping Some windows will form groups when they are brought near other windows of the same type. The resulting groups can be controlled using a single title bar for all windows. When windows are grouped together, a new Group Bar appears above the Title Bar. You can use the Group Bar to move, close, or minimize the entire group. Note Window docking works between multiple windows of the same application. For example, MULTI Debugger windows will only dock with other Debugger windows; they will not dock with MULTI Editor windows or EventAnalyzer windows. If your window manager includes a Maximize button, you should not use this button on the group bar. For information about window docking options, see Window Docking Options Dialog Box on page 188. UNIX Docking Limitations Due to the design of the X protocol, the window manager running has nearly absolute control over window position and size, and the application is reduced to a much less active role. Window docking attempts to give you the benefits of a window manager at the application level. Green Hills Software, Inc. 171

184 8. Configuring and Customizing MULTI Some window managers, such as KDE, will not allow a window to be created smaller than a certain size. While you can still use window groups in these situations, the group bar will take up more space than normal. The following X Window Managers are supported: afterstep Blackbox Desktop Window Manager (dtwm) FVWM, FVWM2, FVWM95 Ice Window Manager (icewm) KDE Window Manager (kwin) Window grouping is disabled by default for the KDE window manager because it does not allow windows to be created with a height smaller than 25 pixels. Metacity OpenLook Window Manager (olwm) Sawfish Tabbed Window Manager (twm) WindowMaker (wmaker) wm2 Does not use a horizontal title bar, which is required for window grouping. The following X Window Managers do not work properly with window docking and are not supported. If you use one of these window managers, set Windows Docking Options to Disable All Window Management (see Window Docking Options Dialog Box on page 188). PWM Ion A window manager not listed in either of the above lists has not been verified to work properly. 172 MULTI: Editing Files and Configuring the IDE

185 Configuring File Extensions Configuring File Extensions While using the Builder, Editor, and Debugger, some operations require a file to be selected from a graphical file chooser. These file choosers provide a set of filters which allow only relevant files to be displayed. While common extensions are present in these filters, additional custom extensions and file types may be required. These extensions can be added by customizing the file extension mappings used by MULTI. Extension Mapping Files The extension mappings are stored in configuration files named extensions.udb in a directory named file_types. They are applied in the same order as configuration files, starting with the defaults directory and followed by the site-wide and user configuration directories (see Using Startup Files on page 155). To add custom file extensions, create a directory named file_types in either the site or user configuration directories and create an extensions.udb file defining the custom file extension. The extension mapping configuration files contains entries describing individual file types as well as collections of file types for use in individual file choosers. File Format For information about the generic package options file format and the syntax descriptions below, refer to the Package Option Notation section of the Register Explorer chapter of the MULTI: Debugging manual. Described below are the specifics of the file format. Green Hills Software, Inc. 173

186 8. Configuring and Customizing MULTI Header Each extension mapping configuration file contains a header which identifies the version of the file: xdf { xdfheader { version = num } } The only supported version is 1. File Types Each file type is contained in a subgroup located within the xdf group. The name of this subgroup can be any valid identifier except xdfheader or presets. Inthis section, Ftype represents the top level package name. Name Each file type can have a name associated with it. This name will appear in the drop-down list of the file chooser, so it should be concise. A name is given to a file type by a key-value pair of the form: xdf { "Ftype" { name = { "value" } } } If this key-value pair is omitted, Ftype is used as the name of the file type. Extensions Each file type must have one or more extensions associated with it. Each extension is associated with a file type by a key-value pair of the form: xdf { "Ftype" { extension = { "value1"[, "value2"] } } } The extension value may contain a wildcard pattern using asterisks to represent a match for any arbitrary sequence of characters. If an asterisk is not present, an asterisk will be implicitly added before the value. Thus, a value of.bar would be implicitly translated into the *.bar pattern and match any files whose names end in.bar. Avalueof.Bar* would not undergo any translation, and would match any files whose names begin with.bar. 174 MULTI: Editing Files and Configuring the IDE

187 Configuring File Extensions Presets Presets are groups of file types that share similar properties. File choosers in MULTI determine which file types to display based upon presets. Each preset subgroup is contained within the presets subgroup of the xdf group and can be named any valid identifier. Name Each preset has a name, defined by a key-value pair of the form: xdf { presets { pgroup { name = { "value" } } } } If this key-value pair is omitted, the preset is named pgroup. File types File types associations for presets. File types are listed in the drop-down list of the file chooser in the order that they are defined in the file type list. Defined by a key-value pair of the form: xdf { presets { pgroup { filetype = { "value1"[, "value2"] } } } } Preset inheritance Presets can inherit settings from other preset groups, which is equivalent to importing all of the filetype groups from the associated preset while keeping the ordering distinct. Imported file types are placed after the final explicit filetype key-value pair for a preset. A preset is inherited by a key-value pair of the form: xdf { presets { pgroup { include = { "name1"[, "name2"] } } } } The value of this pair is equivalent to the name of the preset given by its include directive (or the default value: pgroup). Green Hills Software, Inc. 175

188 8. Configuring and Customizing MULTI Using a Custom Web Browser with UNIX Several configuration options are available to control the web browser used for displaying online help. To access these options, select Config Options General tab (Tools Options General tab in the MULTI Builder), then click Help to open the Online Help Options dialog box (see Online Help Options Dialog Box (UNIX only) on page 191). The command used to start a web browser is specified in the Browser Command field of the Online Help Options dialog box. The default settings assume the browser executable is capable of understanding file URLs. If the executable does not recognize file URLs, you will need to create a wrapper script to translate the file URLs into absolute file paths. For example, create the following Perl script, browseradapter.pl, as an executable in a directory in your path: #!/usr/local/bin/perl -w $ARGV[1]=~/file:(.*)$/; system($argv[0]." ".$1); The above script takes its second argument, the file URL, strips off the absolute path, then executes the program specified in its first argument on that file. You can use this Perl script to configure MULTI to use any program to display online help, such as vi, by adding the following to your configuration files: browseruseremote: Off browsercommand: browseradapter.pl vi For more information about modifying your configuration files, see Chapter 8, Using MULTI Scripts in the MULTI: Debugging book. By defaultmultiassumesthatthe web browser supportsthe -remote option to use previously opened web Browser. If your browser does not support -remote command line syntax or JavaScript, you should clear the Browser supports -remote command line option check box. (see Online Help Options Dialog Box (UNIX only) on page 191). This option is off by default when running in non-gui mode. 176 MULTI: Editing Files and Configuring the IDE

189 Configuration Options Chapter 9 This Chapter Contains: General Configuration Options Builder Configuration Options Debugger Configuration Options MULTI Editor Configuration Options Session Configuration Options Colors Configuration Options Deprecated Configuration Options

190 9. Configuration Options Chapter 8, Configuring and Customizing MULTI discusses how you can customize your interface using MULTI s configuration options. This chapter describes these configuration options and their default settings. Many, but not all of these options can be controlled using the Options window and/or configuration files. (To open the Options dialog box, select Config Options from the Launcher, Debugger, or Editor, or Tools Options from the Builder.) All of the options described in this chapter can be set or edited using the configure command in the Debugger s command pane. The descriptions given in this chapter for each configuration option are grouped according to the tabs in the Options dialog box. The equivalent Debugger command setting for each GUI choice is given in parentheses after the option name that appears in the dialog box. The command setting must be preceded by the configure command when it is entered in the command pane. For example, using the GUI option Warp pointer, the selection Never is followed by: (WarpPointer Never). This indicates that the command entered in the Debugger would be: configure WarpPointer Never. Note Configuration options are not case sensitive, thus configure WarpPointer Never and configure warppointer never are equivalent and are both valid. In this chapter, we used mixed case notation to make the options more readable. Note To save your configuration, choose Config Save Configuration as Default before you quit MULTI; otherwise, your configuration changes will be lost (see Saving Configuration Settings on page 153). 178 MULTI: Editing Files and Configuring the IDE

191 General Configuration Options General Configuration Options This section describes configuration options that affect the overall appearance of MULTI. Most of these options appear on the General tab of the Options dialog box. General Options Tab Save window positions and sizes Permitted settings for this option are: Selected (RememberWindowPositions On) [default] Remembers the position and size of windows created by MULTI, so the next time a window of the same type is created it will appear in the same location. Sizes and positions are remembered even after you exit and restart MULTI. Cleared (RememberWindowPositions Off) Do not remember the position and size of windows created by MULTI. Positions and sizes are saved independently for each different type of window. The first window of a given type is positioned in the saved location, and any new windows of the same type are slightly offset from the location of the open window and given the saved size. For example, if you resize the Builder window, move it to a specific location on your screen, and then close the window; the next time a Builder window is created it will appear in the same place and with the same size. Not all windows are affected by this option; in particular, Data Explorer windows are not affected. Use icons for buttons Permitted settings for this option are: Selected (iconifiedbuttons On) [default] Toolbar buttons are displayed with mnemonic icons. Cleared (iconifiedbuttons Off) Toolbar buttons are displayed with textual names. Display close (x) buttons Permitted settings for this option are: Selected (CloseButtonOnTitlebar On) [default for UNIX] A Close button will appear on the Toolbar of new windows. This option only affects new windows created after you change the setting, except for Debugger windows, which adjust to the new setting immediately. Cleared (CloseButtonOnTitlebar Off) [default for Windows] The Close button will not appear on Toolbars. Green Hills Software, Inc. 179

192 9. Configuration Options Launch clipboard manager UNIX only Permitted settings for this option are: Selected (clipmanlaunch On) [default] The clipboard manager, which stores selections that have been sent to the clipboard by all applications, will run after MULTI has exited, making the contents of the clipboard accessible to other applications. Cleared (clipmanlaunch Off) The contents of the clipboard are lost when MULTI exits. Match exact case in searches Determines the case sensitivity of all text searches in MULTI. Permitted settings for this option are: Selected (ExactCase On) Searches will be case-sensitive. Cleared (ExactCase Off) [default] Searches will be case-insensitive. This option can also be set on a per-editor-window basis with the Edit Find dialog box. For more information see Interactive Searching Using the Search Dialog Box on page 26. Allow beeping Permitted settings for this option are: Selected (beep On) [default] MULTI beeps on various error conditions, such as a search that does not match anything. Cleared (beep Off) MULTI never beeps. Show tooltips UNIX only Permitted settings for this option are: Selected (tooltips On) [default] Tooltips, small explanatory boxes that pop up when you hover the cursor over a GUI item, will be displayed if they are available for that item. Cleared (tooltips Off) Tooltips will never be displayed. Warp pointer Permitted settings for this option are: Never (WarpPointer Never) [default for Windows] Never move the mouse pointer automatically. The mouse cursor can only be changed by physically moving the mouse. Into Dialog Box (WarpPointer IntoDialogue) [default for UNIX] Warp the mouse pointer to the default button of new dialog boxes that appear. In & Out of Dialog Box (WarpPointer In&OutDialogue) Warp the mouse pointer into the default button of new dialog boxes, and warp it back to its previous location when the dialog box is closed. 180 MULTI: Editing Files and Configuring the IDE

193 General Configuration Options Print command Specifies the command used to send information to a printer. The default is lpr (PrintCommand command). Editor UNIX only Specifies which editor MULTI uses when the user requests an editor to be started. Currently supported options are: MULTI Editor (ExtEditor_Choice "Multi Editor") [default] Use the MULTI Editor. Emacs (ExtEditor_Choice "Emacs") Use the Emacs editor. Vi (ExtEditor_Choice "Vi") Use the Vi editor. Other (ExtEditor_Choice "Other") Use an editor that is not available in the list. Configure Editor Opens a dialog that allows you to specify configuration settings that are specific to the editor selected in the Editor field: If the MULTI Editor is selected, clicking this button opens the MULTI Editor tab. For more information, see MULTI Editor Options Tab on page 216. If any other editor was selected in the Editor field, clicking this button opens the Other Editor Configuration dialog box. For more information, see Configure Other Editor Options on page 184. Green Hills Software, Inc. 181

194 9. Configuration Options Version Control Specifies which version control system MULTI uses. Permitted settings for this option are: Auto Detect (VersionControlType AutoDetect) [default] Version control is auto-detected based on the file currently in use. Disable (VersionControlType Disable) Version control is disabled. CVS (VersionControlType CVS) (Concurrent Versions System) An open-source network-transport version control system. See Integrating with CVS on page 118. MVC (VersionControlType MVC) (MULTI Version Control) The Green Hills Software version control system provided as a part of MULTI. See Integrating with MULTI Version Control (MVC) on page 112. RCS (VersionControlType RCS) A version control system available with many UNIX systems. See Integrating with RCS on page 119. PVCS (VersionControlType PVCS) A system of version control and configuration management software from MERANT that runs on DOS, Windows, OS/2 and various UNIX platforms. See Integrating with PVCS on page 122. ClearCase (VersionControlType ClearCase) A version control system from Rational Software. See Integrating with ClearCase on page 118. (Windows only) SourceSafe (VersionControlType SourceSafe) A version control system from Microsoft. See Integrating with SourceSafe on page 119. Custom (VersionControlType Custom) For version control systems other than those listed above. See Integrating with a Custom Version Control System on page 124 for information about configuring MULTI for use with other version control systems. Configure Version Control Opens a dialog box that you use to specify configuration settings that are specific to the version control selected in the Version Control field. For more information, see Version Control Configuration Options on page 185. Vertical scroll bar location Permitted settings for this option are: Right (ScrollLocation Right) [default] The vertical scroll bar will appear on the right-hand side of windows Left (ScrollLocation Left) The vertical scroll bar will appear on the left-hand side of windows. 182 MULTI: Editing Files and Configuring the IDE

195 General Configuration Options Horizontal scroll bar location Permitted settings for this option are: Top (ScrollHLocation Top) The horizontal scroll bar will appear at the top of windows. Bottom (ScrollHLocation Bottom) [default] The horizontal scroll bar will appear at the bottom of windows. Phase of moon in scroll bar box Permitted settings for this option are: Selected (moon On) The approximate phase of the moon will be displayed in the nook of the vertical and horizontal scroll bars instead of the Green Hills Software logo. Cleared (moon Off) [default] Moon phase is not displayed. Scroll bar width in pixels Specifies the width of scroll bars in num pixels. The default is 18 (ScrollbarWidth num). Main Font UNIX only Opens a font selection dialog which you can use to set the main font that is used for most textual display. Click Main Font and use the dialog box that opens to select any font installed on your system. This font should normally be set to a fixed width font, so that characters in the same column on different lines will line up properly. The default for UNIX is courier-bold (font font_name). The default for Windows is Courier New (font font_name). Button Font Opens a font selection dialog which you can use to set the button font which is used on buttons, menus, and other GUI controls. Click Button Font and use the dialog box that opens to select any font installed on your system. The default for UNIX is -*-interface system-medium-r-*-*-12-*-*-*-*-*-*-*(buttonfont font_name). The default for Windows is MS Sans Serif (ButtonFont font_name). Kanji Font UNIX only Opens a font selection dialog which you can use to set the 16-bit font used to display Kanji text. Click Kanji Font and use the dialog box that opens to select any font installed on your system. There is no default setting (KanjiFont font_name). Green Hills Software, Inc. 183

196 9. Configuration Options Menus Opens the Menus dialog box, which you can use to edit the GUI menus used by MULTI. It displays the currently defined menus using the same format as the menu command. See Configuring and Customizing Menus on page 162. Mouse Opens the Mouse Commands dialog box, which you can use to edit the mouse bindings used by MULTI. The mouse bindings are displayed in the same format as the mouse command. See Customizing Keys and Mouse Clicks on page 165. Keys Opens the Keyboard Commands dialog box, which you can use to edit the key bindings used by MULTI. The key bindings are displayed inthesameformatas the keybind command. See Customizing Keys and Mouse Clicks on page 165. Window Docking Opens the Window Docking Options dialog box, which you can use to configure how multiple windows appear and function in MULTI. See Window Docking Options Dialog Box on page 188 for details. Help UNIX only Opens the Online Help Options dialog box, which contains additional configuration options for the online help system. For more information about using this dialog box, see Online Help Options Dialog Box (UNIX only) on page 191. Configure Other Editor Options This dialog box opens when have selected an alternate editor (any editor other than the MULTI Editor) on the General tab and click the Configure Editor button. (If you select the MULTI Editor on the General tab, the MULTI Editor tab will open instead. See MULTI Editor Options Tab on page 216). The dialog box contains the following options specific to the editor type selected. Not all options will appear for every editor type. Path to Editor (ExtEditor_EmacsPath for emacs; ExtEditor_ViPath for Vi; ExtEditor_OtherPath for Other editors). This option controls where the binary is located in the system. If it is not a fully qualified pathname then the editor must be in your path. 184 MULTI: Editing Files and Configuring the IDE

197 General Configuration Options Use XTerm UNIX only (ExtEditor_EmacsUseXTerm for emacs; ExtEditor_ViUseXTerm for Vi; ExtEditor_OtherUseXTerm for Other editors). Determines whether the editor will be launched from within an xterm. Console mode editors should enable this option. Command line arguments (ExtEditor_EmacsArgumentFormat for emacs; ExtEditor_ViArgumentFormat for Vi; ExtEditor_OtherArgumentFormat for other editors). Determines what arguments the editor will be launched with and in what format. There are three special character sequences that will be replaced when the editor is run, the substitution rules are: %file0 replaced with the first file to be edited %line replaced with the line number to go to when opening the file (removed if MULTI does not specify a line number) %files if there is more than one file to edit then this will be replaced with all but the first file, each file will be separated by a space (removed if MULTI only specifies one file to edit) Version Control Configuration Options When you click the Configure Version Control button on the General tab of the Options window, a dialog opens containing options that are specific to the version control type selected in the Version Control field. The possible options and settings that appear in this dialog are described in the table below. Not all options will appear for every version control type. Note If you select Custom as your version control type, a Custom Configuration dialog box will appear instead. See Custom Version Contol Options on page 186 for a description of the fields in this dialog box. Green Hills Software, Inc. 185

198 9. Configuration Options Automatic Checkout Permitted settings for this option are: Selected Files are automatically checked out when you start to edit them. Cleared [default] Files are not automatically checked out. The equivalent configuration commands are: For MVC Versctrl_MVCAutoCheckout For RCS Versctrl_RCSAutoCheckout For ClearCase Versctrl_ClearCaseAutoCheckout For SourceSafe Versctrl_SourceSafeAutoCheckout For Custom Version Control System Versctrl_CustomAutoCheckout This option is not available if you have selected the CVS version control system, since a file is always checked out when you are using CVS. Location of VC binary (For CVS, ClearCase, and SourceSafe version control systems only.) Specifies the name of the command to run, according to your version control system. The defaults are: For CVS cvs (Versctrl_CVSPath cvs) For ClearCase cleartool (Versctrl_ClearCasePath cleartool) SourceSafe ss.exe (Versctrl_SourceSafePath ss.exe) SourceSafe database location (Versctrl_SourceSafeDatabase) SourceSafe only. Specifies the location of the SourceSafe database. In other words, this is the location of the srcsafe.ini file corresponding to the desired database. Root of checkout (Versctrl_SourceSafeRoot) SourceSafe only. Specifies the working directory of the root ($/) of the SourceSafe database. The MULTI integration with SourceSafe assumes that the directory structure of a database is maintained when files are checked out from that database. For example the $/example.c file in the database is checked out to root_of_checkout/example.c. Custom Version Contol Options If you select Custom as your version control type, a Custom Configuration dialog box opens when you click the Configure Version Control button from the General tab of the Options window. This window contains fields for setting the configuration options listed below, which must be set to configure MULTI 186 MULTI: Editing Files and Configuring the IDE

199 General Configuration Options for use with your version control system. (For more information about using a custom version control system, including sample configuration settings, see Integrating with a Custom Version Control System on page 124.) Under VC (vc_undervc command) Used when the version control system has been set to Custom. Specifies the shell command used to determine if a given file is under version control. When the specified command is issued with a filename appended, it will return true (zero exit status) if the file is under the version control system, or false (nonzero exit status) if the file is not under version control. Check Out (vc_co command) Specifies the shell command used to check out a file from version control for editing. When the specified command is issued with a filename appended to it, the file will be checked out for modification. If an error occurs, the specified command will print an error message will to standard output and return a nonzero exit status. Get (vc_get command) Used when the version control system has been set to Custom. Specifies the shell command used to get a read-only copy of the latest version of a file. When the specified command is issued with a filename appended to it, the command will get a read-only copy of the specified file. If an error occurs, the command will print an error message to standard output and return a nonzero exit status. Un Check Out (vc_unco command) Used when the version control system has been set to Custom. Specifies the shell command used to undo the effects of a checkout by reverting to the latest version of the file in the version control system and (if applicable) restoring the file s checked-in status, discarding any edits since the check out. When the specified command is issued with a filename appended to it, the command will cancel any check out of the file and revert to the version in the version control system without checking in any changes. If an error occurs, the specified command will print an error message to standard output and return a nonzero exit status. Check In (vc_ci command) Used when the version control system is set to Custom. Specifies the shell command used to check a file into a version control system as the latest version. When the specified command is issued with a filename appended to it, the command will check in any changes made to the specified file. If the sequence %c appears in the command, it will be replaced by a quoted string that contains the comments the user entered. If an error occurs, the specified command will print an error message to standard output and return a nonzero exit status. Green Hills Software, Inc. 187

200 9. Configuration Options Create (vc_create command) Used when the version control system is set to Custom. Specifies the shell command used to put a file under version control for the first time. When the specified command is issued with a filename appended to it, the command will place the specified file under version control. If an error occurs, the command will print an error message to standard output and return a nonzero exit status. Show History (vc_show command) Used when the version control system has been set to Custom. Specifies the command used to output a list of the versions of a file, with optional comments or information about each. When the specified command is issued a filename is appended to it and the standard output of the command is collected and shown to the user. Who (vc_who command) Used when the version control system has been set to Custom. Specifies the shell command used to determine which user has a file checked out. When the specified command is issued with a filename appended to it, the command will print to standard output the username of the person who has the file checked out, or print nothing if the file is not checked out. Previous Version (vc_prevver command) Used when the version control system has been set to Custom. Specifies the shell command used to retrieve the version number of a file s previous version. When the specified command is issued with a filename appended to it, the command will print the previous version number of the file to standard output. This configuration setting is not required for simple version control operations. Automatic Checkout (Versctrl_CustomAutoCheckout) Specifies whether files are automatically checked out when you start to edit them. Window Docking Options Dialog Box This dialog box opens when you click the Windows Docking buttononthe General tab of the Options window. This dialog box contains two tabs: Global Options The options on this tab apply to all MULTI applications (see Window Docking Global Options on page 189). Any options selected on this tab will override any application-level options set on the Application Options tab. 188 MULTI: Editing Files and Configuring the IDE

201 General Configuration Options Application Options The options on this tab apply only to the specific application specified in the Application text box of the tab (see Window Docking Application Options on page 190. These application-level options can be overridden by options set on the Global Options tab. The options on each of these tabs are described below. For more information about window docking, see Configuring Window Docking on page 171. Window Docking Global Options The following items on the Global Options tab apply to all applications: Disable all window management Completely disables both window alignment (snapping) and window grouping. Disable all grouping Completely disables any grouping of windows, overriding any Application Options. Docking Distance Specifies the distance at which windows will snap to each other, either side-by-side or vertically. There are two settings: Opposing edges Specifies the distance in pixels to snap windows when the left edge of a window docks with the right edge of another, or the top of one window docks with the bottom of another. Same edge Specifies the distance in pixels to snap windows when aligning the edges of vertically adjacent windows. For example, you can align a series of windows in a column along the left edge. Green Hills Software, Inc. 189

202 9. Configuration Options Compatibility UNIX only Disables certain window docking behaviors that may not be supported or function correctly in some specific circumstances. Specifically: Disable grouping in KDE Disables any grouping of windows when the KDE window manager is detected. This setting overrides any application-level options and is selected by default. For more information, see UNIX Docking Limitations on page 171. Disable activation follows focus Disables the raising all windows in the same group as a window which gets the focus. This option is selected by default. Disable geometry caching Disables caching of window manager window geometry. Selecting this option will cause a small window to open and close each time an application is started, so that MULTI can detect window manager geometry properties. This option is cleared by default and should not be selected unless the MULTI cannot properly detect a change in window managers. Window Docking Application Options The following items on the Application Options tab allow specific window grouping behavior to be configured on a per-application basis. Application Displays the location of the window docking configuration file that is currently being viewed. This file may be located in the site wide configuration directory or in the user configuration directory. Any changes are saved to the user configuration directory. Window Lists the available window types (which vary depending on the application). Each window must include support for configurable window grouping. Docks to For the selected Window, this field specifies what other types of windows will form groups when docked. The up and down arrows can be used to move window types between the Docks to and Does not dock to lists. 190 MULTI: Editing Files and Configuring the IDE

203 General Configuration Options Does not dock to For the selected Window, this field specifies what other types of windows will not form groups when docked. The up and down arrows can be used to move window types between the Docks to and Does not dock to lists. Online Help Options Dialog Box (UNIX only) This dialog box opens when you click the Help buttononthegeneral tab of the Options window. Method Specifies which help system should be used to display online help. Permitted settings for this option are: Oracle Help for Java (OnlineHelpMethod OHJ) OracleHelpforJavawill be used to display online and contextual help. This option is not available on machines running Solaris Web Browser (OnlineHelpMethod Browser) The browser specified by BrowserCommand will be launched on the HTML file that contains the online help. See the sections below for information about configuring the web browser. The default value of this option is set automatically and depends on your system configuration. Browser command This field displays the executable name of the program used to display HTML online help files. The default is netscape (BrowserCommand executable) This option is only in effect if Method Browser is selected (OnlineHelpMethod Browser). Browser supports -remote command line option This option applies only when Method Browser has been specified (OnlineHelpMethod Browser). Permitted settings for this option are: Selected (BrowserUseRemote On) [default] The web browser specified by Browser Command will be launched using the -remote command line syntax. When used with Netscape and other browsers that support -remote, MULTI will use previously opened web browsers to display online help, instead of launching a new browser for each help page. Cleared (BrowserUseRemote Off) Online help pages will open in new browser windows. Green Hills Software, Inc. 191

204 9. Configuration Options Other General Configuration Options The options in this section are not accessible from the Options dialog box. These options are set in a configuration file, or by using the configure command in the Debugger command pane. BlinkingCursor [On Off] On [default] The vertical bar cursor in various windows (such as the Debugger command pane and the Editor) will blink. Off The cursor will be a solid non-blinking bar. ClearKeys UNIX only Removes all of the key bindings so they can be created from scratch with keybind. ClearMenus Removes all menus so they can be created from scratch using menu. ClearMice Removes all mouse button bindings so they can be created from scratch with mouse. ClickPause time UNIX only [default is 4] Specifies the length of time, in time tenths of a second, that MULTI waits between successive button presses to recognize double or triple clicks. For example: If time is 4, two clicks on the same button, in the same mouse location, within four tenths of a second, are treated as a double-click. If the two clicks are separated by more than time tenths of a second, they are treated as two single-clicks. If no mouse binding requiring multiple clicks exists for a particular mouse location, MULTI executes the mouse binding immediately without waiting for multiple clicks. configurefile filename Used within a configuration file to read in another configuration file specified by filename. Afterfilename is processed, processing of the original configuration file continues as normal. 192 MULTI: Editing Files and Configuring the IDE

205 General Configuration Options DisAsmStyle [remote XORmacs UNIX] Controls the style of disassembled Motorola series code. This option may have one of three values: remote [default] Use XORmacs style if the code is destined for execution on an embedded processor or UNIX style for native development. XORmacs AlwaysuseXORmacs style (such as MOVE.L (12,A6),D0). unix Always use UNIX/Sun style (such as movel GrabTimeout time UNIX only [default is -1] Specifies an interval used to force programs to release any X-server keyboard or mouse grabs: If time is less than zero, MULTI does not check to see if there are any outstanding grabs on the X-server each time it stops. If time is greater than zero, MULTI checks to see if the program has any outstanding grabs when the program is stopped by a signal or breakpoint. If both the keyboard and the mouse are grabbed, MULTI waits time seconds before aborting the other program s grabs and then continues debugging, allowing you to use the mouse and keyboard to issue commands to the Debugger. This option is useful for Solaris native development only. iconify [On Off] UNIX only [default is Off] Specifies whether or not the next MULTI window will be minimized as an icon when it opens. This option is only applied to the next window created and does not affect existing windows. If you repeatedly configure this option to On, it will remember the number of times you have done this, and cause the next num windows to be created minimized (one per time you configure the option to On). After the correct number of windows come up minimized, this option resets itself to Off. ignoremotion num [default is 4] Specifies the number of pixels the mouse can move during a press and release of a mouse button. If the mouse moves less than num pixels between a button press and release, the click is treated as a single click. If the mouse is moved by more than num pixels between press and release, the mouse click is no longer treated as a single click but as two independent press and release events. Green Hills Software, Inc. 193

206 9. Configuration Options keybind Used to assign an action to a key. For more information, see Customizing Keys and Mouse Clicks on page 165. menu Used to define a menu. For more information, see Configuring and Customizing Menus on page 162. menudelay time [default is 25] The delay, in milliseconds, between moving the cursor over a submenu entry and the submenu opening. If set to 0, submenus will open immediately. mouse Used to assign an action to mouse button clicks. For more information, see Customizing Keys and Mouse Clicks on page 165. multiiconprename string UNIX only When you iconify a window, string will appear as the prefix of the icon name. For example, if you set string to MULTI, when you iconify your editor window, the icon will be named MULTI:Filename.c, instead of Filename.c. multiwinprename string string will appear as the prefix of the Window names in the Title Bar. NoDecoration [On Off] UNIX only UNIX only [default is Off] If this option is On and the window manager supports it, all windows appear without title bars. On If the windows manager supports it, all windows appear without title bars. Off [default] Windows appear with title bars. showgrepcommand [true false] true [default] The full grep command prints out whenever the grep command is executed. false The full grep command does not print out. synchronous [On Off] UNIX only Synchronous mode ensures that X-window calls from MULTI complete before they return. This can be useful when running MULTI on faulty X-servers. On Enable synchronous X-windows mode. Off [default] Disable synchronous X-windows mode. 194 MULTI: Editing Files and Configuring the IDE

207 Builder Configuration Options UseWMHinting [On Off] [default is Off] Fixes a problem that occurs with the CDE window manager on HP-UX machines. Do not turn this configuration option On unless the host is a HP-UX machine. UseWMPositioning [On Off] On MULTI allows the window manager to determine where all windows should go. Off [default] MULTI automatically places windows in convenient locations. Builder Configuration Options This section describes configuration options that affect the Builder. These options can all be configured on the Builder tab of the Options window. Open build details window Permitted settings for this option are: Always (ShowProgress Always) The Build Details window will open every time you build an application, even if no warnings or errors are produced. On Warnings and Errors (ShowProgress On Warning and Errors) [default] The Build Details window will open if your build produces warnings or errors. On Errors (ShowProgress On Errors) The Build Details window will open if your build produces errors, but will not open for warnings. Automatically open editor on errors Permitted settings for this option are: Selected (autoediterrors On) [default] The code that caused the first error of the build will automatically display in an Editor window. Cleared (autoediterrors Off) Errors will display in the Build Details window. Double-click an error to open it in an Editor window. On warnings Permitted settings for this option are: Selected (autoeditwarnings On) The code that caused the first warning will automatically display in an Editor window. Cleared (autoeditwarnings Off) [default] Warnings will display in the Build Details window. Double-click a warning to open it in an Editor window. Green Hills Software, Inc. 195

208 9. Configuration Options Use MULTI Editor on errors (even if alternate editor is specified elsewhere) Permitted settings for this option are: Selected (alwaysusemetofixbuilderrors On) [default] Errors and warnings will be displayed in the MULTI Editor even if you have configured the MULTI environment to use an alternate, third-party editor. Cleared (alwaysusemetofixbuilderrors Off) Errors and warnings will be displayed in the editor you use in your MULTI environment. Automatically open connection files in opened.gpj files Permitted settings for this option are: Selected (autoopenconnectionfilesfromgpjfiles On) [default] Any target connection (.con) files present in an open Builder file are opened by the Connection Organizer. Cleared (autoopenconnectionfilesfromgpjfiles Off) Target connection files are not automatically opened by the Connection Organizer. Automatically share target connections Permitted settings for this option are: Selected (autoconnectionmode On) [default] The primary target connection is used. Cleared (autoconnectionmode Off) Multiple target connections can run concurrently. Advanced users who need to have multiple target connection running must clear this option before starting multiple connections. Display connection type in Connection Chooser Permitted settings for this option are: Selected (displayconnectiontypeinchooser On) The type of a connection method is displayed in brackets after the name in the drop-down list in the Connection Chooser dialog. Custom connection methods have no type displayed. Cleared (displayconnectiontypeinchooser Off) [default] Only the name of the connection method is displayed. 196 MULTI: Editing Files and Configuring the IDE

209 Debugger Configuration Options Debugger Configuration Options This section describes configuration options that affect the Debugger. Most of these options appear on the Debugger tab of the Options dialog box. Debugger Options Tab To access the following options, select Config Options Debugger tab. Ask before halting to set breakpoint Permitted settings for this option are: Selected (VerifyHalt On) [default] The Debugger will ask for confirmation before halting the process to set a breakpoint Cleared (VerifyHalt Off) The Debugger will automatically halt, set the breakpoint, and continue the process without requiring user intervention. Use procedure relative line number (vs. file relative) Permitted settings for this option are: Selected (ProcRelativeLines On) [default] Debugger commands, such as the e command, interpret line numbers as procedure relative, instead of file relative. Cleared (ProcRelativeLines Off) Line numbers are treated as file relative. You can always specify file relative line numbers regardless of the setting of this option by using the # character before line number arguments to commands. Display all numbers/characters as hex Permitted settings for this option are: Selected (HexMode On) All numeric values are displayed in hexadecimal format Cleared (HexMode Off) [default] Display format is based on the natural display format for that type. For integral types, the natural display format is decimal. View unsigned char as integer Permitted settings for this option are: Selected (ViewUnsignedCharAsInt On) The natural display format of unsigned chars will be the same as for ints. This is useful when you want to view byte values as numerical values instead of characters. Cleared (ViewUnsignedCharAsInt Off) [default] The natural display format for unsigned chars is a literal character, such as A Green Hills Software, Inc. 197

210 9. Configuration Options Coloring for multiple debuggers Specifies how the background color of new Debugger windows is chosen. It is useful to turn this on when using multiple Debugger windows to make them visually distinct. Permitted settings for this option are: Do Not Color (BackgroundMode Off) All Debugger windows use the normal background color. Use Color Offsets (BackgroundMode Offset) [default] New Debugger windows will use predetermined offsets from the normal background color. This option is usually best since it will pick colors near the current background color, and keep the text as legible as possible. Use Preset Colors (BackgroundMode Preset) New Debugger windows will use a color from a set of pre-chosen, highly distinctive colors. Line numbers in source pane Specifies how line numbers are displayed on the left side of the Debugger source pane. Permitted settings for this option are: No Number (LineNumberMode None) No line numbers are displayed. File Number (LineNumberMode File) The file relative line numbers are displayed. Proc Number (LineNumberMode Proc) The procedure relative line numbers are displayed. Both Numbers (LineNumberMode Both) [default] Both file-relative and procedure-relative line numbers are displayed. Show variable values in tooltips Permitted settings for this option are: Never (fastest and safest) (hovervalues: Never (fastest and safest)) Never show variable values in tooltips. On Mouse Hover (hovervalues: On Mouse Hover) When the mouse is positioned over a variable show its value in a tooltip. On Mouse Hover with Shift Key (hovervalues: On Mouse Hover with Shift Key) [default] When the mouse is positioned over a variable while the shift key is depressed show its value in a tooltip. Position of buttons Specifies the location of the toolbar inside of Debugger windows. Permitted settings for this option are: Top (DebugButtonsLoc Top) [default] The toolbar appears below the menu bar and above the source pane. Bottom (DebugButtonsLoc Bottom) The toolbar appears below the command pane and above the status bar. 198 MULTI: Editing Files and Configuring the IDE

211 Debugger Configuration Options Debugger child windows Windows only Controls how Debugger child windows (such as Data Explorer, monitor, and the breakpoint window) interact with the Debugger window in terms of stacking order and focus. Permitted settings for this option are: Stay above debugger (ViewsAreChildrenMode Children) [default] Child windows are always displayed in front of the Debugger, and the keyboard focus stays with the Debugger when a child window appears. This makes it easy to keep track of child windows and keeps the focus with the Debugger for further command input, but can be annoying if the child windows start to obscure the Debugger window. Child windows can be minimized, but this mode precludes partially obscuring a child window with the Debugger to save space. Can be below debugger (ViewsAreChildrenMode Toplevel) Child windows can be either above or below the Debugger, and keyboard focus remains with the Debugger for further command input when a child window first appears. Because the keyboard focus remains with the Debugger, child windows will appear to flash above the Debugger and then immediately go behind it, so this option is most useful on a large screen where child windows do not overlap the Debugger when they first appear. Are initially focused (ViewsAreChildrenMode KeepFocus) Child windows can be either above or below the Debugger, and also receive the keyboard focus when they first appear. This keeps child windows from immediately going behind the Debugger, but takes the focus away from the Debugger. Further command input into the Debugger is not possible until you click the Debugger again to give it the keyboard focus. Command pane height in lines Specifies the initial height of the command pane in num lines of text. The equivalent command for this setting is: CWindLines num [default is 10]. Command pane prompt Specifies the string used as a prompt in the Debugger command pane to indicate that user input is desired. The equivalent command is: prompt string [default is MULTI>]. Configure Debugger Buttons Opens a dialog box which you can use edit the Debugger toolbar buttons using the same format as the debugbutton command. This dialog box is only accessible from the MULTI Debugger. The dialog box lists currently defined buttons on the left, and available icons on the right. For more information, see the debugbutton option in Other Debugger Configuration Options on page 207. Green Hills Software, Inc. 199

212 9. Configuration Options More Debugger Options This button opens the More Debugger Options dialog box which contains additional configuration options for the Debugger (see More Debugger Options Dialog on page 200). Minimum initial size (WxH) Specifies the minimum initial size of a Data Explorer window in characters (width) and lines (height). The equivalent command is: MinViewSize widthxheight [default is 40x3] If left blank, MULTI will auto-size the Data Explorer windows appropriately. Maximum initial size (WxH) Specifies the maximum initial size of a Data Explorer window in characters (width) and lines (height). The equivalent command is: MaxViewSize widthxheight [default is 40x42] Ifthe minviewsize (see above) is greater in either dimension than the maxviewsize, themaxviewsize value is used. Initial position (XxY) Specifies the initial position from the top-left of the screen for a Data Explorer window, specified in characters (width) and lines (height). The equivalent command is: FirstPosition horizxvertp [default is 0x0] To give the coordinates in pixels, put a p after them (for example, 100x100p). This option only applies to the first Data Explorer window. Subsequent Data Explorer windows are offset from the first one that was created, avoiding excessive overlap. If this option is left unspecified (blank), the Debugger auto-positions all Data Explorer windows. More Debugger Options Dialog This dialog box opens when you click More Debugger Options buttononthe Debugger tab of the Options window. Automatically dereference pointers Permitted settings for this option are: Selected (DerefPointer On) [default] MULTI automatically follows pointers when it encounters them and prints both the pointer value and the object it points to. Cleared (DerefPointer Off) MULTI only displays the value of the pointer. 200 MULTI: Editing Files and Configuring the IDE

213 Debugger Configuration Options Check syntax of breakpoints when they are set Permitted settings for this option are: Selected (BpSyntaxChecking On) [default] Commands associated with a breakpoint must pass syntax checking for the breakpoint to be set. Breakpoint commands that fail syntax checking cannot be set. Cleared (BpSyntaxChecking Off) A syntax error in a breakpoint command will not be detected by MULTI until the breakpoint is hit and MULTI tries to execute the associated commands. Continue running script files on error Permitted settings for this option are: Selected (ContinuePlaybackFileOnError On) The Debugger will not stop if it encounters an error while running a script file. Instead, it will ignore the error and continue reading and performing commands out of that file. Cleared (ContinuePlaybackFileOnError Off) [default] The Debugger aborts running a script file if it encounters an error. See also AbortPlaybackFileOnSeriousError in Other Debugger Configuration Options on page 207. s (step) and n (next) are blocking by default Permitted settings for this option are: Selected (BlockStep On) No Debugger commands will be executed until a step or next finishes. Cleared (BlockStep Off) [default] Subsequent commands can execute before the step or next is finished, which can cause scripts that use s or n to appear to behave inconsistently. A step or next can be made blocking or non-blocking regardless of the setting of this option by appending an n (for non-blocking) or b (for blocking) to the command. Show locations of variables for print command Permitted settings for this option are: Selected (ShowAddress On) [default] The location (address in memory or register name) of a variable is printed when using the print command. Cleared (ShowAddress Off) The location of a variable will not be printed; only the value is displayed. Green Hills Software, Inc. 201

214 9. Configuration Options Display typedef type instead of basic type Permitted settings for this option are: Selected (LeaveTypedef On) Data explorer windows for structures will display the name of the type definition Cleared (LeaveTypedef Off) [default] Data explorer windows for structures will display the actual self-contained type. Show position in non-gui (-nodisplay) mode Permitted settings for this option are: Selected (ShowPosInNoDisplayMode On) [default] When running in non-gui mode, MULTI will print the line of source associated with the current line pointer, each time the current line pointer moves. This is the line that will be affected by the next Debugger command executed. Cleared (ShowPosInNoDisplayMode Off) The line of source code associated with the current line will not display. Repeat last command on return key in non-gui (-nodisplay) mode Permitted settings for this option are: Selected (DisableCarriageReturnRepeat On) The Return key does not repeat the last entered command. Cleared (DisableCarriageReturnRepeat Off) [default] The Return key can be used to repeat the last entered command when running in non-gui mode. Print return values when stepping out of functions Permitted settings for this option are: Selected (PrintReturnValues On) If a function returns a value print the return value to the command pane when stepping out of the function Cleared (PrintReturnValues Off) [default] Do not print return values of functions when stepping out of them Show target windows when connecting to debug server Permitted settings for this option are: Selected (ShowTargetWindows On) The Target and IN/OUT windows will appear when you connect to a debug server. Cleared (ShowTargetWindows Off) Target and IN/OUT windows will be created when you connect to a Debug server, but they will be hidden. You can make the windows appear with the targetwindow command. Or you can switch to the target pane and I/O pane in the Debugger window to access the functionality of the two windows. For more information, see the targetwindow and debugpane commands, and information about the multi-purpose pane in the MULTI: Debugging manual. 202 MULTI: Editing Files and Configuring the IDE

215 Debugger Configuration Options Request OSA package when MULTI cannot figure it out Permitted settings for this option are: Selected (RequestOsaPackage On) If MULTI thinks that the program is a freeze-mode debugging project (see Chapter 26, Freeze-Mode Debugging and OS-Awareness in the MULTI: Debugging book) but cannot determine the Operating System Awareness (OSA) package, MULTI will prompt you for the package name. You can choose the package name so that MULTI can provide the corresponding debugging features, or select Cancel to continue without OSA. Cleared (RequestOsaPackage Off) [default] MULTI will not prompt you for the OSA package name and will continue without OSA. Delete dead tasks from group Permitted settings for this option are: Selected (DeleteDeadTaskFromGroup On) The Task Manager will delete dead task fingerprints from the task group. For more information about task groups and the meaning of dead tasks, see Chapter 25, Run-Mode Debugging in the MULTI: Debugging book. Cleared (DeleteDeadTaskFromGroup Off) [default] The Task Manager will not delete dead task fingerprints from the task group. Automatically verify ROM image is up-to-date Permitted settings for this option are: Selected (autoverifyromsections On) [default] When an executable residing in the target s ROM begins executing, the Debugger will automatically check whether the host and target versions of the executable match. For more information, see the romverify command in Chapter 30, Debugger Commands in the MULTI: Debugging book. Cleared (autoverifyromsections Off) The Debugger will not check the target s version of the executable. Green Hills Software, Inc. 203

216 9. Configuration Options Translate DWARF debugging information (requires dwarf2dbo license) Permitted settings for this option are: Selected (autodwarf2dbo On) Enables automatic translation of DWARF debugging information when an executable built with a third-party compiler that generates DWARF information is loaded. This option is only meaningful if you have licensed dwarf2dbo; otherwise, it will have no effect. Cleared (autodwarf2dbo Off) [default] Disables automatic translation of DWARF debugging information. For more information about translating DWARF debugging information, see Using the Debugger with Third-Party Compilers in Appendix D, Using Third-Party Tools with the MULTI Debugger in the MULTI: Debugging book. Translate stabs debugging information (requires stabs2dbo license) Permitted settings for this option are: Selected (autostabs2dbo On) Enables automatic translation of Stabs debugging information when an executable built with a third-party compiler that generates Stabs information is loaded. This option is only meaningful if you have licensed stabs2dbo; otherwise, it will have no effect. Cleared (autostabs2dbo Off) [default] Disables automatic translation of Stabs debugging information. For more information about translating Stabs debugging information, see Using the Debugger with Third-Party Compilers in Appendix D, Using Third-Party Tools with the MULTI Debugger in the MULTI: Debugging book. Resuse Data Explorer Permitted settings for this option are: Selected (UnifyViewWindows On) Causes MULTI to display newly opened variable in an existing, non-frozen Data Explorer when available. Cleared (UnifyViewWindows Off) Causes each newly viewed variable to be displayed in a separate Data Explorer. For more information, see Chapter 9, Viewing and Modifying Variables with the Data Explorer in the MULTI: Debugging book. 204 MULTI: Editing Files and Configuring the IDE

217 Debugger Configuration Options Stepping over C++ exception or longjmp When the Debugger performs a next operation over a subroutine that calls longjmp or throws a C++ exception (implemented by a call to longjmp internally), the subroutine does not return in the normal way due to the transfer of control within the function call. This is significant because the Debugger uses a temporary breakpoint just after the normal return address to implement the next operation. This is also true of step if there is no source available for the subroutine. When longjmp is called, this temporary breakpoint is bypassed due to the transfer of control, and execution can run away since the breakpoint will never be hit. This configuration option controls how MULTI attempts to properly catch unexpected transfers of control while stepping through code. Permitted settings for this option are: Ignore/Run Away (longjmpstepmode IgnoreRunAway) [default] Let the code call longjmp without attempting to detect abnormal transfers of control. Minimize Temp Stops (longjmpstepmode MinimizeTempStops) Fixes the problem in a way that does not cause temporary stops in longjmp as the program runs normally. This option inserts and removes a temporary breakpoint at longjmp for each next over a function call. Maximize Step Speed (longjmpstepmode MaximizeStepSpeed) Fixes the problem in a way that minimizes the time it takes to do a next. This option leaves a permanent breakpoint at longjmp, and will result in execution always halting due to a breakpoint being hit whenever the program calls longjmp, even during normal execution. Debug server timeout in seconds Specifies the number of seconds to wait for communication from a debug server before assuming it is dead and disconnecting from it. The equivalent command for this setting is: ServerTimeout seconds [default is 15]. A timeout that is too low will sometimes mistakenly disconnect from the debug server, and is not recommended. A fairly high timeout can be useful for very slow debug servers or debug servers that are being debugged. A high timeout can be frustrating if the debug server actually does die, because the Debugger cannot accept input while it s waiting for communication from a debug server. Interval to refresh Task Manager (in seconds) Specifies the polling interval in seconds. MULTI checks for interesting events happening in the underlying RTOS and refreshes the Task Manager periodically. The equivalent command for this setting is: ServerPollInterval seconds [default is 1 for INTEGRITY; 5 for other real-time operating systems]. Green Hills Software, Inc. 205

218 9. Configuration Options Criteria to decide if a task is in a group Controls how to match a task fingerprint against a task. For more information about how the fingerprint is used in the construction process of a task group, see Chapter 25, Run-Mode Debugging in the MULTI: Debugging book. Permitted settings for this option are: Task Name (TaskMatchCriteria Name) [default] Matches against the name of the task. Task Identifier (TaskMatchCriteria Id) Matches against the identifier of the task. Task Name or Identifier (TaskMatchCriteria NameOrId) Matches against the name or identifier of the task. Prompt when exiting Debugger Controls whether a confirmation dialog box appears when a user attempts to close the Debugger. Permitted settings for this option are: Confirm If Process Started (PromptQuitDebugger Normal) [default] The confirmation dialog box is displayed only if the Debugger is attached to a process that has been started. If the Debugger is attached to a process that has not been started, the Debugger closes without displaying the confirmation dialog box. In a run-mode debugging environment, the Debugger closes without displaying the confirmation dialog even though the process has been started. Always Confirm (PromptQuitDebugger Always) The Debugger will not close until the user confirms the action in the confirmation dialog box. Never Confirm (PromptQuitDebugger Never) The Debugger never displays the confirmation dialog box before closing. Maximum size for container display The equivalent command for this setting is: maxcontainerdisplaysize num [default is 20] Sets the maximum number of elements initially displayed when a container is viewed in a Data Explorer. Increment to maximum container size The equivalent command for this setting is: containersizeincrementnum [default is 10] Sets the number of elements to add when expanding a container that is being viewed in a Data Explorer. 206 MULTI: Editing Files and Configuring the IDE

219 Debugger Configuration Options Other Debugger Configuration Options The options in this section are not accessible from the Options dialog box. These options can be set in a configuration file or by using the configure command in the Debugger command pane. AbortPlaybackFileOnSeriousError [On Off] [default is Off] On The Debugger will abort running a script file if an apply, backout, or rload command fails, even if the option ContinuePlaybackFileOnError is On (see the Debugger commands apply, backout, and rload). Off [default]. AllowExecutionInAssertionCommand [On Off] On Execution of command line procedure calls is allowed from within assertion commands. This is somewhat risky because command line procedure calls may affect the state of the program counter, potentially causing improper functioning of assertions and breakpoints. Off [default]. AllowExecutionInBpCommand [On Off] On Stepping and execution of command line procedure calls are allowed from within a breakpoint command. This is somewhat risky because infinite breakpoint command recursion can occur if the execution from within the breakpoint command causes the same or another breakpoint to be hit. The resume command is always allowed in a breakpoint command. Off [default]. AssertionSyntaxChecking [On Off] On Commands associated with an assertion must syntax check without errors before the assertion is set. The syntax checking verifies that Debugger commands will not result in errors when they are executed and variables are accessible in the scope where the assertion is set. Off [default] Allows assertions to reference variables which are not in the current scope, although using such assertions is not recommended. AttemptToShowOldVersionOfUpdateSource [On Off] On The Debugger will display the versions of source files that were used to build the executable being debugged by using the version control history to check out the appropriate version of the file. Off [default]. Green Hills Software, Inc. 207

220 9. Configuration Options ClearButtons Removes all of the Debugger buttons (except for the Close buttonifitis present) so they can be created from scratch with debugbutton. debugbutton Lists the defined Debugger buttons. Used with additional configuration options to add, delete, and configure buttons. See Configuring and Customizing Toolbar Buttons on page 160 for details. DownloadWindow [true false] The Download Window is a window which shows the current progress of a program download. The option can be set to: true [default] The download window will be used when downloading a program to the debug server. false The download window will not be used. EchoCommandsFromPlaybackFiles [true false] true When executing from a playback file, Debugger commands being executed will be displayed. false [default] When executing from a playback file, Debugger commands being executed will not be displayed. ExprCaseSensitivity [Language_Default On Off] Controls the case sensitivity of expression evaluation in the Debugger. This option may take one of three values: Language_Default [default] The Debugger follows the case sensitivity rules for the language of the program being debugged. (This setting is recommended.) On Expression evaluation is case sensitive. Off Expression evaluation is not case sensitive. FormatStringMaxDepth num Limits the depth to which nested structs are displayed in a Data Explorer Window. num [default is 0x7fffffff] The number of levels of nested structs to display. The valid range is 1 unlimited (0x7fffffff). 208 MULTI: Editing Files and Configuring the IDE

221 Debugger Configuration Options FormatStringMaxLength num Limits the length of the value displayed on each row in a Data Explorer window. Data values displayed on a single row in a Data Explorer can be very long, for example when displaying a long string value, or a structure with many nested structs. num [default is 8192] The number of characters to display in a row. For example, if this is set to 2000, only the first 2000 characters of a long string will display, followed by... to indicate there are more characters that are not displayed. The valid range is 1024 to 10 megabytes ( ). geometry widthxheight [[+x_offset+y_offset] [-x_offset-y_offset]] [default depends on screen size and varies from system to system. The width is approximately wide enough to display 80 characters on a line.] This configuration command sets the size and position of the Debugger window: The width and height correspond to the pixel size of the Debugger window. The optional x_offset and y_offset values indicate the pixel offset at which the Debugger window appears from the top left corner of the screen for the + variant or from the bottom right corner of the screen for the - variant. For example, the entry: geometry 500x specifies a 500 pixel wide by 700 pixel high Debugger window that appears in the top left corner of the screen: GlobalHeading [On Off] On Enables the global scope entry in the Browse window. Off [default] Disables global scope entry in the Browse window. GotoHitsBpAtTargetAddress [On Off] On If you are using the Debugger command g, any breakpoint at the destination will be hit as soon as execution begins at the new location. This option also controls whether a breakpoint set on the first instruction of a procedure called from the command line is hit. Off [default] The breakpoint will not be hit. See the g command in Chapter 30, Debugger Commands in the MULTI: Debugging book for more information about the g command. history num [default is 256] This option specifies how many commands to remember for the Debugger command history mechanism. For more information see Chapter 30, Debugger Commands in the MULTI: Debugging book. Green Hills Software, Inc. 209

222 9. Configuration Options icongeometry widthxheight+x_offset+y_offset UNIX only [default is 32x64+0+0] Specifies the dimensions for the icon that is used when the Debugger is minimized (some window managers will ignore this setting): width and height The width and height of the icon in pixels. x_offset and y_offset The number of pixels the icon should be offset from the top left corner of the screen. interleavedoutput [true false] Controls whether output from Debugger panes other than the command pane will also be output to the command pane. true [default] Output from Debugger panes other than the command pane will be output to the command pane. For example, the I/O pane will show up in command pane the with the prefix I/O:. false Output from other panes will not appear in the command pane. KeepLoaders [On Off] On The Debugger will keep certain item chooser windows (such as file choosers) open after they have been used once, so they can be used multiple times. Off [default] Item chooser windows disappear after being used once. LinesNonOverlapped num [default is 4] By default, when the Debugger opens a Data Explorer or monitor window with UseWMPositioning Off (see Other General Configuration Options on page 192), the new window is stacked on top of previous windows to save screen space. This setting leaves the top num lines of the previous window visible. ProcQualifiedLocalImpliesOutermostBlock [On Off] When the current line pointer is in an inner block of a procedure and that inner block defines a variable which has the same name as a variable in the outer block, a procedure qualified reference to the name of the variable can either refer to the variable of that name in the outermost block or the current inner block. This option determines which of the two options is used: On The outermost block is used. Off [default] The current inner block is used. paddedhex [true false] true Forces hex values to be displayed padded to their full width with zeros. For example, a four byte variable with a value of 0x8 will be displayed as 0x false [default] Hex values will not be displayed as entered. 210 MULTI: Editing Files and Configuring the IDE

223 Debugger Configuration Options QuietTogCmd [On Off] On The tog command does not echo the status of the breakpoint(s) it toggles. Seealsotheq option for the tog command in Chapter 30, Debugger Commands in the MULTI: Debugging book. Off [default]. RecordCommentedCommandsFromMacros [true false] When command recording is enabled, commands executed from playback files are recorded as comments. This option controls whether commands executed from macros are also recorded as comments. true Commands executed from macros are recorded as comments. false [default]. sdlnamedisplay [On Off] On [default] The procedure name listed in stack traces will display the mnemonic SDL name instead of the C source name whenever possible for SDL generated code. For more information about SDL commands, see Chapter 30, Debugger Commands in the MULTI: Debugging book. SetBPAtAdrInitWhenExecing [On Off] On [default] MULTI will set a breakpoint at the starting routine of a program when the program is run. Execution is resumed automatically when this breakpoint is hit unless a user breakpoint was set at the same spot. This is necessary to prevent corrupted call stack traces. Off MULTI will not set a breakpoint at the starting routine of a program when the program is run. ShellConfirm [On Off] On [default] If MULTI is running in the background, the shell command will open a dialog box which allows you to confirm or cancel the execution of the shell command before the shell command executes. This is helpful when MULTI is running in the background, because the shell commands have no accessible standard output or standard error. Off MULTI will always execute shell commands immediately, without opening the dialog box. For more information, see the shell command in Chapter 30, Debugger Commands in the MULTI: Debugging book. sharedsymbols [true false] true [default] MULTI will attempt to debug shared objects. false MULTI will not attempt to debug shared objects. Green Hills Software, Inc. 211

224 9. Configuration Options ShowTraceOSAWindows [true false] true [default] The trace OSA window will open when packets in user mode address spaces are selected. false The trace OSA window will not open when packets in user mode address spaces are selected. SilentlyReloadSymbols [On Off] On The Debugger automatically kills any existing process and reloads the symbols without displaying this dialog. This is useful if you are using a Debugger primarily to examine symbols and not to debug running processes. Off [default] When the executable open in the Debugger changes, the Debugger displays a dialog asking if any existing process should be killed and the symbols reloaded. StepToBpIgnoresResumeInBpCmd [true false] Controls whether the c (continue) command in a breakpoint is ignored. (This option is incorrectly named, because it ignores the Continue command, not the Resume command.). true The c command in the breakpoint command list will be ignored, a warning will be printed, and the program will be stopped at the breakpoint. false [default] The c command in the breakpoint command list will not be ignored. For example, if you have a breakpoint with the command list print x; c and step on to this breakpoint, the program will start running, because the c command causes the program to continue. The c command inside a breakpoint always causes the program to start running, which is incorrect behavior if you want to step on to that line. Note that the resume command should be used inside breakpoint command lists. If the breakpoint s command list is print x; resume, the program stops when you step on to the breakpoint. If you run the program and it hits the breakpoint, it will keep running (the program resumes whatever it was going to do before hitting the breakpoint). 212 MULTI: Editing Files and Configuring the IDE

225 Debugger Configuration Options TBtypeBG color TBtypeFG color Specifies the background color (commands end with BG) or foreground color (commands end with FG) for Tree Browser displays, where: type is one of the following: FunctionNormal (TBFunctionNormalBG and TBFunctionNormalFG) Functions displayed in the static call Tree Browser which have debugging information. FunctionNoInfo (TBFunctionNoInfoBG and TBFunctionNoInfoFG) Functions displayed in the static call Tree Browser which do not have debugging information. FunctionRecursive (TBFunctionRecursiveBG and TBFunctionRecursiveFG) Functions displayed in the static call Tree Browser that may be recursive. FunctionAdrTaken (TBFunctionAdrTakenBG and TBFunctionAdrTakenFG) Nodes representing the possibility of calls to a function through function pointer in a Tree Browser. DynNormal (TBDynNormalBG and TBDynNormalFG) Functions displayed in the dynamic call Tree Browser with debugging information. DynNoInfo (TBDynNoInfoBG and TBDynNoInfoFG) Functions displayed in the dynamic call Tree Browser without debugging information. FileNormal (TBFileNormalBG and TBFileNormalFG) Files displayed in the file call Tree Browser with debugging information. FileNoInfo (TBFileNoInfoBG and TBFileNoInfoFG) Files displayed in the file call Tree Browser without debugging information. ClassUnion (TBClassUnionBG and TBClassUnionFG) Unions displayed in the class Tree Browser. ClassStruct (TBClassStructBG and TBClassStructFG) Types displayed in the class Tree Browser with debugging information. ClassNoInfo (TBClassNoInfoBG and TBClassNoInfoFG) Types displayed in the class Tree Browser without debugging information. ClassClass (TBClassClassBG and TBClassClassFG) Class data types displayed in the class Tree Browser. ClassEnum (TBClassEnumBG and TBClassEnumFG) Enum data types displayed in the class Tree Browser. BG or FG Specifies whether you are changing the background or foreground color of the displayed items. color Specifies, in RGB (## ## ##) format, the new color. Green Hills Software, Inc. 213

226 9. Configuration Options ViewDef [number_option] [eval_option] [[-]other_options] [default is NaturalOrHex ReEvalContext -ShowAddress -ShowFType -Alternate -PadHex ShowBases -ShowAllFields ShowDerived ExpandValue OpenPointer ShowChanges] Specifies how data will be displayed in Data Explorer windows, where: number_option can be one of the following: NaturalOrHex Numbers display in their default states unless HexMode On is set (see Debugger Options Tab on page 197). Natural Numbers display in their default states. Hex, Dec, Oct, Binary Numbers and characters display in base 16, base 10, base 8, or base 2 notation, respectively. eval_option specifies how the Debugger re-evaluates expressions when updating Data Explorers, and can be one of the following: ReEvaluate Each expression is re-evaluated in the same context it as when the Data Explorer displaying it was first created. ReEvalContext Expressions are re-evaluated within the current procedure at the top of the call stack. ReEvalInGlobal When expressions are re-evaluated, only looks for variables in the global scope. UseAddress Uses last valid address of variables being displayed. more_options can include any of the options listed below. (Prepending an option with a dash (-) disables the behavior.) ShowAddress Displays the address (rather than name) of the variable. ShowFType Shows the type of each variable, class, or structure. Alternate Displays data in an alternate format, if available. PadHex Adds zeros to the left of hexadecimal numbers to maintain same bit width, as needed. (Otherwise, only non-zero hexadecimal digits display.) ShowBases Displays the base classes of a C++ class along with a derived instance. ShowAllFields Displays all the fields of a complicated structure. ShowDerived Determines the most derived C++ class type of the current object and redisplays the object cast to that type. ExpandValue Displays the value in memory (if in readable memory) that a pointer references. OpenPointer Dereferences all pointers. ShowChanges Highlights values that have changed. 214 MULTI: Editing Files and Configuring the IDE

227 MULTI Editor Configuration Options TraceAlwaysOn [On Off] Trace collection is automatically enabled when connecting to a target that supports trace. On Trace collection will automatically be reenabled after trace is collected. When you click the Stop Tracing button, the trace data collected most recently is displayed, and trace collection is automatically reenabled. When the program completes execution, trace data is displayed and trace collection is automatically reenabled. Off [default] Trace collection will not be reenabled automatically. WarnOnBpReplacement [On Off] On The Debugger will display a warning before replacing a breakpoint that was already there. This is useful to avoid losing a long breakpoint command by accidentally replacing that breakpoint with a new breakpoint which has no command. Off [default]. ViewWindowDefaultToTree [true false] Controls whether View windows are displayed in tree mode or flat mode by default. true [default] View windows will be displayed in tree mode. false View windows will be displayed in flat mode. You can switch between tree and flat mode by pressing Ctrl + T or using the View window menu. WarnOnCmdAdrLinePromotion [On Off] On The Debugger will display a warning when setting a breakpoint on a line with no corresponding assembly code. Off [default]. MULTI Editor Configuration Options This section describes configuration options that affect the appearance and behavior of the MULTI Editor. If you are using the MULTI Editor, you will use the MULTI Editor tab of the Options dialog box for most settings (see MULTI Editor Options Tab on page 216). If you are using an alternate Editor, see Configure Other Editor Options on page 184. Green Hills Software, Inc. 215

228 9. Configuration Options MULTI Editor Options Tab To access the following options, select Config Options MULTI Editor tab. Reuse editor windows Permitted settings for this option are: Selected (OpenFilesInNewBuffers On) Files opened from the Builder or Debugger will open in a new buffer in the existing Editor window. Cleared (OpenFilesInNewBuffers Off) [default] Every file opened from the Builder or Debugger will open in a new Editor window. Create backup files when saving Permitted settings for this option are: Selected (EditorBackups On) A backup of the on-disk version of a file will automatically be created before saving over it. The backup file has the same name as the original file, with a tilde (~) appended to it. Cleared (EditorBackups Off) [default] Backup files will not be created. Allow middle click to paste Permitted settings for this option are: Selected (allowmiddleclick On) [default for UNIX] Clicking the middle mouse button will have the same effect as pasting from the selection buffer. Cleared (allowmiddleclick Off) [default for Windows] Clicking the middle mouse button will not paste from the clipboard. Enter spaces in place of tabs Permitted settings for this option are: Selected (TabsAreSpaces On) Tab characters entered into an Editor window will be replaced by an appropriate number of space characters in the Editor buffer, regardless of whether the Tab is the result of press of the Tab key, a paste command, or an auto-indent by the Editor. Cleared (TabsAreSpaces Off) [default] Space characters are not inserted in place of Tab characters. Drag and drop text editing Permitted settings for this option are: Selected (DragAndDrop On) [default] Text can be moved in the Editor by selecting a block of text and dragging the mouse to a new location. Cleared (DragAndDrop Off) Text cannot be moved by dragging the mouse. 216 MULTI: Editing Files and Configuring the IDE

229 MULTI Editor Configuration Options Allow overtype mode Permitted settings for this option are: Selected (allowovertypemode On) Allows switching between insert and overtype mode. Cleared (allowovertypemode Off) [default] Does not allow switching between insert and overtype mode. Tab size Specifies the number of spaces used to display a Tab in the Editor. The equivalent command for this setting is: TabSize spaces [default is 8]. Indent size Specifies the number of spaces in an indentation. The equivalent command for this setting is: EditIndent spaces [default is 4]. Ctrl+cursor jump size Specifies the value used by the UpSome, DownSome, LeftSome, and RightSome commands in the Editor. The equivalent command for this setting is: EditSomeSize num [default is 5] These are bound to the Ctrl + Left Arrow keys. For example, Ctrl + LeftArrow will move the cursor left by num characters. Configure Editor Buttons Opens the Configure Buttons dialog box, which allows you to edit the Editor buttons using the same format as the editbutton configuration option (see Configuring and Customizing Toolbar Buttons on page 160). The dialog box lists currently defined buttons on the left, and available icons on the right. More Editor Options Opens the More Editor Options dialog box, which contains additional configuration options for the Editor. See More Editor Options Dialog Box on page 220. Implicit auto indent Permitted settings for this option are: Selected (AiImplicitIndent On) [default] The Editor automatically indents thefileasyoutype. Cleared (AiImplicitIndent Off) The Editor will not automatically indent your file. Green Hills Software, Inc. 217

230 9. Configuration Options Implicit auto indent in comments Permitted settings for this option are: Selected (AiImplicitIndentInComments On) [default] Comments will be indented when auto-indenting multiple lines. Cleared (AiImplicitIndentInComments Off) Comments are not modified unless you auto-indent a single line. Switch bodies indented two instead of one Permitted settings for this option are: Selected (AiSwitchInTwo On) [default] For C or C++ source files, switch bodies are indented two levels so that case labels are indented one level in from the switch. For Ada source files, select bodies are indented two levels so that labels are indented one level in from the select. Cleared (AiSwitchInTwo Off) For C or C++ source files, the case labels are even with the switch. For Ada source files, the labels are even with the select. Indent comments when indenting multiple lines Permitted settings for this option are: Selected (AiTouchComments On) Comments are indented when auto-indenting multiple lines. Cleared (AiTouchComments Off) [default] Comments are only indented if you auto-indent a single line. Comments stick flush left Permitted settings for this option are: Selected (AiCommentsStayFlushLeft On) [default] All comments will be kept directly on the left margin. To indent a comment that is stuck to the left margin while this option is selected, insert a space just before the start of the comment, then auto-indent the comment. To move a comment to the left margin, regardless of the position where the comment started, insert a number sign (#) as the first character of a comment. For example, if you are coding in C, type: /*# and the comment is automatically moved to the left margin. Cleared (AiCommentsStayFlushLeft Off) Indents will be applied to comments. 218 MULTI: Editing Files and Configuring the IDE

231 MULTI Editor Configuration Options C chars aligned like * in comments Allows characters other than an asterisk (*) to line up in comments as if they were asterisks. The equivalent command for this setting is: AiCharsLikeStarInComment char_string [default is - (dash)] The default setting allows correct automatic indentation of comments which have a column of - (dashes) down the left side, lined up under the * in the /* sequence. To have characters other than an asterisk (*) line up in comments as if they were asterisks, make them part of the char_string. C paren indent mode Controls how the Editor indents a line in a source file if it starts within an open parenthesis/close parenthesis pair. Permitted settings for this option are: Even with parentheses (AiParenIndentMode EvenWithParen) If there is a non-whitespace character between the open parenthesis and the end of its line, the lines enclosed in parentheses start at the same column as that character. Otherwise, the lines enclosed in parentheses start in the column just after the open parenthesis. For example: void foo (void) { bar( argument_one, argument_two ); } Indent in two (AiParenIndentMode IndentInTwo) [default] Lines enclosed in parentheses start two indent levels in from the line that contains the open parenthesis. For example: void foo (void) { bar( argument_one, argument_two ); } Green Hills Software, Inc. 219

232 9. Configuration Options Ada paren mode Controls how the Editor indents a line in an Ada source file if it starts within an open parenthesis/close parenthesis pair. Permitted settings for this option are: Even with parentheses (AiAdaParenIndentMode EvenWithParen) [default] If there is a non-whitespace character between the open parenthesis and the end of its line, the lines enclosed in parentheses start at the same column as that character. Otherwise, the lines enclosed in parentheses start in the column just after the open parenthesis. Indent inttwo (AiAdaParenIndentMode IndentInTwo) The lines enclosed in parentheses start two indent levels in from line that contains the open parenthesis. More Editor Options Dialog Box To open this dialog box, click More Editor Options on the Multi Editor tab of the Options window. Print 2 columns in landscape Windows only Permitted settings for this option are: Selected (EditPrint2Column On) The Editor prints files in landscape mode with two pages per sheet. Cleared (EditPrint2Column Off) [default] The Editor prints one page per sheet in portrait mode. Temp file directory Specifies the directory where MULTI stores its temporary files. The equivalent command for this setting is: TempFileDir dirpath The default is blank, which has the following results: (Windows) Uses the values of the TMP or TEMP environment variables and defaults to the current directory if those variables are not set. (UNIX) Uses the values of the TMPDIR or TEMP environment variables and defaults to /tmp if those variables are not set. Initial width in characters Specifies the initial width of Editor windows in characters. The equivalent command for this setting is: EditWidth width [default is 80] This option is only useful when Save window positions and sizes is set to Cleared (rememberwindowpositions off) (see General Options Tab on page 179). 220 MULTI: Editing Files and Configuring the IDE

233 MULTI Editor Configuration Options Initial height in characters Specifies the initial height of Editor windows in characters. The equivalent command for this setting is: EditHeight height [default is 32] This option is only useful when Save window positions and sizes is set to Cleared (rememberwindowpositions off) (see General Options Tab on page 179). Selection margin width in pixels Specifies the width of the left margin in the Editor in pixels. The equivalent command for this setting is: SelectionMarginWidth num [default is 13] Ifthewidthis0, the left margin does not appear and entire lines of text can no longer be selected by using the margin. Changing the selection margin width affects only new Editor windows. Generate auto-recover file every... seconds Specifies the number of seconds between generation of auto-recover files. The equivalent command for this setting is: EditIncrFrequency num [default is 120] The Editor will create an auto-recover file every num seconds as you edit. If the power goes out or the Editor crashes, the next time you open the same file, you will be given the option to re-apply the edits saved in the auto-recover file. Per File Settings Defaults The settings in this section are used when a file is first opened. Changes to the default settings will automatically be applied to all files open in the Editor. To change the settings for an individual file without affecting other open files, choose View Per File Settings in the Editor. Spaces per indent for Ada Specifies the number of spaces in an indentation for Ada files. The equivalent command for this setting is: AdaIndentSize num [default is 3]. Ada continuation line indent Specifies the number of spaces in an indentation for a continuation line in Ada files. The equivalent command for this setting is: AdaContinuationSize num [default is 2]. Word wrap Permitted settings for this option are: Selected (WordWrap On) If lines are longer than the wrapping width, the Editor will automatically split lines on word boundaries as you type. Cleared (WordWrap Off) [default] Lines will not wrap. Green Hills Software, Inc. 221

234 9. Configuration Options Wrap column The equivalent command for this setting is: WrapColumn width [default is 79] When Word wrap is selected (WordWrap On), width specifies the last column a character will appear before wrapping to the next line. If a line is a single word and cannot fit within width columns, it will be put on a line by itself. Wrap indent offset The equivalent command for this setting is: WrapIndent num [default is 2] When a word wraps to the next line, the word is automatically indented num extra spaces from where it would normally appear. Fill Paragraph Column Specifies the column at which each line will be wrapped when using Ctrl + Shift + A to reformat comments. The equivalent command for this setting is: fillparagraphcolumn num [default is 80]. Other MULTI Editor Options The options in this section are not accessible from the Options dialog box. These options can be set in a configuration file or by using the configure command in the Debugger command pane. autograbheadfiles [On Off] Controls whether the MULTI Editor automatically grabs function prototypes from a source s file s include files when the source file is loaded. On [default] The MULTI Editor will automatically grab function prototypes when opening source files. In some cases, the answer service may not provide the Editor with the header file list. However, if the header file paths in the source file are relative to the source file s directory, the MULTI Editor will be able to obtain some of the information on its own. Off The MULTI Editor will not grab function prototypes when opening source files. ClearEditButtons Removes all Editor buttons so they can be created from scratch with editbutton. 222 MULTI: Editing Files and Configuring the IDE

235 MULTI Editor Configuration Options editbutton Creates a new Editor button. For information about this command, see Configuring and Customizing Toolbar Buttons on page 160. The usage of this command is: editbutton name commands iconname ignored_placeholderhelpstring tooltip The arguments name, commands, iconname, helpstring, and tooltip are either single words or a quoted strings. Quoted strings are of the form: "This is a quoted string." "These are quotes \" \" within a quoted string." The argument name gives the name of the button. If Use icons for buttons is Cleared(iconifiedButtons Off), this is the name on the button. If no tooltip string is provided, name also becomes the tooltip. The argument commands indicates the commands that should be executed when the button is pressed. The argument iconname gives the name of icon to use for the button if Use icons for buttons is Selected(iconifiedbuttons On): For a list of allowable icons, click Configure Editor Buttons from the MULTI Editor tab of the Options window. Alternatively, you can specify the full path to your own 16-color bitmap file as the icon. If no icon is specified, the help icon (question mark) is used. The argument ignored_placeholder is ignored and not used by this command. However, it serves as a placeholder, so it must remain in the command. The argument helpstring specifies the text that appears in the status bar when the mouse moves over the button. The argument tooltip specifies the text that appears in the small pop-up box when the mouse hovers over the button for a short time. EditParenMatch time [default is 10] Every time you type a right parenthesis, right square bracket, or right curly brace, the Editor briefly selects the matching one. The Editor will pause on this highlight of the previous match for time tenths of a second. A value of 0 (zero) will disable matching. Green Hills Software, Inc. 223

236 9. Configuration Options Session Configuration Options This section describes configuration options that allow you to control what information from the current session MULTI remembers for use in future sessions. The following options are available on the Session tab of the Options window. Save command history between sessions Permitted settings for this option are: Selected (SaveCommandHistory On) [default] The command history for each executable will be saved. If the executable has not been debugged before, it will have no previous command history. Cleared (SaveCommandHistory Off) The command history will not be saved. Save data explorers between sessions Permitted settings for this option are: Selected (SaveViewWindows On) Saves data explorers between MULTI sessions on the same executable. This will save position and size as well as the variable which the data explorer was viewing. Cleared (SaveViewWindows Off) [default] Data explorers will not be saved. Save arguments between sessions Permitted settings for this option are: Selected (SaveRunArguments On) [default] Saves the last arguments supplied to run the target process between MULTI sessions on the same executable. To run the executable with no arguments use the R command. Cleared (SaveRunArguments Off) Arguments are not saved. Save debugger window position Permitted settings for this option are: Selected (SaveDebuggerWindowPos On) Saves and restores the size and position of the MULTI Debugger window on a per executable basis. Note that the Debugger window is only sized and positioned on window creation, so debugging a different executable from an already opened MULTI will not have any effect. Cleared (SaveDebuggerWindowPos Off) [default] Debugger window position will not be saved. 224 MULTI: Editing Files and Configuring the IDE

237 Session Configuration Options Remember breakpoints Determines if the Debugger remembers breakpoints that you have set for a program the next time you debug the same program and whether shared object breakpoints are saved between sessions. Permitted settings for this option are: Never (RememberBreakpoints Never) Debugger will clear all breakpoints whenever you load or reload a program. Across Reloads (RememberBreakpoints WithinSession) [default] The Debugger will remember breakpoints that you have set when you reload the program within a single session. Breakpoints are lost when you exit MULTI. Across Sessions (RememberBreakpoints AcrossSessions) The Debugger will remember breakpoints for a program even if you exit and restart MULTI. Note that shared object breakpoints are only saved and restored in Across Sessions (RememberBreakpoints AcrossSessions) mode. For more information about shared object breakpoints, see Chapter 5, Executing and Controlling Your Program from the Debugger in the MULTI: Debugging book. Restored breakpoints overwrite breakpoints set by scripts Permitted settings for this option are: Selected (OverwriteScriptBreakpoints On) Previously saved breakpoints will overwrite breakpoints that have been created by a script run automatically for the current executable. Cleared (OverwriteScriptBreakpoints Off) [default] Previously saved breakpoints will not overwrite breakpoints that have been created by a script run automatically for the current executable. Remember last connect command used for process Permitted settings for this option are: Selected (SaveDebugServer On) [default] Saves the most recently used Connection Method on a per-executable basis. If the executable is started and MULTI is not connected, the saved Connection Method will be used as the default in the Connection Chooser dialog box. Cleared (SaveDebugServer Off) The last Connection Method is not saved. Automatically save changed connection files Permitted settings for this option are: Selected (autosaveconnectionsinfiles On) [default] MULTI saves any outstanding changes to all Target Connection files loaded in the Connection Organizer when you exit. Cleared (autosaveconnectionsinfiles Off) Changes to Target Connection files will not be automatically saved. Green Hills Software, Inc. 225

238 9. Configuration Options Automatically save User Methods changes Permitted settings for this option are: Selected (autosaveuserconnections On) [default] MULTI saves any outstanding changes to the User Methods Target Connection file when you exit. Cleared (autosaveuserconnections Off) All changes to the User Methods Target Connection file will be lost, even if Automatically save changed connection files is Selected (autosaveconnectionsinfiles On). Directory Memory Determine which directory to initially display in the File Chooser. Permitted settings for this option are: Across Sessions (RememberDirs RememberAcross) File Chooser will always open in the previously viewed directory for the same operation, even after closing and restarting MULTI. The user directories will only be used on the very first run of MULTI, or if a user settings file cannot be found. Within Sessions (RememberDirs RememberWithin) [default] File Chooser will open in the appropriate previously viewed directory, but it will not remember directories viewed in previous sessions. File Chooser will use the User directories initially each time MULTI is restarted. None (RememberDirs RememberNever) File Chooser will always open with the appropriate User directory, and never remember which directory was previously viewed. 226 MULTI: Editing Files and Configuring the IDE

239 Session Configuration Options User Directories Opens the User Directories dialog box, which sets the directories the File Chooser starts with if directory memory is not available or is turned Off. To change any of the settings in this dialog box, select the check box, then enter the full path of the directory. General Files: Selected (GenFileSet true) Opens the General Files Directory field, where you can enter the path. Cleared (GenFileSet false) [default] The current working directoryis used. General Files Directory (GenFilesDir pathname) [default is current working directory] Use this field to enter the directory path for general files. Source Files: Selected (SourceFileSet true) Opens the Source Files Directory field, where you can enter the path. Cleared (SourceFileSet false) [default] The current working directory is used. Source Files Directory (SourceFilesDir pathname) [default is current working directory] Use this field to enter the directory path for source files. Build Files: Selected (BuildFileSet true) Opens the Build Files Directory field, where you can enter the path. Cleared (BuildFileSet false) [default] The current working directory is used. Build Files Directory (BuildFilesDir pathname) [default is current working directory] Use this field to enter the directory path for build files. Executables/Binaries: Selected (ExecFileSet true) Opens the Executables/Binaries Directory field, where you can enter the path. Cleared (ExecFileSet false) [default] The current working directory is used. Executables/Binaries Directory (ExecFilesDir pathname) [default is current working directory] Use this field to enter the directory path for executables. Debug Servers: Selected (DebugServerSet true) Opens the Debug Servers Directory field, where you can enter the path. Cleared (DebugServerSet false) [default] The current working directory is used. Debug Servers (DebugServersDir pathname) [default is current working directory] Use this field to enter the directory path for debug servers. Green Hills Software, Inc. 227

240 9. Configuration Options Show version control information on file chooser dialog box UNIX only Permitted settings for this option are: Selected (ShowVersionControl true) If a user has the file checked out, the File Chooser dialog box will display the name of that user next to the filename in a column titled Version Control. Cleared (ShowVersionControl false) The Version Control column will be hidden and the version control system will not be queried. Warning: Selecting this option causes MULTI to query the version control system for each file. On some version control systems, turning on this option might slow down File Chooser performance significantly. Colors Configuration Options This section describes configuration options that you can use to change the display colors for MULTI. The following options are available on the Colors tab of the Options window. To edit colors, double-click the colored box next to any option to open the Color Chooser. For more information, see Color Chooser on page 232. (UNIX) Color options are expressed in RGB hexadecimal format as a number sign (#) followed by the six-digit hexadecimal value. For example, #FF0000 specifies the color bright red. (Windows) Color options are expressed in RGB format as three decimal values. For example, specifies the color bright red. In the tables that follow, the default RGB values provided are in hexadecimal, but decimal values will appear on the Colors tab for Windows users. Load Color Scheme UNIX only Opens the Color Scheme dialog box, which you can use to select from a list of predefined color schemes. If you prefer a different appearance from the default color scheme, you can try these to find the one that is closest to what you want. 228 MULTI: Editing Files and Configuring the IDE

241 Colors Configuration Options Two color mode UNIX only Permitted settings for this option are: Selected (BlackWhite On) MULTI uses only the foreground and background color for its drawing (except in icons). This increases drawing speed in low graphics bandwidth situations. Cleared (BlackWhite Off) [default] MULTI uses multiple colors according to the color scheme selected. Global Colors UNIX only Global colors can only be set on UNIX systems. They affect the default colors for user interface elements. The following global color options may be set: Background (Background color) [default is #FFFFFF] Background color of user areas, such as the color behind the text you enter. Foreground (Foreground color) [default is #000000] Color of text. Control Area (ControlColor color) [default is #C0C0C0] Background color of control areas, such as menu bars and buttons. Selection (Select color) [default is #000080] Background color of text selections. The foreground color of selections is based on the foreground setting and is chosen automatically. Green Hills Software, Inc. 229

242 9. Configuration Options Debugger Colors Controls how certain elements are displayed in the Debugger. The colors you can customize are: Assembly (Assembly color) [default is #0000FF] Color of interlaced assembly code. Break Dot (BDotColor color) [default is #00CD00] Color of break dots, which indicate locations where breakpoints may be set. Status (BreakColor color) [default is #FF0000] Color of the program status and debug server messages ( STOPPED, RUNNING, etc.). Context Arrow (PointerColor color) [default is #0000FF] Color of the context arrow, which indicates what context to use for commands in the Debugger. File line numbers Selected (UsefileRelLineBG true) [default ] Enables file relative line numbers. Cleared (UsefileRelLineBG false) Disables file relative line numbers. Color Field (filerellinebg color [default is #FFFFFF] Color of the background behind the column of file relative line numbers in the source pane. Procedure line numbers Selected (UseprocRelLineBG true) [default ] Enables procedure relative line numbers. Cleared (UseprocRelLineBG false) Disables procedure relative line numbers. procrellinebg color [default is #e4e4e4] Color of the background behind the column of procedure relative line numbers in the source pane. Syntax Coloring Permitted settings for this option are: Selected (ColorSyntax On) [default] Source code will be syntax colored. based upon the Syntax Color Settings listed below. Cleared (ColorSyntax Off) Source code will not be syntax colored. 230 MULTI: Editing Files and Configuring the IDE

243 Colors Configuration Options Syntax Color Settings Colors may be set for the following items: Comments (Comment color) [default is #008000] Keywords (Keyword color) [default is #0000FF] Dead Code (DeadCode color) [default is #808080] Color of code enclosed in an #if 0... #endif block. Numbers (Number color) [default is #E000E0] Strings (String color) [default is #800000] Characters (Character color) [default is #C000C0] Customized (Customized color) [default is #008080] Color C++ comments in C Permitted settings for this option are: Selected (CppCommentsInC On) [default] C++ style comments (//) will be syntax colored as comments in both C++ and C source files. Cleared (CppCommentsInC Off) C++ style comments will not be syntax colored as comments in C source files. More Color Options Opens the More Color Options dialog box which contains additional colors which can be configured. Green Hills Software, Inc. 231

244 9. Configuration Options More Color Options Dialog Box To open this dialog box, click More Color Options Colors tab of the Options window. Legacy Builder Colors Colors may be set for the following Builder items: NoBuild (NoBuild color) [default is #B00000] Program (Program color) [default is #900010] SubProject (SubProgram color) [default is #C80020] Source (Source color) [default is #00B010] Header (Header color) [default is #007010] Documentation (Documentation color) [default is #A0A0A0] Library Build (SingleLibrary color) [default is #000080] Object (Object color) [default is #000050] Library (Library color) [default is #004580] Script (Script color) [default is #808000] Other (Other color) [default is #808080] Connected targets Foreground color of the Connected targets list. The equivalent command for this setting is: startedconnectionfg color [default is #008000] Diffview Colors Background color of the current selection in the Diff ViewerForeground The equivalent command for this setting is: diffhighlight color [default is #e0ffd0] Color Chooser The Color Chooser is used to select and customize colors for any of MULTI s color options. To open the Color Chooser, double click any of the color boxes in the Colors tab of the Options window. (Windows) The standard color chooser is used. For more information, see your Windows documentation. 232 MULTI: Editing Files and Configuring the IDE

245 Deprecated Configuration Options (Unix) The Color Chooser consists of a rectangle indicating the current color, three sliders to control the levels of red, green, and blue in the current color, and a number of preset basic colors: 1. To select one of the basic colors, click one of the colored boxes; or to create a color that is not available in the basic colors, use the color sliders or the text fields beneath them to form the color you want. 2. When you have found the color you want, click OK to replace the color; or if you do not want to use the new color, click Cancel to discard the change and close the Color Chooser. Deprecated Configuration Options The following configuration options are deprecated: BuilderPosition x_offsetxy_offset [p] [default is 0x0] Indicates the initial position of the Builder window from the upper left corner of the screen in x_offset characters and y_offset lines. To specify these offsets in pixels, append the letter p (such as 10x20p). This option is only useful when the Save window positions and sizes is Cleared(RememberWindowPositions Off ). For more information, see Save window positions and sizes in General Options Tab on page 179. DontUseVC On Off [default is Off] SettoOn disable version control, and On to enable version control. This option has been superseded by the VersionControlChoice option. lowbandwidthtovc [true false] Used in the legacy Builder. true The Builder will not request the checkout status from the version control system for each file. false The Builder will request checkout status for each file. MinWindowSize widthxheight [p] [default is 51x6] Specifies the minimum initial size of a non-view window, such as an I/O, Target, or Monitor window, in width characters and height lines. To specify these sizes in pixels, append the letter p to the value. If left unspecified, the Debugger will auto-size windows appropriately. This option is only useful when the Save window positions and sizes is Cleared(RememberWindowPositions Off ). For more information, see Save window positions and sizes in General Options Tab on page 179. Green Hills Software, Inc. 233

246 9. Configuration Options MaxWindowSize widthxheight [p] [default is 128x20] Specifies the maximum initial size of a non-view window in width characters and height lines. To specify these sizes in pixels, append the letter p to the value. This option is only useful when the Save window positions and sizes is Cleared(RememberWindowPositions Off ). For more information, see Save window positions and sizes in General Options Tab on page MULTI: Editing Files and Configuring the IDE

247 Part IV License Administration

248

249 Chapter 10 Licensing Overview This Chapter Contains: License Types Licensing Procedures Using a Dongle

250 10. Licensing Overview Green Hills products require software licenses to run, and use software to manage the licenses. The software available for administering Green Hills licenses includes: Green Hills License Manager (GHSlm) for more information see Chapter 13, GHSlm: Green Hills License Manager. Elan License Manager (ElanLM) for more information, see Chapter 14, ElanLM: Legacy License Manager. We recommend that you use GHSlm, but current tools also support ElanLM for compatibility with legacy installations. If you are a first time user, or have obtained new licenses for MULTI 4.0, you should use GHSlm. If you are an existing user with licenses for MULTI 3.x or earlier, and have ElanLM installed, you can continue to use these licenses and ElanLM. Regardless of the software used, in MULTI 4.0 most license administration tasks are performed with the MULTI License Administrator interface. MULTI License Administrator is described in detail in Chapter 11, License Administration with the MULTI License Administrator. License Types To maximize flexibility, the Green Hills tools support several different licensing models. They are: Computer-locked licenses This model is only supported on Windows hosts. The license allows an unlimited number of specific MULTI components to run on one particular PC. The license is locked to a specific Windows PC and cannot be moved. Dongle-locked licenses This model is only supported on Windows hosts. This type of license requires a dongle, which is a hardware security device that is attached to the PC via the USB or parallel port. The license allows an unlimited number of specific MULTI components to run on a Windows PC where a particular dongle is installed. For more information, see Using a Dongle on page 245. Floating licenses Licenses are managed by a license server, which allows some number of users to run MULTI components at the same time. The number of users allowed is determined by the number of seats that have 238 MULTI: Editing Files and Configuring the IDE

251 License Types been purchased. A single user may consume more than one license if they have more than one copy of MULTI running. Named-user licenses The licenses are managed by a Green Hills License Manager Device, which allows a number of distinct users to run MULTI components at the same time. The number of users allowed is determined by the number of seats that have been purchased. A single user will only consume a single license, even if they have more than one copy of MULTI running. This model is only supported with the Green Hills License Manager Device. Computer-locked and dongle-locked licenses are not installed on the network. They only work on Windows PCs, and use separate licenses for each machine or dongle. Floating licenses and named-user licenses are installed on a network and use a license server to keep track of the licenses. In the case of floating licenses, the server can be an application that runs on a workstation or server, or a standalone Green Hills License Manager Device on the network. Green Hills License Manager Device The Green Hills License Manager Device is a standalone device that connects to the network and provides access to floating or named-user licenses. It supports DHCP, and is very easy to install and maintain. For information about installation and configuration of a Green Hills License Manager Device, see Chapter 12, Green Hills License Manager Device. Normally, License Manager Devices are shipped with licenses preinstalled, so they are ready for immediate use. Additional licenses can be added later using MULTI License Administrator (see Chapter 11, License Administration with the MULTI License Administrator ). Because of the security and stability afforded by the Green Hills License Manager Device, it offers features not available with other host-based license servers: Redundant servers You can install several devices and configure them as a license server cluster to provide load balancing and fail-safe operation. Clients can communicate with any member of the cluster without losing functionality, and the loss of any member will not interrupt the cluster s ability to serve licenses. The cluster will only cease to function Green Hills Software, Inc. 239

252 10. Licensing Overview if the majority of servers become unavailable. For more information, see Redundant License Manager Devices on page 285. Leased licenses (or commuter licenses) Users can check out a license from the license manager and have this license converted into a temporary commuter license for their laptop. Commuter licenses allow licensed users to take full advantage of the software without purchasing separate licenses for this purpose. This can be useful for demonstrations, on-site visits, and other situations where the user is working remotely and a direct connection to the corporate intranet is not available. For more information, see Obtain Commuter Nodelock Lease on page 277. License caching The client-side tools can cache their licenses on the client, to improve responsiveness and decrease network load. Web-based administration The License Manager Device includes a web server. You can use the License Manager s web interface to obtain up-to-date information about the device s status, including the number of licenses installed, licenses in use, and licenses available. You can also use the web interface to configure the device, including changing the list of named users, setting up address filters, and setting logging options. For more information, see License Manager Device Web Interface on page 267. Because it is based on proprietary hardware, the License Manager Device does not support the use of ElanLM software and can only be used with clients that support GHSlm licensing software. Licensing Procedures Before you can use the Green Hills tools, you need to have appropriate software licenses installed and available. When you start MULTI, it checks for a valid license. If it cannot obtain a license, MULTI License Administrator automatically starts with a special dialog box that lists the license managers detected and asks whether you would like to configure MULTI to use these servers. If you run the other tools when no licenses are available, they will fail with an error message. Most of these problems can be resolved using MULTI License Administrator (see Chapter 11, License Administration with the MULTI License Administrator ). 240 MULTI: Editing Files and Configuring the IDE

253 Licensing Procedures In general, the following procedures must be completed before you can use the Green Hills products: Install Software Request License Install License These steps are not necessary if you are using existing licenses. 1. Installing Software Software installation is covered in MULTI: Getting Started. 2. Requesting Licenses License requests are performed with the MULTI Licensing Wizard, which is accessed through the MULTI License Administrator window. Please see Chapter 11, License Administration with the MULTI License Administrator for more information. 3. Installing Licenses Licenses are installed with the MULTI Licensing Wizard. Please see Chapter 11, License Administration with the MULTI License Administrator for more information. Note Because license manager devices are often shipped with licenses preinstalled, you usually do not need to request or install licenses. License installation is performed by installing the device as described in Chapter 12, Green Hills License Manager Device. Important Considerations for License Servers The following should be taken into consideration when selecting a machine to host the license server: The license server operates only if a valid license has been installed. License servers using the ElanLM software can provide licenses to any client application that supports ElanLM. License servers running the GHSlm software License Manager Devices can provide licenses to any client that supports GHSlm. In a Windows environment, the GHSlm license server can only be run on machines with an NT based operating systems installed (such as Windows NT, 2000, and XP). Use of Windows 9x/ME machines as GHSlm license Green Hills Software, Inc. 241

254 10. Licensing Overview servers is not supported, however GHSlm can be used on Windows 9x/ME clients. License servers using a particular software technology (such as ElanLM) cannot provide licenses to clients that do not support that software. For example, Green Hills tools running on Linux cannot use licenses installed on an ElanLM license server. Floating licenses can only be installed on the host computer or device for which the license was granted. Do not install floating licenses on the client machines. For host-based floating licenses, you must install the license server software on an easily accessible network host machine that is up and running when developers need licenses. The architecture of floating licenses requires that TCP/IP is installed and configured correctly on both the server machine and all the client machines. In a Windows environment, avoid using dial-up networking on the license server s host computer. Doing so causes Windows to change its default IP address. The license server will detect this address change and may stop granting license requests for security reasons. License Server Compatibility The following table describes the license management software supported by recent versions of the Green Hills tools: Host MULTI Release Licensing Software Windows (NT/2000/XP) Solaris HP-UX MULTI 4.x GHSlm (see Chapter 13, GHSlm: Green Hills License Manager ) or ElanLM (see Chapter 14, ElanLM: Legacy License Manager ) MULTI1.89toMULTI3.x ElanLM (see Chapter 14, ElanLM: Legacy License Manager ) 242 MULTI: Editing Files and Configuring the IDE

255 Licensing Procedures Host MULTI Release Licensing Software Windows (98/ME) MULTI 1.89 to MULTI 4.x ElanLM (see Chapter 14, ElanLM: Legacy License Manager ) GHSlm can only be used with MULTI 4.0 and only for client-side support. Linux MULTI 3.x and higher GHSlm (see Chapter 13, GHSlm: Green Hills License Manager ) Server Codes Licenses are locked to a server code, which defines where the licenses can be installed. When requesting licenses, it is important that you provide the correct server code from the correct machine. The following table provides tips for using the correct code when requesting licenses from Green Hills Software: Computer-locked Open MULTI License Administrator on the machine where the products will be run. The Server Code is displayed at the top of the main window. Dongle-locked Open MULTI License Administrator on the machine where the dongle is currently installed. The Server Code is displayed at the top of the main window. You can verify that the dongle is detected by comparing the server code to the same machine s server code when the dongle is not installed. If those codes match, see Troubleshooting Dongle Problems on page 246. Named-user Use the server code for the license manager device that will act as the license server for the licenses. Open MULTI License Administrator, locate the device in the list of license managers, then double-click the device entry to open the Configure dialog box. The server code appears in the LM Server Code field (see Configure Dialog Box on page 259) Green Hills Software, Inc. 243

256 10. Licensing Overview Floating (with license manager device) Use the server code for the license manager device that will act as the license server for the licenses. Open MULTI License Administrator, locate the device in the list of license managers, then double-click the device entry to open the Configure dialog box. The server code appears in the LM Server Code field (see Configure Dialog Box on page 259). Floating (host-based license server) Open MULTI License Administrator on the machine that will act as the license server (see Important Considerations for License Servers on page 241). The Server Code is displayed at the top of the main window. Depending on your licensing platform and software, there may be additional steps. Please refer to the appropriate chapter for detailed instructions on installing and using your specific type of license. Green Hills License Manager (GHSlm) See Chapter 13, GHSlm: Green Hills License Manager. Elan License Manager (ElanLM) See Chapter 14, ElanLM: Legacy License Manager. Green Hills License Manager Device See Chapter 12, Green Hills License Manager Device. 244 MULTI: Editing Files and Configuring the IDE

257 Using a Dongle Using a Dongle A dongle is a hardware security device that is attached to the PC via the USB or parallel port to verify to the software that the computer is properly licensed. Dongle-locked licenses allow an unlimited number of specific MULTI components to run on a Windows PC where a particular dongle is installed. Use of dongles is only supported on Windows hosts. There are two types of dongles currently used with Green Hills Software products: dongles that connect to the parallel port, and those that connect to ausbport. Dongle Installation Use the following instructions to install a dongle: 1. In order to use dongle-locked licenses, you must install the dongle-driver software. To install dongle-driver software: a. Insert the Green Hills CD. If the multimedia screen appears, close it. b. Use Windows Explorer to explore the CD drive. c. Open the licensing folder. d. Open the dongle_drivers folder. Or, if you use ElanLM legacy license manager software, you can select the legacy folder and install dongle-drivers while you install the software (see Chapter 14, ElanLM: Legacy License Manager for more information). e. Double-click setup.exe to launch the dongle-driver installation Wizard. 2. After installing the software, insert the dongle into the parallel or USB port. 3. Open MULTI License Administrator. Use the items in the License menu to request and install licenses as needed. Green Hills Software, Inc. 245

258 10. Licensing Overview Troubleshooting Dongle Problems Most dongle problems are due to the following issues: Dongle drivers are outdated or not installed correctly You can use the Sentinel Medic program from Rainbow Technologies to diagnose the types of problems. Rainbow Technologies is the manufacturer of the dongles and dongle drivers used by Green Hills products. We recommend downloading the latest version of the drivers and the Sentinel Medic application from the Rainbow Technologies ( web site. There is more than one dongle installed Green Hills tools only recognize one dongle at a time. Dongles from other vendors are not visible to our tools, so they should not pose a problem. There is a conflict with some other device Some devices, such as printers from certain manufacturers, will attempt to take over the parallel port and exclude other devices from using it. This can cause Green Hills tools to fail to recognize an attached dongle. You may be able to use a dongle that uses a different port. Please contact Green Hills technical support for assistance. There are incompatibilities with other devices or certain hardware Rainbow Technologies maintains a web site with lists of known incompatibilities, accessible from their main corporate web site ( Other Dongle Problems Rainbow Technologies maintains dongle troubleshooting information on their web site ( If you have further questions, please contact Green Hills technical support. 246 MULTI: Editing Files and Configuring the IDE

259 License Administration with the MULTI License Administrator Chapter 11 This Chapter Contains: Opening the MULTI License Administrator Install or Configure License Server Requesting Licenses The MULTI License Administrator Window Configure Dialog Box Environment Variables

260 11. License Administration with the MULTI License Administrator The MULTI License Administrator is a graphical interface used to perform license administration tasks, and configure license manager servers and devices. When you first start MULTI, it checks for a valid MULTI license. If it cannot obtain a license, the MULTI License Administrator starts with a special dialog box that lists the license servers detected on the network, and asks whether you would like to configure MULTI to use these servers. If no license servers are detected, the MULTI Licensing Wizard will automatically open (see The MULTI Licensing Wizard on page 248). You can use this Wizard to install or configure a license server, or to diagnose license problems. Opening the MULTI License Administrator The License Manager Administration interface can be opened from the MULTI Launcher. To open the MULTI License Administrator from the Launcher, select Utilities License Administrator. The MULTI License Administrator is a standalone program that can also be launched from a command line: For UNIX, the executable is mlmadmin. For Windows, the executable is mlmadmin.exe. The MULTI Licensing Wizard When the MULTI License Administrator is initially launched, it opens with the MULTI Licensing Wizard. This Wizard provides assistance in performing tasks such as requesting and installing licenses, configuring license servers, and license administration. 248 MULTI: Editing Files and Configuring the IDE

261 Opening the MULTI License Administrator The items available in the MULTI Licensing Wizard are: Request a license from Green Hills Select this item to request a license by , fax, mail, or online. For more information, see Requesting Licenses on page 252. Install a license which I already have For more information, see Install License File in License Menu on page 255. Install or configure license server software on this machine Formore information, see Install or Configure License Server on page 250. Check for new licenses For more information, see Configuration Tools Menu on page 260. Obtain a commuter lease license from a local license server For more information, see Obtain Commuter Nodelock Lease on page 277 in Chapter 12, Green Hills License Manager Device. Perform license administration tasks Select this item to open the main MULTI License Administrator window. For more information, see The MULTI License Administrator Window on page 253 Verify license configuration Select this item to verify that the computer is properly configured to use a particular license type. Green Hills Software, Inc. 249

262 11. License Administration with the MULTI License Administrator Note By selecting the Take me straight to the administration panel when launching this utility box, you can skip this Wizard when you open the MULTI License Administrator in the future. If you need to access this Wizard again, you can open it from the MULTI License Administrator by selecting File Licensing Wizard. If you have installation or configuration problems that cannot be resolved through the Wizard, click the Generate Support Request button to open a window that will automatically be populated with diagnostic information. You can cut and paste this information into an and sent it to Green Hills Technical Support (support@ghs.com). Install or Configure License Server Once you start the MULTI License Administrator, you can install or configure license server software. Note This information does not apply to License Manager Devices. For information about installation and configuration of devices, see Chapter 12, Green Hills License Manager Device. 1. The MULTI License Administrator should open with Welcome screen of the MULTI Licensing Wizard. IftheMULTI License Administrator opens without the Wizard, select File Licensing Wizard. 2. On the Welcome screen, select Install or Configure license server software on this machine. 3. Select one of the following licensing options: Install a Green Hills license server on this machine Installs GHSlm server software on the machine. Configure the Green Hills license server on this machine Opens the Server Settings dialog box, which you can use to configure the GHSlm license server. See Server Settings Dialog Box on page 251 for more information. Install a Legacy License Server (Elan) on this machine Installs ElanLM Legacy license servers software on the machine. Although ElanLM options are available to support Legacy installations, it is not recommended. GHSlm should be used for all new installations. 250 MULTI: Editing Files and Configuring the IDE

263 Install or Configure License Server Configure the Legacy License Server (Elan) on this machine On Windows, this selection will open the ElanLM Control Panel (see ElanLM License Server Startup for Windows on page 301). On UNIX, this will display text that provides instructions about configuring the server. Note Configuration settings will not be applied if the Services applet is open in the Windows Control Panel. Server Settings Dialog Box The Server Settings dialog box opens when you select Configure the Green Hills license server on this machine from the MULTI Licensing Wizard or License Configure Server on Local Machine in the MULTI License Administrator. This dialog box is used to configure the GHSlm license server and contains the following fields. Log File Enter the absolute path to the file where logging information should be stored. TCP Port Enter the TCP port on which the server listens for license requests. The default is IP Addr Filter Enter the 32-bit value indicating an IP address filter which the server will use to deny requests from unauthorized IP addresses. Log Verbosity Enter a number to indicate the verbosity of the logging messages. The value 1 indicates normal messages. Higher numbers can be specified to provide more logging information. Debug Level Enter a number to indicate the verbosity of the debugging messages in the log. The value 0 specifies no messages. Higher numbers can be specified to provide more debugging information. Green Hills Software, Inc. 251

264 11. License Administration with the MULTI License Administrator Start/Stop Windows only Click to start or stop the license server. Start/Stop does not function correctly if the Windows Cotnrol Panel Services applet is open. Requesting Licenses License requests can be made through the MULTI Licensing Wizard, orusing the Licensing menu in the MULTI License Administrator. 1. If you request licenses through the MULTI Licensing Wizard, you are offered the choice of generating your license request online, or creating a license request that you can , fax or mail to Green Hills Software. 2. If you use the Licensing menu in the MULTI License Administrator, or choose to , fax, or mail your license request from the MULTI Licensing Wizard, alicense Request Generator form will open for you to complete. 3. Once you complete the form you will be given the option to save the license request to a file, the license request to Green Hills Software, or print the license request. Customers in the Americas, Australia, and New Zealand can send license requests by: license@ghs.com Fax: (805) (Attn: Licensing) License requests for Ada/Safety-critical products are handled by the safety-critical team. These requests should be sent by: adalicense@ghs.com Fax: (727) Requests from the rest of the world are handled from our European support center. These requests should be sent by: license@ghs.nl Fax: +31 (0) MULTI: Editing Files and Configuring the IDE

265 The MULTI License Administrator Window 4. License requests will be processed as quickly as possible within business hours. If you have questions, call Green Hills toll free support line 877-GHS-TECH ( ) in the US, or worldwide. The MULTI License Administrator Window The MULTI License Administrator window contains two parts. The top half of the window provides information about the host computer and the bottom half provides information about license managers on the network. There are three types of license managers that may appear in the list: Device License manager devices. For more information, see Chapter 12, Green Hills License Manager Device. Native Host-based license managers. Legacy Legacy license servers (not listed on Linux). For more information, see Chapter 14, ElanLM: Legacy License Manager. The MULTI License Administrator window contains the following fields: Green Hills Software, Inc. 253

266 11. License Administration with the MULTI License Administrator Server Code Displays the server code of the computer or dongle running the MULTI License Administrator. Legacy Server Code Displays the server code of the computer or dongle running the MULTI License Administrator in the style used by Legacy license servers. GHS_LMHOST Displays the value of the GHS_LMHOST environment variable, which determines which license managers are used. GHS_LMPORT Displays the value of the GHS_LMPORT environment variable. This value must be set when the license manager has been configured to use a TCP port other than the default of The TCP port value is used by Green Hills tools to request licenses from a license manager. In order for Green Hills tools to work with a server configured for an alternate TCP port, the GHS_LMPORT environment variable must be set on the client machine to the matching port number. Available License Managers Lists the IP Address, Host Name, Type, and Description (if applicable) for all available license managers detected on the network. If the list is blank, click Refresh. Refresh Click this button to refresh the list of license managers. The license administration program will perform a broadcast to find available license managers on the network. Configure Select a license manager device from the list, then click Configure to display the configuration dialog box (see Configure Dialog Box on page 259). You can only configure license manager devices with this tool. Use Selected LM Click to configure your environment to use the selected license server. Specify Servers Click to open a dialog box which you can use to specify a comma-separated list of servers which the MULTI License Administrator will attempt to contact the next time you click Refresh. This setting is necessary if the server cannot be reached by broadcast. 254 MULTI: Editing Files and Configuring the IDE

267 The MULTI License Administrator Window File Menu The MULTI License Administrator window File menu contains the following options: Licensing Wizard Launches the MULTI Licensing Wizard. For more information, see The MULTI Licensing Wizard on page 248. Close Closes the MULTI License Administrator. License Menu The MULTI License Administrator window contains the License menu, which provides access to the following options: Install License File Select this item to install a new license file on the current computer. The Choose License File dialog box opens. Select a license file, then click Install. Request Evaluation License Connects you to the Green Hills Evaluation License web site, where you can complete an Evaluation License Request online. New evaluation license requests are often fulfilled automatically 24 hours a day. For security reasons, the evaluation license generator attempts to prevent automatic handling of licenses to free or anonymous accounts. If you are requesting an evaluation licenses outside of normal business hours, you should avoid using an address from Yahoo, Hotmail, AOL, or other similar services. Request New License Select this item to open the License Request Generator. Complete the form, then click Send to complete the license request, or save the request to a file and the file as an attachment to Green Hills Licensing (license@ghs.com). For more information, see Requesting Licenses on page 252. Diagnose License Problems Select this item to run a utility to help identify common license problems. The utility will go through the process of obtaining a license, then output verbose information about the internals of the license request attempt. This output will often elucidate the cause of licensing problems. Configure Server on Local Machine Select this item to open the Server Settings dialog box (see Server Settings Dialog Box on page 251). Green Hills Software, Inc. 255

268 11. License Administration with the MULTI License Administrator Legacy Tools Menu The Legacy Tools menu provides access to the following options: Note The Legacy Tools menu is not available on Linux. View Available Licenses Select this menu item to view a list of legacy licenses available from servers in the GHS_LMHOST environment variable. This menu item uses the legacy licstat command line tool. View Licenses In Use View a list of legacy licenses in use from servers in the GHS_LMHOST environment variable. This menu item uses the legacy licstat command line tool. Generate Report Generate a license report from a log file on disk. This menu item uses the legacy wlmrpt command line tool on Windows, or elmrpt on UNIX (see License Manager Reports with WlmRpt on page 307 or License Manager Reports with elmrpt on page 320). 256 MULTI: Editing Files and Configuring the IDE

269 The MULTI License Administrator Window Shortcut Menus When you right-click an Available License Manager entry, a context-sensitive shortcut menu will open. The menu items available will differ depending on the type of license manager. If the selected license manager is a license manager device, the shortcut menu will contain the following items: Open Browser-based Configuration Opens the device s web interface, which gives you browser-based access to configuration settings. For more information, see License Manager Device Web Interface on page 267. This item is the same as selecting Tools Open Browser Configuration in the Configure dialog box (see Configuration Tools Menu on page 260). Check for New License Select this item to contact the Green Hills Software web site and search for an updated license for this device. If one is found, a dialog box will open with the message: A new license is available. Would you like to save the license file, or upload it to the device (this will restart the license manager)? and the following buttons below: Save, Upload, Save and Upload, andcancel. This item is the same as selecting Tools Check for New License in the Configure dialog box (see Configuration Tools Menu on page 260). Generate Report Select this item to generate a report for this device from a log file on disk. Start Logging Select this item to start logging license manager activity. A File Chooser will open. Specify the log file, then click Save. The file you have specified will appear in the Log File field of the Configure dialog box. To change the log file, first Stop Logging, then Start Logging and specify a new log file. This item is the same as selecting Logging Start Logging in the Configure dialog box (see Logging Menu on page 260). Green Hills Software, Inc. 257

270 11. License Administration with the MULTI License Administrator Stop Logging Select this item to stop the license manager activity log. This option is only available when logging is currently enabled (Start Logging has previously been selected). This item is the same as the Logging Stop Logging selection in the Configure dialog box (see Logging Menu on page 260). View Log Select this item to open the license log. This item is the same as selecting Logging View Log in the Configure dialog box (see Logging Menu on page 260). Legacy Shortcut Menu If the selected license manager is a legacy license server, the shortcut menu will contain the following items: View Available Licenses Select this item to view a list of licenses that the selected legacy server can grant. View Licenses In Use Select this item to view a list of licenses that the selected legacy server has granted. 258 MULTI: Editing Files and Configuring the IDE

271 Configure Dialog Box Configure Dialog Box The Configure dialog box displays configuration information about license manager devices. To open the Configure dialog box, select a device in the list click Configure, or double-click the device name. This dialog box is only available for license manager devices. The Configure dialog box displays the following information about the selected device: LM Server Code This hexadecimal number uniquely identifies the license server hardware. If new licenses are installed on the server or device, they are configured to run specifically on only this hardware, as identified by its unique hostid. When requesting new licenses, this hostid must be specified as part of the request. This number is displayed for reference purposes only; it cannot be changed by the user. Host Name The host name of license manager device. IP Address The IP address of the license manager device. Netmask The netmask used by the license manager device. Default Gateway The gateway used by the license manager device. Log File The filename and path of the log file for this device, if one exists. To set or change the log file, select Logging Start Logging (see Logging Menu on page 260). If logging has already been started, you must Stop Logging before you can set a new log file. Green Hills Software, Inc. 259

272 11. License Administration with the MULTI License Administrator Configuration Tools Menu The Configuration dialog box Tools menu contains the following items: Check for New License Select this item to contact the Green Hills Software web site and search for an updated license for this device. If one is found, a dialog box will open with the message: A new license is available. Would you like to save the license file, or upload it to the device (this will restart the license manager)? and the following buttons below: Save, Upload, Save and Upload, and Cancel. Open Browser Configuration Opens the device s web interface, which gives you browser-based access to configuration settings. For more information, see License Manager Device Web Interface on page 267. Change Network Settings Opens a dialog box that you can use to change network settings for the IP Address, Netmask and Default Gateway. When done, click OK. Logging Menu The Configuration dialog box Logging menu contains the following items: Start Logging Select this item to start logging license manager activity. A File Chooser will open. Specify the log file, then click Save. The file you have specified will appear in the Log File field. To change the log file, first Stop Logging, then Start Logging and specify a new log file. Stop Logging Select this item to stop the license manager activity log. This option is only available when logging is currently enabled (Start Logging has previously been selected). View Log Select this item to open the license log. Click Update in the log view window to refresh the log display. 260 MULTI: Editing Files and Configuring the IDE

273 Environment Variables Environment Variables Certain license administration settings can be controlled by way of environment variables. Note To set environment variables on Windows XP/2000/NT: 1. From the desktop, right-click My Computer and select Properties. 2. From the Properties window, click the Advanced tab, then click Environment Variables. 3. The Environment Variables dialog box will open. In System Variables, find the variable you need to modify and click Edit, or click New to set a new variable. For Windows 98/ME, add the environment variable to the AUTOEXEC.BAT file. Separate multiple server names with a comma, a colon, or a semicolon. The following environment variables can be used to control your connection to GHSlm or ElanLM license managers: GHS_LM_CONNECTION_RETRY Specifies the number of times that the client will attempt to connect to the license server before quitting. By default, MULTI will attempt to obtain a license for a few seconds before quitting. See also GHS_LM_CONNECTION_RETRY_TIME, below. GHS_LM_CONNECTION_RETRY_TIME Specifies the period of time to elapse between attempts to connect to the server. The default value is 2. See also GHS_LM_CONNECTION_RETRY, above. GHS_LMDEBUG Specifies the level of debugging information to be generated. This variable can be set to one of the following values: 5 Verbose 11 Maximum Green Hills Software, Inc. 261

274 11. License Administration with the MULTI License Administrator GHS_LMHOST Specifies the names of your license servers and the method by which licenses should be requested. This variable can be set in one of the following ways: Search In Order lm1[,lm2 ] Search Randomly #lm1[,lm2 ] For Windows 2000 clients using ElanLM, the host name or IP address of the license servers must be preceded by symbol. For example, if the license server s name is global_serv, theghs_lmhost environment variable must be set GHS_LMINFO_DIR Specifies a directory in which to create the.lmi file, (to contain debugging output) if GHS_LMDEBUG or GHS_LMSHOW is set. GHS_LMREFRESH Specifies in seconds how frequently the client must reestablish contact with the server to refresh its license. This variable may be set to any integer between 1 and 150. The default setting is 45. GHS_LMSHOW Enables verbose output. GHS_LMWHICH Specifies the type of license that the client will attempt to obtain first. This variable can be set to one of the following values: ghs [default] GHSlm license server. elan The legacy ElanLM license server. GHSlm Environment Variables The following environment variables can only be used to control your connection to the new GHSlm license manager: GHS_LMDELAY Specifies the maximum acceptable time to elapse (in seconds) before receiving a response from a server once a connection has been successfully established. This number should account for the overall transit speed of Ethernet communication on your network. The default is MULTI: Editing Files and Configuring the IDE

275 Environment Variables GHS_LMPORT Specifies the port on which license requests are sent. The default is to use port For this variable to take effect, you must also change the port on your server. In the MULTI License Administrator, you can set this by selecting License Configure Server on Local Machine and specifying a value for TCP Port (see Server Settings Dialog Box on page 251). ElanLM Environment Variables The following environment variables can only be used to control your connection to the ElanLM legacy license manager: Note On UNIX, when a client requests a license, but none are available on the server, the client either returns an error to the user or enters the license server s queue to wait until a license is available. In general, interactive applications (that is, MULTI, debug servers, simulators) do not queue for a license, but non-interactive applications (that is, the compilers) do queue for licenses. The queuing mechanism has several parameters that affect its behavior, most of which can be controlled by using environment variables. GHS_LMQ_GIVEUP Specifies the number of seconds to spend in the queue waiting for a license before reporting that no licenses are available and exiting with an error. The default value is 1200 (20 minutes). If this variable is set to 0, the client will not enter the queue if a license is not granted immediately, the application exits with an error message. A value of -1 instructs the client to continue to wait until a license is available. GHS_LMQ_POLL Determines the base rate (in seconds) of how often the application polls the license server for a license. Use this base rate in conjunction with the GHS_LMQ_METHOD environment variable (described below). If not specified, the default poll base rate is 5 seconds. Green Hills Software, Inc. 263

276 11. License Administration with the MULTI License Administrator GHS_LMQ_METHOD Use in conjunction with GHS_LMQ_POLL to provide control of how frequently the application polls the license server. This automatically prevents the application from wasting resources by continuously polling, which increases network traffic and consumes other related resources. This variable can be set to one of the following values: 0 constant (poll every 5 seconds). 1 [default] double each time (wait for 5 seconds, then wait 10 seconds, then 20, etc.) 2 increases linearly (wait for 5 seconds, then wait 10 seconds, then 15, then 20, etc.) 264 MULTI: Editing Files and Configuring the IDE

277 Chapter 12 Green Hills License Manager Device This Chapter Contains: Connecting the License Manager Device to the Network License Manager Device Web Interface Client Configuration Redundant License Manager Devices

278 12. Green Hills License Manager Device Green Hills license manager software manages the use of Green Hills Software licensed products on the network. License manager software can run natively on a PC or UNIX workstation, or on a Green Hills License Manager Device (LMD). The Green Hills license manager device is a physical device that is connected to the network to serve license requests. The use of a license manager device makes it easier to use Green Hills software. Typically, the device is included as part of the delivery of Green Hills product with licenses preinstalled, so the software can be used as soon as the device is connected to the network. Traditional host-based license servers require installation and configuration of licenses, which costs time in the critical starting point of a project when developers need to get up and running quickly. In addition, if a host computer that is used as a license server is replaced, the license manager software has to be moved to the new computer, and the licenses transferred. A dedicated license manager device, eliminates the need for these license transfers. This chapter provides information that will be useful primarily to system administrators who are administering the Green Hills license manager device. End users may also find some of this information valuable, particularly the status reporting available from the license manager device s web interface. Topics covered include: Configuration of the license manager device Logging of license manager communication License manager status reporting Upgrading the license manager (to take on a new set of licenses, for example) Connecting the License Manager Device to the Network The license manager device must be connected to the network, powered on, and have its network configuration established properly in order for the installed licenses to be usable. The license manager device is factory configured to use DHCP to obtain its IP address and network configuration. If the license manager device is unable to obtain its network configuration from a DHCP server within five seconds of power up, then it uses the following private class C address: MULTI: Editing Files and Configuring the IDE

279 License Manager Device Web Interface The IP address of the license manager device can also be set with MULTI License Administrator, the host-based license administration interface (see Accessing MULTI License Administrator on page 267). Accessing MULTI License Administrator MULTI License Administrator is a standalone program that you can use for administration and configuration of user licenses. MULTI License Administrator can be opened from the Launcher bar by selecting Utilities License Administrator. MULTI License Administrator can also be launched from a command line: UNIX The executable is mlmadmin. Windows The executable is mlmadmin.exe. Since the device is not reachable with a standard TCP/IP connection until the network configuration has been established properly for your network, this program uses network broadcasts (address ) to communicate with the license manager device. License Manager Device Web Interface The license manager device contains a web server that provides a convenient and useful set of web pages for interacting with the license manager. Once the device has been connected to the network and its network configuration has been established, a web browser can be used to access the web interface. The URL to access the web page through a browser is simply the IP address of the device. For example, if the IP address of the device is , use the following browser URL: The web interface is divided into four main sections as seen in the main selection bar: Program see Status Page on page 268. Configure see Configuration Page on page 271. License see License Page on page 277. Green Hills Software, Inc. 267

280 12. Green Hills License Manager Device Help see Help Page on page 282. Status Page The Status page is the default web page that is displayed when the browser connects to the license manager device. This page automatically refreshes every ten seconds. If the license manager is not running, then the page will display: Green Hills License Manager: OFF Otherwise, the heading will be: Green Hills License Manager: ON and a table listing all licensed products will be displayed as shown below: This table contains the following columns (see the pages indicated for more information): Program on page 269. Licenses in Use on page 269. High Water Mark on page 270. Maximum Licenses onpage MULTI: Editing Files and Configuring the IDE

281 License Manager Device Web Interface Program This is the name of the licensed executable, such as multi (MULTI Development Environment) or ecomppc (PowerPC compiler). In some cases, the license corresponds to a feature that does not map to a single executable, for example timemachine. Sometimes, instead of an ASCII name, a number will display in this column with the link (name?) next to it. The number is the product code, and it indicates that the license manager has a license for a program that was created after the license manager device was installed. As a result, the program name is not in the device s name database. To create a product name association for this code, click (name?). Aform will open which you can use to assign an executable name to correspond to the product code. This assignment is not required for normal use of managed licenses, however it is necessary if a commuter nodelock lease will be required for the product (see Obtain Commuter Nodelock Lease on page 277). The name-to-code correspondence entries are stored in volatile memory. If the device is power cycled, the name-to-code correspondence must be reentered. Licenses in Use This is the number of licenses for the corresponding program that are currently checked out or in use. If the value matches the number of Maximum Licenses, no more licenses for the product are available for use. If Licenses in Use is greater than zero, the link (who?) appears next to the displayed value. 1. Click (who?) to display a list of how licenses for this product are being used. 2. A new page will open with an entry for each licensed user of the program. For example, if user dave has a license for MULTI, then dave will be one entry in the list. Leased licenses are also indicated. When redundant license manager devices are in use (see Redundant License Manager Devices on page 285), the number of entries in the list may not match the actual number of licenses in use. This is because when a device grants a license, the remaining redundant devices in the cluster will indicate the license Green Hills Software, Inc. 269

282 12. Green Hills License Manager Device as checked out, but only the device handling the user s request directly will have an entry in its list of Licenses in Use. High Water Mark This field indicates the maximum number of licenses of the program that have ever been checked out simultaneously since the device was powered on. This value is reset each time the device is powered on. This field is useful for determining the maximum usage that a particular program has over time. Most Green Hills products are licensed on a per-user basis, with a license permanently checked out for a user the first time they use a product. As a result, the High Water Mark and Licenses in Use values are usually the same. Maximum Licenses This is the number of licenses installed for the corresponding product. For example, if the maximum licenses for MULTI is 10, the license manager will allow a maximum of ten users of MULTI. 270 MULTI: Editing Files and Configuring the IDE

283 License Manager Device Web Interface Configuration Page The Configuration page presents a form for setting a variety of license manager options: This form contains the following fields, text and check boxes (see the pages indicated for more information): TCP Service Port on page 272. Log to Device-Resident File on page 272. IP Address Filter on page 272. Description on page 273. Verbose Logging on page 273. Debug Mode on page 273. Change User Lists on page 274. The configuration page also displays two important numbers for reference: LM host id on page 277. License Serial Number on page 277. Green Hills Software, Inc. 271

284 12. Green Hills License Manager Device In order for any of the configuration settings you enter on this page to take effect, the license manager device must be restarted. See License Page on page 277 for more information. TCP Service Port Green Hills software products obtain licenses from the license manager device using a TCP connection. By default, the device listens on TCP port This default can be changed by specifying a different port in this field. In addition to this server configuration, Green Hills software running on the host computer must be told to use the alternate port. This is done by setting the GHS_LMPORT environment variable to the same port number. Log to Device-Resident File Every significant licensing event, such as obtaining a license, releasing a license, etc, can be logged by the license manager. It is recommended that you use MULTI License Administrator to connect to the license manager device so the log can be generated on your host computer system. For more information, consult Chapter 11, License Administration with the MULTI License Administrator. The alternative is to log to a RAM-based file resident on the device itself, but since RAM on the device is limited, the history that can be logged in this manner is limited. To log to a local RAM file, enter a filename (no directory specifiers are allowed) in this field. IP Address Filter By default, the license manager device will respond to any licensing request it receives, regardless of the source of the request on the network. In some cases, the system administrator may desire to limit access to a device to a particular subset of the network topology. This can be accomplished by assigning a non-zero dotted decimal IP address in this field. The IPv4 address is made up of four octets, each separated by a decimal point. If an octet of the IP address filter address is equal to 0 (zero), then any value for 272 MULTI: Editing Files and Configuring the IDE

285 License Manager Device Web Interface that octet in the client s IP address is allowed. If an octet of the IP address filter is non-zero, the corresponding octet of the source IP address must match exactly. For example, if the IP address filter is , then any client on the subnet,suchas , can access the license manager. Requests from other subnets, such as will be denied. Description This is a human-readable string used to identify this device when MULTI License Administrator lists available license servers on the network. The description has no use other than identification. If a description is not used, the license manager device can still be uniquely identified by its IP address, Ethernet hardware address, or hostid. A description may be useful when a network has multiple license manager devices or servers in use, with each one serving a particular group of users. For example, you could set the description to The Tools Group or Firmware Development, or any description up to 64 characters in length. Verbose Logging When logging is enabled, only significant licensing events are recorded. Selecting this check box will cause the license manager to log more events, some of which may be useful in visualizing the activity of the license manager. Debug Mode When this option is selected, license manager logging is enabled and the log output is sent to the device s RS-232 serial port. The license manager log can be displayed by connecting a standard serial emulation program, such mterminal, at 9600 baud. (For information about mterminal, see MULTI: Debugging.) Generally, Debug Mode should not be required, since the log can be read over the network using MULTI License Administrator. Green Hills Software, Inc. 273

286 12. Green Hills License Manager Device Change Admin Password Some pages of the web interface are are password protected. To change the administrative password: Click Change Admin Password. You will be prompted to enter the current login name and password. (The login name is admin.) Enter a new password. Passwords are case sensitive. The minimum length is 6 characters, and the maximum is 16. Re-enter the new password to verify. Change User Lists When the license manager device is first powered up with per-user licenses installed, no user list will be assigned. A licensed product can be used prior to the assignment of user lists. User lists will auto-populate, that is, the first users who use a licensed product will be automatically added to the user list for that product. Once a user is added to a user list, whether by auto-population or by manual setting, the only way to remove or change that entry is to use the Change User Lists web page. 1. Select Change User Lists to open the web page. 2. The operation of this web page is straightforward. The first column lists licensed Program names. The second column lists Licensed Users for the corresponding programs. 274 MULTI: Editing Files and Configuring the IDE

287 License Manager Device Web Interface 3. Click an item in the Program column to display the User List page for that program: 4. This page displays the User detail for the specified program. One User field appears for each license available. 5. Type a user name into the text field to assign a valid user to the list. 6. After adding or changing users for this program, click OK. 7. The User List page will refresh and reopen. The changes you made will display in the table. 8. When you are finished making changes, click Save at the bottom of the page to save user list changes into permanent storage. Green Hills Software, Inc. 275

288 12. Green Hills License Manager Device Note For security purposes, a maximum of three changes (three clicks of Save) are allowed in any 24 hour period when the license device is running. If a fourth Save to the User List page is attempted, a message will display indicating that the maximum number of daily changes to the user list has been exceeded, and the user list changes will not be saved. 9. The license manager device must be restarted for new user lists to take effect. Select License Restart License Server to restart the device. About Per-user Licensing and Administration Most Green Hills users will have what is known as per-user license for the software. A per-user license provides a specific user with the right to invoke/use a program an unlimited number of times simultaneously from the desktop. This is unlike the traditional floating license, which provides the user with the right to invoke/use a program, and when that use is finished another invocation can reuse the license. A good example of the advantage of using per-user licenses is when a user is launching a parallel build that invokes three compilations simultaneously. In a floating license environment, three floating licenses would be needed. With a per-user license, only a single license is consumed for the build. The other main difference between floating and per-user licensing is that the per-user license can only be used by a single, unique user, whereas a floating license can float among users. Traditionally, users tend to think of Green Hills software tools as being offered in seats, where the number of seats of the tools matches the number of users of the tools. The per-user licensing scheme implements this concept, providing each developer with the software tools available. If a group has ten users of a Green Hills product, then that group must have ten seats or ten per-user licenses for that product. A per-user license provides a unique user with the right to use a product, but the choice of which user this license is assigned to is the decision of the user s organization (system administrator, manager, etc.). The list of valid users for a particular product is managed via the web server interface, through the Change User Lists page. 276 MULTI: Editing Files and Configuring the IDE

289 License Manager Device Web Interface LM host id This hexadecimal number uniquely identifies the license manager device hardware. If new licenses are installed on the license manager device, they are configured to run specifically on only this single device, as identified by its unique LM host id (see License Page on page 277 for information about uploading a new license key file). When requesting new licenses, this LM host id must be specified as part of the request. This number is displayed for reference purposes only; it cannot be changed by the user. License Serial Number This number uniquely describes the license key file that is currently installed on the license manager device. When requesting new licenses or communicating with Green Hills technical support regarding any license management topic, this serial number must be provided in order for Green Hills to cross reference the installed licenses with other information, such as the customer s name, purchase order number, etc. With this information, Green Hills can verify what types of licenses are installed and be better able to service your request. This number is displayed for reference purposes only; it cannot be changed by the user. License Page The License page contains the following links (see the pages indicated for more information): Obtain Commuter Nodelock Lease on page 277. Show List of Licensing Files on page 280. Upload and Install License on page 281. Restart License Server on page 282. Obtain Commuter Nodelock Lease Many developers have an occasional requirement to use their Green Hills software away from the office. For example, they may want software installed Green Hills Software, Inc. 277

290 12. Green Hills License Manager Device onto a laptop to take into the field to debug a problem. Green Hills has introduced the concept of a temporary commuter license. With a commuter license: A user can check out a license from the license manager and have this license converted into a temporary commuter license for their laptop. Because the remote license has a time limit, it is referred to as a lease. The remote license will only run on a specific target machine, which is called a nodelock. Commuter licenses preserve the customer s investment in Green Hills software by allowing a licensed user to take full advantage of the software even when working remotely without purchasing separate licenses for this purpose. 1. To obtain a commuter nodelock lease, select the Obtain commuter nodelock lease link. The Obtain Commuter Lease page will open with a form for you to complete: 2. Enter the following information: User Name The user s login name. Host Code The number that describes the target machine (e.g. the laptop) that will be running the software remotely. To determine the appropriate value for the host code, run the command servecode -g on the target machine (the servecode program is available from the top level of the Green Hills software installation which must 278 MULTI: Editing Files and Configuring the IDE

291 License Manager Device Web Interface first be installed on the target machine). The result of this command will be a hexadecimal number similar to the following: 0x1e2ed92 Using this example, you would enter 0x1e2ed92 in the form s Host Code field (do not include any spaces in the number). MULTI License Administrator can also be used to display the host code (see Accessing MULTI License Administrator on page 267). Length of Lease in Days This is the number of days the remote machine will be licensed for. It is important to note that once a lease request is submitted, one license (for all licensed products) will be checked out from the license manager for the duration of the specified period. Obtaining a commuter lease for a particular user means that this user s license on the network will be disabled until the term of the lease expires. For security reasons, it is not possible to check a lease back in to recover a license before the expiration date. 3. When the information has been entered correctly on the form, click Submit to activate the lease and generate the license key for the target machine. Information similar to the following will be displayed in the browser: Click to save license file: config0.lck 4. Depending on your browser, you can save the file by right-clicking Save Link As or Save Target As. On some browsers, simply clicking the link will open a file chooser that you can use to to select the location for downloading the file to your local disk. 5. After saving the license key to your computer s hard drive, transfer the file to the target machine, placing it in the top level directory containing the Green Hills tools installation. 6. In order to use this license, run the following command from the directory where your tools are installed: update -f config0.lck -n all Alternatively, use MULTI License Administrator to install the license (see Accessing MULTI License Administrator on page 267). 7. Once the lease expires, the managed license is automatically added back to the pool of licenses available from the license manager and the temporary nodelock on the target machine expires simultaneously. No action is Green Hills Software, Inc. 279

292 12. Green Hills License Manager Device required by the user to return a leased license. Once a lease expires, another lease for the same target machine can be generated. Only one nodelock lease is permitted per target machine. Also note, leases are recorded in nonvolatile memory, so the lease will be reserved until the user-specified expiration occurs even if the license manager is restarted or the device power cycled. Show List of Licensing Files If you generate a lease license, and for some reason do not save it to the target machine, you can save it at a later time. When you select Show List of Licensing Files, a list of the device-resident license key files will be displayed, similar to the following: Click to save a license file: config.lck config0.lck config.lck is the master license file for the licenses managed by the device and is typically preinstalled by Green Hills Software. License files that contain a number (e.g. config0.lck, config1.lck, etc.) correspond to commuter licenses created with the commuter nodelock lease feature. The only use of these license key files is for installation of temporary nodelock licenses for the commuter machine. To save license files: 1. Select the license file you want to save and click its link. 2. A Save As dialog box opens. Specify the file to Save As, thenclickok. Up to ten commuter lease license files may be created and saved on the device before being downloaded and used. After config9.lck is used, the file config0.lck will be reused for the next lease license key file. Therefore, if more than ten commuter leases are simultaneously required, the license keys must be downloaded before they are overwritten. Once a commuter lease is created, the license manager has an independent permanent record of the lease until it expires. 280 MULTI: Editing Files and Configuring the IDE

293 License Manager Device Web Interface Upload and Install License In some cases, the license key that is preinstalled by Green Hills on the license manager device will need to be field upgraded. For example, if a customer purchases additional licenses that will be managed by an existing license manager device, a new license key must be obtained from Green Hills software and installed on the device. Only one license key file can be installed in the license manager device. When the new key is installed, the previous key (and its licenses) become void. The new key will contain enough licenses to meet the new customer usage requirement. Do not attempt to use this link to install anything other than a license provided by Green Hills for this purpose. To upload a new license key: 1. Select Upload and Install License. A form will be displayed which you can use to enter the name of the license file: 2. Click Browse to select the file using a standard file chooser. 3. Once the correct license key file is selected, click Load to transfer the file to the license manager device. 4. The key will automatically be installed and saved into nonvolatile storage. 5. In order for the new licenses to take effect, the license manager device must be restarted. The above instructions assume that you have already obtained a valid license key file from Green Hills Software via or other means. If your host computer has access to the internet, you can obtain new licenses from the Green Hills web site and have them automatically installed on the Green Hills Software, Inc. 281

294 12. Green Hills License Manager Device device with the MULTI License Administrator selection: Check for New License (see Accessing MULTI License Administrator on page 267). If selected and a valid license is found, you can choose to upload and install this license directly onto the device. Help Page Restart License Server Select Restart License Server to restart the license manager software running on the device. If new licenses are uploaded, you must restart the license manager before new licenses can be used. Restarting the license manager is also required for changes made on the Configuration page to take effect (see Configuration Page on page 271). The license manager can also be restarted to clear the current status information and reclaim outstanding licenses (except for leases). Power cycling the license manager device is another way to to force the license manager to restart. Note A license manager restart or device power cycle may result in users encountering some down time. It is best to consult the Status page (see Status Page on page 268) to determine who the current users are and notify them before initiating a license manager restart. Select Help to open this chapter in your browser. 282 MULTI: Editing Files and Configuring the IDE

295 Client Configuration Client Configuration Client TCP Port If the license manager device is configured to use a TCP port other than the default port of 2009, users must ensure that client software programs connect to the new port. This is achieved by setting the environment variable GHS_LMPORT. For example, on UNIX, using C shell: setenv GHS_LMPORT 2004 Consult your system administrator if you are not sure how to set environment variables. Specifying a License Manager Device When a licensed Green Hills software program runs, it will attempt to obtain a license from a license manager using a TCP connection. For the most efficient operation, the program must know the IP address of the license manager device. You can specify the device s IP address by setting the environment variable GHS_LMHOST. For example, on UNIX: setenv GHS_LMHOST Note If you are not sure what the license device s IP address is, you can use MULTI License Administrator to perform a broadcast to locate license manager devices on the network, then display them in a list. (see Accessing MULTI License Administrator on page 267). If the program is unable to obtain a license, you can set the environment variable GHS_LMDEBUG to 10 or higher. This will cause the Green Hills software program to output some diagnostic information regarding its attempt to communicate with the license manager device. If GHS_LMHOST is not explicitly set, the client application sends a UDP broadcast message over the network in an attempt to find a license manager. If a license manager device receives the broadcast, it will respond, and the TCP connection for licensing will be established. This means that if the user s host computer is within broadcast range of the installed license manager, and a DHCP Green Hills Software, Inc. 283

296 12. Green Hills License Manager Device server is running on the network, then no IP address knowledge or configuration is necessary by either users or system administrators; the license manager device will obtain its IP address and network configuration automatically from the DHCP server, and Green Hills Software programs will find the server via broadcast. The device simply needs to be plugged into the network via Ethernet and powered on, and it can immediately begin serving licenses to users. Despite the ease of use of the license broadcast, for maximum efficiency, the license manager device s IP address should be explicitly set with the GHS_LMHOST variable. Broadcasting for every license request may result in slower round-trip license manager communication on some systems. Specifying Multiple License Manager Devices In some installations, more than one license manager device will be used. The most common scenario would be when redundant license manager devices are being employed. Multiple license manager devices are specified by including a comma separated list. For example: setenv GHS_LMHOST , , When multiple devices are specified in this manner, client programs attempt to connect to the license manager devices in the order listed. In the above example, if is available on the network, the client will connect to it, and the other devices will not be contacted at all. Random Selection of License Manager Devices In a multiple license manager device configuration, such as a redundant cluster, it may be helpful to have clients connect to a randomly selected device. This will implement a rudimentary form of load balancing. To configure clients to select randomly from a list of multiple license manager devices, precede the comma separated list with the special # character. For example: setenv GHS_LMHOST # , , MULTI: Editing Files and Configuring the IDE

297 Redundant License Manager Devices The # character is a comment character for many shells. If placing this setenv command into a shell initialization script, this character must be escaped. For example: setenv GHS_LMHOST \# , , or setenv GHS_LMHOST # , , If the client fails to connect to the randomly selected license server, the client follows the list in left to right order and attempts communication with the next address in the list (skipping the previously randomly selected entry that already failed). Using the example entry above, if is randomly selected but the client fails to connect to that address, will be attempted next. If that address fails, will be contacted. Specifying the License Manager Type The GHS_LMWHICH environment variable is a client setting that specifies what type of license to look for first. Clients that obtain their licenses from a license manager device should have this environment variable set to: GHS_LMWHICH=ghs If you use MULTI License Administrator, clicktheuse Selected LM button to automatically set GHS_LMWHICH to the correct value. You can also set GHS_LMWHICH manually on the client machine. Consult your system administrator if you are not sure how to set environment variables. Redundant License Manager Devices Redundant Server Theory of Operation Multiple license manager devices can be installed on a user s network in order to implement a redundant server cluster. License manager devices are preconfigured for use within a redundant cluster. Once configured, the device cannot be used in a standalone configuration. When a redundant license manager device cluster is running, licenses can be served by any of the devices in the cluster. License grants and releases are check-pointed between the Green Hills Software, Inc. 285

298 12. Green Hills License Manager Device redundant devices, so that the pool of licenses is virtually served by all the license manager devices, as opposed to dividing the available licenses evenly amongst the devices. Redundant license manager devices use UDP broadcasts to detect peer servers and checkpoint license events between each other. Because of the use of broadcasts, peer servers must be within broadcast range of each other. If a redundant license manager device goes down, the remaining devices in the cluster will continue to serve licenses. As a security consideration, the remaining devices will continue to operate only as long as a majority of the devices are still running. For example, if there are three devices in a cluster, one of the devices can fail without affecting a user s ability to obtain licenses, but at least two of the devices must be running for the cluster to continue to serve licenses. Similarly, in a cluster of five devices, two of the devices can go down without affecting users. If a license manager device goes down, it can later be added back to the cluster simply by powering it on. When a redundant cluster is available, users can set the GHS_LMHOST environment variable to any of the available devices. A suggested method is to list all of the license manager devices. For example, if a cluster of three redundant license manager devices have the IP addresses , , and , thentheghs_lmhost variable can be set to the comma separated list of all three. For example, using UNIX C shell: setenv GHS_LMHOST , , Green Hills software applications will attempt to use the first address in the list ( ). If this device is unavailable, then the application will attempt to use the next license manager device ( ). If this device is unavailable, the application will attempt to use MULTI: Editing Files and Configuring the IDE

299 Chapter 13 GHSlm: Green Hills License Manager This Chapter Contains: GHSlm License Server Installation for Windows GHSlm License Server Installation for UNIX GHSlm License Administration Utilities

300 13. GHSlm: Green Hills License Manager This chapter describes the installation and administration of the Green Hills License Manager (GHSlm) server and software. This is Green Hills Software s recommended licensing software and is available in host-based license servers and the Green Hills License Manager Device (see Chapter 12, Green Hills License Manager Device ). In this chapter: Windows refers to Windows graphical user interface (GUI). Command line refers both to the Windows DOS prompt and to UNIX command line; differences are noted when applicable. Note Important Notes on Using GHSlm: The license manager is usually configured to bind to TCP port If this causes a conflict, use the MULTI Licensing Wizard to configure the server to use a different port. If you use a non-standard port, you will also need to set the GHS_LMPORT environment variable on client machines to configure them to use the correct port (see Install or Configure License Server on page 250). In order to run Green Hills Software products, you must obtain and install a valid license. Information about requesting and installing licenses can be found in the License Menu on page 255. In a Windows environment, the GHSlm license server can only be run on machines with an NT based operating systems installed (such as Windows NT, 2000, and XP). Use of Windows 9x/ME machines as GHSlm license servers is not supported. The license server must not be running when licenses are installed. See GHSlm License Server Startup and Shutdown for Windows on page 290 for instructions on starting and stopping the GHSlm license server. Some license types are stored in the executables themselves. If you receive a patched executable from Green Hills, you may need to update it with your licenses before you can use it. For instructions, see the Example in Installing Licenses with update on page MULTI: Editing Files and Configuring the IDE

301 GHSlm License Server Installation for Windows GHSlm License Server Installation for Windows This section provides information about installing the License Server software, and how to obtain and install a license key on a Windows machine. GHSlm software is installed by default with the rest of the tools. In order to activate the license server, you need to register it as a service with the operating system. Note In a Windows environment, the GHSlm license server can only be run on machines with an NT based operating systems installed (such as Windows NT, 2000, and XP). Use of Windows 9x/ME machines as GHSlm license servers is not supported. Installing GHSlm License Server Software The following installation instructions are for installing GHSlm License Server software on a Windows machine in a floating-license environment. It is recommended that you exit all running programs before performing the installation.! Warning Do not install Green Hills Software products into directories that contain spaces in their pathnames. To install GHSlm license server software: 1. Install the Green Hills Tools as described in MULTI: Getting Started. 2. From the MULTI Launcher, select Utilities License Administrator to open MULTI License Administrator. (For more information, see Opening the MULTI License Administrator on page 248.) 3. Select Install a Green Hills license server on this machine (see Install or Configure License Server on page 250). This installs the server with a default configuration. See Server Settings Dialog Box on page 251 if you need to change the server s configuration. 4. If desired, you can request and install licenses as described in Chapter 11, License Administration with the MULTI License Administrator. If you choose not to install licenses at this time, you can request and install licenses later, however clients will not be able to use the server until licenses have been installed. Green Hills Software, Inc. 289

302 13. GHSlm: Green Hills License Manager You can also install GHSlm from a command line, using the following instructions: 1. Open a command prompt and cd to the directory where MULTI is installed. 2. Use the wrap_svc program to register lm as a service, and schedule it to run when the system starts up by entering the following command: wrap_svc -m auto register Note Before using wrap_svc to change the properties of the license server, make sure that any MULTI License Administrator windows and the Services applet in the Windows Control Panel are closed on the machine. Otherwise, your changes may fail to take effect. For more information about about wrap_svc, see Controlling the License Server with wrap_svc on page 292. GHSlm License Server Startup and Shutdown for Windows If the GHSlm License Server software is installed according to the instructions above, the license server will automatically run whenever the system is booted and shutdown when the system is brought down. If there is a need to start or stop the license server manually, you can use one of the following methods: Click Start/Stop in the Server Settings dialog box (see Server Settings Dialog Box on page 251. Use the Services applet in the Windows Control Panel. TheServices applet does not function correctly if the MULTI License Administrator Server Settings dialog box is open. Use the wrap_svc command as follows: wrap_svc start wrap_svc stop Before using wrap_svc to change the properties of the license server, make sure that any MULTI License Administrator windows and the Services applet in the Windows Control Panel are closed on the machine. Otherwise, your changes may fail to take effect. 290 MULTI: Editing Files and Configuring the IDE

303 GHSlm License Server Installation for UNIX GHSlm License Server Installation for UNIX This section provides information about installation and licensing on a UNIX system. Installing GHSlm License Manager Software on UNIX By default, GHSlm software is installed with the tools. You should only need to configure and launch the license manager software. GHSlm License Server Startup for UNIX and Linux The GHSlm license server executable is named lm. It is located in the directory that contains the Green Hills distribution. To start the license server, simply run this executable. Because the license server must be up and running before any of the client programs will work, you may want to modify the startup scripts on the server to launch lm at boot time. Please consult your OS documentation for information about how to accomplish this. If you have any problems, please contact Green Hills Technical Support. Configuring the GHSlm License Manager Software GHSlm is configured with MULTI License Administrator. For details, see Install or Configure License Server on page 250. Green Hills Software, Inc. 291

304 13. GHSlm: Green Hills License Manager GHSlm License Administration Utilities This section provides information about the administrator commands available for the Green Hills License Manager. Except when noted otherwise, these administrator commands are available for Windows and UNIX hosts. mlmadmin Administrator program used for installing license keys, listing users, and other administrative functions. For more information, see Chapter 11, License Administration with the MULTI License Administrator. find_ghs_licenses Lists licenses and license servers installed on the local network. This utility processes a license server log file and prints a comma delimited summary of the license usage by product and date, which is suitable for importing into a spreadsheet for graphing and further analysis. For more information, see Listing Licenses with find_ghs_licenses on page 294. lic_log_summary A Python script that serves as a reference implementation of a log summarizing tool. This utility processes a license server log file and prints a comma-delimited summary of license usage by product and date, suitable for importing into a spreadsheet for graphing and further analysis. For more information, see Log Summary with lic_log_summary on page 295. update Low-level utility for installing licenses. For more information, see Installing Licenses with update on page 296. wrap_svc Windows only Wrapper executable which allows the GHSlm License Server to act as a Windows service. Windows services can be launched automatically at system startup, and can be controlled through the Services applet in the Windows Control Panel. For more information, see Controlling the License Server with wrap_svc on page 292. Controlling the License Server with wrap_svc The wrap_svc tool allows you to register the GHSlm License Server as a Windows service, and control the service once it is registered. The tool is launched from the command line as follows: wrap_svc [options ][action ] 292 MULTI: Editing Files and Configuring the IDE

305 GHSlm License Administration Utilities Note Before using wrap_svc to change the properties of the license server, please make sure that any MULTI License Administrator windows and the Services applet in the Windows Control Panel are closed on the machine. Otherwise, your changes may fail to take effect. The following options can be used with wrap_svc: -n name Tells wrap_svc to act on the service registered with this name. The default name is ghs_lm. -e executable Register this executable as the license server. The default is lm.exe. -m mode Set the startup mode to mode. The default is manual Supported modes are: auto the service starts automatically at boot. manual the service must be started manually. disabled the service is marked as disabled. The following actions can be used with wrap_svc: print Print the current service registration information. register Register (or update) the registration information. restart Restart the service. start Start the service. stop Stop the service. unregister Unregister the service. Green Hills Software, Inc. 293

306 13. GHSlm: Green Hills License Manager Example 1. Registering the License Server for Automatic Startup To register the GHSlm License Server as a service and have it start up automatically when the machine boots, enter the command: wrap_svc -m auto register Example 2. Starting the License Server To start the GHSlm License Server after it is registered, enter the command: wrap_svc start Listing Licenses with find_ghs_licenses The find_ghs_licenses tool lists licenses installed on the local network, including servers that you are not currently using. The tool is launched from the command line as follows: find_ghs_licenses [options ] By default, the tool will contact the default servers and list information about them. For more information about setting the default servers, see Chapter 11, License Administration with the MULTI License Administrator. The following options can be used with the find_ghs_licenses command: -b -x Broadcast to find servers. Do not start with the default servers. Implies -b. Example 3. Using find_ghs_licenses To list information about licenses on the default servers, enter the command: find_ghs_licenses This generates output similar to: Server TARPON: 2009 ( ): ecomppc (2901): 10 installed, 2 in use, 7 hwm 294 MULTI: Editing Files and Configuring the IDE

307 GHSlm License Administration Utilities This indicates that the server named tarpon, listening on port 2009, has10 licenses for ecomppc (the PowerPC C/C++ compiler) installed. Of those 10, 2 are currently in use. Since the server was started, the most licenses that have been in use at any time (hwm the high water mark) is 7. Log Summary with lic_log_summary The lic_log_summary utility is a Python script that serves as a reference implementation of a log summarizing tool. This utility processes a license server log file and produces a summary of the license usage by product and date. The output is in a comma-separated values format, which can easily be imported into spreadsheet and database applications for advanced reporting and graphing capabilities. With this data, it should be easy to produce reports in different formats to suit your needs The utility is run from the command line as follows: lic_log_summary.py [options ][products ] The following arguments can be used with the lic_log_summary utility: --help -m Print usage information. Total usage by month, rather than by day -ghs Assume the log file is in GHSlm format (default). -elan Assume the log file is in Elan format. -f file Read the log file from file, rather than stdin. products Only display information about the specified products. If no products are specified, all products will be included. Green Hills Software, Inc. 295

308 13. GHSlm: Green Hills License Manager Example 4. Using lic_log_summary The command: lic_log_summary.py -m -elan -f ghs_elmd.log will display a summary of license usage from the Elan formatted log file named ghs_elmd.log, with usage totalled by month and product. Note This utility is written in the Python language, and requires a Python interpreter to run. Python is freely available from the Python Website ( which also includes excellent documentation on Python. The utility is provided as a script, so that its source code can be examined and modified to suit the needs of the end user. It should be simple to study the script and implement the same concepts in other languages if desired. Installing Licenses with update The update command is used to install licenses. Normally, this task is performed with MULTI License Administrator (see Chapter 11, License Administration with the MULTI License Administrator ). However, there are a few cases where you may want to run update directly. The command line format is: update [options ][executables all] The following options are the most commonly used with update. For security reasons, not all options are listed. -n Re-install existing licenses into new executables. This is most commonly used when a patched executable is dropped into an existing installation. -f filename -a Specifies the name of the file containing the existing licenses. By default, update will use the file config.lck. Update all executables related to the listed executables, if possible. executables Update the executables listed. 296 MULTI: Editing Files and Configuring the IDE

309 GHSlm License Administration Utilities all Update all executables in the current directory. Example 5. Installing Existing Licenses into New Executables If you receive a patched executable from Green Hills, you may need to update it with your existing licenses before it will work. To accomplish this, copy the new executable into your Green Hills directory and execute the following command: update -na all Green Hills Software, Inc. 297

310 13. GHSlm: Green Hills License Manager 298 MULTI: Editing Files and Configuring the IDE

311 ElanLM: Legacy License Manager Chapter 14 This Chapter Contains: Important Notes on Using ElanLM ElanLM License Server Installation for Windows ElanLM License Server Startup for Windows ElanLM License Administration with Windows Utilities ElanLM License Server Installation for UNIX ElanLM License Server Startup for UNIX License Administration with Command Line Utilities Resource Files Troubleshooting

312 14. ElanLM: Legacy License Manager This chapter describes the installation and administration of the Green Hills Legacy License Manager (ElanLM) server and software. Users that do not specifically require the use of ElanLM should use the GHSlm licensing technology instead. More information about GHSlm can be found in Chapter 13, GHSlm: Green Hills License Manager In this chapter: Windows refers to Windows graphical user interface (GUI) Command line refers both to the Windows DOS prompt and to UNIX command line; differences are noted when applicable. Important Notes on Using ElanLM In order to run Green Hills Software products, you must obtain and install a valid license. These steps can be performed with MULTI License Administrator. For information, see License Menu on page 255 in Chapter 11, License Administration with the MULTI License Administrator. In order to use the utilities for ElanLM on Windows, you must install the Legacy Licensing Software as described in ElanLM License Server Installation for Windows on page 301. MULTI License Administrator expects certain tools to be installed when working with ElanLM servers, and may generate an error if they are not installed. On UNIX hosts, these utilities are installed with all distributions and do not need to be installed separately. When installing floating licenses, the floating license directory must be a local directory. For security reasons, the license server will not load licenses from a network directory. When installing floating licenses, the license installer may report that the license sever is down. The license server must be launched before the client machines can access the available licenses. For more information about launching the license server and setting it to launch automatically at startup, see ElanLM License Server Startup for Windows on page 301, or ElanLM License Server Startup for UNIX on page MULTI: Editing Files and Configuring the IDE

313 ElanLM License Server Installation for Windows ElanLM License Server Installation for Windows This section provides information about installing ElanLM License Server software, and obtaining and installing a license key on a Windows machine. Installing ElanLM License Server Software The following installation instructions are for installing ElanLM License Server software on a Windows machine in a floating-license environment. It is recommend that you exit all running programs before performing the installation. To install ElanLM License Server software: 1. Insert the Green Hills CD. If the tools install auto-runs, close it. 2. Use Windows Explorer to explore the CD drive. 3. Open the licensing folder. 4. Open the legacy folder. 5. Double-click setup.exe to launch the Legacy (Elan) License Utilities Wizard. 6. Click Next to through the remaining installation screens. If the machine you are working on will act as a license server, click Customize on the Setup Options screen. When the screen appears asking what type of license to install, select This machine will act as a license server. If you will be using dongle-locked licenses, you can install dongle-drivers with the legacy software. ElanLM License Server Startup for Windows In Windows, the ElanLM license server is launched from the Control Panel: 1. Select Start Settings Control Panel. 2. In the Control Panel, open ElanLM (Green Hills). TheElan License Manager dialog box will open. On Windows XP/2000/NT, you must be a member of the administrators group to perform this step. Green Hills Software, Inc. 301

314 14. ElanLM: Legacy License Manager 3. In the Startup area of the dialog box, select one of the following options: Manual The license server will not start automatically when Windows is restarted. Automatic Automatically launches the license server using the most recent settings when Windows is restarted. Disabled (Windows XP/2000/NT only) Disables the license server. 4. Click Settings to enter Startup settings in a dialog box (see Startup Settings on page 302). If the license server is currently running, these settings are displayed in read-only mode. If the license server is not running, any changes you make on this dialog box are saved and used the next time the license server is launched. 5. After verifying or changing settings, click OK. 6. To start the license server, click Launch. After the license server starts, the label of the Launch button changes to Stop. Setup is complete. To determine if the license server is running open the ElanLM (Green Hills) dialog box from the Control Panel. The License Manager dialog box displays a message above Launch/Stop indicating whether or not the license server is running. Startup Settings The following Startup options can be set in the Settings dialog box: Debug Mode Activates debug mode and flushes the log file after each message. The default behavior of the license server is to flush the log file after each packet is processed; however, there may be many messages per packet, depending on the Verbosity level (see below). When you use debug mode, the message DEBUG mode is on prints to the log file. Key Directory Loads all keys found in the specified key directory or set of directories. Multiple directories can be specified as a colon-separated list of directory names. If no key directory is specified, the default key directory is used. 302 MULTI: Editing Files and Configuring the IDE

315 ElanLM License Server Startup for Windows Log File Name Creates a log file and writes all relevant information to that file. If the file already exists, this option appends the new information to the end of the file. The specified filename must be a complete pathname. Using a log file is recommended because it provides a way of tracking problems should they occur. You must have a log file in order to use Wlmrpt to create a report. Log File Size Limit Sets the size limit for the log file. When the size reaches the maximum, the log file is moved to file.old and the current log file is truncated. The default unit is in bytes. It may also be specified in kilobytes or megabytes. We recommend that you set a limit on the size of the log file to 1 MB. For efficiency, the log file size is actually checked only every 100 lines; consequently, the log file may grow beyond the limit slightly before it is backed up and truncated. Resource File Applies the specifications from the resource file. Resource files provide a means to implement highly customized features such as domain restriction, license reservation and exclusion, and held license periods. You can either use resource files provided by Green Hills Software or create your own. For a complete description, see Resource Files on page 325. If the resource file is modified, the license server automatically re-reads it. Start Time Sets the start time (in seconds). This is the period after a system crash that the license server waits for clients to reconnect. The time period gives existing clients a chance to reconnect before new clients can connect. The default is 180 seconds. Zombie Timeout Sets the zombie period (in seconds). If a client does not communicate with the license server within this time period, the license server assumes the client is dead and retrieves its licenses. The default zombie interval is usually 3 minutes. Note that the license server cleans up zombies every 60 seconds, so it may take up to 1 minute more for the licenses to be returned. The zombie time-out must be 180 seconds or more. Green Hills Software, Inc. 303

316 14. ElanLM: Legacy License Manager Verbosity Sets the verbosity of the messages printed to the log file. When a level is selected, all levels less than or equal to the level are printed. Levels 5 and higher are considered debugging levels. The license server defaults to level 3. The levels are: 1 Only error messages. 2 License failures. 3 License activity. 4 Client connects and disconnects. 5 Message for every packet received. 6 Message for every packet sent. 7 More client and zombie information. 8 Information about key and resource file. 9 Everything. ElanLM License Administration with Windows Utilities The following license administration utilities are available from the Windows Start menu. To launch these utilities, choose Start Programs Green Hills Software Legacy (Elan) Licensing Utilities, and then choose the desired utility. Some ElanLM administration utilities are accessible through through the Legacy Tools menu in MULTI License Administrator. For more information, see Legacy Tools Menu on page 256. Find Available Licenses Helps you locate licenses that are available to the Windows machine. For more information, see Find Available Licenses on page 305. Install Licenses Legacy license installation Do not use. To install licenses, use MULTI License Administrator instead (see License Menu on page 255 in Chapter 11, License Administration with the MULTI License Administrator ). 304 MULTI: Editing Files and Configuring the IDE

317 ElanLM License Administration with Windows Utilities License Request Generator Legacy license request generation Do not use. To request licenses, use MULTI License Administrator instead (see License Menu on page 255 in Chapter 11, License Administration with the MULTI License Administrator ). WlmAdmin This utility is deprecated. Please use MULTI License Administrator instead (see Chapter 11, License Administration with the MULTI License Administrator ). WlmCntrl This utility is deprecated. Please use Legacy Tools View Available Licenses in MULTI License Administrator instead (see Legacy Tools Menu on page 256). WlmQuery This utility is deprecated. Please use Legacy Tools View Available Licenses in MULTI License Administrator instead (see Legacy Tools Menu on page 256). WlmRpt Reports on license availability and license activity. For more information, see License Manager Reports with WlmRpt on page 307. Note You can administer Windows-hosted license servers using the administrator commands in License Administration with Command Line Utilities on page 314. However, for ease of use, Green Hills Software recommends that you use MULTI License Administrator or the Windows utilities found in this section. Find Available Licenses This utility finds all the licenses currently available to a Windows machine. It performs the following functions: Lists all the computer-locked and dongle-locked licenses installed on the machine. Scans all the servers listed in GHS_LMHOST and lists the licenses installed on them. Broadcasts to find additional servers on the network and lists the licenses installed on those servers. Opens the Find GHS Licenses dialog box: Green Hills Software, Inc. 305

318 14. ElanLM: Legacy License Manager The dialog box displays the following information for each machine (the current machine and each license server): License Packs Provides information about the.key files used to install licenses. For each license pack, the dialog box lists the server, the installation date, and the authorization id for the.key file. This information can be used to verify that all the.key files have been installed. Installed Licenses Lists all the individual licenses that are installed. For each licensed feature, the type of license and the expiration date are listed. For floating licenses, additional information is provided, such as how many licenses are installed, how many are in use, and any restrictions on the license s use. You can expand a licensed feature to list the total number of licenses available on that server, each individual installation for that feature (in case you have installed more than one license pack), and which users are currently using a license. The dialog box includes the following buttons: Reload Keys When you select a license server, the Reload Keys button becomes available. It will send a message to the selected license server, telling it to reload all of the keys in its license directories. This is useful if recently loaded licenses are not showing up in the dialog box. 306 MULTI: Editing Files and Configuring the IDE