|
DataMuseum.dkPresents historical artifacts from the history of: Rational R1000/400 |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about Rational R1000/400 Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - download
Length: 270859 (0x4220b) Types: TextFile Notes: R1k Text-file segment
└─⟦8527c1e9b⟧ Bits:30000544 8mm tape, Rational 1000, Arrival backup of disks in PAM's R1000 └─ ⟦5a81ac88f⟧ »Space Info Vol 1« └─⟦f746409bd⟧ └─⟦this⟧
Rational Environment Release Information D_12_1_1 Release \f Copyright 1990 by Rational Part Number: 508-003207-003 September 1990 (Software Rev. D_12_1_1) EXABYTE is a registered trademark of EXABYTE Corporation. IBM is a registered trademark and RISC System/6000 is a trademark of International Business Machines Corporation. PostScript is a registered trademark of Adobe Systems Incorporated. Rational and R1000 are registered trademarks and Rational Environment and Rational Subsystems are trademarks of Rational. Sony is a registered trademark of Sony Corporation of America. Sun Workstation is a registered trademark of Sun Microsystems, Inc. VT100 is a trademark of Digital Equipment Corporation. Rational 3320 Scott Boulevard Santa Clara, California 95054-3197 \f D_12_1_1 Release Contents 1. Overview 1 2. Supported Configurations and Upgrades 1 3. Compatibility 2 4. Upgrade Impact 3 4.1. Impact of Specification Changes 3 4.2. Impact of Implementation Changes 4 4.3. Impact of Keymap Changes 5 5. Known Problems 5 5.1. Problem for Registering 2167 PDL 5 5.2. Problem for the Mc68020_Bare CDF Debugger 6 5.3. Problem for Cmvc.Copy with Goal => Source 7 5.4. Name Resolution for Editor.Key.Define Command 7 5.5. Problem for Loaded Main Programs in Copied Views 8 5.6. Problem for Displaying CMVC Generation Differences 8 5.7. Clarification of Access Control 9 5.8. Problem for Setting Debugging Breakpoints 9 5.9. Problem for Debugging Code Views 10 5.10. Problem for Incrementally Editing Named or Labeled Statements 10 5.11. Problem for Archive-Copying Views 11 5.12. Problem for Copying Archived Units with Subunits 12 5.13. Problem with Only_Change_Imports Parameter in CMVC Commands 12 5.14. Problem for Token Management 12 6. New Environment Interfaces 13 6.1. Package Cmvc_Access_Control 13 6.2. Package Remote_Passwords 13 6.3. Procedure What.Search_List_Resolution 14 6.4. Procedure Cmvc.Compare 15 6.5. Procedure Cmvc.Accept_Changes_Effort 15 6.6. Procedure Command.Make_Procedure 16 6.7. Procedures in Package Editor.Screen 16 6.8. Functions in Package System_Utilities 16 6.9. Procedure Refresh_Terminal_Information 16 6.10. Generic Procedure System_Backup.Backup_Generic 17 6.11. Procedure Verify_Backup 18 6.12. Declarations for Managing Per-Session Pricing 18 6.12.1. Procedure Accept_Tokens 20 6.12.2. Procedure Donate_Tokens 21 6.12.3. Function Get_Machine_Id 24 6.12.4. Function Get_Site 24 6.12.5. Procedure Show_Site 24 6.12.6. Procedure Show_Tokens 24 6.13. Declarations of Interest to Toolsmiths 25 7. Changes from D_10_20_0 27 7.1. Changes to Parameter Value Conventions 27 7.1.1. New Special Names 28 7.1.2. New Attribute 'If 28 7.1.3. Miscellaneous Naming Changes 29 7.1.4. Options Parameter Changes 29 7.2. Changes Pertaining to Subclasses 30 7.3. Editor Changes 30 R September 1990 iii\f Rational Environment Release Information 7.4. Changes to Terminal and Screen Operations 31 7.5. Change to Deleting Command Windows 31 7.6. Changes in Editing Ada Units 31 7.7. Ada Formatting Changes 33 7.8. Changes to Common.Complete 34 7.9. Changes to Debugging 35 7.10. Changes to Session Switches 35 7.11. Changes to Library Management 36 7.12. Access-Control Changes 37 7.13. Changes to Links Management 37 7.14. Compilation Changes 37 7.14.1. Promotion 37 7.14.2. Pragmas 38 7.14.3. Units in the Archived State 39 7.14.4. Program Library 40 7.14.5. Switch-Dependent Changes to the R1000 Compiler 40 7.14.6. Switch-Independent Changes to the R1000 Compiler43 7.14.7. Representation Clauses 43 7.14.8. Compiler Switches 46 7.15. Archive Changes 48 7.15.1. Specification of Objects to Be Archived 48 7.15.2. Assignment of Access Control to Restored Objects49 7.15.3. Specification of Tape-Drive Devices 49 7.15.4. Specification of Remote Devices 50 7.15.5. Archive Options 51 7.15.6. CMVC Access Required by Archive Commands 52 7.15.7. Archiving Code Views and Loaded Main Programs 53 7.15.8. Miscellaneous Archive Changes 54 7.16. Changes to !Io.Text_Io 54 7.17. System-Management Changes 54 7.17.1. Expiration of Operator Password 55 7.17.2. Mechanism for Summarizing Logged Tape Errors 55 7.17.3. Changes Pertaining to Operator Capability 57 7.17.4. Changes Pertaining to Login Limits 57 7.17.5. Changes Pertaining to EEDB 57 7.17.6. Miscellaneous System-Management Changes 58 7.18. Changes Pertaining to Printing 59 7.18.1. !Commands.Abbreviations.Print 59 7.18.2. Queue.Print 60 7.19. System Backup Changes 60 7.19.1. Improved Do_Backup Implementation 61 7.19.2. Support for 8-Millimeter Cartridge Tape Drive 61 7.19.3. Guidelines for Choosing Tape Size 62 7.19.4. Backups on Systems with Two Tape Drives 63 7.19.5. Restoring Backups 64 7.19.6. Bug Fixes Pertaining to Backup 65 7.20. General Tape-Related Changes 65 7.20.1. Default Tape Drive 65 7.20.2. Specifying a Tape Drive through Various Commands66 7.20.3. User-Written Applications 66 7.20.4. Tape-Mount Requests 67 7.20.5. Tape-Related Messages in the Error Log 68 7.20.6. DFS Backup 68 7.21. CMVC Changes 69 7.21.1. Activities 69 iv September 1990 R\f D_12_1_1 Release 7.21.2. Code Views 69 7.21.3. Commands from Package Cmvc 70 7.21.4. Imports 71 7.21.5. CDB Capability 72 7.21.6. Work Orders 72 7.22. Networking Changes 72 7.23. Miscellaneous Environment Changes 73 7.24. Changes of Interest to RDF Users 74 8. Documentation 76 8.1. New Hard-Copy Documentation 76 8.1.1. Package Cmvc_Access_Control 76 8.1.2. Appendix F for the R1000 Target 76 8.1.3. Reference Summary 76 8.2. New Online Documentation 77 8.2.1. New Declarations 77 8.2.2. Updated Packages 78 9. Training 79 10. Appendix A: Examples of Switch-Dependent Compiler Fixes 79 10.1. Constraining Incomplete Types 79 10.2. Completing Types by Constraining Truly Private Types 80 10.3. Exceptions in Generics 81 10.4. Parameter Subtype Checking for Generic Formal Calls 82 11. Appendix B: Summary of Changes from Previous Releases 83 11.1. Editing Images (D_10_20_0) 84 11.1.1. Package Editor.Macro 84 11.1.2. Package Editor.Image 84 11.2. Editing Specific Types (D_10_20_0) 85 11.2.1. Dependents Object Editor 85 11.2.2. Changes in Editing Ada Units 86 11.2.3. Ada Completion 86 11.2.4. Changes to Object.Sort 87 11.2.5. Searchlists 87 11.3. Debugging (D_10_20_0) 87 11.3.1. Debugger Maintenance 87 11.3.2. Selections in Debugger Windows 87 11.4. Session and Job Management (D_10_20_0) 89 11.4.1. Session Switches 89 11.4.2. Log Procedures 89 11.4.3. Remote Execution 90 11.5. Library Management (D_10_20_0) 90 11.5.1. Compilation 90 11.5.2. Library Switches 90 11.6. Text Input/Output (D_10_20_0) 91 11.7. Data and Device Input/Output (D_10_20_0) 91 11.8. String Tools (D_10_20_0) 91 11.9. Programming Tools (D_10_20_0) 91 11.10. System-Management Utilities (D_10_20_0) 91 11.10.1. Logoff on Disconnect 91 11.10.2. Systemwide Login 92 11.10.3. Print Spooler 92 11.10.4. Password Policy 92 11.10.5. System-Availability Tools 92 11.11. Project Management (D_10_20_0) 93 11.11.1. Tools 94 11.11.2. Joining Controlled Objects 94 R September 1990 v\f Rational Environment Release Information 11.11.3. Import-Restriction Files 94 11.11.4. Controlling Objects 95 11.11.5. Demotion of Checked-In Ada Units 95 11.11.6. Creating New Spec Views 95 11.11.7. Pretty-Printing and Controlled Ada Units 95 11.11.8. Compatibility-Database Utilities 96 11.12. Networking (D_10_20_0) 96 vi September 1990 R\f D_12_1_1 Release 1. Overview This D_12_1_1 release of the Rational Environment: * Introduces a number of new Environment interfaces. The most significant of these interfaces is package Cmvc_Access_Control, which provides a means of managing access control at the level of views and subsystems. The new interfaces are compatible additions that do not affect existing code on the R1000. * Provides a revised R1000 compiler that is validated for ACVC 1.10. Note that some of the revisions to this compiler are available only when explicitly enabled by a library switch; enabling these revisions causes the compiler to produce code that is incompatible with the code generated by the D_10_20_0 release of the Environment. By default, the switch is set so that compatible code is generated, allowing customers with existing compiled code to make the transition to the fully revised compiler at their convenience. * Supports a variety of system configurations and hardware upgrades. D_12_1_1 can be installed on all series of the R1000; on Series 200 and 300 machines, D_12_1_1 supports the optional 64-megabyte memory-expansion upgrade and the 8-millimeter cartridge tape drive. Note that the 8-millimeter cartridge tape drive makes unattended system backups possible by enabling a full system backup to be put onto a single tape. No change has been made to the way backups are initiated (the command interfaces remain the same, with minimal changes in the tape-mount request). * Improves linking and loading performance by a factor of 5 through new underlying mechanisms called program libraries. * Provides support for per-session pricing of Rational products. * Fixes about 300 bugs from the D_10_20_0 release. 2. Supported Configurations and Upgrades D_12_1_1 supports the following configurations of the R1000: * Series 100 * Series 200 (Models 10, 20, and 40) * Series 300 System (300S) * Series 300 Coprocessor (300C) for the IBM RISC System/6000 and Sun Workstation servers. D_12_1_1 supports two kinds of tape drive on the Series 200, 300S, and 300C systems: R September 1990 1\f Rational Environment Release Information * The 9-track tape drive, which is standard on the Series 200 and an optional upgrade to the Series 300S. * The 8-millimeter cartridge tape drive, which is standard on the Series 300S and 300C and an optional upgrade to the Series 200. D_12_1_1 also supports the optional expansion of memory from 32 megabytes to 64 megabytes to improve system performance. This upgrade applies to Series 200, 300S, and 300C systems. The combinations of configurations and upgrades supported by D_12_1_1 are shown in Table 1. Table 1 Configurations and Upgrades Supported by D_12_1_1 ---------------------------------------- | | | | | | | | 8-mm |9-Track|32-Mb | 64-Mb| |Configura| Tape | Tape |Memory| Memory| | tion | Drive | Drive | | | ---------------------------------------- | | | | | | |Series |N/A |Standar|Standa| N/A | |100 | |d | rd | | ---------------------------------------- | | | | | | |Series |Upgrade|Standar|Standa| Upgrad| |200 | |d | rd | | ---------------------------------------- | | | | | | |Series |Standar|Upgrade|Standa| Upgrad| |300S |d | | rd | | ---------------------------------------- | | | | | | |Series |Standar|N/A |Standa| Upgrad| |300C |d | | rd | | ---------------------------------------- 3. Compatibility D_12_1_1 is fully compatible with all production versions of Rational layered software products, except as noted: Design Facility: 2167 6_0_7 or later (with workarounds, see section 5) Design Facility: 2167A 6_2_5 or later Documentation Tools 10_2_9 or later Design Tools 10_2_9 or later Rational Teamwork Interface 1_0_0 or later Rational Publishing Interface 1_0_0 or later 2 September 1990 R\f D_12_1_1 Release CDF: 1750A 3_0_1 or later CDF: 68K OS2000 4_1_3 or later CDF: 68K Bare 5_1_1 or later (with workarounds, see section 5) Mail 11_4_5 or later Target Builder 9_4_4 or later RXI 10_4_3 or later 4. Upgrade Impact The Environment can be upgraded from D_10_20_0 to D_12_1_1 without forcing customers to Archive.Save and Restore their applications. Customers will not have to modify or recompile any of their own tools, with the possible exception of: * Tools written against the unit specifications listed in "Impact of Specification Changes," below. * Customizations of the unit bodies listed in "Impact of Implementation Changes," below. The new declarations listed in section 6 are all installed incrementally and therefore have no impact on user-written tools. Once upgraded to D_12_1_1, a system cannot be reverted to a previous Environment release. Rational Training software has not been tested in this release. 4.1. Impact of Specification Changes The installation process for D_12_1_1 overwrites a number of Environment unit specifications. Overwriting these specifications causes the demotion of any customer-created tools written against them. The installation process tries to recompile such tools automatically; however, depending on the nature of the tools, some may require modification before they can be recompiled. Units that cannot be recompiled during installation are listed in the installation log. Following are the unit specifications that are overwritten when D_12_1_1 is installed: * !Commands.Abbreviations.Print * !Implementation.Compatibility * !Tools.Bounded_String R September 1990 3\f Rational Environment Release Information * Backup commands in !Commands.Abbreviations: Do_Backup, Full_Backup, Primary_Backup, and Secondary_Backup * !Machine.Initialize_Print_Spooler As described in section 7.16, D_12_1_1 changes the specification of package !Io.Text_Io in order to conform to the Reference Manual for the Ada Programming Language. However, because of the nature of the change (eliminating a default parameter value in the Text_Io.Open procedure), the installation process is able to use underlying Environment mechanisms to install the change rather than overwriting the package specification. Consequently, the installation process does not demote any user-written tools that are written against !Io.Text_Io. Note that if customers should subsequently demote any tools that depend on the existence of the default parameter value, these tools will need to be modified before they can be recompiled. 4.2. Impact of Implementation Changes The installation process for D_12_1_1 overwrites a number of unit bodies. Because these bodies may contain user customizations, their contents are saved as text files in the same library as the overwritten bodies. The names of these files are of the form unit_name_Vnn, where nn is the unit's default version number. The customizations then can be transferred to the new implementation. Following are the units whose bodies are overwritten when D_12_1_1 is installed: * Customizable backup procedures: - !Commands.Abbreviations.Do_Backup (See sections 6.10 and 7.19.1 for more information about the new Do_Backup'Body.) - !Commands.Abbreviations.Full_Backup - !Commands.Abbreviations.Primary_Backup - !Commands.Abbreviations.Secondary_Backup * Machine initialization procedures: - !Machine.Initialize'Body - !Machine.Initialize_Daemons'Body - !Machine.Initialize_Housekeeping'Body - !Machine.Initialize_Print_Spooler - !Machine.Initialize_Servers'Body * Customizable printing procedures: 4 September 1990 R\f D_12_1_1 Release - !Commands.Abbreviations.Print - !Commands.Abbreviations.Print_Window'Body * Customizable compilation procedures: - !Commands.Abbreviations.Code'Body - !Commands.Abbreviations.Install'Body 4.3. Impact of Keymap Changes New implementations for the keymap procedures are available for D_12_1_1. These implementations provide additional keybindings both for the Environment product and for layered products. All new machines will be delivered with the new keymap implementations. Because the keymap procedure bodies on existing machines may contain user customizations, the installation process creates a world called !Machine.Editor_Data.Masters and puts the new standard keymaps there. If a customer site wants to replace the existing systemwide keymap for a given terminal with the new standard keymap for that terminal, the system manager (or other appropriate person) can: 1. Copy the terminal_name_@ objects from !Machine.Editor_Data.Masters into !Machine.Editor_Data. This will overwrite the existing objects for that terminal. Alternatively, the existing keymaps in !Machine.Editor_Data can be edited (rather than overwritten) using information from the new standard keymaps in !Machine.Editor_Data.Masters. 2. Enter the Enable_Product_Keymaps procedure in !Machine.Editor_Data to enable keybindings for any layered products that have been installed on the system. 3. Promote the terminal_name_Commands procedure to the installed state. 4. Enter the Refresh_Terminal_Information procedure to cause the new keymap to take effect. (See section 6.9.) 5. Known Problems 5.1. Problem for Registering 2167 PDL If the Design Facility: 2167 (6_0_7) layered product is in use on your R1000, then upgrading to the D_12_1_1 Environment may cause a Program_Error (elaboration order) exception to be raised R September 1990 5\f Rational Environment Release Information whenever you attempt to register 2167 PDL or invoke Design commands. This problem arises only if you are using the load views that are delivered with the product instead of the code views. You can detect the problem during a system boot - if the load views are being used, then attempts to initialize PDL will fail. To work around this problem, first decide whether you really need to use the product's load views, which are made available for customizations. If the default system activity !Machine.Release.Current.Activity points to the product's load views and you do not have customizations in those load views, then change the activity to point to the product's code views. If, however, you have customized this product, you must add the following pragma to each of five unit bodies: pragma Elaborate (Cache_Operations); These unit bodies are all in the load view of the Pdl_Definition subsystem; they are listed below: Pdl_Definition'View.Units : Library (Load_View); Components'Body Data'Body Inputs_And_Outputs'Body Interrupts'Body Requirements'Body You must edit each of these five units, inserting the pragma on the line immediately preceding package body Name is. For example, in Pdl_Definition'View.Units.Components'Body, you must change: package body Components is to: pragma Elaborate (Cache_Operations); package body Components is 5.2. Problem for the Mc68020_Bare CDF Debugger If the CDF: 68K Bare (5_1_1 or later) layered product is in use on your R1000, then upgrading to the D_12_1_1 Environment may cause a Program_Error exception to be raised whenever you execute the Debug.Invoke command on a CDF main program. This problem arises because of a spec/load incompatibility that is now detected by the D_12_1_1 Environment. The immediate workaround is to set the Command_Cg.Check_Compatibility session switch to False. This must be done for each session using the Mc68020_Bare CDF debugger. 6 September 1990 R\f D_12_1_1 Release As part of the D_12_1_1 installation process, new Ax25 and Mc68020_Bare debugger views are provided to solve the problem. See the Installation Procedure for a description of when these views need to be installed and how to install them. Note that after these views have been installed, the session-switch workaround need not be used. 5.3. Problem for Cmvc.Copy with Goal => Source When you use Cmvc.Copy to copy load views and the Goal parameter is set to Compilation.Source, any loaded main programs in the copied views lose their code segments. This applies to any of Cmvc.Copy's derivatives - namely, Cmvc.Make_Path, Cmvc.Make_Sub- path, and Cmvc.Make_Spec_View. Note that this problem should be a rare occurrence because the default value for the Goal parameter is Compilation.Coded. 5.4. Name Resolution for Editor.Key.Define Command In previous releases, the Command_Name parameter of the Editor.Key.Define command accepted any fully qualified procedure name enclosed in a single set of quotation marks. In the D_12_1_1 release, this command accepts a procedure name only if it resolves to a unique object. Thus, the following is accepted only if !Users.Anderson.My_Print is a loaded main program (in this case, the specified name resolves to a single object): Editor.Key.Define (Key_Name => "CM_F1", Command_Name => "!Users.Anderson.My_Print", Prompt => False); If !Users.Anderson.My_Print is not a loaded main procedure, the command must be specified as follows (the 'Spec attribute causes the specified name to resolve uniquely): Editor.Key.Define (Key_Name => "CM_F1", Command_Name => "!Users.Anderson.My_Print'Spec", Prompt => False); As in previous releases, the following form (with nested quotation marks) can be used regardless of whether the specified command is a loaded main program: Editor.Key.Define (Key_Name => "CM_F1", Command_Name => """!Users.Anderson"".My_Print", Prompt => False); R September 1990 7\f Rational Environment Release Information 5.5. Problem for Loaded Main Programs in Copied Views If you use CMVC commands to copy a view containing a loaded main program and transfer the resulting copy to an R1000 running the D_10_20_0 release of the Environment, the loaded main program in the transferred view will not be executable on the destination machine. This is the case even if the R1000_Cg.Delta1_Code_View_Compatibility and R1000_Cg.Retain_Delta1_Compatibility switches were set to True when the loaded main program was created. The CMVC commands that affect loaded main programs in this way are Cmvc.Copy, Cmvc.Make_Path, Cmvc.Make_Subpath, Cmvc.Make_Spec_View, and Cmvc.Release. Note that the Archive.Copy command does not affect loaded main programs in this way. The workaround for this problem is to copy the view as usual with the appropriate CMVC command and use the Archive.Copy command to (re)copy the loaded main program into the newly created view. If this newly created view is a release, you must use the Library.Unfreeze command to unfreeze the loaded main program before you enter the Archive.Copy command. There is no workaround if the loaded main program is controlled. Note that there is no easy way to know that this problem exists at the time the new view is created. The CMVC operation will succeed and the loaded main program will be coded and executable in the new view. The problem will appear only when the new view is archived (Archive.Copy will give a message) and execution is attempted on the D_10_20_0 machine. 5.6. Problem for Displaying CMVC Generation Differences As usual, you can display CMVC generations of a controlled object in a view either by entering the Cmvc.Edit command in the view, followed by Common.Definition on the desired object, or by entering the Cmvc.Def command directly on the object in the view. Furthermore, you can use Common.Expand on the resulting generation image to show the differences between consecutive generations of the object. In the current release, however, attempts to display certain kinds of differences will either fail with a constraint error or display the difference incorrectly (a changed line will appear to be out of position by one line). This behavior arises when the differences between two generations are due to user changes that occur immediately next to changes in pretty-printer alignment. It is important to note that this problem affects only the display of the differences; the data in the CMVC database is not affected, and no other operations are affected. There is no workaround for this problem. 8 September 1990 R\f D_12_1_1 Release 5.7. Clarification of Access Control To create a subsystem in a world using the Cmvc.Initial command, you must belong to a single group that has both RCOD access and RW default access to the world. Similarly, to copy or restore a subsystem into a world using Archive commands, the identity of the archive server job must belong to a single group that has both RCOD access and RW default access to the world. The new documentation insert for package Cmvc_Access_Control and the new online help for package Archive incorrectly imply that the creating/copying/restoring identity may belong to different groups that only collectively have the required access. 5.8. Problem for Setting Debugging Breakpoints Under certain circumstances, attempts to set a breakpoint in a subprogram will fail with a message like the following: The breakpoint has been created but could not be activated: Problem encountered activating breakpoint: Illegal Pc value Inactive Permanent Break 1 at .GUMP.FOO.1S [any task] This failure occurs when both of the following are true: * The R1000_Cg.Retain_Delta1_Compatibility switch is set to False, and * The compilation unit in which the subprogram is declared contains an instantiation to which that subprogram is passed as a parameter. For example, assume that procedure Example, below, has been coded with the R1000_Cg.Retain_Delta1_Compatibility switch set to False. When debugging procedure Example, attempts to set a breakpoint in the declaration of procedure Foo will fail: with Text_Io; procedure Example is generic with procedure P (X : Integer); package G is end G; package body G is begin P (1); end G; procedure Foo (X : Natural) is begin Text_Io.Put_Line ("foo called:" & Integer'Image (X)); end Foo; R September 1990 9\f Rational Environment Release Information package Inst is new G (Foo); begin null; end Example; The workaround is to put the instantiation and the subprogram declaration into separate compilation units. Thus, in procedure Example, above, a breakpoint can be successfully set in procedure Foo after the instantiated package Inst has been moved to a separate subunit. 5.9. Problem for Debugging Code Views A new feature of D_12_1_1 is that code views and loaded main programs can be debugged using the source-level Rational debugger, provided that the original Ada units still exist in the same location and have not been recompiled since the code view/loaded main program was created. Under certain circumstances, however, names of objects in code views cannot be resolved by Debugger commands. In particular, using the Debug.Source or Debug.Definition command with default parameter values causes obscure name-resolution messages to be displayed whenever command arguments are designated by cursor position alone. The messages that may appear include at least the following: Problem encountered resolving location's path name: Name caused unexpected diana node kind to be encountered Problem encountered resolving location's path name: Name component not found in context Problem encountered resolving location's path name: Library unit has no body The workaround is to always select (highlight) the object in question in addition to indicating it via cursor position. 5.10. Problem for Incrementally Editing Named or Labeled Statements An incorrect error message is produced if you incrementally edit and repromote a named or labeled statement that occurs inside a nested block. For example, assume you want to change a list of statements that includes Named_Statement and occurs in a nested block within Example_Procedure. To do so, you select the list indicated below and incrementally edit it: package body Example_Package is procedure Example_Procedure is 10 September 1990 R\f D_12_1_1 Release begin declare ... begin ... -- Selected and incrementally edited Named_Statement: -- statement list. declare -- ... -- begin -- ... -- end Named_Statement; -- ... -- end; end Example_Procedure; end Example_Package; When you repromote the list, the following error message is displayed: Statement name NAMED_STATEMENT is a co-resident homograph of block name NAMED_STATEMENT [LRM 8.3 (17, 15)] A workaround is to demote the entire unit to source to make the change. Alternatively, you can select and incrementally edit the entire enclosing program unit (in this case, the enclosing subprogram Example_Procedure) instead of just the statement list. 5.11. Problem for Archive-Copying Views Under certain fairly rare circumstances, copying views with Archive commands results in the following error message: *** Internal Error - Unable to iterate over child objects ... while setting ACLs because of some unknown failure in ... the directory system while operating on <1> *** Cmvc_Access_Control.Initialize is quitting after errors. This message occurs when a view that has never contained compiled Ada units is copied to a destination other than a subsystem. That is, the views in question contain only text files and/or Ada units that have never been promoted beyond the source state; views such as these do not have compatibility databases. When such views are copied to nonsubsystem destinations, the Archive command attempts to construct an enclosing subsystem and reports an error because it expects but does not find a compatibility database. To recover from this situation, you must: 1. Execute the Cmvc_Maintenance.Check_Consistency command on the newly created subsystem. R September 1990 11\f Rational Environment Release Information 2. Execute the Cmvc_Access_Control.Initialize command on the newly created subsystem (unless you do not want the subsystem to be put under CMVC access control). 5.12. Problem for Copying Archived Units with Subunits When you copy a unit in the archived state, the operation will fail if that unit has subunits. Affected operations include: * Using Library.Copy or Archive.Copy to copy any set of objects that contains at least one archived parent unit. * Using Cmvc.Copy, Cmvc.Make_Path, Cmvc.Make_Subpath, Cmvc.Make_Spec_View, or Cmvc.Release to copy a view that contains at least one archived parent unit. The workaround is to promote the archived units to the source state before attempting the copy operation. 5.13. Problem with Only_Change_Imports Parameter in CMVC Commands When you use commands such as Cmvc.Copy, Cmvc.Make_Path, and Cmvc.Make_Subpath to create new views, the operation will fail if both the Only_Change_Imports parameter is True and the new views are being created with a different target key (via a different model). The workaround is to set the Only_Change_Imports parameter to False and specify the current imports to the command. 5.14. Problem for Token Management Many Rational products now are purchased on a per-session basis. Under per-session pricing, a customer purchases a specific number of concurrent usages (called tokens) for a given product. When a user session references any of the product's facilities, the referencing session acquires one of the product's tokens. When all of the product's tokens are in use, any session attempting to use the product will have to wait until a token has been released. A problem exists in D_12_1_1 with the way tokens are released. As documented in section 6.12, a session should release its token when the following two conditions are met: * The session logs out. * All of the session's background jobs have terminated. However, in D_12_1_1, the token is not released unless a third condition also is met: namely, that another session attempts to 12 September 1990 R\f D_12_1_1 Release get the token. This third condition gives rise to a scenario in which a user could effectively "lock up" a token indefinitely simply by using the product, logging off at the end of the day, and then logging back in first thing the next morning. If no other session has attempted to get the token in the meantime, the original user automatically re-obtains the token, even if he or she doesn't actually use the relevant product. 6. New Environment Interfaces D_12_1_1 provides a number of new interfaces, including two new packages and a number of new declarations that are incrementally inserted into existing packages. 6.1. Package Cmvc_Access_Control A major new package, !Commands.Cmvc_Access_Control, has been added to the Rational Environment in D_12_1_1. This package provides convenient mechanisms for managing access control in Rational Subsystems. Package Cmvc_Access_Control is documented in the upgrade to the Project Management (PM) book of the Rational Environment Reference Manual. This document is delivered with the D_12_1_1 Environment. 6.2. Package Remote_Passwords The commands in package !Tools.Dtia_Rpc_Mechanisms'Spec_View.Units.Remote_Passwords can be used to add, change, or delete entries in a remote passwords file, which is a text file that specifies the usernames and passwords to be used when accessing remote hosts. By default, the commands in this package modify the remote passwords file for the current session. Thus, these commands provide a convenient alternative to locating the file in the library hierarchy and then editing it directly. Furthermore, the commands in this package provide a way to encrypt the passwords listed in the file. A remote passwords file contains one or more entries of the following form: host_name username password_value where host_name names a machine to which the user has access, username is a valid username for that user on the specified machine, and password_value is the required password for the specified username. The form of password_value must be one of the following: R September 1990 13\f Rational Environment Release Information * A literal password, which is a string of any length not containing blanks. (This string may, but need not, be enclosed by quotation marks.) Entries for literal passwords are case-sensitive, so the entry slithy_toves differs from Slithy_Toves. * The special value <PROMPT>, which causes the user to be prompted for the password during an operation that accesses the remote host. * An encrypted password, which appears as a hexadecimal string enclosed in angle brackets. If the password value has been encrypted using the Data Encryption Standard, the hexadecimal string has the prefix DES:. If the password value has been encoded in hexadecimal notation, the string has the prefix HEX:. * The null string (""), which indicates that no password is required. (In this case, the password_value can be omitted altogether.) For example, assume that the remote passwords file for your current session contains the following entries: machine_1 alice "slithy_toves" machine_2 guest "" machine_3 anderson <PROMPT> machine_4 operator <DES:29A1EB449C1A03F6> The first entry allows you to gain access to Machine_1 under the username alice, whose password is the literal string slithy_toves (note that the quotation marks in the entry can be omitted). The second entry provides access to Machine_2 as a guest user with no password (note that password column can be left blank). The third entry allows you to gain access to Machine_3 under the username anderson; a prompt is displayed for you to enter the required password. The fourth entry allows you to access Machine_4 as Operator; the password for operator has been encrypted using DES. You can use the Add and Change commands to create and modify entries in the current remote passwords file. Both commands provide an Encryption parameter that specifies the type of encryption (if any) to be used for the password. This parameter accepts the values Des, Hex, or None (which causes a literal string to be entered without encryption). If you decide to edit the remote passwords file directly, you can enter encrypted passwords using the Show_Encryption command to generate the encrypted value and then region-copying it into the file. 6.3. Procedure What.Search_List_Resolution procedure Search_List_Resolution (Name : String := "<CURSOR>"); 14 September 1990 R\f D_12_1_1 Release Determines the object to which the specified name resolves in the context of the current searchlist. The resolution and the searchlist entry that provide the resolution are displayed in the message window. The fully qualified name of the procedure is !Commands.What.Search_List_Resolution. 6.4. Procedure Cmvc.Compare procedure Compare (Destination : String := "<CURSOR>"; Source : String := "<REGION>"; Compare_Both : Boolean := True; Show_New_Uncontrolled : Boolean := True; Show_New_Controlled : Boolean := True; Show_Uncontrolled : Boolean := True; Show_Severed : Boolean := True; Show_Modified : Boolean := True; Show_Equal : Boolean := False; Ada_Units : Boolean := True; Files : Boolean := True; Response : String := "<PROFILE>"); Compares a pair of views or configuration objects. The Compare_Both parameter determines whether the views are compared symmetrically or just the Source is compared against the Destination. The Ada_Units and Files parameters can be used to specify the kinds of objects that are compared. The remaining parameters determine the kinds of differences displayed. The fully qualified name of the procedure is !Commands.Cmvc.Compare. 6.5. Procedure Cmvc.Accept_Changes_Effort procedure Accept_Changes_Effort (Destination : String := "<CURSOR>"; Source : String := "<REGION>"; Compare_Both : Boolean := False; Show_New_Uncontrolled : Boolean := False; Show_New_Controlled : Boolean := True; Show_Uncontrolled : Boolean := False; Show_Severed : Boolean := False; Show_Modified : Boolean := True; Show_Equal : Boolean := False; Ada_Units : Boolean := True; Files : Boolean := True; Response : String := "<PROFILE>") renames Compare; Displays the effect of using Cmvc.Accept_Changes from the Source into the Destination. The fully qualified name of the procedure is !Commands.Cmvc.Accept_Changes_Effort. R September 1990 15\f Rational Environment Release Information 6.6. Procedure Command.Make_Procedure procedure Make_Procedure (Name : String := ">>Simple Procedure Name<<"; Context : String := "$"); Creates an installable Ada procedure containing the contents of the command window designated by the cursor. The procedure has the specified Name and is created in the given Context. With clauses are added to the procedure definition as needed so that unqualified names will semanticize correctly. Also, if needed, a Links.Add is attempted. The fully qualified name of the procedure is !Commands.Command.Make_Procedure. 6.7. Procedures in Package Editor.Screen procedure Set_Columns (Columns : Natural); procedure Set_Lines (Lines : Natural); Sets the height (lines) and width (columns) of the terminal screen for the current session. Changes take effect at Set_Lines calls. These procedures are in !Commands.Editor.Screen. 6.8. Functions in Package System_Utilities function Terminal_Lines (Line : Port := Terminal) return Natural; function Terminal_Columns (Line : Port := Terminal) return Natural; Reports the number of lines and columns associated with a port. These functions are especially useful with RXI, where screen size can vary. These functions are in !Tools.System_Utilities. 6.9. Procedure Refresh_Terminal_Information procedure Refresh_Terminal_Information; Refreshes the system's internal cache of terminal information. This should be done whenever any of the following objects from !Machine.Editor_Data have been changed: Terminal_Recognition, Terminal_Types, @_Keys, @_Commands. Entering the Refresh_Terminal_Information command causes these changes to take effect without rebooting the system; users who log in after the refresh will get the changed information. Note that information from the objects listed above is read automatically whenever the system boots, so it is not necessary to call Refresh_Terminal_Information from the !Machine.Initialize procedure. 16 September 1990 R\f D_12_1_1 Release The fully qualified name of this procedure is !Commands.System_Maintenance'Spec_View.Units.Refresh_Terminal- _Information. 6.10. Generic Procedure System_Backup.Backup_Generic generic with procedure Backup_Starting (Is_Full : Boolean); with procedure Backup_Finishing (Was_Successful : Boolean); procedure Backup_Generic (Variety : Kind; Wait_Until : String); Provides a more complete form of the System_Backup.Backup procedure. The Backup_Generic procedure itself is not used interactively; rather, it is instantiated and called with the !Commands.Abbreviations.Do_Backup procedure, described in section 7.19.1. Commands that instantiate and call Backup_Generic require operator capability. The fully qualified name of this procedure is !Commands.System_Backup.Backup_Generic. As implemented in the standard Environment, the !Commands.Abbreviations.Do_Backup procedure passes parameters to the Backup_Generic procedure to specify the kind of backup to be performed (full, primary, or secondary), as well as the time at which the backup is to begin. The backup tape can be mounted at any time after the !Commands.Abbreviations.Do_Backup procedure is entered and before the backup is scheduled to begin. The Backup_Generic procedure provides formal procedures (Backup_Starting and Backup_Finishing) through which various system characteristics are set for the duration of the backup and then restored afterward. Backup_Starting executes just before the actual backup is scheduled to begin and Backup_Finishing executes immediately after the backup finishes. As instantiated in the standard !Commands.Abbreviations.Do_Backup procedure, the Backup_Starting formal procedure broadcasts a message to all users informing them that a backup is beginning, saves the current memory scheduler and snapshot settings, and then turns off memory scheduling and snapshot warnings. The Backup_Finishing formal procedure restores memory scheduling and snapshot warnings according to the saved settings. Because the Do_Backup command provides a standard instantiation for this generic procedure, customers do not have to instantiate it themselves. However, if desired, the system manager can edit the body of !Commands.Abbreviations.Do_Backup to change the standard instantiation of the two formal procedures. One possibility is to use Backup_Finishing to send mail when the backup has completed. Another possibility is to use Backup_Starting and Backup_Finishing to turn off the disk-collection daemon for the duration of the backup. Doing so will prevent disk collection from interfering with the backup. However, turning off disk collection is recommended only for backups made on the 8-mm cartridge tape drive, because such backups require significantly less time than those made on R September 1990 17\f Rational Environment Release Information 9-track tape drives. In any case, turning off disk collection is not recommended if the disks are very full. 6.11. Procedure Verify_Backup procedure Verify_Backup; Verifies that a backup is complete and can be restored. This procedure simulates the tape operations involved in restoring a backup, checking to make sure that the all of the required labels exist and are correct. You should use this command to verify your backup before you try to restore the Environment from it (that is, before you "go back in time"). You can use this procedure to verify 9-track backup tapes and 8-mm cartridge backup tapes. When verifying a multitape backup, you must load the backup index tape (formerly known as the "blue tape") first and then the data tapes in sequence. The Verify_Backup procedure generates the same messages on the operations console as an actual recovery would generate, confirming tape operations as well as skip and read operations. If the backup is restorable, the procedure concludes with the following message: Successfully completed scan of backup tape If the backup is not restorable, the procedure concludes with the following message: *** Verify_Backup DID NOT complete In most cases, verifying a backup takes two to three hours. Less time may be required for verifying backups on 8-mm cartridge tapes or on lightly loaded systems. More time may be required for verifying backups on 9-track tapes or on heavily loaded systems. The fully qualified name of this procedure is !Commands.System_Maintenance'Spec_View.Units.Verify_Backup. 6.12. Declarations for Managing Per-Session Pricing Many Rational products are now purchased on a per-session basis. Under per-session pricing, a customer purchases a specific number of concurrent usages that are authorized for a given Rational product. For example, by purchasing the Rational Environment under per-session pricing, a customer obtains a total number of concurrent logins that are authorized on the customer's R1000s. Each concurrent usage permission is referred to as a token. A particular system is authorized for some number of tokens, possibly zero, for each of the Rational products. As user sessions reference the facilities provided by a given product, 18 September 1990 R\f D_12_1_1 Release each referencing session acquires a token for that product. A session retains its tokens until it is terminated (logged out); however, if background jobs associated with a session continue to execute after the session is logged out, the session's tokens are not released until the last background job completes. The Environment login token is an exception - it is released when the session itself is terminated, regardless of whether background jobs continue. Note that the console command interpreter has a login protocol but does not consume a login token. Rational personnel are responsible for placing tokens on systems according to the customer's purchase agreements. Tokens are generally placed at the factory and delivered with new systems; when additional tokens are purchased subsequent to delivery, Rational representatives add them to existing systems. Once tokens have been placed on a system, however, customers may transfer them to other systems that reside within the same site, where the notion of a site is defined in the Rational Price Guide; a site is essentially a set of R1000s that meet certain criteria, such as sharing a single support contract. For example, if a customer has three R1000s at a single site and has purchased a total of 15 concurrent logins for the Environment, then that customer can distribute the logins between those three machines (for example, to authorize 7 logins on one R1000 and 4 logins each on the others). However, if the same customer purchases an additional R1000 and places it on a separate support contract (thereby defining a different site for that R1000), none of the original 15 logins will be transferable to the new machine. A buy-out number exists for each product. The buy-out number is the number of tokens that can be placed on a single system after which token enforcement is no longer performed. For example, Environment logins have a buy-out number of 12; this means that if a customer places 12 login tokens on the same system, that system will allow unlimited concurrent logins. (Consequently, putting a thirteenth token on this machine would waste a token.) If, however, the customer puts 11 or fewer login tokens on the system, then the number of concurrent logins is limited to the exact number of tokens. Thus, when all of a product's tokens on a given system are taken, further attempts to use that product on that system cause a message to be displayed indicating that the token-usage limit is exceeded. Another session will have to be terminated before further attempts will succeed. The transfer of tokens is subject to stringently enforced restrictions: * Transfers must be completed on the same calendar day (12 a.m. to 12 p.m.). If this condition is not met, the donated tokens will be lost and can be restored only through the Rational Response Center. A fee may be assessed for this service, as specified in the Rational Price Guide. R September 1990 19\f Rational Environment Release Information * The two machines involved in the transfer must be part of a single site. * A given machine cannot both accept and donate tokens (for any product) on the same calendar day. * Operator capability is required to perform token transfers. The D_12_1_1 release of the Environment provides new declarations in !Commands.System_Maintenance'Spec_View.Units for managing per- session pricing: Commands for transferring tokens: Accept_Tokens, Donate_Tokens Commands for displaying site and token information: Show_Site, Show_Tokens Functions for use in tools: Get_Machine_Id, Get_Site Commands for Rational personnel only: Setup_Machine, Set_Site The commands for Rational personnel are for use in converting existing machines to per-session pricing, initializing new machines, and updating site membership to reflect support contract changes. Information about Setup_Machine and Set_Site can be found in their online specifications; the remaining declarations are documented in the following sections. 6.12.1. Procedure Accept_Tokens procedure Accept_Tokens (Product : String; Donation : Positive; Resulting_Count : Positive; Code : String; Response : String := "<PROFILE>"); Completes the transfer of tokens for the specified product from one R1000 to another. The transfer of tokens between machines is initiated by the Donate_Tokens procedure on the donating machine. Among other things, the Donate_Tokens procedure displays a call to the Accept_Tokens procedure in which specific parameter values are filled in: * The Product parameter specifies the name of the product for which tokens are being accepted. If the product has not previously been authorized, successfully accepting tokens will authorize it. The exact name that can be specified for a given product is supplied by Rational when that product is purchased. You can also list the names of the purchased products on a given R1000 by executing the Show_Tokens procedure. It is important to note that product names are case-sensitive and must be entered 20 September 1990 R\f D_12_1_1 Release exactly as they are given in the Show_Tokens display. * The values of the Donation and Resulting_Count parameters reflect the input that was given to the Donate_Tokens procedure. (These parameter values specify the number of transferred tokens and the total number of tokens on the accepting machine, respectively.) * The value of the Code parameter is a unique authorization code valid only for the current day, on the current machine, at a particular site; this code is generated by the Donate_Tokens procedure. Without this code, the transfer cannot be completed. The displayed call to Accept_Tokens must then be copied to the accepting R1000 and executed there. (Alternatively, the call can be executed remotely using the Remote.Run procedure.) As a result, the new number of authorized tokens is recorded in the accepting machine's error log, and the new tokens are made available immediately. Restrictions: * The Accept_Tokens procedure must be run on the same calendar day as the Donate_Tokens procedure. If this condition is not met, the donated tokens will be lost and can be recovered only by contacting the Rational Response Center. * The donating and accepting machines must reside within a single site. * The accepting machine cannot donate tokens on the same calendar day. * Machines that are not set up for per-session pricing cannot accept tokens. * Execution of the Accept_Tokens procedure requires operator capability. 6.12.2. Procedure Donate_Tokens procedure Donate_Tokens (Product : String; Donation : Positive; Resulting_Remote_Count : Positive; Remote_Machine_Id : Long_Integer; Remote_Site : String; Response : String := "<PROFILE>"); Initiates a transfer of tokens for the specified product from one R1000 to another. R September 1990 21\f Rational Environment Release Information When a customer purchases a Rational product on a per-session basis, the customer obtains a specific number of tokens for that product. These tokens represent the rights of individual users to use a particular product; the number of tokens on a given R1000 determines the number of users that can use that product concurrently. The Donate_Tokens and Accept_Tokens procedures allow the customer to distribute tokens (product usages) among multiple R1000s within the same site. The parameters specify the information required by the transfer, as follows: * The Product parameter specifies the name of the product for which tokens are transferred. The exact name that can be specified for a given product is supplied by Rational when that product is purchased. You can also list the names of the purchased products on a given R1000 by executing the Show_Tokens procedure. It is important to note that product names are case-sensitive and must be entered exactly as they are given in the Show_Tokens display. * The Donation parameter specifies the number of authorized tokens to be transferred from the current machine. * The Resulting_Remote_Count parameter specifies the number of authorized tokens that will exist on the accepting R1000 as a result of the transfer. * The Remote_Machine_Id parameter specifies the R1000 that is to accept the transferred tokens; to obtain a value for this parameter, you can use the Show_Machine_Id command on the accepting machine. An error results if you specify the machine identification number of the current machine (the current machine cannot donate tokens to itself). * The Remote_Site parameter specifies the site to which the accepting machine belongs. To obtain a value for this parameter, you can use the Show_Site command on the accepting machine. The specified site must match the site of the donating machine. The Donate_Tokens command displays a call to the Accept_Tokens procedure with the appropriate parameter values filled in. The transfer is completed when the Accept_Tokens call is copied to the accepting R1000 and executed there. In addition to displaying the required call to the Accept_Tokens procedure, the Donate_Tokens procedure records the initiated transfer in the donating R1000's error log. Restrictions: * The Accept_Tokens procedure must be run on the same calendar day as the Donate_Tokens procedure that generated it. If 22 September 1990 R\f D_12_1_1 Release this condition is not met, the donated tokens will be lost and can be recovered only by contacting the Rational Response Center. * The donating and accepting machines must reside within a single site. Donate_Tokens will fail if the specified Remote_Site is different from the site of the current machine. * The Donate_Tokens procedure fails if the transfer would leave the donating machine with a negative number of tokens. * The donating machine cannot accept tokens on the same calendar day, regardless of product. * Machines that are not set up for per-session pricing cannot donate tokens. * Execution of the Donate_Tokens command requires operator capability. Example: Assume that you have two R1000s at your site and a total of 10 authorized logins that are currently distributed so that each R1000 has 5. Assume further that you want to transfer 3 logins from one machine to the other, resulting in 8 logins on the other machine. The Donate_Tokens procedure initiates the transfer: Donate_Tokens (Product => "Login", Donation => 3, Resulting_Remote_Count => 8, Remote_Machine_Id => destination_machine_id, Remote_Site => "destination_machine_site"); The procedure displays the Accept_Tokens procedure with specific parameter values in the current output window. This display includes the authorization code to complete the transfer: Accept_Tokens (Product => "Login", Donation => 3, Resulting_Count => 8, Code => "a_unique_authorization_code"); To complete the transfer, you now need to copy the displayed Accept_Tokens procedure into a file, archive it to the destination machine, and enter it in a command window there (or the call to Accept_Tokens can be executed remotely using the Remote.Run procedure). R September 1990 23\f Rational Environment Release Information 6.12.3. Function Get_Machine_Id function Get_Machine_Id return Long_Integer; Returns the machine identification number for the current machine. Equivalent to "!Implementation".Machine.Get_Id, except that it returns Long_Integer. 6.12.4. Function Get_Site function Get_Site return String; Returns the site identification for the current machine. Returns the null string ("") if the site has not been set. 6.12.5. Procedure Show_Site procedure Show_Site; Displays the site identification for the current machine. To donate tokens for one machine to another, it is necessary to know that both have the same site identification. 6.12.6. Procedure Show_Tokens procedure Show_Tokens (User_Filter : String := ""; Product_Filter : String := ""; Include_Sessions : Boolean := True; Include_Debugging : Boolean := False; Include_Statistics : Boolean := False); Shows token information for the specified user or product. System managers can use this command after a token transfer to verify that the current machine has the correct token limit. They can also use this command to compare actual usage with purchased usage. When no more tokens are available for a given product, end users who want to use that product can use this command to find out which sessions have the tokens. By default, this command displays the following fields of information for every token-managed product: * Users. Lists the user sessions that currently have tokens. * Limit. Shows the number of authorized tokens that have been placed on the current machine. * Current. Shows the number of tokens that are currently in use (one for each of the sessions listed under Users). * Buy_Out. Shows the number of tokens after which enforcement is no longer performed. This number is established by 24 September 1990 R\f D_12_1_1 Release Rational on a product-by-product basis. You can use the User_Filter and Product_Filter parameters to specify a particular username or a particular product name for which to display token information. You can set the Include- _Sessions parameter to False to cause the display to omit the information in the Users field. The remaining parameters (Include_Debugging and Include_Statistics) are for internal use only. Example: Product Users Limit Current Buy_Out -------- ------------------- ----- ------- ------- Login 12 4 12 SJL.S_1 RJS.S_1 JIM.S_1 PHIL.S_1 X Interface 10 2 12 SJL.S_1 RJS.S_1 Design_Facility 8 1 12 RJS.S_1 In this example, Limit and Buy_Out are equal for Login, so there is no limit on the number of concurrent logins. However, for the remaining products, the maximum usage is set by Limit. 6.13. Declarations of Interest to Toolsmiths Following are new declarations pertaining to CMVC implementation: * !Implementation.Cmvc_Implementation.Element_Operations.Saves_ Source * In !Implementation.Cmvc_Implementation_Errors: Text_Creation_Storage_Error : constant Status := 41; Database_Storage_Error : constant Status := 42; No_Common_Ancestor_Found : constant Status := 43; Source_Is_Checked_Out : constant Status := 44; Destination_Is_Checked_Out : constant Status := 45; Database_Was_Locked : constant Status := 46; Database_Access_Control_Violation : constant Status := 47; Source_Not_Saved_In_Database : constant Status := 48; Line_Too_Long_For_Storage : constant Status := 49; Source_Object_Is_Locked : constant Status := 50; Source_Object_Is_Access_Protected : constant Status := 51; Following are new declarations in !Io.Pipe: * function Debug_Image R September 1990 25\f Rational Environment Release Information * function Get_Daemon_Interval * procedure Run_Daemon * procedure Set_Daemon_Interval Following are new declarations in package !Implementation.Directory: * Declarations pertaining to categories: - type Category - function Get_Category - function Has_Category - function Is_Gateway - function Is_Resident - procedure Set_Category * Declarations pertaining to orders: - function Convert - function Get_Order - type Order - function Order_Category - function Order_Subclass - procedure Set_Order * Declarations in package Directory.Ada: - function Get_Order * Declarations in package Directory.Naming: - function Get_Order - procedure Release * Declarations in package Directory.Statistics: - function Object_Is_Slushy - function Object_Order Following are new declarations in !Implementation.Object_Subclass: 26 September 1990 R\f D_12_1_1 Release * function Cmvc_Access_Subclass * function Defined_Subclasses * function Design_Info_Subclass * function Element_Cache_Subclass * function Executable_Code_Subclass * type Iterator * function Markup_Subclass * function Maximum_Subclass * function Minimum_Subclass * function Object_Code_Subclass * function System_Subsystem_Subclass * function System_View_Subclass 7. Changes from D_10_20_0 This section describes the changes, enhancements, and user-visible bug fixes that D_12_1_1 makes to existing features of the Environment. The information in this section is presented in roughly the same order in which it would be found in the Rational Environment Reference Manual: beginning with naming and subclass information (which will appear in a hard-copy upgrade to the Reference Summary), through general editing and screen operations (EI), editing specific types of objects such as Ada units and command windows (EST), debugger information (DEB), library-management information including links, access control, switches, compilation, and archive (LM), information about !Io.Text_Io (TIO), system-management information including backup and tape-related changes (SMU), and information about subsystems and CMVC (PM). Following these are sections about Environment changes that pertain to networking and RDF. 7.1. Changes to Parameter Value Conventions This section includes changes to the conventions for entering well-formed parameter values in Environment commands. Such conventions include the rules for constructing naming expressions and option specifications. R September 1990 27\f Rational Environment Release Information 7.1.1. New Special Names Table 2 New Special Names --------------------------------------------------------------- | | | | Special | Description | | Name | | --------------------------------------------------------------- | | | |"<HOME>" |Resolves to the user's home world; fails if this is| | |not defined. | --------------------------------------------------------------- | | | |"< |Resolves to the enclosing subsystem; fails with an | |SUBSYSTEM>"|error message if the context is not a subsystem or | | |an object in a subsystem. | --------------------------------------------------------------- | | | |"<VIEW>" |Resolves to the enclosing view; fails with an error| | |message if the context is not a view or an object | | |in a view. | --------------------------------------------------------------- 7.1.2. New Attribute 'If The attribute 'If specifies one or more conditions. An object must satisfy at least one to be matched. The conditions, specified as arguments to the 'If attribute, are listed in Table 3. Table 3 Arguments for the Conditional 'If Attribute ---------------------------------------------------- | | | | |Long Form| Short | Description | | | Form | | ---------------------------------------------------- | | | | |Controlle| |Matches objects if they are | |d | |controlled. | ---------------------------------------------------- | | | | |Checked_ |In |Matches objects if they are | |In | |controlled and checked in. | ---------------------------------------------------- | | | | |Checked_ |Out |Matches objects if they are | |Out | |controlled and checked out. | ---------------------------------------------------- 28 September 1990 R\f D_12_1_1 Release Table 3 Arguments for the Conditional 'If Attribute (cont.) ---------------------------------------------------- | | | | |Long Form| Short | Description | | | Form | | ---------------------------------------------------- | | | | |Frozen | |Matches objects if they are | | | |frozen. | ---------------------------------------------------- Example 1. The name @'If(~Controlled) matches all objects in the current library that are not controlled. Example 2. The name @'If(Out) matches all controlled, checked-out objects in the current library. Example 3. The name @'If(~In) matches the set of objects that are not controlled or are not checked in. This name is equivalent to @'If(~Controlled, Out). Example 4. The name @'If(Controlled)'If(Frozen) matches the set of objects that are both controlled and frozen. In contrast, the name @'If(Controlled, Frozen) matches the set of objects that are either controlled or frozen. 7.1.3. Miscellaneous Naming Changes An object of subclass Object_Set can now be used as an indirect file, just as text files and activities can. For example, the State.Referencers object for a view is of subclass Object_Set; therefore, you can enter the following command from the view's State directory to obtain a list of that view's referencers: Library.Resolve ("_Referencers"); The ambiguous abbreviated special name "<S>" now resolves to "<SELECTION>" (not to "<SWITCH>"). Bugs were fixed so that every special name resolves as expected when used as an argument to the Definition command. In particular, the command Definition ("<SWITCH">); displays the library switch file associated with the current library. Bugs were fixed so that Definition ("<TEXT>"); now allows the cursor to be immediately to the right of a highlighted region. 7.1.4. Options Parameter Changes In an Options parameter, you can no longer use the null string to specify a Boolean value for an option. R September 1990 29\f Rational Environment Release Information 7.2. Changes Pertaining to Subclasses The subclass abbreviation Main_Body now matches both Main_Function_Body and Main_Procedure_Body. The File class has the three new user-visible subclasses shown in Table 4. Table 4 New User-Visible Subclasses in File Class ------------------------------------------------------ | | | | | Short |Long Form | Description | | Form | | | ------------------------------------------------------ | | | | |Cmvc_ |Cmvc_ |File containing CMVC access-control| |Acc |Access |information for a view or subsystem| | | |(see PM book) | ------------------------------------------------------ | | | | |Element|Element_ |Element cache for storing permanent| |s |Cache |collections of Ada program elements| | | |(part of Rational Design Facility) | ------------------------------------------------------ | | | | |Markup |Markup |Text file containing markup, | | | |generated from abstract document | | | |(part of Rational Design Facility) | ------------------------------------------------------ 7.3. Editor Changes The behavior of Text.Create has been augmented. When applied to an existing text file, this command brings the file into a window and opens it for editing (equivalent to Common.Edit). You can now modify an image that contains a selection without causing the selection to be turned off. The selection remains if you type into the area preceding or following it or if you type directly into the selection itself. Characters typed at the start of a selection are included inside the selection; characters at the boundaries of a selection can be transposed with characters outside the selection. Several performance enhancements have been made: * Characters typed into an image are processed faster. * Searches for prompts (for example, Next Item and Previous Item) are faster. 30 September 1990 R\f D_12_1_1 Release * Text files are brought up for reading approximately twice as fast as before. * Unnecessary repainting and scrolling are avoided. Bug fixes were made so that rapidly switching between Overwrite and Insert modes does not cause a failure to display typed characters. 7.4. Changes to Terminal and Screen Operations A new session switch, Session.Flash_Screen, allows screen-flashing instead of beeping as an alert signal on a Facit terminal. The maximum screen size is now 160 by 160. This is especially useful for users running the RXI product on workstations. Bug fixes were made so that character insertion does not fail on VT100 terminals. After resizing the screen, you can use Format to reformat the contents of each command window to accommodate the new line length. 7.5. Change to Deleting Command Windows The Common.Release command (typically bound to the Object-X key combination) now has a different effect when used in a command window. In particular, Object-X promotes the command window's contents before removing the window. Thus, when used in a command window, Object-X is no longer equivalent to Common.Abandon (Object-G), which removes the command window and discards its contents. This change is intended to make the effect of Object-X more consistent across all types of Environment windows. However, the change may also cause you to inadvertently execute commands when you only wanted to remove a command window. From now on, you should use Window-K to remove command windows from the screen, and use Object-G to discard a command window and its history. 7.6. Changes in Editing Ada Units You can now edit a subunit in the source state while its parent is being compiled. Furthermore, you can now create a subunit before its stub exists in the parent unit, when the parent unit is any of the following: frozen, checked in, locked, or in the archived or coded state. However, the subunit cannot be promoted until you edit the parent unit to insert the stub. R September 1990 31\f Rational Environment Release Information Bugs were fixed so that a message is now produced whenever Ada.Make_Inline is unable to inline a subunit without obsolescing its installed parent. Completion can now be used on generic instantiations. Ada.Create_Body no longer puts the with clauses from the spec into the body. Ada.Create_Body now provides incomplete discriminated types with a record type completion. Incomplete nondiscriminated types are still provided with a derived type completion. Ada.Create_Body now inserts two newlines (rather than only one) at the end of every body. Ada.Create_Private now completes private discriminated types with a record type completion. Private nondiscriminated types are still completed with a derived type completion. You can now use Common.Demote to demote a highlighted list of statements, declarations, and so on in an Ada unit. Demoting a list removes dependencies that might otherwise prevent you from making changes elsewhere in the Ada unit. When a list is demoted, it is replaced with a statement prompt; in contrast to Common.Edit, Common.Demote displays no additional window. (Thus, you use Common.Edit to actually make changes to the highlighted statements and Common.Demote to merely remove the dependencies on them.) As is the case for any incremental operation, a controlled unit must be checked out before a statement list in it can be demoted. Demoting (rather than editing) a statement list is useful when you want to remove dependencies on the following: * Subprograms to which you want to add parameters with defaults * Types or subtypes for which you want to change the bounds * Variables for which you want to change initialization expressions The Region.Fill command has been enhanced so that you can fill a comment in an Ada unit without having to select the comment first. Filling a comment adjusts the placement of the words in it, putting as many words as possible on each line. An Ada comment is a contiguous set of lines, each beginning with the string "-- ". Any line containing only the "-- " string serves to delimit separate comments - for example: -- First line of first comment -- Second line of first comment; the next line serves as a -- delimiter: -- -- First line of second comment -- Second line of second comment 32 September 1990 R\f D_12_1_1 Release To fill an Ada comment, you can put the cursor on any nondelimiting line within that comment. Note that, when multiple comments are separated as shown above, you can also choose to fill them as a single comment by selecting them as a group and then filling them (the delimiter lines containing only the comment string are eliminated). In all cases, the leading "--" strings are adjusted automatically. Fill mode has been enhanced. When you type an Ada comment in fill mode, comment delimiters are automatically supplied for continuation lines. Semantic checking was improved for incremental insertions. You cannot incrementally insert illegal uses of private types. You cannot incrementally insert circular with clauses (for example, if package spec X withs package spec Y, then you cannot incrementally insert with X; into package spec Y). Semanticize and promote no longer allow "=" as a generic formal subprogram with nonlimited arguments. Bug fixes were made so that Object.Move works properly. Previously, Object.Move would move the selected structures into an insertion window that would have to be promoted as a separate step. Now Object.Move both moves and promotes the selected structures. Common.Definition can now traverse from an abort statement to the task referenced in that statement. 7.7. Ada Formatting Changes The Format operation is now more conservative about discarding user-entered text when attempting to correct syntax errors. Specifically, this operation will discard text only in the following instances: * The word or is discarded if it immediately follows the word select. * The word do is discarded if there is no matching accept. * An unmatched right parenthesis is discarded if it follows a matched right parenthesis. * In a series of consecutive semicolons, all but one is discarded. * An unmatched >> is discarded. * An unmatched end; is discarded. * An unmatched end name; is discarded. R September 1990 33\f Rational Environment Release Information * An unmatched end loop name; is discarded. The Format operation now diagnoses certain kinds of syntax errors that formerly were detected only by the Semanticize operation. The Format operation now leaves the cursor in more predictable places. For example, assume that the cursor is on the letter F of the variable Foo when you press the Format key. The cursor stays on the same letter of the same variable, even if the Format operation moved the variable. Similarly, if a Format operation inserts tokens to the left of the cursor, the cursor will be pushed to the right by the inserted tokens. However, if a prompt is inserted among those tokens, the cursor is left on the prompt. If the Format operation needs to insert a missing end, it attempts to do so as close to the cursor as possible, if that makes sense. If such placement does not make sense, the Format operation will generally insert a [statement] or [declaration] prompt immediately after the matching begin. (Formerly, the Format operation would insert a missing end as far away as possible from the matching begin.) During syntactic completion, the Format operation now avoids incorporating comments in the completed constructs. Thus, the syntactic completion of: A := 3 -- comment will result in: A := 3; -- comment instead of placing the semicolon on the line following the comment. The Format operation now completes based literals by inserting a trailing pound sign (#) and/or a leading 16. For example, #1234 will complete to 16#1234#. The Format operation no longer discards comments typed before a [comp_unit] prompt. The Format operation no longer discards printable non-Ada characters like ? and \. Instead, these characters are underlined as syntax errors. 7.8. Changes to Common.Complete The initial level of detail in a Completion menu now expands procedures and elides packages and generics. As always, you can perform elide and expand operations to display the desired level of detail. 34 September 1990 R\f D_12_1_1 Release Bug fixes were made so that completion works properly on function calls that are used as arguments to other subprograms. 7.9. Changes to Debugging The Debug.Put command now supports the display of types defined in package Work_Order_Implementation. Code views and loaded main programs can now be debugged using the full capabilities of the Rational debugger, provided that the original Ada units still exist in the same location and have not been recompiled since the code view/loaded main program was created. A new switch, R1000_Cg.Full_Debugging controls whether full use can be made of the debugger. When False (the default), this switch causes the compiler to use certain optimizations that generate code only for a subset of constructs; consequently, under the debugger, single-stepping appears to skip statements, and breakpoints cannot be set in certain places. When True, this switch suppresses the compiler optimizations, thereby enabling full use of the debugger on the produced code. The Debug.Put command now handles generic information better. In particular, this command no longer fails with an unhandled exception when displaying certain records or arrays that have types exported from generic instantiations as component types. The Debug.Put command now displays arrays with consistent spacing. Note that this slight difference in formatting may have some impact on user tools that compare Debugger images. Bug fixes were made so that the Debug.Reset_Defaults command successfully starts the debugger in the background as documented. The Debug.Stack and Debug.History Commands no longer cause a stopped task to start running when the debug option Freeze_Tasks is True. 7.10. Changes to Session Switches String-valued switches are now case-sensitive. For example, the value of switches such as Queue.Footer or Session_Ftp.Remote_Directory now preserve upper- and lowercase letters as entered by the user. There are two new session switches: * Session.Flash_Screen Controls whether the terminal flashes when the Environment discovers an error. When the switch is set to True, the terminal flashes in reverse video instead of beeping when an R September 1990 35\f Rational Environment Release Information error is discovered. For this to take effect, the Beep_On_Errors switch must be set to True. Some terminal configurations may not support this option. The default is False. This switch takes effect only at login. * Session.Push_Definition_Mark Controls whether the cursor location is pushed onto the mark stack when Common.Definition is executed. This is helpful for retracing a path through multiple definitions but may decrease the utility of marks specifically set by the user. The default is False. Changes to this switch take effect immediately. * Command_Cg.@ A new set of session switches that control the coding of declare blocks in command windows. The set of Command_Cg session switches is parallel in name and function to the set of R1000_Cg library switches, which control the coding of Ada units. There are also new library switches that affect compilation; see section 7.14.8 below. 7.11. Changes to Library Management Worlds can no longer be created within a subsystem or view. The Library.Delete and Library.Destroy commands now report an error if you try to use them to destroy individual nondefault versions. Library.Delete allows you to delete an object's default version; Library.Destroy allows you to destroy the entire object and all of its versions. The Library.Delete and Library.Destroy commands now report an error if you specify the null string ("") as the value of the Existing parameter. The Library.Copy and Library.Move commands now report an error if you specify the null string ("") as the value of the To parameter. Furthermore, the Library.Move command will not allow the null string as the value of the From parameter. (In contrast, the Library.Copy command allows the null string as a value of the From parameter, interpreting it to mean the enclosing library.) The Library.Copy command no longer copies associated files (files whose names are enclosed in angle brackets, such as <Foo>) when the Recursive parameter is True. The Environment now enforces the rule that associated files can be created only as subobjects of Ada objects (either specs or bodies). Such files can no longer be created directly in directories. 36 September 1990 R\f D_12_1_1 Release Files can now be created as subobjects of files - for example, Text.Create ("foo.bar") creates file Bar as a child of the existing file Foo. The child file Bar is listed in the directory under Foo and indented. Deleting the parent file Foo automatically deletes the child file Bar. 7.12. Access-Control Changes Setting an object's ACL no longer changes the object's "time stamp" (time of last modification). If you set the ACL of an Ada unit while you are viewing or editing it, a new version of that unit is created on which the new ACL is set. Furthermore, your read or write lock will automatically transfer to the new version (you will see the version number increment in the window banner), and the previous version with the old ACL becomes a deleted version. Similarly, if you set the ACL of an Ada unit while another user is viewing it, a new version is created on which the new ACL is set. However, the other user continues to view the previous version, which automatically becomes a deleted version. Note that you cannot set the ACL of an Ada unit that another user is editing. Bug fixes were made so that Access_List operations that verify users and groups now check only objects of the correct subclass in !Machine.Users and !Machine.Groups. 7.13. Changes to Links Management Commands from package Links can no longer be used to add individual links to a view (you must use CMVC import operations instead). You must now have read access (R) to a world to view its links and owner access (O) to change its links. Commands in package Links now log messages to notify you of successful completion. 7.14. Compilation Changes 7.14.1. Promotion A new procedure spec is created when you promote the body of a library procedure that is in the source state and neither frozen nor checked in. The new spec is created even if the procedure already had a spec; the existing spec is overwritten, if it is in the source state and neither frozen nor checked in. Whereas pragmas and full-line comments from the existing spec are preserved in the new spec, comments to the right of context clauses or the parameter profile are lost. (If you use RDF R September 1990 37\f Rational Environment Release Information annotations, it is recommended that you enter them as full-line comments.) This enhancement reduces the number of steps required for making changes to the parameter profile of a procedure: 1. Demote the spec and body of the procedure whose parameter profile is to be changed. 2. Make the desired changes in the body. 3. Repromote the body. The existing spec is overwritten by a new spec that contains the desired changes. The Compilation.Promote and Compilation.Make commands now correctly implement Scope => Load_View. This means that the correct look-through is performed when coding a main program against an activity. 7.14.2. Pragmas Pragma Main has three optional parameters: pragma Main (Target => target_name, Activity => "activity_file_name" , Elaboration_Order => "file_name") * Target. Specifies the name of the target for which the pragma is intended. This is useful during cross-development, when you may want to compile a unit as a main program for one target, but not for others. This parameter controls the applicability of the pragma in the following way: if the specified name matches the target key of the enclosing library, the pragma is used; otherwise, the pragma is ignored by the current target compiler. Leaving this parameter unspecified causes the pragma to be used wherever the unit is compiled (that is, the parameter value defaults to the target referenced by the current target key). If a unit is to be compiled as a main program for each of several targets, the unit can contain one pragma Main for each target. When the unit is compiled for one of these targets, the compiler filters out all but the pragma Main whose Target parameter matches the target key; if none of the pragma Mains specifies the current target key, the unit is not compiled as a main program. Thus, you can compile the unit for different targets without having to edit the source code to add or remove the pragma. * Activity. Specifies the name of the activity to be used when generating elaboration code for the main program. If the Activity parameter is omitted, the default activity for the current session is used. This parameter has no effect for any target other than the R1000. 38 September 1990 R\f D_12_1_1 Release * Elaboration_Order. Allows the user to specify additional ordering constraints for the elaboration order. This parameter specifies the name of a file that is in the same format as the elaboration-order listing file (an indirect naming file). Units will be elaborated in the order in which they occur in the elaboration-order file. This parameter has no effect for any target other than the R1000. A new pragma, pragma Case_Method, allows users to specify the search strategy (Linear_Search, Binary_Search, or Jump_Table) to be used for case statements. When no search strategy is specified, the compiler will choose an appropriate method. See Appendix F for more details. Pragma List and pragma Page are now supported by Compilation.Compile. A new pragma, pragma End_Of_Unit, can be used to specify the boundary between adjacent compilation units that are stored in a text file. For example, assume that you are transferring compilation units from a text-based computer system to the R1000, and one of the transferred text files contains multiple compilation units separated by comments and pragmas. Before using Compilation.Parse to parse this file, you can insert pragma End_Of_Unit between the adjacent units to clarify which of the comments and pragmas belong at the end of the preceding unit and which belong at the beginning of the following unit. After the units have been parsed, pragma End_Of_Unit is automatically removed. If you omit pragma End_Of_Unit, the Environment parses interunit pragmas and comments by dividing them at the first full-line comment (a comment that stands alone on a line and is not the continuation of a right-trailing comment above it). All pragmas and comments up to (but not including) such a comment are put at the end of the preceding compilation unit, and the remaining pragmas and comments are put at the beginning of the following compilation unit. 7.14.3. Units in the Archived State Bugs were fixed with respect to the way units in the Archived state are handled. An archived unit can now be promoted to the source state even if it contains syntax errors that prevent its type from being known. No attempt is made to install the stub of an archived unit when it is promoted to source. It is recommended that you promote an archived unit to the source state before promoting it to any other state; doing so will permit error messages to be displayed if the second promotion fails. Finally, the Library.Reformat_Image command can be used to reformat the image of an archived unit; in the process, this command also promotes the unit to the source state. R September 1990 39\f Rational Environment Release Information 7.14.4. Program Library Compilation information about code views and loaded main programs is now stored in a new underlying mechanism called a program library, which replaces code databases. Because of this new mechanism: * Code views and loaded main programs can now be debugged using the full capabilities of the Rational debugger, provided that the original Ada units still exist in the same location and have not been recompiled since the creation of the code view/loaded main program. * Code views and loaded main programs now consume less disk space and are about five times faster to create. Note that if you need to create code views and loaded main programs that can be copied to machines running the D_10_20_0 Environment, you must create them so that they have code databases as well as program libraries. To do this, you must set both of the following switches to True for the appropriate libraries, as described below: R1000_Cg.Delta1_Code_View_Compatibility := True R1000_Cg.Retain_Delta1_Compatibility := True When creating a code view, you must set these switches in the load view from which the code view is to be created. When creating a loaded main program, you must set the first switch for the library that is to contain the loaded main program; you must set the second switch for the library containing the main subprogram as well as for the library that is to contain the loaded main program (these may, but need not, be different libraries). Note that the code database for loaded main programs and for code views are not visible objects. See also sections 7.14.8, 7.15.7, and 7.21.2. 7.14.5. Switch-Dependent Changes to the R1000 Compiler The D_12_1_1 release of the Environment contains a major revision of the R1000 compiler. This version of the compiler has been validated under release 1.10 of the Ada validation suite (ACVC 1.10) and includes significant new features, improved generated-code quality, and numerous bug fixes. Certain of these new features and bug fixes are available only when explicitly enabled by a switch. This is because enabling these features and bug fixes causes the compiler to produce code that is incompatible with the code generated by previous versions of the compiler. In the D_12_1_1 release of the Environment, these features and fixes are disabled by default, so that the D_12_1_1 compiler generates code that is compatible with D_10_20_0 and earlier compilers. This allows sites with existing compiled code (or with R1000s that have not yet been upgraded to 40 September 1990 R\f D_12_1_1 Release D_12_1_1) to take full advantage of the revised compiler at their convenience. Note that validation under ACVC 1.10 applies only when the new features and fixes are enabled. Following are the new features that are available only when explicitly enabled: * Unlimited code-size capacity. Previous versions of the compiler limited the size of the generated code for a single compilation unit. When enabled, there is no limit on the size of the generated code for a single unit. * Expanded support for representation clauses: - Full support for enumeration representation clauses. - Full support for dynamic storage-size length clauses for access types. (Static clauses for access types are always fully supported without having to be explicitly enabled; see section 7.14.7.) - Full support for dynamic and static storage-size length clauses for task types. - Full support for small length clauses for fixed-point types. - Full support for size-length clauses for fixed-point types. (Size-length clauses for integer, enumeration, and access types are always fully supported without having to be explicitly enabled; see section 7.14.7.) - Restricted support for size-length clauses for floating-point, array, record, and task types. (Such clauses are valid only if they specify the default sizes for the relevant types; see section 7.14.7 for further commentary.) Following are the bug fixes that are available only when explicitly enabled (examples of the effects of these bug fixes are given in section 10): * A discriminated type can be constrained prior to the complete type declaration. * Exceptions declared in generic instances are distinct. * When generic formal subprograms are called, parameter subtype checking is made against the actual generic subprogram's parameter profile rather than that of the generic formal subprogram. To cause the compiler to generate D_10_20_0-compatible code in a given library (thereby disabling the new features and fixes listed above), use the default value for the following new R September 1990 41\f Rational Environment Release Information library switch: R1000_Cg.Retain_Delta1_Compatibility := True You should use the default value if: * You have existing code that was compiled using the D_10_20_0 compiler and you do not need to take advantage of the new features and fixes. * You are creating code views and/or loaded main programs that must be copied to an R1000 that still has the D_10_20_0 Environment. In this case, you must also set the R1000_Cg.Delta1_Code_View_Compatibility switch to True. To enable the new features and fixes, obtain better code quality, and thereby permit the compiler to generate code that is incompatible with the D_10_20_0 compiler, set the switch to False in the appropriate library, view, or model: R1000_Cg.Retain_Delta1_Compatibility := False You should set the switch to False if: * You are starting new development that will not need to be copied to D_10_20_0 systems. * You have existing code that was compiled under D_10_20_0, but you need to take advantage of new features and bug fixes and/or you need to use an ACVC 1.10-validated compiler. To convert existing code, you must set the switch to False in each of the affected libraries or views, demote the units to the installed state, and then repromote them to the coded state. Code views cannot be recompiled and therefore should be destroyed. The spec, body, and all subunits of a given library unit are always coded compatibly with the spec. That is, the current value of the R1000_Cg.Retain_Delta1_Compatibility switch is consulted only when the spec is coded; that same value is used when the other parts are coded, regardless of the actual switch value at the time. All units coded under previous versions of the compiler are considered to have been compiled with the Retain_Delta1_Compatibility switch set to True. Note that units coded with one setting of the switch may reference units coded with the switch set the other way. However, there is one restriction: when a main program is prelinked, a check is made to ensure that each unit in a spec view was coded with the same switch setting as the corresponding unit in the load view. The compatibility checker also makes this check when checking load view/spec view compatibility. 42 September 1990 R\f D_12_1_1 Release To avoid confusion, it is recommended that you use the same switch setting for all units in a given view. Furthermore, to prevent problems with spec view/load view compatibility, it is recommended that you use the same switch setting for all views in a given subsystem. 7.14.6. Switch-Independent Changes to the R1000 Compiler The following R1000 compiler changes are in effect regardless of the value of the R1000_Cg.Retain_Delta1_Compatibility switch: * The D_12_1_1 compiler now elaborates units in the closure of a main program in a different order from that used by the D_10_20_0 compiler. Both the D_10_20_0 and D_12_1_1 elaboration orders are legal; therefore, the change in elaboration order should not cause legal Ada programs to fail. (Erroneous programs that depend on a particular elaboration order may fail as a result of this change, however.) You can use the Elaboration parameter of pragma Main to cause the D_12_1_1 compiler to use an elaboration order other than the default. * The R1000 compiler now provides restricted support for size-length clauses for floating-point, record, array, and task types. Such clauses are valid only if they specify the default sizes for the relevant types. In contrast, the D_10_20_0 compiler ignored these clauses without imposing any restrictions on the sizes that could be specified. See section 7.14.7 for further commentary. * Functions that return results of a locally declared subtype no longer raise unhandled exceptions at runtime. * Constraint_Error is raised instead of Numeric_Error on almost all constraint checks. 7.14.7. Representation Clauses The D_12_1_1 compiler provides the following kinds of support for representation clauses: * Full support is provided for up to ten kinds of representation clauses. Such clauses can be used to change the way the compiler represents a given type. Note that: - Six of these clauses are supported only if new compiler features are explicitly enabled by setting the R1000_Cg.Retain_Delta1_Compatibility switch to False. - The other four clauses are supported regardless of the switch setting. These four clauses are supported exactly as they were in the D_10_20_0 release of the compiler. R September 1990 43\f Rational Environment Release Information The "Appendix F for the R1000 Target" describes the valid representations that can be specified in these clauses. Clauses that specify invalid representations produce errors unless the Ignore_Invalid_Rep_Specs switch is set to True. * Restricted support is provided for four kinds of representation clause. Such clauses are accepted only if they specify the the representations that the R1000 compiler would otherwise use for the relevant types. This restriction applies regardless of the setting of the R1000_Cg.Retain_Delta1_Compatibility switch. This restriction is a change from the D_10_20_0 release of the compiler, which ignored these clauses regardless of the values they specified. The "Appendix F for the R1000 Target" describes the valid (default) representation of each of the relevant types. Clauses that specify invalid (nondefault) representations produce errors unless the Ignore_Invalid_Rep_Specs switch is set to True. * No support is provided for the remaining three kinds of representation clauses. Each such clause produces an error, regardless of the values it specifies, unless either the Ignore_Unsupported_Rep_Specs switch or the Ignore_Invalid_Rep_Specs switch is set to True. The following table shows the representation clauses to which the various kinds of support (full, restricted, and no support) apply. Support is indicated for the D_10_20_0 and D_12_1_1 releases of the compiler; information about the D_12_1_1 release is divided according to the value of the R1000_Cg.Retain_Delta1_Compatibility switch: Table 5 R1000 Compiler Support for Representation Clauses -------------------------------------------------------- | | | | | | | |D_12_1_1: |D_12_1_1: | | | | Retain_ | Retain_ | | | | Delta1- | Delta1- | |Kind of Clause |D_10_20_0 | _Compati-| _Compati-| | | | bility | bility | | | | = True | = False | | | | | | |Size clauses for: | | | | | | | | | | Integer type |Full |Full |Full | | | | | | | Enumeration type |Full |Full |Full | -------------------------------------------------------- 44 September 1990 R\f D_12_1_1 Release Table 5 R1000 Compiler Support for Representation Clauses (con.) -------------------------------------------------------- | | | | | | | |D_12_1_1: |D_12_1_1: | | | | Retain_ | Retain_ | | | | Delta1- | Delta1- | |Kind of Clause |D_10_20_0 | _Compati-| _Compati-| | | | bility | bility | | | | = True | = False | | | | | | | Access type |Full |Full |Full | | | | | | | Fixed-point type |No |No |Full | | | | | | | Floating-point type |Ignored |Restricted|Restricted| | | | | | | Task type |Ignored |Restricted|Restricted| | | | | | | Record type |Ignored |Restricted|Restricted| | | | | | | Array type |Ignored |Restricted|Restricted| | | | | | |Static storage-size | | | | |clauses for: | | | | | | | | | | Access type |Full |Full |Full | | | | | | | Task type |No |No |Full | | | | | | |Dynamic storage-size | | | | |clauses for: | | | | | | | | | | Access type |No |No |Full | | | | | | | Task type |No |No |Full | | | | | | |Small length clauses |No |No |Full | -------------------------------------------------------- R September 1990 45\f Rational Environment Release Information Table 5 R1000 Compiler Support for Representation Clauses (con.) -------------------------------------------------------- | | | | | | | |D_12_1_1: |D_12_1_1: | | | | Retain_ | Retain_ | | | | Delta1- | Delta1- | |Kind of Clause |D_10_20_0 | _Compati-| _Compati-| | | | bility | bility | | | | = True | = False | | | | | | |Enumeration |No |No |Full | |representation clauses | | | | | | | | | |Record representation |No |No |No | |clauses | | | | | | | | | |Address clauses |No |No |No | | | | | | |Interrupt entries |No |No |No | -------------------------------------------------------- 7.14.8. Compiler Switches When the Reject_Inevitable_Exceptions switch is set to True, it now overrides the value of the Flag_Inevitable_Exceptions switch. Thus, inevitable exceptions are: * Ignored if both switches are False * Flagged with a warning if Flag_Inevitable_Exceptions is True and Reject_Inevitable_Exceptions is False * Flagged with an error if Reject_Inevitable_Exceptions is True, regardless of the value of Flag_Inevitable_Exceptions There are new library switches that affect compilation: * R1000_Cg.Retain_Delta1_Compatibility When True (the default), causes the D_12_1_1 compiler to produce code that is compatible with previous releases, thereby disabling the new compiler features and bug fixes listed in section 7.14.5. When False, this switch enables all of these new features and bug fixes in the D_12_1_1 compiler, thereby causing the compiler to produce code that is incompatible with previous releases. Note that validation under ACVC 1.10 applies only when the switch is set to False. 46 September 1990 R\f D_12_1_1 Release * R1000_Cg.Delta1_Code_View_Compatibility When False (the default), causes code views and loaded main programs to be compatible with only the D_12_1_1 compiler. When True, causes the creation of code views and loaded main programs that can be copied to machines running the D_10_20_0 compiler: - To create a compatible code view, this switch must be set to True for the load view from which the code view is to be created; furthermore, R1000_Cg.Retain_Delta1_Compatibility must also be set to True for this load view. For more information about code views, see section 7.21.2. - To create a compatible loaded main program, this switch must be set for the library that is to contain the loaded main program. Furthermore, the R1000_Cg.Retain_Delta1_Compatibility switch must also be set to True for both the library that contains the main subprogram and the library that is to contain the loaded main program (these may, but need not, be different libraries). * R1000_Cg.Check_Compatibility When True (the default), spec/load view compatibility is checked whenever a main program is coded. As a result, programs containing incompatibilities will now fail to code, even if they used to execute successfully. To permit programs containing incompatibilities to code, you must set the switch to False. * R1000_Cg.Full_Debugging When False (the default), causes the compiler to use certain optimizations that produce faster code but also restrict the use of the debugger. In particular, the optimized compiler generates code only for a subset of constructs; consequently, under the debugger, single-stepping appears to skip statements, and breakpoints cannot be set in certain places. When True, this switch suppresses the compiler optimizations, thereby enabling full use of the debugger on the produced code. * Semantics.Ignore_Invalid_Rep_Specs When False (the default), all invalid representation specifications are flagged as errors, thus preventing the units that contain them from being installed. When True, both invalid and unsupported representation specifications are flagged with warning messages in the log and are otherwise ignored. (Setting this switch to True overrides the value of the Ignore_Unsupported_Rep_Specs switch.) R September 1990 47\f Rational Environment Release Information Representation specifications are considered invalid if they do not conform to the restrictions specified in the "Appendix F for the R1000 Target." For most purposes, the Ignore_Invalid_Rep_Specs switch and the Ignore_Unsupported_Rep_Specs switch should have the same value. * R1000_Cg.Package_Integration When False (the default), a separate module (an R1000 task) is generated for each of a set of nested packages. When True, the code generator treats each nested package (whenever possible) as if all of its declarations were declared directly within the parent package. This optimization mainly saves space, but it also eliminates the time required to activate another module. This optimization is not possible if the nested package contains tasks or an initialization block or has a separate body. Code generated with this switch set to True is not compatible with code generated by D_10_20_0 compilers. A new set of session switches with the prefix Command_Cg controls the coding of declare blocks in command windows. The set of Command_Cg session switches is parallel in name and function to the set of R1000_Cg library switches, which control the coding of Ada units. 7.15. Archive Changes 7.15.1. Specification of Objects to Be Archived The Archive.Restore command now accepts an indirect file of object names. Archive.Copy will no longer allow you to copy an object onto itself; that is, the following combination of parameters is prohibited: Archive.Copy ("local_name", "*", "*"); Archive will no longer copy a subsystem onto an existing subsystem unless the Replace option is specified. Overwriting an existing subsystem can cause inconsistencies among the CMVC database, views, and import relationships. Although you are not prevented from doing so, it is recommended that you not copy a view onto another view. Doing so overwrites not only user-defined objects, but view state as well. In particular, this may mean that information may be lost about the referencers of the overwritten view. To copy just the user-defined objects in a view, use a suitable naming expression, such as "view_name.units". 48 September 1990 R\f D_12_1_1 Release 7.15.2. Assignment of Access Control to Restored Objects Restore operations (such as the Archive.Restore command and the restore portion of the Archive.Copy command) now assign the ACLs of restored objects differently. In previous releases, the default was to assign each restored object its original ACL (the ACL with which the object was saved). In D_12_1_1, the default is to assign ACLs as follows: * Objects restored into views always inherit their ACLs from the context into which they are restored. This preserves the ACLs that are assigned by CMVC access control. Furthermore, whole views and subsystems are restored with their CMVC access-class assignments. * Objects restored outside subsystems keep the ACLs with which they were saved, unless they overwrite existing objects. In this case, the restored objects are given the ACLs of the objects they overwrite. For objects restored outside subsystems, you can override the default ACL assignment with the Object_Acl, World_Acl, and Default_Acl options. As in previous releases, you can use these options to specify the new (default) ACL to be assigned, or you can specify the literal values Archived, Inherit, or (new in D_12_1_1) Retain: * The Archived value assigns each restored object the ACL with which it was saved, regardless of whether it overwrites an existing object. * The Inherit value causes each restored object to inherit its ACL from the context into which it is restored (this is the default - and only - behavior for objects restored into views). * The Retain value causes each restored object to keep the ACL with which it was saved, unless it overwrites an existing object. In this case, the restored object is given the ACL of the object it overwrites (this is the default behavior for objects restored outside views). Under certain circumstances, a restore operation now sets an object's ACL immediately after the object is restored, instead of waiting until the end of the operation. Specifically, an object's ACL is set immediately only if it provides sufficient access for the archive job to complete successfully. Otherwise, the ACL is set after the archive job has completed what it needs to do. 7.15.3. Specification of Tape-Drive Devices As is explained in section 2, certain R1000s can be upgraded to have two tape drives. Accordingly, you can now specify a naming expression for the Device parameter in the Save, List, and R September 1990 49\f Rational Environment Release Information Restore commands in order to indicate which tape drive the operator should use. In previous releases, only the special default value "MACHINE.DEVICES.TAPE_0" could be used to initiate a tape-mount request; any other string was interpreted as a library name. Now, however, you can replace the default value with a fully qualified pathname to reference a specific tape drive. (A fully qualified naming expression begins with !; in contrast, the default special string value omits the !.) For example, assume that your R1000 has two tape drives with logical numbers 0 and 3. To request that the operator use tape drive 3, you can specify the Device parameter with the fully qualified name "!Machine.Devices.Tape_3". The resulting tape-mount request will then contain the following message field: Additional Info => Use tape drive 3 Note that this message field merely displays a suggestion to the operator; the tape drive that is actually used is determined by the operator's response to the remainder of the tape-mount request. As in previous Environment releases, the default string value causes a tape-mount request to be displayed with no special instructions to the operator. Any naming expression that does not reference a tape drive will be interpreted as a library name. See also sections 7.19.4 and 7.20 for other information pertaining to R1000s with two tape drives. 7.15.4. Specification of Remote Devices The Device parameter in the Save, List, and Restore commands can now be used to specify a remote device - that is, a library or a tape drive on another R1000. For example, assume you are logged into an R1000 called M_1, which is the machine onto which objects are to be restored. Assume further that the tape drive you want to use is on an R1000 called M_2, which is connected to M_1 through the network. Then you can use the following Device parameter to specify the default drive on M_2: Device => "!!M_2!Machine.Devices.Tape_0" Whereas the device is read on M_2, the data is sent through the network and restored on M_1. Note that if you insert the remote R1000 name in front of the default Device value (MACHINE.DEVICES.TAPE_0), you must also insert an exclamation mark (!) between the R1000 name and that value. You can also save objects to devices on other machines. For example, assume you are entering the Save command on M_1 to save objects that reside on that machine. Then the following Device parameter causes the Data and Index files to be saved in a directory on M_2: 50 September 1990 R\f D_12_1_1 Release Device => "!!M_2!Some_Directory 7.15.5. Archive Options The Options parameter in various Archive commands accepts new options: * Delta1 A Boolean option for the Archive.Save command. When True, writes a tape that can be restored on an R1000 that is still running the D_10_20_0 release of the Environment. Setting this option to True is necessary only if the tape will contain loaded main programs or code views. Because Environment releases are upward-compatible, a tape made with the option can also be restored on R1000s with later Environment releases. * Enable_Privileges A Boolean option for the Archive.Copy command. When True, causes the copy operation to attempt to enable privileges. Enabling privileges allows the command to override access control when reading and creating objects. Privileges can be enabled only if the copying username belongs to the predefined group called Privileged. Note that this option enables privileges for all of the identities associated with the command, including the identities of any archive servers that are invoked on other machines. In contrast, entering the Operator.Enable_Privileges command enables privileges only for the initiating username on the current machine. * Links[=worlds] An option for the Archive.Copy, Archive.Restore, or Archive.Save command; specifies that the command is to copy only the links for each of the specified worlds, without copying the worlds themselves. Copying with the Links option is a more powerful alternative to using the Links.Copy command, which copies links among worlds on the same R1000. In contrast, copying with the Links option allows you to copy links between R1000s. If the option name is specified by itself (that is, if the worlds portion of the option is omitted), then the command copies the links of all worlds specified by the Objects parameter. An error is generated if the Objects parameter specifies no worlds. To copy other objects along with the links from one or more worlds, you can specify the world names as the value to the Links option. * Require_Parents R September 1990 51\f Rational Environment Release Information A Boolean option for the Archive.Copy or Archive.Restore command. When True, prevents objects from being copied unless the required destination context already exists. This option overrides the default command behavior, which is to create any missing hierarchical structure (for example, nested libraries) that is required to copy the objects under the desired names. * Uncontrol A Boolean option for the Archive.Copy or Archive.Restore command. When True, permits controlled objects to be overwritten by making them uncontrolled in the destination view for the duration of the copy operation. (The overwritten objects are automatically made controlled again at the end of the operation.) This option has no effect unless the Replace option is also specified. Specifying the Uncontrol option guarantees that controlled objects are overwritten. However, making the objects uncontrolled severs them from the objects to which they are joined. Furthermore, when these objects are recontrolled, they are given new reservation tokens, so that their change history is effectively lost. Note that when the Replace option is used without the Uncontrol option, an attempt is made to check out the objects in question, thereby preventing loss of history. The Uncontrol option is subject to CMVC access control. * Volume=volume id An option for the Archive.Copy or Archive.Restore command; specifies the disk volume on which to create destination worlds. Each disk volume is identified by an integer between 1 and 31; for example, a four-disk system has disks 1, 2, 3, and 4. Omitting this option is equivalent to specifying the value 0, which instructs the operation to pick the disk volume with the most free space. 7.15.6. CMVC Access Required by Archive Commands Restore operations now check CMVC access when restoring a subsystem or view: * To restore a view into an existing subsystem, the identity of the restore job (or the archive server job) must belong to a group that has Owner access for the subsystem into which the view is restored. (The Owner access class is defined in the new package Cmvc_Access_Control.) * To restore a subsystem into a world, the identity of the restore or archive server job must belong to a single group that has RCOD access to the world in which the subsystem is to be restored as well as RW default access to this world. 52 September 1990 R\f D_12_1_1 Release The Archive.Save and Archive.Copy commands now check CMVC access when saving and copying subsystems and views. * To save a view, the identity of the archive job must belong to a group that has Reader access to that view. * To save/copy a subsystem and the views in it, the identity of the archive job must belong to a group that has Reader access to the subsystem and to each of the views to be archived. 7.15.7. Archiving Code Views and Loaded Main Programs If you need to transfer code views or loaded main programs from the D_12_1_1 Environment to a machine running the D_10_20_0 Environment, you can do so only if you have created them under special switch settings. This is due to the program-library mechanism (see section 7.14.4). Furthermore, if you are archiving using Archive.Save, you must specify the Delta1 option in the command's Options parameter, although this option is not required for Archive.Copy. Note that special steps are required for code views and loaded main programs because archiving them involves transferring code segments. In contrast, archiving ordinary compiled Ada units involves transferring them as source and then optionally recompiling them on the destination R1000. The following steps show how to create and save a code view (or a loaded main program) in a D_12_1_1 Environment so that you can restore it in either a D_10_20_0 or a D_12_1_1 Environment: 1. Set both of the following switches to True for the appropriate libraries: * R1000_Cg.Delta1_Code_View_Compatibility := True R1000_Cg.Retain_Delta1_Compatibility := True When a code view is created, these switches must be set in the load view from which the code view is to be created. When a loaded main program is created, the first switch must be set for the library that is to contain the loaded main program; the second switch must be set for the library containing the main subprogram as well as for the library that is to contain the loaded main program (these may, but need not, be different libraries). 2. Create the desired code view (or load the main program). 3. Enter the Archive.Save command with the Delta1 option: Archive.Save (Objects => loaded_mains_or_code_views, Options => "Delta1, R1000"); R September 1990 53\f Rational Environment Release Information If you omit the Delta1 option from the Archive.Save command, a Nonexistent_Page_Error exception is raised when you attempt the restore operation on a D_10_20_0 machine. To copy a code view or a loaded main program from a D_12_1_1 Environment to a D_10_20_0 Environment, follow steps 1 and 2 above and enter the Archive.Copy command without the Delta1 option: Archive.Copy (Objects => loaded_mains_or_code_views); No extra switch settings or archive options are required for archiving code views and loaded main programs from a D_10_20_0 Environment to a D_12_1_1 Environment; the copied objects are treated as if they were compiled with both of the above switches set to False. See also sections 7.14.8 and 7.21.2. 7.15.8. Miscellaneous Archive Changes Copied objects that were frozen at their source are now refrozen at their destination. In D_10_20_0, objects that were frozen in a primary subsystem were restored as frozen in a secondary only if the Promote option was also specified. Now there is no need to give the Promote option for this purpose. 7.16. Changes to !Io.Text_Io The Text_Io.Open command has been changed to conform to the LRM spec. In particular, the Mode parameter for this command now has no default value, so the command now has the following specification: procedure Open (File : in out File_Type; Mode : File_Mode; Name : String; Form : String := ""); Commands in package Text_Io can now be used to open and read switch files, activities, work orders, work-order lists, and ventures as if they were text files. This is equivalent to using Display-type commands (such as Switches.Display) to produce a textual image of such objects. Such textual images are useful because you can perform operations like File_Utilities.Difference on them. 7.17. System-Management Changes See sections 7.19 and 7.20 for changes pertaining to system backups and other tape interfaces. 54 September 1990 R\f D_12_1_1 Release 7.17.1. Expiration of Operator Password Special accommodation is now made for Operators who did not change their passwords before the old passwords expired. If the Operator tries to log in with an expired password (and no current password exists), a message to this effect is displayed and a login prompt appears requesting an authorization code. The Operator can obtain a unique authorization code from the Rational Response Center and enter this code at the appropriate prompt. Note that: * The Operator must know the old, expired password. * The authorization code is valid only for a specific machine on the current date. * The authorization code is case-sensitive (all uppercase). Note that it may also be possible for the Operator to simply log in as another user and use the Operator.Change_Password command to set a new password. However, the above login process is the only solution if all user passwords have expired. 7.17.2. Mechanism for Summarizing Logged Tape Errors Package !Tools.System_Availability'Spec_View.Units.System_Report has been enhanced so that the System_Report.Generate procedure can now summarize the number of tape errors that have been logged to the system error log over the specified period of time. The summary of logged tape errors is displayed when you specify the value System_Report.Tape_Mounts for the Report_Type parameter. You can use the summarized tape-error information to evaluate the quality of 9-track tapes on which important information has been recorded. For example, you can execute this procedure after performing an archive on a 9-track tape drive to determine the likelihood of restoring the archive. Note that this tool is inappropriate for evaluating the quality of 8-mm cartridge tapes because the kinds of errors that this tool summarizes are not logged by 8-mm cartridge tape drives. Although this command can be used to evaluate quality of the tapes used for a backup, it is recommended that you use the new Verify_Backup command to determine whether a backup can actually be restored. See section 6.11. Each time a tape is written or read, tape errors are logged to a system error log file in !Machine.Error_Logs. Among these tape errors, two types are of particular interest: * Read-data retry errors are logged when a read operation fails to read a given block and has to repeat the attempt. Note that a read operation is aborted on the thirteenth consecutive retry error. Thus, twelve such errors are logged before a read operation fails. R September 1990 55\f Rational Environment Release Information * Write-data retry errors are logged whenever a write operation cannot write a given block and has to traverse to another block to repeat the attempt. Note that a write operation is aborted on the thirteenth consecutive write-data retry error. Thus, twelve such errors are actually logged before a write operation fails. The System_Report.Generate procedure scans the appropriate files in !Machine.Error_Logs and summarizes the logged errors on a per-operation basis. The summarized information is reported in a display such as the following, where each entry represents a single read or write operation (the columns are explained below). In this example, the tape operation on volume 043506 has had enough errors to indicate a significant problem, whereas the tape operation on volume 043509 has actually failed: Request Time Mount Wait Processing Volume Density Errors ============== ========== ========== ====== =========== ========= 90/01/13 08:30 00:07 00:26 043500 GCR_6250CPI 143 90/01/13 09:02 00:26 00:07 043501 GCR_6250CPI 1 90/01/13 09:35 01:05 00:39 043502 GCR_6250CPI 216 90/01/13 11:19 00:20 00:07 043503 GCR_6250CPI 5 90/01/13 11:46 00:27 00:25 043504 GCR_6250CPI 3 90/01/13 12:38 00:26 00:07 043505 GCR_6250CPI 3 / 3 / 13 90/01/13 13:11 00:10 00:19 043506 GCR_6250CPI 10 / 25 / 136 90/01/13 13:40 00:05 00:36 043507 GCR_6250CPI 1 / 2 /168 90/01/13 14:21 00:08 00:19 043508 GCR_6250CPI 69 90/01/13 14:48 00:29 00:07 043509 GCR_6250CPI 12 / 162 / 400 * Request Time indicates the time at which the mount request for the operation was issued. * Mount Wait indicates how long the operator took to answer the mount request. * Processing indicates how long it took to read or write the tape. * Volume indicates the tape label. * Density indicates the density with which the tape was written (for 9-track tapes only). 56 September 1990 R\f D_12_1_1 Release * Errors displays several types of error data. If this column contains only one number, that number represents the total number of errors logged for the operation. If this column contains a triple number, the leftmost number is the maximum number of consecutive retry errors encountered, the middle number is the total number of retry errors in the operation, and the rightmost number is the total number of errors of any kind. As a rule of thumb, information recorded on a 9-track tape is reliable if the tape has 5 (or fewer) consecutive retry errors, 25 (or fewer) total retry errors, and 100 (or fewer) total errors (that is, 5 / 25 / 100). If a backup tape has greater numbers of errors in these categories, it is recommended that you consult the Rational Customer Support Response Center. 7.17.3. Changes Pertaining to Operator Capability Operator capability is no longer required for report-producing operations from packages System_Backup and Scheduler. These commands are System_Backup.History, Scheduler.Display, Scheduler.Set_Wsl_Limits, Scheduler.Use_Default_Wsl_Limits, and Scheduler.Working_Set_Size. The Operator.Force_Logoff command no longer requires operator capability if the user performing the operation is the same as the user being forced off. Commands in package Operator that require operator capability and that affect machine state now report successful completion in !Machine.Error_Logs.Log@. The logged messages also report the executing user and session, if these are other than System. 7.17.4. Changes Pertaining to Login Limits The number of permitted concurrent logins (sessions) for each Series 300S and 300C is set at the factory. If a user attempts to log in after the maximum number has been reached, the following message will appear: Login denied - resource restriction An existing session will have to be logged out before that user can log in. 7.17.5. Changes Pertaining to EEDB The special character $ can now be used as an argument to EEDB commands to reference the currently running release. Furthermore, the special character $$ can now be used to reference the successor to the default configuration. The R September 1990 57\f Rational Environment Release Information successor name is constructed from the default by appending or incrementing the trailing letter. The sequence of successors would be D_11_0_2 => D_11_0_2A => ... => D_11_0_2Z => D_11_0_2ZA ... EEDB now recognizes the abbreviations CDF, EM, UDF, and DTIA as representing the appropriate subsystems. 7.17.6. Miscellaneous System-Management Changes The Operator.Change_Password command now requires the new password to be different from the old password. That is, users are not permitted to make trivial changes. The Operator.Force_Logoff command now allows enough time to commit large buffers before logging off. The Operator.Shutdown command has been made more robust. Package Daemon was changed to make the DDB object manager a Weekly client rather than a Daily client. The "hard-wired" default collection thresholds have been changed. The hard-wired defaults are the values that are in effect if no collection thresholds are specified in the !Machine.Initialize_Daemons procedure. These new default values are given in Table 6. Note that the !Machine.Initialize_Daemons procedure will automatically adjust the hard-wired values so that smaller values are set for systems with large-capacity disk drives and larger values are set for the Series 200 Model 10 with 337-megabyte disk drives. Customers should not change the values assigned by the !Machine.Initialize procedure unless advised to do so by Rational personnel. Table 6 Default Values for Collection Thresholds --------------------- | | | |Threshold | Default | | | Value | --------------------- | | | |Start_ | 15 | |Collection| | --------------------- | | | |Raise_ | 10 | |Priority | | --------------------- | | | |Stop_Jobs | 7 | --------------------- 58 September 1990 R\f D_12_1_1 Release Table 6 Default Values for Collection Thresholds (cont.) --------------------- | | | |Threshold | Default | | | Value | --------------------- | | | |Suspend_ | 5 | |System | | --------------------- !Machine.Initialize_Daemons now starts a new server called Smooth_Snapshots, which reduces the impact of snapshots, especially on machines with the 64-megabyte memory-expansion upgrade. The default parameter values are used for the Smooth_Snapshots procedure; these values should never be changed by customers. When you execute the Tape.Examine_Labels command with the Volume_Labels_Only parameter set to False, a diagnostic message now appears in the current output whenever the command detects an inconsistency within a data segment on an ANSI-standard labeled tape. The message attempts to explain the inconsistency. Prior to this release, the command would fail with an unhandled exception. When the command is executed with Volume_Labels_Only set to True, it no longer raises Constraint_Error when trying to unload the tape. Functions in System_Utilities now interpret the null string to mean any of a user's sessions instead of just the user's default session. For example, the command System_Utilities.Logged_In ("Fred","") returns True if Fred is logged in under any session. Similarly, the command System_Utilities.Last_Logout ("Fred","") returns the last time Fred logged out of any session. The Environment now initiates its own recovery in situations where Library.Compact_Library has accidentally been run on worlds such as !Machine.Users and !Users. Rebooting the system is no longer necessary. 7.18. Changes Pertaining to Printing You can now specify files as devices for commands in package Queue. When a file is specified, the output characters are written to that file (rather than to a printer, for example). 7.18.1. !Commands.Abbreviations.Print The !Commands.Abbreviations.Print command now has additional parameters. The Class parameter specifies a file denoting the class. The Trace_Only parameter, when True, displays the R September 1990 59\f Rational Environment Release Information Queue.Print command that is generated without actually executing it. (This allows you to review the print options that will be used before the command actually executes.) procedure Print (Name : String := "<IMAGE>"; Options : String := ""; Banner : String := "<DEFAULT>"; Header : String := "<DEFAULT>"; Footer : String := "<DEFAULT>"; Class : String := "!Machine.Lp_Class"; Trace_Only : Boolean := False); 7.18.2. Queue.Print Bug fixes were made to the Queue.Print command so that the following combination of Twoup and Wide options works properly for American standard-sized paper: Options => "Postscript => (Twoup, Wide)" The Banner page of a printout now has rows of asterisks at top and bottom, making it easier to distinguish from other printout pages. The PostScript header page is now printed either first or last, depending on the value of the Reversed option. When Reversed is True, the header page is the last page printed. When Reversed is False, the header page is the first page printed. Prior to this release of the Environment, the PostScript header page was always printed last. Bug fixes were made so that long filenames no longer overlap the page number in the heading, even when Ada units are printed using the Fancy option under PostScript processing. Bug fixes were made so that long Ada units can be printed without incurring storage/allocation errors. 7.19. System Backup Changes The specifications for the various backup commands remain as they are in D_10_20_0, so operators will continue to initiate backups the same way. However, the implementation of these commands has been enhanced in the present release. In particular, the procedure !Commands.Abbreviations.Do_Backup has been enhanced to take advantage of the new generic procedure !Commands.System_Backup.Backup_Generic (see section 6.10). Furthermore, all backup commands (both in !Commands.Abbreviations and in !Commands.System_Backup) have been enhanced to take backups on the 8-mm cartridge tape drive as well as on the 9-track tape drive. 60 September 1990 R\f D_12_1_1 Release 7.19.1. Improved Do_Backup Implementation The procedure !Commands.Abbreviations.Do_Backup has been enhanced to take advantage of the new generic procedure !Commands.System_Backup.Backup_Generic (see section 6.10). This enhancement affects the other backup commands in !Commands.Abbreviations, which call Do_Backup - namely, Full_Backup, Primary_Backup, and Secondary_Backup. As in previous Environment releases, the Do_Backup procedure starts the specified kind of backup at the specified time, adjusting certain system settings for the duration of the backup. In D_12_1_1, Do_Backup'Body now adjusts these system settings by instantiating the formal procedures that are associated with !Commands.System_Backup.Backup_Generic. These formal procedures are instantiated as follows: * The Backup_Starting formal procedure, which executes as the backup begins, broadcasts a message announcing the backup to all users, saves the current memory scheduler and snapshot settings, and turns off memory scheduling and snapshot warnings. * The Backup_Finishing formal procedure, which executes as the backup ends, restores memory scheduling and snapshots using the saved settings. The system manager can edit Do_Backup'Body to further customize system settings for the duration of backups. Section 6.10 presents several possible customizations. Note that all backup procedures now display progress messages in the current output window to indicate when the backup starts and finishes each disk volume. 7.19.2. Support for 8-Millimeter Cartridge Tape Drive All backup operations (both in !Commands.Abbreviations and in !Commands.System_Backup) have been enhanced to take backups on the 8-mm cartridge tape drive as well as on the 9-track tape drive. Each backup taken on the 8-mm cartridge tape drive requires only a single tape cartridge, in contrast to the multiple tape reels required for backups taken on a 9-track tape drive. Consequently, the 8-mm cartridge tape drive permits unattended backups because the operator can leave after entering the Do_Backup command and mounting the tape. Unattended backups also take significantly less time because the time spent changing tapes is eliminated. For example, a backup that takes 8 hours to complete on a 9-track tape drive may take as little as 4 hours on an 8-mm cartridge tape drive. When the 8-mm cartridge tape drive is used, slight differences appear in the backup tape-mount request. In particular, the tape-mount request does not prompt for a separate "blue tape"; R September 1990 61\f Rational Environment Release Information instead, a backup index is written immediately following the data on the same 8-mm cartridge tape. Section 7.20 describes the effect of the 8-mm cartridge tape drive on Environment tape interfaces other than backups. 7.19.3. Guidelines for Choosing Tape Size To ensure unattended backups when using the 8-mm cartridge tape drive, it is recommended that you choose a single tape large enough to hold the entire backup. Guidelines for choosing the appropriate tape size are given in Table 7. To use this table, you need to know the total number of disk blocks that are used on your machine. You can obtain this information using the Operator.Disk_Space command. Note that a tape larger than the minimum can always be used. Tape sizes are given in several ways, depending on the brand of tape. EXABYTE tapes are identified by their length in meters. Sony tapes are identified by their cartridge type, which correlates to minutes of playing time (for example, P6-15MP and P5-15MP indicate 15-minute tapes). P6 mode tapes, which are used in the United States, have a smaller capacity in megabytes than P5 mode tapes, which are used (at least) in Europe. Both P5 and P6 tapes are listed in the table. Table 7 Minimum 8-mm Cartridge Tape Size for Full Backups ---------------------------------------- | | | |Total Number| | |of |Recommended Minimum Tape | |Disk Blocks |Size | |Used | | ---------------------------------------- | | | | 0-235,500|Sony P6-15MP Video 8 | | |Sony P5-15MP Video 8 | | |EXABYTE 8MM Data Cartridge | | |15 m | ---------------------------------------- | | | |235,501-471,|Sony P6-30MP Video 8 | | 500|Sony P5-30MP Video 8 | | |EXABYTE 8MM Data Cartridge | | |54 m | ---------------------------------------- | | | |471,501-943,|Sony P6-60MP Video 8 | | 500|Sony P5-60MP Video 8 | | |EXABYTE 8MM Data Cartridge | | |54 m | ---------------------------------------- 62 September 1990 R\f D_12_1_1 Release Table 7 Minimum 8-mm Cartridge Tape Size for Full Backups (cont) ---------------------------------------- | | | |Total Number| | |of |Recommended Minimum Tape | |Disk Blocks |Size | |Used | | ---------------------------------------- | | | | 943,501-1,|Sony P6-90MP Video 8 | | 415,000|Sony P5-60MP Video 8 | | |EXABYTE 8MM Data Cartridge | | |112 m | ---------------------------------------- | | | |1,415,001-1,|Sony P6-120MP Video 8 | | 887,000|Sony P5-90MP Video 8 | | |EXABYTE 8MM Data Cartridge | | |112 m | ---------------------------------------- | | | |1,887,001 or|May require multiple | | greater|cartridges for backup | ---------------------------------------- As the table indicates, machines with greater than 1,887,001 used disk blocks may require multiple tapes for backups. However, because the estimates in the table are conservative, it may in fact be possible to put an entire backup for such a machine on a single 120-minute (or 112-meter) tape. As an example, assume that Operator.Disk_Space produces the following display: Volume Capacity Available Used % Free ====== ======== ========= ======= ====== 1 625482 257433 368049 41 2 655776 255030 400746 38 3 655776 247569 408207 37 4 655776 220230 435546 33 Total 2592810 980262 1612548 37 This machine has a total of 1,612,548 used disk blocks. Therefore, this machine requires a tape such as a Sony P6-120MP tape for a single-tape backup. 7.19.4. Backups on Systems with Two Tape Drives Series 200 and Series 300S machines can optionally have both a 9-track tape drive and an 8-mm cartridge tape drive. When two kinds of tape drive are available on a single machine, the system R September 1990 63\f Rational Environment Release Information manager must decide which tape drive to use for system backups. It is important to make this decision early for two reasons: * It is recommended that the tape drive used for backups should be made the default tape drive (drive number 0). Doing so simplifies the operator's response to the backup tape-mount request, so that only a carriage return is needed for the On which drive? prompt. (See section 7.20.4.) * Incremental backups (primary and secondary) must be made on the same kind of tape drive as the full backup on which they are based. Full and incremental backups made on different kinds of tape drive are incompatible and cannot be restored together. Thus, if you make a full backup on an 8-mm cartridge tape drive, you must make all subsequent primary backups on that tape drive. If you want to switch to the 9-track tape drive, you must start by taking a full backup on that drive. 7.19.5. Restoring Backups As in previous releases of the Environment, backups that are taken on 9-track tape drives use multiple tapes - the data is written on at least one tape and the backup index is written on an additional, separate tape. (In previous Environment releases, this additional tape was called the "blue tape"; it is now referred to as the backup index tape.) When a 9-track backup is restored, the tape-mount request prompts you for the backup index tape first. The tape-mount request then prompts you for the remaining tapes in order. Backups taken on 8-mm cartridge tape drives usually require only a single tape, which contains both the data and the backup index, in that order. During restoration, when you are prompted for a backup index tape, you need mount only the sole tape cartridge. The restoration operation skips through this tape until the backup index is found. After reading the backup index, the restoration operation automatically returns to the beginning of the tape to read the data. On very large systems, a backup taken on an 8-mm cartridge tape drive may require multiple tapes. The backup operation writes to these tapes as if they were logically a single tape - that is, the backup index is written immediately following the data on the last tape. Consequently, restoration of multitape backups is a two-pass process. The tape-mount request first prompts you to mount each tape in sequence so that the tapes can be skipped through until the backup index is found. Then the tape-mount request prompts you to mount the sequence again so that the tapes can be read and the data restored. During restoration on an 8-mm cartridge tape drive, progress messages appear on the operations console. These messages report when the backup index has been located and when it is being processed; subsequent messages report when the backup data has 64 September 1990 R\f D_12_1_1 Release been located and when it is being processed. Note that a new command called Verify_Backup is available for determining whether backups are complete and restorable; see section 6.11. 7.19.6. Bug Fixes Pertaining to Backup The new implementation of Do_Backup corrects several bugs from D_10_20_0. In particular, the time specified by the Starting_At parameter is now absolute rather than relative to the time at which the tape is mounted. Consequently, the actual backup now begins at the Starting_At time no matter when the tape is mounted (as long as it is mounted before the backup is scheduled to start). Furthermore, because of the new Backup_Starting formal procedure, the message announcing the backup is now displayed when the actual backup begins rather than when the Do_Backup command is executed. Another important bug fix is that secondary backups now work correctly. Secondary backups are based on primary backups, just as primary backups are based on full backups. In previous releases, secondary backups did not work properly. 7.20. General Tape-Related Changes All Environment tape interfaces (packages Tape, Archive, System_Backup, and so on) now accommodate the 8-mm cartridge tape drive in addition to the 9-track tape drive. (See section 7.19.2 for information specifically about backups taken on the 8-mm cartridge tape drive.) 7.20.1. Default Tape Drive Many prompts and commands require that you specify a tape drive using its logical tape-drive number. The default value for these prompts and commands is always drive number 0. Therefore, by convention, the tape drive whose number is 0 is the default drive. When a machine has both an 8-mm cartridge tape drive and a 9-track tape drive, the system manager must decide which drive is to serve as the default. The default drive is then assigned drive number 0, and the remaining drive can be assigned a drive number from 1 through 3. The default drive should be the tape drive that will be used for system backups. Logical tape-drive numbers are assigned using the IOP ENVIRONMENT menu during the boot process. The initial assignments are usually set by Rational technical representatives, although system R September 1990 65\f Rational Environment Release Information managers can change the assignments during subsequent system boot processes. System managers who want to do this should contact their Rational technical representatives for assistance. 7.20.2. Specifying a Tape Drive through Various Commands Several commands in package Tape have a Drive parameter through which the user may specify the tape-drive number for the desired drive. On machines with only one tape drive, the value 0 is the only meaningful value for this parameter; on machines with two drives, you can specify any number that has been assigned to a drive. For Tape commands that do not have a Drive parameter (such as Tape.Read and Tape.Write), you can use the To_Operator parameter to send the operator a request for a particular tape drive. The string that you enter is displayed in the Additional Info => field of the tape-mount request. However, this message field merely serves as a suggestion to the operator; the tape drive that is actually used is determined by the operator's response to the remainder of the tape-mount request. As described in section 7.15.3, several commands in package Archive have a Device parameter through which the user may specify where to read or write the archive's Data and Index files. On machines with two tape drives, you can now specify the Device parameter with a fully qualified naming expression (such as "!Machine.Devices.Tape_3") to request that the operator use a particular tape drive. However, such a naming expression merely serves to display special instructions in the Additional Info => field of the tape-mount request; the tape drive that is actually used is determined by the operator's response to the remainder of the tape-mount request. 7.20.3. User-Written Applications User-written applications written against Device_Independent_Io must open specific devices for reading or writing. When such applications are to perform tape operations, they must be passed naming expressions that reference a particular tape drive by its logical number. For example, the name "!Machine.Devices.Tape_0" references the default tape drive; the name "!Machine.Devices.Tape_3" references tape drive number 3. The subsequent tape-mount request displays a message indicating that the specified tape drive must be used; you cannot specify a different tape drive during the tape-mount request. In contrast, applications written against Tape_Tools do not require names that reference specific tape drives. Instead, the drive to be used is specified during the tape-mount request. When writing tape-related applications, bear in mind that tape marks written on 8-mm cartridge tapes occupy much more space than 66 September 1990 R\f D_12_1_1 Release tape marks written on 9-track tapes. In particular, each tape mark written on an 8-mm cartridge tape occupies 2 megabytes of space. Thus, when an application writes tape marks between files, writing a large number of small files can easily exhaust the space on a single tape. 7.20.4. Tape-Mount Requests A number of commands initiate a tape-mount request on the operations console. Such commands include commands from package Tape, commands from package Archive, the various backup commands, and user applications written against Device_Independent_Io and Tape_Tools. When such commands are entered on an R1000 with two tape drives, the initiated tape-mount requests differ slightly from those initiated from a single-drive machine. Certain prompts and fields appear only when machines have two tape drives. In particular, the tape-mount request initiated from a two-drive machine displays the On which drive? prompt, which asks the operator to specify the logical number of the tape drive on which the tape operation is to take place. Note that if a particular tape drive has been specified to a Tape or Archive command, the request for that drive will appear in the Additional Info => field; the operator may, but need not, specify the requested drive at the On which drive? prompt. This prompt does not appear on machines with only one tape drive. Similarly, the tape-mount verification following a two-drive tape-mount request displays the Kind of Drive field along with the label information for the mounted tape. The kind of drive is given as 8MM for 8-mm cartridge tape drives and 9_TRACK for 9-track tape drives. For example, assume that a Series 200 has been upgraded so that it has an 8-mm cartridge tape drive as well as a 9-track tape drive, and that the 8-mm cartridge tape drive is tape drive 0 (the default) and the 9-track tape drive is tape drive 3. The following is a tape-mount request and subsequent verification in which the default 8-mm tape drive is specified: Please Load Tape (Kind of Tape => CHAINED_ANSI, Direction => WRITING, Volume Set Name => BACKUP, 07-NOV-89 16:47:23 3) Is Tape mounted and ready to read labels? yes On which drive? [ 0] Info on mounted tape is (Kind of Drive => 8MM, Kind of Tape => UNLABELED_TAPE, Writeable => TRUE) OK to overwrite volume? [YES] R September 1990 67\f Rational Environment Release Information What should the volume id handling mode be? [AUTO_GENERATE] Volume id of tape is now: 007100 In contrast, the following tape-mount request and verification show that the nondefault 9-track drive has been specified: Please Load Tape (Kind of Tape => CHAINED_ANSI, Direction => WRITING, Volume Set Name => BACKUP, 07-NOV-89 16:47:23 3) Is Tape mounted and ready to read labels? yes On which drive? [ 0] 3 Info on mounted tape is (Kind of Drive => 9_TRACK, Kind of Tape => UNLABELED_TAPE, Writeable => TRUE) OK to overwrite volume? [YES] What should the volume id handling mode be? [AUTO_GENERATE] Volume id of tape is now: 007100 7.20.5. Tape-Related Messages in the Error Log In !Machine.Error_Logs.Log@, log entries pertaining to tape operations now reflect the type of drive. When the type of drive is 9 track, the entry also reports the density. Following are examples of messages reporting each kind of tape drive and density: 13:34:33 --- Tape_Handling Tape_Mounted Volume_Id=TEST1 , Type_Of_Drive=9Track, Density=PE_1600CPI 13:34:33 --- Tape_Handling Tape_Mounted Volume_Id=TEST2 , Type_Of_Drive=9Track, Density=GCR_6250CPI 12:37:05 --- Tape_Handling Tape_Mounted Volume_Id=012601, Type_Of_Drive=8mm 7.20.6. DFS Backup Backups of the Diagnostic File System (DFS) can be made on the 8-mm cartridge tape drive. If the DFS backup is to be made on a tape drive other than the default drive 0, the nondefault drive number must be specified. For example, to specify drive number 3, append /unit=3 to the backup command: CLI> backup/unit=3 68 September 1990 R\f D_12_1_1 Release Omitting the drive number causes the DFS backup to be taken on drive 0. 7.21. CMVC Changes Worlds can no longer be created within a subsystem or view. Commands from package Links can no longer be used to add individual links to a view (you must use CMVC import operations instead). 7.21.1. Activities As before, the Common.Edit command brings up a command window containing the Activity.Change command. Now, however, the prompts for this command supply as default values the names of the spec view and load view from the entry containing the cursor. Similarly, when the Common.Object.Insert command brings up the Activity.Insert command, the prompts for this command now supply the names of the subsystem, spec view, and load view from the entry you have selected. The context characters $, $$, and ^ can now be used in parameter values for commands in package Activity (such as Activity.Insert, Activity.Change, and so on). 7.21.2. Code Views Because of a new underlying mechanism called program library, code views can now be debugged using the full capabilities of the Rational debugger, provided that the original Ada units still exist in the same location and have not been recompiled since the code view was created. Furthermore, code views now consume less disk space and are about five times faster to create. By default, code views no longer contain a code database because the function of this database has been replaced by the program-library mechanism. If you need to create code views that can be copied to machines running the D_10_20_0 Environment, you can set both of the following switches to True for the load views from which the code views are to be created: R1000_Cg.Delta1_Code_View_Compatibility := True R1000_Cg.Retain_Delta1_Compatibility := True Setting these switches to True causes code views to be created with both a program library and a code database; such code views can then be copied to and used on machines that have not yet been upgraded from D_10_20_0. R September 1990 69\f Rational Environment Release Information Code views now contain an empty file called State.This_Is_A_Code_View. User-defined tools can check for this file to determine whether a view is a code view. Before this release, tools could check for the code database as an overt indication of whether a view is a code view. 7.21.3. Commands from Package Cmvc The Cmvc.Accept_Changes command now: * Produces fewer warning messages. In particular, it does not produce warnings regarding uncontrollable objects (these include objects in the State directory, stubs, and associated files). * Handles the deletion of associated files without failing. (Associated files are associated with cross-target compilation and appear enclosed in angle brackets in a library - for example, <name>.) The Cmvc.Build command is now able to preserve a view's subclass when rebuilding a view from a configuration object. In particular, a configuration object that was originally made from a combined view will now be rebuilt as a combined view. Previously, such a view would have been rebuilt as a load view. Bug fixes have been made so that each use of Cmvc.Check_In logs checkin notes only once (rather than twice) in a work order. If the Cmvc.Check_Out command fails because an object is already checked out, a message is displayed reporting the view in which the object is currently checked out. The Cmvc.Destroy_View command now: * Ensures that views are destroyed in the correct order. If the Destroy_Configuration_Also parameter is True, the command will destroy a view whether or not a configuration exists for that view in the CMVC database. * Destroys RDF views without going through the RDF policy checks that govern the demotion of units. Because destroying a view involves demoting units, such policy checks could prevent you from destroying the view. To avoid the policy checks, the Cmvc.Destroy_View command essentially sets the policy portion of the view's target key to R1000. The Cmvc.Join command now permits you to specify a view for the What_Object parameter. Specifying a view causes all of the controlled objects in that view to be joined to their counterparts (if any) in the view named by the To_Which_View parameter. The Cmvc.Make_Controlled command now: 70 September 1990 R\f D_12_1_1 Release * Does not allow stubs to be put under CMVC control. (Stubs are new or withdrawn Ada units that have temporary names assigned by the Environment; these temporary names begin with an underscore (_) - for example, _Ada_8_.) * Saves source for only four subclasses of files - namely, Text, Postscript, Log, or Markup. * Closes objects for editing before making them controlled. * Makes an object's parents controlled recursively when the object itself is made controlled. That is, not only the immediate parent library is made controlled, but also its parent library and so on, up to the view's Units directory. The Cmvc.Remove_Unused_Imports command scans the with clauses of each unit in a view to determine which imports are unused in that view. Now, however, in spec views, this command no longer scans any with clauses that occur after a pragma Private_Eyes_Only. Such clauses do not need to be scanned because no links are created for the units they reference. The Cmvc.Replace_Model command now: * Preserves the existing value of the Subsystem_Interface switch in the view whose model is being replaced. This switch determines whether a view is treated as a spec view or a load view. Thus, you can now change the model in a spec view without causing the view to be treated as a load view (and thereby corrupted). * Resolves link conflicts appropriately. That is, when you replace a model, the new model may introduce links that conflict with existing links created by imports. Such conflicts are resolved in favor of the existing, import-created links. The Cmvc.Show command now shows whether or not source is being saved in the CMVC database for the specified objects. 7.21.4. Imports Operations that perform imports now create a file called State.Imports_Image in each importing view. This file is a text file that contains the names of all of the view's imports. The file is updated each time the view's imports are changed. The State.Imports_Image file provides a mechanism that makes it possible to refresh the imports of released views. This, in turn, makes it possible to copy releases to another host out of sequence - that is, to copy a release before you have copied all of the views it imports. Similarly, it is now possible to rebuild views from their configuration objects before rebuilding their imports. In either case, you can now copy or rebuild the R September 1990 71\f Rational Environment Release Information imported views at your convenience and then use the Cmvc.Import command to reestablish the original import relationships. Note that you can consult the State.Imports_Image file to see which imported views still need to be copied or rebuilt. 7.21.5. CDB Capability Sites that develop applications on multiple hosts can now exercise an optional special control over operations that affect the compatibility databases (CDBs) of primary and secondary subsystems. This special control, called CDB capability, can be granted to one or more access-control groups that already have Owner access to the subsystems in question (for a description of Owner access, see the documentation for package Cmvc_Access_Control.) Whereas Owner access is always required to execute CDB-related commands, CDB capability provides an additional control for sites that choose to use it. To put CDB capability into effect, you must first create a file called !Machine.Cdb_Capability. You can then grant CDB capability to individual groups by granting them write access (W) to this file. A group must have Owner access to a given subsystem and write access to the !Machine.Cdb_Capability file to name the subsystem in the Cmvc_Maintenance.Make_Primary, Cmvc_Maintenance.Make_Secondary, or Cmvc_Maintenance.Destroy_Cdb command. CDB capability also controls whether a group can use the Primary and Revert_Cdb options in the Archive.Copy and Archive.Restore commands. 7.21.6. Work Orders Operations in package Work_Order now encode usernames in various work-order fields so that these names will be displayed even if the corresponding users have been deleted from the system. This applies to notes, comments, and work-order status. Usernames in the user field of a work order are not treated this way, so they will be lost if the corresponding users are deleted. 7.22. Networking Changes Changes were made in FTP to make it compatible with most UNIX FTP implementations, which require that the interchange form of a file contain a newline (CRLF) sequence at the end of the last line. This newline is added in D_12_1_1. Without it (as in D_10_20_0), UNIX-based tools cannot read a text file transferred from an R1000 via FTP. This FTP change affects transfers between R1000s running different Environment releases. When a text file is transferred using FTP and the Transfer_Type is Ftp.Ascii, Ftp.Ascii_Cc, or Ftp.Ascii_Telnet: 72 September 1990 R\f D_12_1_1 Release * An empty line is added to the end of the file upon transfer from an R1000 running D_12_1_1 to one running D_10_20_0. * If the file ends with an empty line, that empty line is removed from the end of the file upon transfer from an R1000 running D_10_20_0 to one running D_12_1_1. To avoid the effects of the FTP change when transferring files between R1000s running different releases, you can use Archive.Copy or you can use FTP with Transfer_Type => Ftp.Image or Ftp.Binary. Package Transport_Name has been enhanced so that Host_Name parameters accept strings that are host addresses in addition to strings that are host names. Higher-level tools such as those in packages Ftp, Archive, and Telnet also accept host addresses in addition to host names. A host address can be either: * An Internet address in decimal dotted notation (such as "89.64.1.230"); such an address is taken to be an address in the "TCP/IP" network * An Ethernet address in hexadecimal dashed notation (such as "08-00-14-40-AB-CD"); such an address is taken to be an address in the "Ethernet" network. Package Ftp now supports Ascii_Telnet mode. Ascii_Telnet mode is the same as Ascii mode, with the following difference: in Ascii_Telnet mode, the end of each page can be represented by the transmitted sequence CR & LF & FF. Bug fixes were made so that commands in packages Ftp or Transfer_Generic no longer fail if they receive an FTP error 532 ("need account for storing files") in response to a STOR or RETR command. Instead, they now supply an account and try again. This is particularly helpful when the FTP server is the VM Interface Program for TCP/IP, running on an IBM machine. 7.23. Miscellaneous Environment Changes The Message.Send command permits the Who parameter to be specified using standard Environment naming expressions. You can use wildcards, set notation, and so on to match one or more of the usernames listed in !Machine.Users. For example: Message.Send ("[HVZ,Loren,RK]","Hello"); Bugs were fixed in package Log to avoid raising the Storage_Error exception on large messages. Bugs were fixed in Program.Run_Job so that if you have enabled privileged mode, you can now change identities without entering the password of the new identity. R September 1990 73\f Rational Environment Release Information Bug fixes were made to package File_Utilities so that comparisons can be made among two-part Ada units (specs are compared to specs and bodies are compared to bodies). Further bug fixes were made so that Ada units can be compared to text files. The remote debugger is now more persistent about trying to contact Rational's Response Center. (This applies only to machines that are configured to have a remote debugger.) Bug fixes were made to improve the disk driver's error recovery. In package !Tools.Bounded_String, pragma Subsystem now has different parameter values: pragma Subsystem (Tools, Private_Part => Open); 7.24. Changes of Interest to RDF Users The speller dictionaries have been augmented. Furthermore, bugs were fixed so that the speller no longer counts errors twice on the last line of an image. Changes pertaining to package Abstract_Document: * Restrictions have been relaxed on the presence of both covers and paragraphs in an abstract document. * The Preview Object Editor now properly displays the image of a list containing a table. * The Preview Object Editor no longer makes the error that generates the following internal error message on the message window: Internal Error, REFRESH_LEVELS called with CURRENT_LINE_OBJECT=0 Changes pertaining to LRM interfaces: * Ada_Program.Depth_First_Traversal no longer skips over the formal parameters of subprogram renames and task entries when Major_Elements_Only is set to True. * Bug fixes were made to improve the handling of operator symbols (such as *) in package Declarations. * Bug fixes were made in the way task-type program units are handled. Changes pertaining to PDL mechanisms: * Bug fixes were made to improve error handling during failed PDL registration attempts. 74 September 1990 R\f D_12_1_1 Release * The argument parser no longer constructs indexed arguments with inappropriate index lists. * Pdl.Annotation.Argument.Corresponding_Info now returns the correct values for Complex_Name arguments. * Annotation insertion now properly places annotations on the unit declaration of a compilation unit. Requests to insert an annotation on such a unit declaration are placed before the context clause instead of between the clause and the declaration. * Design_Implementation.Complete and Design_Implementation.Format no longer update editor images only on job termination. Editor images are now updated before these operations exit. * The error-recovery mechanisms of the PDL argument parser have been enhanced by the addition of a new lexical recovery scheme to the scanner that improves support for nested text arguments. * The error diagnostics in the description-file analyzers have been improved. * PDL semantic analysis no longer allows successful completion of PDL demotion in cases where the directory operation actually failed. * Cursor analysis during PDL traversal operations no longer prevents multiline arguments from being properly resolved. * PDL.Mark_Warning now allows warning messages to be attached to Ada units during analysis. * Formal subprogram calls during PDL analysis have been reordered to enable proper stack management during traversal in PDL semantics and completion. Miscellaneous changes: * Element_Cache no longer raises the exception Write_To_Read_Only_Page during arbitrary read-only operations. * Bugs were fixed so that Element_Cache objects can be manipulated using commands from package Archive. * Document.Pathname_Of no longer causes the loss of spec or body information on linkages to Ada units. This bug was actually manifested in Abstract_Document.Extract.File_Name. * Mapping.Convert no longer causes Storage_Error to be raised when converting objects of type Target_Info that have large numbers of Ada and Document linkages. R September 1990 75\f Rational Environment Release Information 8. Documentation The D_12_1_1 release of the Environment includes three pieces of new hard-copy documentation and new or updated online help for selected features. 8.1. New Hard-Copy Documentation New hardcopy documentation consists of three tabbed sections that are to be inserted into existing documentation, as described in the following paragraphs. 8.1.1. Package Cmvc_Access_Control The hard-copy documentation for package Cmvc_Access_Control includes reference entries for each command in the package and an introduction that presents a basic usage scenario. This documentation is a separate tabbed section that you can insert into the Project Management (PM) book of the Rational Environment Reference Manual. Within that book, no specific location is presumed; the section page numbering is self-contained. 8.1.2. Appendix F for the R1000 Target The hard-copy revision of "Appendix F for the R1000 Target" has been updated for D_12_1_1 as well as restructured to conform to the sections recommended in the Reference Manual for the Ada Programming Language. In addition to discussing implementation-dependent pragmas more fully, the revision describes the default representation of each type, as well as the values that can be used in representation clauses for these types. This revision is a separate tabbed section that you can insert into the Reference Manual for the Ada Programming Language. 8.1.3. Reference Summary The Reference Summary (RS), which is Volume 1 of the Rational Environment Reference Manual, has been extensively revised up to (but not including) the Master Index. The revision includes the following new and updated sections: * Introduction to the Rational Documentation Set: Briefly describes the contents of each manual in the Rational documentation set, explains how information is organized in these manuals, and suggests how various kinds of users can find information about the Environment. 76 September 1990 R\f D_12_1_1 Release * Parameter Value Conventions: Explains the kinds of values that most Environment commands accept. It is divided into two major sections. "Referencing Environment Objects" explains naming features such as special names, context characters, wildcards, attributes, and so on. "Specifying Other Command Inputs" describes how to use the Options and Response parameters. This section is current to D_12_1_1 and supersedes the various naming sections that now exist in the other books of the Reference Manual. * Environment Specifications: Provides a quick reference to the resources provided by the Environment. It contains the full Ada specification for each unit in the standard D_12_1_1 Environment, organized by pathname. This section also contains !Commands.Abbreviations, which lists the standard abbreviations for Environment commands. 8.2. New Online Documentation New online help has been included for selected declarations and packages. Besides giving general descriptions for each declaration, the new online help provides information about individual parameters. 8.2.1. New Declarations New online help now exists for declarations that have been added to the Environment since D_9_25_1. * Ada.Expand_Names * Cmvc.Accept_Changes_Effort * Cmvc.Compare * Command.Make_Procedure * Compilation.Load * Compilation.Get_Target_Key * Compilation.Set_Target_Key * Compilation.Show_Target_Key * Editor.Screen.Set_Columns * Editor.Screen.Set_Lines * Log.Image * Log.Put_Errors R September 1990 77\f Rational Environment Release Information * Log.Put_Line * Operator.Get_Minimum_Password_Length * Operator.Get_Password_Deadline * Operator.Get_Password_Warning * Operator.Get_User_Deadline * Operator.Get_User_Warning * Operator.Set_Password_Policy * Operator.Show_Password_Policy * System_Backup.Backup_Generic * System_Utilities.Terminal_Columns * System_Utilities.Terminal_Lines * What.Search_List_Resolution 8.2.2. Updated Packages Updated online help exists for selected packages, making all the information in these packages current to D_12_1_1. All of these packages have new introductions that present more extensive information on key concepts. To display information from the package introductions, enter the following command: What.Does ("package_name"); This command brings up a menu of the declarations in that package. From the menu, put the cursor on the entry for the package itself and press either [Help] or [Object] - [?]. The updated packages are: * Access_List, whose introduction includes a reorganized discussion of access control, access lists, groups, access rights, and interactions between access control and other Environment features. * Access_List_Tools. * Archive, whose introduction includes sections describing archive options, archive and access requirements, archive and multiple-host development, plus a series of examples illustrating archive usage. * File_Utilities, whose introduction includes an overview of pattern-matching in file-utility commands. 78 September 1990 R\f D_12_1_1 Release * Library, whose introduction includes sections describing name resolution and context, models, versions, recursive operation, and the switches that control library displays. * Operator, whose introduction includes descriptions of groups, privileges, operator capability, and password policy. * Switches, whose introduction includes basic operations pertaining to switch files and updated descriptions of all library switches. These updated descriptions appear for Semantics, Format, and Directory library switches when you use [Object] - [?] in a library switch file. The updated information for R1000_Cg and Ftp library switches appears only in the introduction to package Switches. * System_Backup, whose introduction includes a brief, updated description of backups. 9. Training No new training in D_12_1_1. The Fundamentals, Advanced Topics, and layered products training scripts do not yet run on Delta2. 10. Appendix A: Examples of Switch-Dependent Compiler Fixes The following examples illustrate the main bugs that have been fixed in the D_12_1_1 compiler. These bug fixes are available only if explicitly enabled. To enable these fixes along with other new features, you must set the following switch to False in the library or view in which compilation is to take place: R1000_Cg.Retain_Delta1_Compatibility := False Note that this switch setting also causes the generated code to be incompatible with code generated by the D_10_20_0 compiler. For more information, see sections 7.14.5 and 7.14.8. 10.1. Constraining Incomplete Types Previous versions of the R1000 compiler rejected any attempt to constrain a discriminated type prior to the complete type declaration (as, for example, the subtypes Man and Woman below). Units containing a constrained incomplete type could be installed but not coded. The current version of the R1000 compiler now fully supports constraining incomplete types, provided that the Retain_Delta1_Compatibility switch is set to False. package Constraining_Incomplete_Types is type Sex is (Male, Female); R September 1990 79\f Rational Environment Release Information type Person (Gender : Sex) is private; -- The following two subtypes constrain an incomplete -- discriminated type. These declarations will be -- rejected by the compiler at coding time unless the -- switch R1000_Cg.Retain_Delta1_Compatibility := False. subtype Man is Person (Gender => Male); subtype Woman is Person (Gender => Female); type Name is access Person; subtype Mans_Name is Name (Gender => Male); subtype Womans_Name is Name (Gender => Female); private type Person (Gender : Sex) is record Father : Name (Gender => Male); Mother : Name (Gender => Female); case Gender is when Male => Wife : Womans_Name; when Female => Husband : Mans_Name; end case; end record; end Constraining_Incomplete_Types; 10.2. Completing Types by Constraining Truly Private Types Previous versions of the R1000 compiler did not allow you to complete a private type by constraining a truly private type. As shown in the examples below, a truly private type refers to a generic formal private type or a type exported from a package with a closed private part. Units containing such declarations could be installed, but not coded. The current version of the R1000 compiler now fully supports such declarations, provided that the Retain_Delta1_Compatibility switch is set to False. Example 1. Type T is completed by constraining a generic formal private type: generic type T (D : Integer) is private; package Example_1 is type TT is private; private -- The following declaration is allowed only with -- the D_12_1_1 compiler: type TT is new T (10); end Example_1; 80 September 1990 R\f D_12_1_1 Release Example 2. Type T is completed by constraining a private type that is exported from a package with a closed private part: with Bounded_String; package Example_2 is type T is private; private -- Bounded_String.Variable_String is a truly private -- type since package Bounded_String has a closed -- private part. The following declaration used to be -- rejected at coding time: type T is new Bounded_String.Variable_String (10); end Example_2; 10.3. Exceptions in Generics The Ada language requires that exceptions declared in generic instances be distinct. However, previous versions of the R1000 compiler created them as the same exception, causing valid Ada programs (such as the example below) to execute incorrectly. The current version of the R1000 compiler fixes this bug, provided that the Retain_Delta1_Compatibility switch is set to False. procedure Exceptions_In_Generics is generic type Domain_Type is private; type Range_Type is private; package Map_Generic is -- If Retain_Delta1_Compatibility := True, then -- these exceptions will be distinct in all -- instances of Map_Generic; otherwise, they will -- (improperly) have the same representation in all -- instances. Undefined : exception; procedure Define (Domain_Value : Domain_Type; Range_Value : Range_Type); function Lookup (Domain_Value : Domain_Type) return Range_Type; -- Raises Undefined if Domain_Value is not in the map. end Map_Generic; R September 1990 81\f Rational Environment Release Information package body Map_Generic is separate; package Map1 is new Map_Generic (String, Integer); package Map2 is new Map_Generic (Integer, Boolean); begin begin if Map2.Lookup (Map1.Lookup ("XYZ")) then [statement] end if; exception -- When Retain_Delta1_Compatibility := True, these -- two exceptions will be distinct and can be used -- to determine which map lookup failed; however, -- when the switch is set to False, these two -- exceptions will not be distinct and the first -- alternative will be executed regardless of which -- map lookup actually failed. when Map2.Undefined => [statement] when Map1.Undefined => [statement] end; end Exceptions_In_Generics; 10.4. Parameter Subtype Checking for Generic Formal Calls When a generic formal subprogram is called, the Ada language requires that constraint checks be made to ensure that the parameter values lie within the bounds of the subtypes for the parameters of the actual subprogram. However, previous versions of the R1000 compiler made these constraint checks against the subtypes for the parameters of the generic formal subprogram. This either raised Constraint_Error where no exception should have been raised or it raised no exception where Constraint_Error should have been raised (as for the code in the following example). The current version of the R1000 compiler now fixes this bug, provided that the Retain_Delta1_Compatibility switch is set to False. procedure Generic_Formal_Call_Constraint_Checks is procedure P1 (X : Integer) is begin null; 82 September 1990 R\f D_12_1_1 Release end P1; procedure P2 (X : Natural) is begin null; end P2; generic with procedure P (X : Integer); procedure G1 (X : Integer); procedure G1 (X : Integer) is begin P (X); end G1; generic with procedure P (X : Natural); procedure G2 (X : Integer); procedure G2 (X : Integer) is begin P (X); end G2; procedure I1 is new G1 (P1); procedure I2 is new G1 (P2); procedure I3 is new G2 (P1); procedure I4 is new G2 (P2); begin I1 (-1); -- Ok I2 (-1); -- Constraint_Error (used to be OK) I3 (-1); -- OK (used to raise Constraint_Error) I4 (-1); -- Constraint_Error end Generic_Formal_Call_Constraint_Checks; 11. Appendix B: Summary of Changes from Previous Releases This appendix is intended for new Rational customers who have not used the Environment prior to the current (D_12_1_1) release. Accordingly, you do not need to read this appendix if you have used the Delta1 (D_10_20_0) or earlier release of the Environment. The purpose of this appendix is to provide new customers with quick access to information about the main additions and changes that were made to the Environment before the current release but after the Rational Environment Reference Manual was published. The Reference Manual was written for the Delta0 (D_9_25_1) R September 1990 83\f Rational Environment Release Information release of the Environment and therefore does not document any of the features that were introduced by the Delta1 (D_10_20_0) Environment release. This appendix includes excerpts from the Delta1 release note that describe these undocumented features. Note that Delta1 features are not included in this appendix if they are documented in the new online help (see section 8.2). For easy reference, this appendix is organized into the same sections as the Rational Environment Reference Manual. 11.1. Editing Images (D_10_20_0) 11.1.1. Package Editor.Macro Keyboard macros can be saved in a clear text form that can be edited. To save keyboard macros in this form, use the Editor.Macro.Save procedure with Expanded => True. If Expanded is False, the macros will be saved in binary form. If the macros are saved in editable form, they will be reparsed at each login, which can be time-consuming. In general, users are advised to edit the macro file, make sure that it is correct, and then save the macros in binary form. If changes are made to the macro file, a user must run Editor.Macro.Restore or log off and then log on again for the changes to take effect. The macro file is created in your home world, and it is called Terminal_Type_Macros, where Terminal_Type can be Rational, Facit, VT100, an RXI-supported workstation, or a user-defined terminal type. The first line of each macro contains the macro number. Each subsequent line describes the keystrokes and contains two entries. The first entry indicates whether the command in that line should be executed immediately (EXECUTE) or should be brought up in a command window (PROMPT). The next entry is the command. At the end of the file is a list of the key bindings that map each macro number to a key. 11.1.2. Package Editor.Image The behavior of Image.End_Of has been modified so that if the actual end of an image is not in column 1, the operation will take the cursor to the first column of the next line after the end of the image. However, if the cursor is already there, it will go to the real end of the image. Thus, if End_Of is iterated, it will toggle like Line.Beginning_Of. This makes it possible to distinguish files that have an empty line at the end 84 September 1990 R\f D_12_1_1 Release from those that do not. 11.2. Editing Specific Types (D_10_20_0) 11.2.1. Dependents Object Editor The new dependents editor replaces the obsolescence, name resolution, and show usage menus. The new output looks similar to the D_9_25_1 display for these menus, and all of the D_9_25_1 menu capabilities still exist. More information is available in dependents/usage menus, and the capability of demoting lists of dependent declarations and statements, rather than entire compilation units, has been added. The initial display of the show usage and obsolescence menus gives the same information as it did in the D_9_25_1 Environment release. Now, however, additional information can be obtained using commands from package Common. The following is a quick overview of how to use some of these new commands. * The initial display will show a list of the immediate dependents for a compilation unit or declaration. Press [Complete] to get the demote closure of the dependents. * The initial display will show a list of compilation units that depend on a compilation unit or declaration. Use the Common.Expand ([Object] - [!]) and Common.Elide ([Object] - [.]) commands to control display information. The editor's window banner will indicate the type of information being displayed. The following terms are used in this banner: - State: Indicates that the state of the item is being displayed. - Unit: Indicates that the name of the compilation unit containing the dependency is being displayed. - Parent: Indicates that the name of the enclosing Ada construct is being displayed. When this construct is the same as the compilation unit, *comp_unit* is displayed. - Kind: Indicates that the type of usage is being displayed. For instance, stmts means that the usage is in a statement, decls means that the usage is in a declaration, and call means that the usage is in a subprogram call. - Item: Indicates that the items containing the usage are being displayed. The item level can be expanded to show the Ada source where the actual usage occurs. At this level, all direct references to the subject of the usage/obsolescence are underlined, and you can use the Editor.Cursor.Next and Editor.Cursor.Previous commands to R September 1990 85\f Rational Environment Release Information traverse through the references. * Region selection can be used to select a set of displayed items. Once selected, [Demote] and [Promote] can be used to demote and promote these items. This can be useful and save a lot of compilation when you have a few dependencies within each of the compilation units in the demote closure. If there are many dependencies in a compilation unit, then the time required to demote and promote them incrementally using the dependents object editor may be longer than that required to demote and repromote the entire compilation unit. Four new session switches were created to control these menu displays. These switches are listed in section 11.4.1. 11.2.2. Changes in Editing Ada Units When editing Ada units, syntactic completion of: procedure p is will result in: procedure P is [declaration] begin [statement] end P; But syntactic completion of: procedure P is begin will result in: procedure P is begin [statement] end P; 11.2.3. Ada Completion If the user requests semantic completion for an Ada fragment that has multiple possible completions, the Environment will display a Completion Menu with the possible choices. This Completion Menu looks exactly as it did in D_9_25_1; however, now a user can select an entry in the menu and press [Complete] and that selection will be used to complete the construct in the command window or Ada program where completion was originally requested. In addition, completion of an Ada fragment with a partial parameter list will result in a full parameter profile expansion that utilizes the partial parameter values where applicable. 86 September 1990 R\f D_12_1_1 Release A new procedure, Ada.Expand_Names, was added in D_10_20_0. Documentation for this procedure is available through D_12_1_1 online help. 11.2.4. Changes to Object.Sort Common.Object.Sort now applies to the window directory. You now can sort on any of the fields in the display. Sort takes a numeric parameter (typically through a prefix key). The values are: 1 By Usage By order of most recent usage 2 By Mode By modified (*), committed ( ), read only (=) 3 By Size By size of image, increasing 4 By Type By object type, (library), (text), and so on 5 By Name By image name Negative numbers reverse the order of the sort. For example, this could be useful if you want to identify all modified buffers or all the text windows. 11.2.5. Searchlists Definition now works from searchlists. 11.3. Debugging (D_10_20_0) 11.3.1. Debugger Maintenance A new package called !Commands.Debug_Maintenance has been added. This package contains a procedure called Wait_For_Job that can be used to synchronize user programs with the debugger. When called, this procedure pauses while the debugger has the running flag on and returns when the program stops in the debugger. This can be useful for writing debugger script programs. For example: Debug.Break (Location => "Test_Program.1s"); Debug.Execute; Debug_Maintenance.Wait_For_Job; Debug.Put (Variable => "Test_Variable"); 11.3.2. Selections in Debugger Windows The ability to make selections in debugger windows and pass selections to debugger commands has been expanded. Certain lines indicating a source location, exception name, or task name can be selected in a debugger ouptut window; the selection then can be used as a parameter to debugger or other Environment commands. The debugger commands will accept special names, such as "<REGION>", "<SELECTION>", and so on. R September 1990 87\f Rational Environment Release Information The following debugger output is selectable: * Reports of events (breakpoint reached, step completed, trace output, exception handled, task stopped) can be selected. They contain the location of the event, task involved, and exception name (if applicable). * Task display output can be selected and used to indicate a task or its defining location. * Stack display output indicates the task and location in the frame. * History display output indicates the task and location of the history entry. * Command echoing for Put and Modify commands can be selected and, if you press [Put], the object will be redisplayed. Selections are interpreted as follows: * Locations: Whenever a location is required in a command, "<SELECTION>" can be specified and, if the selected line contains an Ada location, that location will be used. * Exceptions: The exception name for the Catch, Propagate, and Forget commands will accept a selection. For example, if the debugger catches an exception and displays: Exception .FOO.BAR caught at .BLAP.MUMBLE.3s [task %root_Task] the first line can be selected and the [Propagate] key used to propagate that exception. * Tasks: Lines that indicate a location almost always contain a task name. These lines can be selected. If the null string is given for a task name to a debugger command and a task is selected, that task will be used for the following commands: Clear_Stepping, Execute, History_Display, Hold, Information, Register_Display, Register_Modify, Release, Run, Set_Task_Name, Stack, Stop, Task_Display. * If a command (such as the Break command) requires both a location and a task, the selection is used to derive the location and not the task name. * For example, after Task_Display is executed, a line of the output can be selected, the stack command issued, and the stack for the defining task will be displayed. As another example, if you were to indicate the Break command on the same selection, a breakpoint will be set on the first declaration of the task, but it will apply to all tasks. 88 September 1990 R\f D_12_1_1 Release 11.4. Session and Job Management (D_10_20_0) 11.4.1. Session Switches Thirty new session switches have been added to control CMVC functions: Cmvc_Break_Long_Lines Cmvc_Capitalize Cmvc_Comment_Extent Cmvc_Configuration_Extent Cmvc_Field_Extent Cmvc_Indentation Cmvc_Line_Length Cmvc_Shorten_Name Cmvc_Shorten_Unit_State Cmvc_Show_Add_Date Cmvc_Show_Add_Time Cmvc_Show_All_Default_Lists Cmvc_Show_All_Default_Orders Cmvc_Show_Deleted_Objects Cmvc_Show_Deleted_Versions Cmvc_Show_Display_Position Cmvc_Show_Edit_Info Cmvc_Show_Field_Default Cmvc_Show_Field_Max_Index Cmvc_Show_Field_Type Cmvc_Show_Frozen Cmvc_Show_Hidden_Fields Cmvc_Show_Retention Cmvc_Show_Size Cmvc_Show_Unit_State Cmvc_Show_Users Cmvc_Show_Version_Number Cmvc_Uppercase Cmvc_Version_Extent Default_Venture Four new session switches have been added to control menu displays: Dependents_Delta0_Compatibility Dependents_In_Order_Pathnames Dependents_Show_Library Dependents_Show_Unit_State Two new session switches have been added to control terminal settings: Terminal_Line_Speed Terminal_Padding To obtain a description of any of these switches, enter the Switches.Edit_Session_Attributes procedure, place the cursor on the line containing the switch in question, and enter Common.Explain (for example, by pressing [Object] - [?]). A description will appear immediately below the switch. The Recovery_Locality session switch, previously not implemented, has been removed. New and changed library switches are listed in section 11.5.2. 11.4.2. Log Procedures New procedures Log.Image, Log.Put_Errors, and Log.Put_Line were added in D_10_20_0. Documentation for these procedures is available in D_12_1_1 online help. R September 1990 89\f Rational Environment Release Information 11.4.3. Remote Execution A new package called !Commands.Remote has been added. This package contains procedures that give a user the ability to execute programs on other R1000s on the same network and to display the image of an object from another R1000 (on the same network) in a local I/O window. The identity of the remote jobs (and therefore their access rights) are identical with that for the archive server running on the remote machine, unless the user's local session switch Profile.Remote_Password has a value. See SJM-76 and following pages in the Rational Environment Reference Manual for an explanation of how remote usernames and passwords are used with Archive.Copy; use of the password with commands in package Remote is identical. Remote jobs will run with the username of the remote archive server, but the access rights for the jobs will be as documented in SJM. 11.5. Library Management (D_10_20_0) Changes to library-management facilities are documented in the D_12_1_1 online help for packages Access_List, Access_List_Tools, Archive, File_Utilities, Library, and Switches. Among the new features added in D_10_20_0 are new Archive command options and new library switches. 11.5.1. Compilation New procedures in package Compilation (Load, Set_Target_Key, Show_Target_Key, and Get_Target_Key) were added in D_10_20_0. Documentation for these procedures is available in D_12_1_1 online help. 11.5.2. Library Switches Six new library switches have been added: Elab_Order_Listing Flag_Inevitable_Exceptions Reject_Bad_Lrm_Pragmas Reject_Bad_Rational_Pragmas Reject_Inevitable_Exceptions Reject_Undefined_Pragmas To obtain a description of any of these switches, enter the Switches.Edit procedure, place the cursor on the line containing the switch in question, and enter Common.Explain (for example, by pressing [Object] - [?]). A description will appear immediately below the switch. The Target_Key library switch, previously managed by Rational Subsystems, has been removed. 90 September 1990 R\f D_12_1_1 Release Changes have also been made to session switches. New session switches are listed in section 11.4.1. 11.6. Text Input/Output (D_10_20_0) A Form parameter has been added to a number of input/output procedures. Documentation for this parameter is available in the new "Appendix F for the R1000 Target." 11.7. Data and Device Input/Output (D_10_20_0) No significant changes were noted in the D_10_20_0 release note. 11.8. String Tools (D_10_20_0) No significant changes were noted in the D_10_20_0 release note. 11.9. Programming Tools (D_10_20_0) No significant changes were noted in the D_10_20_0 release note. 11.10. System-Management Utilities (D_10_20_0) 11.10.1. Logoff on Disconnect If this terminal characteristic is enabled, a user's session will be terminated if a disconnect is detected on the terminal's port. A disconnect on an RS232 port is detected by a drop in the DCD signal; a disconnect on a Telnet port is detected by the termination of the Telnet session. In either case, uncommitted buffers will be saved before the user's session is terminated. By default, this feature is not enabled for all ports. To enable the feature, use the Terminal.Set_Logoff_On_Disconnect procedure. Any disconnect event on an RS232 port is passed to the program reading from the port. That is, if the R1000 detects a transition from ON to OFF on the DCD input (pin 8) of the RS232 interface, a disconnect status code will be returned to the program. With previous releases, RS232 disconnect events often were not reported; a bug in the input-handling software caused them to be lost. In particular, if a port is at a login prompt (that is, the port has been enabled for login, but no one is currently logged in) and the R1000 sees DCD switch to OFF, the login manager issues the error message "Unable to process input" immediately following the login prompt. This message is not indicative of a fatal condition; the ability to log in is not adversely affected. This R September 1990 91\f Rational Environment Release Information condition can be avoided by making certain DCD does not switch OFF for RS232 ports being used for logging in. The Rational terminal cable (part no. 125-001808-003) is properly wired to avoid this condition. The DCD can switch OFF if it is connected to the R1000's DTR output; this output is switched OFF by the R1000 to initiate a disconnect. For example, if a port has been configured with Disconnect_On_Logoff = True and DTR is connected to DCD, then whenever anyone logs off the login manager will issue the "Unable to process input" message. DCD can also switch OFF if it is connected to external equipment (such as a terminal server) that switches this signal OFF. 11.10.2. Systemwide Login A systemwide login has been implemented. If a coded, parameterless procedure called System_Login exists in !Machine, it will be executed unconditionally. After this, the D_9_25_1 rules for login procedure execution will be used: a user's searchlist is employed in an attempt to find a parameterless procedure called Login. 11.10.3. Print Spooler The print spooler will notify users of the device on which the request is being printed when the request starts printing and in the print completion message. It will also attempt to queue a request to another device associated with the specified class, if the current device cannot be connected to successfully, before trying again with the original device. 11.10.4. Password Policy Declarations for enforcing password policies were added to package Operator in D_10_20_0. Documentation for managing password policy is available in D_12_1_1 online help. 11.10.5. System-Availability Tools New declarations in the !Tools.System_Availability'Spec_View.Units subsystem include: * Procedure Log_Reader.Load_Logs procedure Load_Logs (Start_Time : Calendar_Time; Stop_Time : Calendar_Time; From_Directory : String := "!Machine.Error_Logs"); 92 September 1990 R\f D_12_1_1 Release Builds a map of all log files, using start and stop times as interval bounds if provided. * Function System_Information.Done function Done (I : Mount_Iterator) return Boolean; * Procedure System_Information.Next procedure Next (I : in out Mount_Iterator); * Procedure System_Information.Initialize procedure Initialize (I : out Mount_Iterator); * Type System_Information.Mount_Information type Mount_Information is record Request_Time : Time_Utilities.Time; Volume : Bounded_String.Variable_String (40); Mount_Time : Time_Utilities.Time; Unload_Time : Time_Utilities.Time; Density : Bounded_String.Variable_String (20); end record; Maintains data about tape activity; the value of the density field is not trustworthy because of hardware limitations. * Type System_Information.Mount_Iterator type Mount_Iterator is private; Retrieves information about tape-mount requests. * Function System_Information.Value function Value (I : Mount_Iterator) return Mount_Information; * Type System_Report.Report_Class Adds new Tape_Mounts enumeration for use with System_Report.Generate; tape-mount information is also included when Everything is used for the report class. 11.11. Project Management (D_10_20_0) The following paragraphs describe new CMVC features and clarify aspects of CMVC behavior that have been subject to misinterpretation. R September 1990 93\f Rational Environment Release Information 11.11.1. Tools The new function !Implementation.Cmvc_Implementation.Element_Operations.Saves_ Source can be used to determine whether the image of an object is stored in the CMVC database. For many of the documented procedures in package Check, there are equivalent functions that are not documented. See the package spec !Tools.Compatibility'Spec_View.Units.Check for details. 11.11.2. Joining Controlled Objects The execution of: Cmvc.Join (What_Object => "X", To_Which_View => "V") is equivalent to: Cmvc.Sever ("X"); Cmvc.Join ("X", "V"); That is, the result is that X is first removed from any join set it is currently in and then it is placed in a join set with V. This means that for views A and B, each with an object X, entering Cmvc.Join (X, A) from B is not necessarily the same as entering Cmvc.Join (X, B) from A. If a new unit is to be added to a join set, the command should always join the new unit to an existing join set. Otherwise, two join sets will result: one with the new unit and the one it was joined to, and one with all the other members of the old join set. If wildcards are used to join objects in a view and the wrong direction is used, large numbers of joined objects can be severed accidentally. Cmvc.Join performs all join operations atomically. This means that any error will result in none of the joins being done, even if there are progress (+++) messages in the log. Most CMVC operations behave this way. 11.11.3. Import-Restriction Files Import-restriction files may be named for the full pathname of a view. For example, if you want to apply an import restriction to subsystem !Subs.Sub1.Code but not to !Other_Subs.Sub1.Code, then you can create an import-restriction file for your load view that is named "Other_Subs_Sub1_Code", rather than naming it simply "Code". If you describe an import restriction with the simple name of a subsystem, the restriction will apply to all subsystems with that simple name. This can result in units from other spec views unexpectedly being absent from the importing view, or the entire Cmvc.Import operation may fail. Rational recommends using full pathnames in naming import restrictions. 94 September 1990 R\f D_12_1_1 Release 11.11.4. Controlling Objects If you try to control an element in a view without saving source, and the CMVC database is already saving source for an element of that name, Cmvc.Make_Controlled will fail. You must destroy all configurations containing the old element, uncontrol the old element in any existing views, and expunge the database before you will be able to control the new element. Interfaces in Cmvc_Implementation enable you to iterate over all configurations and locate the ones containing a particular element. !Implementation.Directory or !Tools.Directory_Tools can be used to find the views containing that element. 11.11.5. Demotion of Checked-In Ada Units Demotion of a checked-in, controlled Ada unit with open insertion points will fail with a message indicating that the unit must first be checked out. Such units should be checked out and checked back in manually. This affects Compilation.Demote as well as the implicit demotions done by Archive when the Remake option is specified. This behavior is necessary because, when the unit is demoted, the system subsumes the insertion point into the parent unit, making its image differ from that stored in the CMVC database. To avoid the manual checkout and checkin operations, do not check in units if they have open insertion points. 11.11.6. Creating New Spec Views When a spec view is created from another spec view that contains controlled objects, the objects in the new spec view will be controlled and joined to the source spec view. In contrast, when a spec view is created from a working view or a released view that contains controlled objects, the objects in the new spec view are left uncontrolled. 11.11.7. Pretty-Printing and Controlled Ada Units Changes to the pretty-printer can result in objects whose image does not match that recorded in the CMVC database. Cmvc_Maintenance.Check_Consistency will report such mismatches. To make the images recorded in the CMVC database consistent with the reformatted images of objects, you can check out and then check in each object without modification. This creates a new generation that has the image produced by the current pretty-printer, which matches the object in the view. Note that the checkout operation also implicitly accepts changes if the object does not correspond to the latest generation in its join set. This means that the contents of the view may be changed by the procedure outlined above. Rational recommends that before the explicit checkout and checkin for pretty-printer compatibility is done, all joined paths and subpaths should be R September 1990 95\f Rational Environment Release Information made consistent; that is, all joined objects should be updated to the most recent generation for that join set. Note also that this procedure will not work for released views, even if the released view is first unfrozen - because objects in released views cannot be checked out. 11.11.8. Compatibility-Database Utilities The new package !Implementation.Compatibility includes programmatic interfaces that can be used to identify whether a subsystem is a primary or a secondary. One function returns the Subsystem_Id for a specified subsystem; other functions return Boolean values. See the online spec for details. The new package Cdb_Maintenance has been added to !Tools.Compatibility. The subprograms in this package are designed to be used by Rational support personnel for diagnosing and addressing problems associated with the compatibility database. See the commented spec for more details. These tools replace the procedure !Commands.Cmvc_Maintenance.Repair_Cdb that is documented in the Project Management book of the Rational Environment Reference Manual. The Verify procedure in the new package replaces and improves on Repair_Cdb with Effort_Only => True. There is no functionality equivalent to Repair_Cdb with Effort_Only => False; instead, repair operations involve recompilation of incompatible units. 11.12. Networking (D_10_20_0) A new optional feature has been added to Telnet_Server. Associated with each Telnet port is a Boolean state variable named Convert_Received_New_Line_To_Cr. When it is True, a received Telnet New_Line signal (CR and LF) will be returned as CR only to the caller of Telnet_Server.Receive. When False, such a signal will be returned as the sequence CR and LF. The default value of this switch (assigned at system boot time) is True. For existing applications, this has worked well: it compensates for the behavior of Bridge and other Telnet clients that send CRLF when the user typed only CR. For future applications that need to transfer binary data, turning this switch off (False) probably will work better. The Telnet_Server exports operations to read and write the value of this switch. 96 September 1990 R