DataMuseum.dk

Presents historical artifacts from the history of:

Rational R1000/400 Tapes

This is an automatic "excavation" of a thematic subset of
artifacts from Datamuseum.dk's BitArchive.

See our Wiki for more about Rational R1000/400 Tapes

Excavated with: AutoArchaeologist - Free & Open Source Software.


top - download
Index: ┃ E T

⟦48372a58f⟧ TextFile

    Length: 112478 (0x1b75e)
    Types: TextFile
    Names: »EST_HELP«

Derivation

└─⟦5f3412b64⟧ Bits:30000745 8mm tape, Rational 1000, ENVIRONMENT 12_6_5 TOOLS 
    └─ ⟦91c658230⟧ »DATA« 
        └─⟦f6fec0485⟧ 
            └─⟦this⟧ 
└─⟦d10a02448⟧ Bits:30000409 8mm tape, Rational 1000, ENVIRONMENT, D_12_7_3
    └─ ⟦fc9b38f02⟧ »DATA« 
        └─⟦f95d63c89⟧ 
            └─⟦this⟧ 

TextFile


  @node !Commands.Ada

  This package contains the set of procedures and types provided
  for Ada object-specific editing.  The commands in package
  !Commands.Common can also be used for Ada object-specific editing.
  @node !Commands.Ada.Code_Unit

  procedure Code_Unit;

  Changes the selected Ada unit or the Ada unit in the current window
  to the coded state.

  The actual effects of this procedure depend on the current state of
  the unit.  If the current state of the unit is:

  o Archived:  The unit is promoted to the coded state.

  o Source:  The unit is promoted to the coded state.

  o Installed:  The unit is promoted to the coded state.

  o Coded:  The procedure has no effect.

  This procedure may involve coding subunits, the parent unit, or the
  corresponding visible part; however, the transitive closure is not
  coded.

  If the operation succeeds, the unit will be read only.

  Units can be demoted to the archived state using the
  !Commands.Compilation.Demote procedure, with the Goal parameter
  assigned the value of Compilation.Archived.
  @node !Commands.Ada.Create_Body

  procedure Create_Body (Name : String := "<IMAGE>");

  Inserts a template for the body of the named visible part, the
  selected visible part, or the visible part in the current window.

  This procedure builds a template for the body of the currently
  selected or named visible part or the visible part in the current
  window.  The template is brought up in a new window, and prompts
  are provided for statements that must be completed.  Any with
  clauses that exist in the visible part are copied into the body
  template.

  Where possible, the body is inserted into the enclosing program
  unit as an in-line program unit.  In-line program units can be
  changed to separate subunits with the Make_Separate procedure.
  If the body is built directly into a library, the unit is a
  compilation unit.

  This procedure allows accurate construction of corresponding
  bodies to existing visible parts.  It constructs the skeleton of
  arbitrary program unit specifications.
  @node !Commands.Ada.Create_Private

  procedure Create_Private (Name : String := "<IMAGE>");

  Inserts a template for the private part of the current package
  visible part.

  This procedure creates the private region of the package.  It has
  no effect if the private part already exists and contains all of
  the declared private types.  The procedure applies recursively to
  enclosed packages.  A prompt is left for the completion of each
  private type or deferred constant.
  @node !Commands.Ada.Delete_Blank_Line

  procedure Delete_Blank_Line (Repeat : Positive := 1);

  Not currently implemented.

  Specifies that Repeat blank lines should be deleted after the
  current line (that is, the line on which the cursor is currently
  located).  If one of the specified lines is a nonblank line, the
  deletion stops, and the nonblank line is not deleted.
  @node !Commands.Ada.Diana_Edit

  procedure Diana_Edit (Name : String := "<CURSOR>");

  For Rational internal use.

  Shows a read-only image of the internal form of the DIANA tree
  corresponding to the node given, based, by default, on the cursor
  position.  This can be used only on Ada units or in Command
  windows.
  @node !Commands.Ada.Get_Errors

  procedure Get_Errors;

  Causes the error underlines in the image to be redisplayed on the
  image.

  These error underlines result from errors in the image.  To remove
  error underlines, use the Common.Clear_Underlining procedure.

  This procedure is useful to display underlining resulting from
  errors after the Clear_Underlining procedure has been used.

  This command is very useful in the following scenario.  Assume
  that you have a unit that has no syntactic errors and many semantic
  errors, so you make changes to the unit to correct semantic errors.
  Inadvertently, you add a syntactic error, which is underlined when
  you press [Format].  Because all the semantic errors are still
  underlined, you may find it difficult to locate the syntactic
  error.  Thus, you may want to execute the Common.Clear_Underlining
  command to remove all underlines.  Then you can press [Format],
  which displays the underlining for the syntactic error.  Once you
  have corrected the syntactic error, you can press [Format] again
  to remove the underlining for syntactic errors that have been
  corrected.  Then you can use the Get_Errors procedure to display
  the semantic errors again so that you can continue correcting them.
  @node !Commands.Ada.Insert_Blank_Line

  procedure Insert_Blank_Line (Repeat : Positive := 1);

  Not currently implemented.

  Specifies that Repeat blank lines should be inserted before the
  current line (that is, the line on which the cursor is currently
  located).  When the insertion has completed, the cursor will be on
  the first blank line inserted.
  @node !Commands.Ada.Install_Stub

  procedure Install_Stub;

  Installs the declaration or stub in the parent unit or library for
  the unit in the current window.

  You might want to install the stub for a unit so that it appears in
  the library structure or to create a link for it.  For subunits,
  you might want to install the stub so the subunit can be compiled
  against.

  If the unit cannot be installed but the stub can be, this procedure
  installs the stub (makes the insertion point into a declaration for
  the unit) without additional semantic checking of the unit.
  @node !Commands.Ada.Install_Unit

  procedure Install_Unit;

  Changes the selected or designated Ada unit, or the Ada unit in the
  current window, to the installed state.

  The actual effect of this procedure depends on the current state of
  the Ada unit.  If the unit is in the following state:

  o Archived:  The unit is promoted to the installed state.

  o Source:  The unit is promoted to the installed state.

  o Installed:  The procedure has no effect.

  o Coded:  The unit is demoted to the installed state.

  If other units depend on the unit and the unit is to be demoted,
  the operation fails and the dependent units are displayed
  in the menu window that is brought onto the screen.  See the
  description of menus in this book for more information on the
  editing operations available on menus.

  Units can be demoted to the archived state using the
  !Commands.Compilation.Demote procedure, with the Goal parameter
  assigned the value of Compilation.Archived.
  @node !Commands.Ada.Make_Inline

  procedure Make_Inline;

  Changes the subunit in the image or selected subunit stub from a
  subunit to an in-line program unit.

  This procedure removes the separate clause and moves the body
  for the subunit into the parent unit.  The library entry for the
  subunit is removed from the library structure.

  Program units can be created as either in-line program units or
  separate subunits.  The Make_Inline procedure allows a program
  unit that is a separate subunit to be changed to an in-line program
  unit.
  @node !Commands.Ada.Make_Separate

  procedure Make_Separate;

  Changes the selected subprogram from an in-line program unit to a
  separate subunit.

  This procedure replaces the body with a separate clause and creates
  a separate library entry containing the body for the unit.

  Program units can be created as either in-line program units or
  separate subunits.  The Make_Separate procedure allows a program
  unit that is an in-line program unit to be changed to a separate
  subunit.
  @node !Commands.Ada.Other_Part

  procedure Other_Part (Name     : String  := "<IMAGE>";
                       In_Place : Boolean := False);

  Finds and displays the other part of the named program unit or the
  program unit in the current window.

  This procedure finds the corresponding visible part if the named
  program unit is a body, or finds the corresponding body if the
  named program unit is a visible part, and displays this other part
  in a window.  If no program unit is named, the program unit in
  the current window is used.  If no program unit is named and the
  current window does not contain a program unit, then the procedure
  has no effect.
  @node !Commands.Ada.Replace_Id

  procedure Replace_Id (Old_Id : String := ">>OLD NAME<<";
                       New_Id : String := ">>NEW NAME<<");

  Replaces all identifiers that match the first string with the
  second string in the current selection.

  This procedure is similar to, but more selective than, a general
  replace mechanism.  It changes Ada identifiers (not comments or
  identifier fragments) in the current window.
  @node !Commands.Ada.Show_Usage

  procedure Show_Usage (Name    : String  := "<CURSOR>";
                       Global  : Boolean := True;
                       Limit   : String  := "<ALL_WORLDS>";
                       Closure : Boolean := False);

  Determines the actual usages, within the scope defined by Limit, of
  the declaration specified in the Name parameter and displays a list
  of these units in an xref window.

  The usages can be seen by taking the definition of the entries
  in the xref, which brings up images of these units in windows,
  with each actual usage of the declaration underlined.  The
  !Commands.Editor.Cursor.Next and Editor.Cursor.Previous
  procedures can be used to move between these usages.  For more
  information, see the description of the editing commands available
  on xrefs in Xref Images in this book.

  Note that if the actual usages are only in the current unit, each
  usage is underlined and an xref window is not created.
  @node !Commands.Ada.Show_Unused

  procedure Show_Unused (In_Unit           : String  := "<IMAGE>";
                        Check_Other_Units : Boolean := True);

  Shows the declarations that are not referenced in a unit.

  The unused references are underlined.
  @node !Commands.Ada.Source_Unit

  procedure Source_Unit;

  Changes the Ada unit in the current window, or the selected or
  designated unit, to the source state.

  The actual effects of this procedure depend on the current state of
  the unit.  If the current state of the unit is:

  o Archived:  The unit is promoted to source.

  o Source:  The procedure has no effect.

  o Installed:  The unit is demoted to the source state.

  o Coded:  The unit is demoted to the source state.

  If other units depend on the unit and the unit is to be demoted,
  the operation fails and the dependent units are displayed
  in the menu window that is brought onto the screen.  See the
  description of menus in this book for more information on the
  editing operations available on menus.

  Units can be demoted to the archived state using the
  !Commands.Compilation.Demote procedure, with the Goal parameter
  assigned the value of Compilation.Archived.

  This procedure brings a new unit to the source state and places an
  entry for it in the library structure under its proper name.  The
  write lock on the unit is released (the unit is read only).
  @node !Commands.Ada.Withdraw

  procedure Withdraw (Name : String := "<IMAGE>");

  Withdraws the stub (library entry for) of the named Ada unit, the
  selected Ada unit from its parent, or the Ada unit in the current
  window and demotes the unit to the source state.

  The stub is replaced with an insertion point.

  The actual effects of this procedure depend on the current state of
  the unit.  If the current state of the object is:

  o Archived:  The procedure has no effect.

  o Source:  The stub declaration is withdrawn from the enclosing
    unit or library.

  o Installed:  The unit is demoted to the source state and the stub
    declaration is withdrawn from the enclosing unit or library.

  o Coded:  The object is demoted to the source state and the stub
    declaration is withdrawn from the enclosing unit or library.

  If other units depend on the unit and the unit is to be demoted,
  the operation fails and the dependent units are displayed
  in the menu window that is brought onto the screen.  See the
  description of menus in this book for more information on the
  editing operations available on menus.

  The user may need to withdraw a unit to change its name or its
  parameter profile.
  @node !Commands.Command

  This package contains the set of procedures and types provided
  for command object-specific editing.  The commands in package
  !Commands.Common can also be used for command object-specific
  editing.
  @node !Commands.Command.Debug

  procedure Debug;

  Executes the program named in the Command window or the selected
  program in a library with debugging enabled.

  This procedure is normally bound to the [Meta][Promote] key
  combination on the Rational Terminal keyboard, which executes
  the program with the Rational Debugger enabled (see the Keymap in
  Volume 1 of the Rational Environment Reference Manual).

  If a selection is used to specify the program to execute, the
  program must not require the user to enter parameter values.  If
  the program does require entry of parameters, an error message will
  result.

  If the Rational Debugger is currently connected to a job, that job
  is killed.  This behavior is controlled by the Debug_Kill_Old_Jobs
  debugger flag (see Debugging (DEB) for more information).  If the
  Debug_Kill_Old_Jobs flag is true, the default value, then the job
  being debugged is killed when a new Debug call is made.  If false,
  the current job is released and continues its normal execution.

  If the Debug_Require_Debug_Off debugger flag is true and if a job
  is being debugged, this command fails.  With this flag true, the
  job currently being debugged must first be eliminated with the
  !Commands.Debug.Debug_Off procedure.  For further information on
  this procedure, see DEB, package Debug.

  As part of executing the Debug procedure:

  o The control and evaluation contexts are cleared.

  o Any stepping operations in progress for the old job are canceled.

  o Tracing requests are canceled.

  o Exception-handling requests are cleared (controlled by the
    Save_Exceptions debugger flag).

  o The default, catch all exceptions request, is installed.

  o Any active breakpoints are deactivated.

  This procedure differs from the !Tools.Debug_Tools.Debug_On
  procedure, which enables debugging only if the task calling
  Debug_On is part of the job being debugged and never results
  in a job being killed.  For further information on the Debug_On
  procedure, see DEB, package Debug_Tools.

  @node !Commands.Command.Spawn

  procedure Spawn;

  Spawns a background job to execute the command in the Command
  window or a program selected in a library window.

  This procedure is the same as the !Commands.Common.Promote
  procedure for Command windows, except that the Spawn procedure
  executes the Command window as a background job.

  If a selection is used to specify the program to execute, the
  program must not require the user to enter parameter values.
  However, it will accept parameters with default values, including
  special names.  If the program does require entry of parameters, an
  error message will result.

  This procedure is similar to executing a Command window normally
  (with the Common.Promote procedure) and then interrupting that
  execution with the !Commands.Job.Interrupt procedure.  The job is
  run as a background job, and control of the cursor is returned to
  the user immediately.
  @node !Commands.Common

  This package defines the commands that pertain to all type-specific
  editing operations.  These commands typically are bound to keys
  (see the Keymap in Volume 1 of the Rational Environment Reference
  Manual).  These commands perform the correct operation for the type
  of image in the current window.
  @node !Commands.Common.Abandon

  procedure Abandon (Window : String := "<IMAGE>");

  Abandons editing of the current image and does not save changes.

  This procedure abandons any changes made to the image in the
  current window since the last commit, releases any locks held
  by the Rational Editor on the entity corresponding to the image,
  destroys the window, and removes the image from the Window
  Directory.

  When some objects are edited, those objects are locked so that no
  other user can edit them.  This procedure releases the locks and
  destroys the window but does not commit the object first.  It is
  similar to the Release procedure except that any changes since the
  last commit on the object are not saved.

  Specifically, this procedure has the following effects:

  o Ada images:  Ends the editing of the Ada image.  Any changes made
    to the image since the last commit or promote are lost.  However,
    incremental changes made to installed or coded units, which are
    permanent as soon as they are promoted, are not lost.  The window
    is removed from the screen and from the Window Directory.  The
    Window parameter specifies the window to be removed from the
    screen.  The default is the current image.

  o Command images:  Ends the editing of the command and removes the
    Command window from the screen.  The Window parameter specifies
    which window should be removed from the screen.  The default is
    the current image, which is the window above which or on which
    the command is executed.

  o Debugger:  Deletes the Debugger window if the Debugger has been
    killed.  Otherwise, the command has no effect.  This command has
    the same effect as the Release procedure.

  o Help and job windows:  Removes the window created by
    the !Commands.What.Does, !Commands.What.Command, and
    !Command.What.Jobs procedures from the screen.  This command
    has the same effect as the Release procedure.

  o Library images:  Ends the editing of the specified image.  The
    window is removed from the screen and from the Window Directory.
    The Window parameter allows you to specify which window should
    be removed.  The default is the current image, unless there
    is a selection in that image.  In that case, the selection is
    abandoned.  Procedure Complete refreshes the library image in the
    current window to the current value of the underlying permanent
    representation and realigns the columns of the image.

  o Links:  Ends the editing of the current set of links.  The window
    is removed from the screen.  Since all changes to links are
    made immediately, this procedure does not abandon any of those
    changes.

  o Menu images:  Ends the editing of the menu.  The window is
    removed from the screen and from the Window Directory.  This
    command has the same effect as the Release procedure.  The Window
    parameter specifies which image to be abandoned.  The default is
    the current image.

  o Searchlists:  Ends the editing of the searchlist and removes the
    window from the screen.  Since all changes to searchlists are
    done immediately, this procedure does not abandon any of those
    changes.

  o Switches:  Abandons the editing of the switches.  The window is
    removed from the screen.  Any changes made to the switches since
    the last commit operation are lost.

  o Text images:  Ends the editing of the image.  Any changes made
    to the image since the last implicit or explicit commit are
    lost.  The window is removed from the screen and from the Window
    Directory.  The Window parameter specifies which window should
    be removed from the screen.  The default, "<IMAGE>", removes the
    current image.

    If a job is currently performing input or output on an I/O
    window, the Abandon procedure will fail.

  o Window images:  Ends the editing of the Window Directory by
    removing the Window Directory from the screen.  The Window
    parameter specifies the window to remove, which is, by default,
    the current image.  This command has the same effect as the
    Release procedure.

  o Xref images:  Ends the editing of the xref.  The window is
    removed from the screen and from the Window Directory.  This
    command has the same effect as the Release procedure.
  @node !Commands.Common.Clear_Underlining

  procedure Clear_Underlining;

  Removes all underlined error designations in the current image.

  These designations typically result from errors in the image,
  but they can also result from running other commands that use
  underlining to indicate specific locations in the image---for
  example, the Ada.Show_Usage command.

  Specifically, this procedure has the following effects:

  o Ada images:  Removes the underlining created by the Semanticize
    and other procedures.  The Semanticize procedure checks the image
    for semantic consistency, underlining semantic errors.

  o Command images:  Removes all underlines in the current Command
    window.
  @node !Commands.Common.Commit

  procedure Commit;

  Makes permanent any changes made to the image in the current
  window.

  Specifically, this procedure has the following effects:

  o Ada images:  Makes permanent any changes to the Ada image.  When
    source Ada images are edited, this procedure saves the changes to
    the image in the underlying permanent representation.  These
    changes are built in temporary areas until the changes are
    committed.  Then the temporary areas are made a permanent part of
    the storage hierarchy when a new version of the unit containing
    the changes is created.

    This procedure is used only for Ada images that are in the source
    state.  Direct editing changes (that is, not incremental) to an
    Ada image in a state other than the source state are not allowed.
    Changes to the unit caused by promoting or demoting the unit are
    permanent and need not be committed.

    The commit operation is also implicitly performed by the Promote,
    Ada.Install_Unit, Ada.Code_Unit (if the unit is source, the
    operation is not incremental, and the operation completes
    successfully), and Release procedures.

  o Command images:  Executes the command in the Command window by
    formatting, semanticizing, and coding it.  This procedure is
    identical to the Promote procedure.

  o Links:  Has no effect, because all changes to links are made
    immediately.  All other operations on links implicitly commit any
    changes.

  o Searchlists:  Commits changes to the searchlist.  Since all
    changes to searchlists are made immediately and permanently, this
    procedure has no effect.  All other operations on searchlists
    implicitly commit any changes.

  o Switches:  Commits changes to the switches.  Changes to the
    switches are made in a temporary area of the Environment.  To
    make those changes permanent and to have them take effect, you
    must commit those changes.

  o Text images:  Makes permanent any changes to the image.  Changes
    to the image are made in a temporary area.  This procedure saves
    those changes, making them permanent, by creating a new version
    of the text file that contains the changes.

    The procedure also commits input in I/O windows.  The input,
    along with a terminator or delimiter if necessary, is sent to the
    program that requested it.  The Window parameter specifies which
    window's image should be committed.  The default, "<IMAGE>",
    commits the current image.

  o Window images:  Makes permanent any changes to the image
    corresponding to the line designated in the Window Directory
    by executing the Common.Commit command on that image.  If there
    is no selection, the procedure executes the Common.Commit command
    on all uncommitted images that are not I/O windows.
  @node !Commands.Common.Complete

  procedure Complete (Menu : Boolean := True);

  Completes the design ated item by inserting new text and prompts
  into the image using information about the syntax and semantics of
  the image type.

  Specifically, this procedure has the following effects:

  o Ada images:  Completes the selected Ada identifier or the
    identifiers in the selected element using Ada's semantics
    for name resolution.  If more than one name can complete the
    identifier and the Menu parameter is set to true, a list of
    choices is produced in the menu window.  See the description of
    menus in this book for more information on the editing operations
    available on menus.

    The identifier is completed using the Ada context that exists for
    the compilation of the selected element, including with clauses,
    use clauses, renaming declarations, and so on.

  o Command images:  Completes the Ada fragment designated by the
    cursor using Ada semantics for name resolution.  If more than
    one name could complete the identifier, and the Menu parameter
    is true, a list of choices is produced in the menu window.  See
    the description of menus in this book for more information on the
    editing operations available on menus.

    This procedure completes only names of identifiers that are
    declared in the fragment in the Command window or that are
    visible through the searchlist.  See package Search_List
    in Session and Job Management (SJM) for more information on
    searchlists.

    Declarations in Command windows must be selected before the
    Complete command will actually complete them.  Statements need
    not be selected for the Complete command to complete them.

  o Library images:  Refreshes the library image in the current
    window to the current value of the underlying permanent
    representation and realigns the columns of the image.
  @node !Commands.Common.Create_Command

  procedure Create_Command;

  Creates a new Command window, if one does not already exist, before
  the current image, or it puts the cursor in the existing Command
  window that is closest to the current image.

  Command windows can be created for Command windows recursively.
  A Command window acting on another Command window can be used
  to create or edit commands or to perform another activity from
  the same context without disturbing the contents of the existing
  Command windows.

  Command windows have use clauses that are automatically added
  by the Create_Command procedure to provide direct visibility
  to the commands that are supported for the image type for which
  the Command window has been created.  Use clauses for packages
  !Commands.Editor and Common are always present.  Additional use
  clauses will be added based on the specific type of image for which
  the Command window has been created.

  Command windows can be created for all image types.

  Specifically, this procedure has the following effects:

  o Ada images:  Creates a Command window below the current Ada
    window if one does not exist; otherwise, it puts the cursor in
    the existing Command window below the current Ada window.  This
    Command window initially has a use clause:
      use Editor, Ada, Common, Debug;

    This use clause provides direct visibility to the declarations
    in packages Ada, Common, Debug, and Editor without requiring
    qualification for names resolved in the command.

  o Command images:  Creates a Command window below the current
    Command window if one does not exist; otherwise, it puts the
    cursor in the existing Command window below the current Command
    window.  This Command window initially has a use clause:
      use Editor, Command, Common;

    This use clause provides direct visibility to the declarations in
    packages !Commands.Editor, Common, and Command without requiring
    qualification for names resolved in the command.

    For certain other window types, other packages are added to the
    use clause to provide visibility to operations used to edit those
    kinds of windows.

  o Debugger:  Creates a Command window below the Debugger window if
    one does not exist; otherwise, the command puts the cursor in the
    existing Command window below the Debugger window.  This Command
    window initially has a use clause:
      use Editor, Common, Debug;

    This use clause provides direct visibility to the declarations in
    packages !Commands.Editor, Common, and Debug without requiring
    qualification for names resolved in the command.

  o Help and job windows:  Creates a Command window below the Help
    window or set of jobs if one does not exist; otherwise, the
    procedure puts the cursor in the existing Command window below
    the Help window or What.Jobs display.  This Command window
    initially has a use clause:
      use Editor, Common;

    This use clause provides direct visibility to the declarations in
    packages Editor and Common for names resolved in the command.

  o Library images:  Creates a Command window below the current
    library window if one does not exist; otherwise, the procedure
    puts the cursor in the existing Command window below the current
    library window.  This Command window initially has a use clause:
     use Editor, Library, Common;

    This use clause provides direct visibility to the declarations in
    packages !Commands.Editor, Library, and Common without requiring
    qualification for names resolved in the command.

  o Links:  Creates a Command window below the current window.  If
    the Command window is created below a window created by the
    Links.Edit or the Links.Visit command, the use clause in the
    Command window includes package Links.  Thus, operations in this
    package are visible in the Command window without qualification.

  o Menu images:  Creates a Command window below the menu if one
    does not exist; otherwise, the procedure puts the cursor in the
    existing Command window below the menu.  This Command window
    initially has a use clause:
      use Editor, Common;

    This use clause provides direct visibility to the declarations in
    packages !Commands.Editor and Common for names resolved in the
    command.

  o Searchlists:  Creates a Command window below the current
    window.  The use clause in the Command window includes package
    Search_List, so operations in package !Commands.Search_List are
    visible in the Command window without qualification.  The use
    clause for searchlist windows is:
      use Editor, Search_List, Common;

  o Switches:  Creates a Command window below the current window.
    The use clause in the Command window:
      use Editor, Ada, Switches, Common;

    includes this package, so operations in this package are visible
    in the Command window without qualification.

  o Text images:  Creates a Command window below the text window if
    one does not exist; otherwise, the procedure puts the cursor in
    the existing Command window below the text window.  This Command
    window initially has a use clause:
      use Editor, Text, Common;

    This use clause provides direct visibility to the declarations in
    packages !Commands.Editor, Text, and Common for names resolved in
    the command.

  o Window images:  Creates a Command window below the Window
    Directory if one does not exist; otherwise, the procedure
    puts the cursor in the existing Command window below the Window
    Directory.  This Command window initially has a use clause:
      use Editor, Common;

    This use clause provides direct visibility to the declarations in
    packages !Commands.Editor and Common for names resolved in the
    command.

  o Xref images:  Creates a Command window below the xref if one
    does not exist; otherwise, the procedure puts the cursor in the
    existing Command window below the xref.  This Command window
    initially has a use clause:
      use Editor, Ada, Common;

    This use clause provides direct visibility to the declarations in
    packages !Commands.Editor, Ada, and Common for names resolved in
    the command.
  @node !Commands.Common.Definition

  procedure Definition (Name     : String  := "<CURSOR>";
                       In_Place : Boolean := False;
                       Visible  : Boolean := True);

  Finds the defining occurrence of the named or designated item and
  displays that defining occurrence in a new window.

  This procedure finds the location where the item is defined.  The
  procedure attempts to find the most reasonable definition of the
  object, given the current editing context.

  Specifically, this procedure has the following effects:

  o Ada images:  Finds the defining occurrence of the designated
    element and brings up its image in a window on the screen,
    typically with the definition of the element selected.  If a
    name is provided to the Name parameter, it is used.  If no name is
    provided, the cursor location is used to designate the element.
    A read-only lock is acquired on the unit.

    The In_Place parameter specifies whether the current frame
    should be used.  The default is false.  The Visible parameter
    specifies whether the specification or body should be displayed.
    The default, true, specifies that the specification should be
    preferred.

    The procedure finds the most reasonable definition of the
    element, given the current editing context.  If the element
    is:

    ---A subunit stub or an insertion point, the corresponding
       subunit is viewed (if the Visible parameter is false).

    ---The visible part of a unit, the corresponding body of the unit
       is viewed (if the Visible parameter is false).

    ---The body of a unit, the corresponding visible part of the unit
       is viewed (if the Visible parameter is true).

    ---A usage of an identifier, the identifier's defining occurrence
       is viewed (if the Visible parameter is true or false).

    ---A declaration of an object, the object's type declaration is
       viewed (if the Visible parameter is true or false).

    If the selected or designated item is in a subsystem spec view,
    then the default session activity is used to find its definition.
    See Project Management (PM) for more information on subsystems
    and activities.

    The following tables illustrate some additional examples of the
    use of the Definition command with the Visible parameter true
    or false.  The first column specifies the location of the cursor
    when the Definition command is executed.  The second and third
    columns specify the effect of setting the Visible parameter to
    true or false, based on the position of the cursor.

  Example 1:
      package P1 is new P; -- instantiation of generic
           . . .
           P1.B;

  Example 2:
      type T; -- incomplete type declaration
           . . .
      type T is new integer; -- corresponding full type declaration
           X:T;
           . . .

  Example 3:
      type T is private;
           . . .
      type T is new integer;
           . . .
           X:T;

    Example 4:
      task type T; -- task incomplete type
           . . .
      task type T is -- specification
           . . .
      task body T is
           . . .
           X:T;

  o Command images:  Finds the defining occurrence of the named or
    designated element and brings up its image in a window on the
    screen, typically with the definition of the element selected.
    The Semanticize or Promote procedure must have been executed
    on the window containing the named or designated element.  If a
    name is provided for the Name parameter, it is used.  If no name
    is provided, a selection is used if one exists.  Otherwise, the
    cursor location is used to designate the element.

    The procedure finds the most reasonable definition of the
    element, given the current editing context and the value of
    the Visible parameter.  The Name parameter specifies which
    element's definition should be given.  The In_Place parameter
    specifies whether the current window should be used, and the
    Visible parameter specifies whether the specification or the body
    should be preferred.

  o Debugger:  Finds the defining occurrence of the designated
    element and brings up its image in a window on the screen,
    typically with the definition of the element selected.

  o Help and job windows:  Brings up on the screen, for help windows,
    an image of the Ada specification unit containing the designated
    declaration in a Help window declaration.  This procedure has no
    effect on displays created by What.Jobs.

  o Library images:  Finds the defining occurrence of the named
    or designated element and brings up its image in a window on
    the screen.  If a name is provided, it is used.  If no name
    is provided, a selection with the cursor in it is used if one
    exists.  Otherwise, the cursor location is used to designate the
    element.  An In_Place parameter specifies whether the existing
    window should be used.  A Visible parameter specifies whether to
    go to the visible part or the body (if possible).

  o Links:  Finds the definition of the selected link or the link on
    which the cursor is located.  This procedure creates or visits a
    window that contains the specification of the source unit of the
    selected link.

  o Menu images:  Brings up on the screen an image of the Ada
    compilation unit containing the designated declaration.  The
    Name parameter specifies which image to display.  The In_Place
    parameter specifies whether the current window should be used.
    The Visible parameter specifies whether the specification or body
    should be displayed.

  o Searchlists:  Finds the definition of the component in the
    searchlist to which the cursor points.  This procedure creates
    a window containing that component.  The In_Place parameter
    allows the user to specify whether the new window will replace
    the current window.  The Visible parameter specifies whether the
    specification or the body should be preferred.

  o Switches:  Finds the definition of the selected switch value
    if that value is a library or library unit.  The procedure
    produces an error for switches that are Booleans, integers,
    or nonswitch name strings.  If the switch is a switch name, a
    window is brought up with the definition of that object in the
    window.

  o Window images:  Moves the cursor to the image of the currently
    designated line, bringing that image onto the screen if
    necessary.  The Name parameter specifies which image should
    be displayed.  By default, it is the image corresponding to the
    current cursor location on the Window Directory.  The In_Place
    parameter specifies whether the current window should be used
    to display the image.  By default, the Window Directory is the
    next window replaced.  The Visible parameter specifies whether
    the specification or the body should be displayed.  The default,
    true, displays the specification.

  o Xref images:  Displays on the screen an image of the designated
    compilation unit with all usages of the declaration indicated
    with underlines.  If the current level of detail is either views
    or subsystems, the procedure brings the image for the designated
    library onto the screen with no underlining.

    The cursor can be moved between underlined usages with the
    !Commands.Editor.Cursor.Next and Editor.Cursor.Previous
    commands.  The usage indications can be removed with the
    Clear_Underlining command.

    Some of the units in the xref display may implicitly depend on a
    declaration but may not have direct usages of the declaration.
    Also, the Environment is conservative about finding all possible
    units that depend on the declaration.  Sometimes it accidentally
    includes a unit in the xref that has no reference.  In these
    cases, executing the Definition command when designating such a
    unit deletes the unit from the xref and gives the message:
      <unit name> doesn't have references!  Zapping the line.

    Executing the Semanticize procedure searches each unit in the
    xref and deletes any entries that have no usages.

  @node !Commands.Common.Demote

  procedure Demote;

  Demotes the designated item to a lower state.

  Specifically, this procedure has the following effects:

  o Ada images:  Demotes an Ada unit or element to a lower unit
    state.  If there is no selection or if the current selection
    is for an entire compilation unit, the procedure changes the
    state of the Ada unit in the current window, assuming there are
    no dependent units.  If there are dependent units, a list of them
    is displayed in the menu window that is brought onto the screen.
    See the description of menus in this book for more information on
    the editing operations available on menus.

    The specific effect of this procedure depends on the current
    state of the unit.  If the current state is:

    ---Archived:  The procedure has no effect.

    ---Source:  The procedure has no effect.

    ---Installed:  The unit is demoted to the source state.

    ---Coded:  The unit is demoted to the installed state.

    If there is a selection other than the entire unit and if
    incremental compilation is allowed on the element selected
    (see the rules on incremental compilation stated above), this
    procedure removes the element from the parent unit, replaces it
    with an insertion point, and leaves the element in the source
    state attached to the insertion point.  The source for the
    element can be visited later by viewing the insertion point.

  o Command images:  Ends the editing of the command.  The contents
    of the Command window are destroyed and the original contents are
    restored.  All history is lost.

  o Library images:  Demotes the selected Ada unit to the next lower
    state.  The procedure changes the state of the selected Ada unit,
    assuming there are no other units dependent on the unit.  If
    there are dependent units, a list of them is displayed in the
    menu window that is brought onto the screen.  See Menus, in this
    book, for more information on the editing operations available on
    menus.

    The specific effect of this procedure depends on the current
    state of the unit.  If the current state is:

    ---Archived:  The procedure has no effect.

    ---Source:  The procedure has no effect.

    ---Installed:  The unit is demoted to the source state.

    ---Coded:  The unit is demoted to the installed state.

  o Menu images:  Attempts to demote the Ada unit containing the
    designated declaration to the next lower state.  The specific
    effect of this procedure depends on the current state of the unit
    and whether other units depend on the unit on which the demote
    is being attempted.  If there are no dependents and the current
    state is:

    ---Archived:  The procedure has no effect.

    ---Source:  The procedure has no effect.

    ---Installed:  The unit is demoted to the source state.

    ---Coded:  The unit is demoted to the installed state.

    If there are dependents, they are indicated by overwriting of the
    existing menu with a new menu containing these dependencies.

  o Text images:  Changes the current text window from read only to
    editable.  If another user or job has a write lock on the file
    being viewed, the Demote command will fail.  The procedure has no
    effect on I/O windows.

  o Window images:  Executes the Common.Demote procedure on the
    designated image.

  o Xref images:  Executes the Common.Demote procedure for Ada images
    on the selected unit.
  @node !Commands.Common.Edit

  procedure Edit (Name     : String  := "<IMAGE>";
                 In_Place : Boolean := False;
                 Visible  : Boolean := False);

  Creates a writable image of the named or designated item, creating
  the window if necessary.

  This procedure creates a new window that contains an image of the
  item to be edited.  If a window with the image already exists, it
  is reused.  The window is created with the default window size and
  is placed by the Rational Editor.  The window remains in the Window
  Directory until the object is released or abandoned.  The window
  disappears if it contains withdrawn or incrementally inserted
  declarations when the declarations or statements are promoted
  successfully.

  Specifically, this procedure has the following effects:

  o Ada images:  Creates a window in which to edit the named or
    selected Ada unit and demotes the unit to source if necessary.

    If there is no selection or if the current selection is for an
    entire compilation unit or subunit declaration, the procedure
    creates a window in which to edit the unit, if necessary, and
    demotes the unit to source if no units depend on the unit.  If
    there are dependent units, a list of them is displayed in the
    menu window that is brought onto the screen, and the operation
    fails.  See the description of menus in this book for more
    information on the editing operations available on menus.  If
    the operation succeeds, a write lock is acquired on the unit.

    If there is a selection other than the entire unit and if
    incremental compilation is allowed on the element selected
    (see the rules on incremental compilation stated above), this
    procedure removes the element from the parent unit, replaces
    it with an insertion point, and brings up a new window with the
    element in it.

    The Name parameter specifies the unit to edit.  The default is
    "<IMAGE>".  The In_Place parameter specifies whether the current
    window should be used.  The Visible parameter specifies whether
    the specification or body should be preferred.

  o Command images:  Replaces the contents of the Command window with
    a [statement] prompt.

  o Library images:  Creates a window in which to edit the named or
    selected object.  An In_Place parameter specifies whether the
    existing window should be used.  A Visible parameter specifies
    whether to bring up the visible part or the body (if possible).

  o Links:  Creates a Command window and places in it the command:
      Update ("selected or current link");

    where selected or current link is the link on which the cursor
    is currently located, whether or not there is a selection.
    Providing a new parameter and promoting the command changes
    the source name for that link.

  o Menu images:  Creates a window in which to edit the Ada unit
    containing the selected declaration.  The procedure demotes the
    unit to the source state, if necessary.  If the demotion of the
    unit will cause obsolescence, the edit fails and a new menu of
    dependent units replaces the existing menu contents.  The Name
    parameter specifies which unit to edit.  The In_Place parameter
    specifies whether the current frame should be used.  The Visible
    parameter specifies whether the specification or body should be
    displayed.

  o Searchlists:  Creates a Command window below the searchlist and
    places in it the command:
      Replace (New_Component =>  "current value",
              Old_Component => "",
              Session => "",
              User => "");

    The New_Component parameter allows the user to specify the new
    searchlist component.  The Old_Component parameter specifies
    the searchlist component to be replaced.  The user and session
    parameters specify the User and Session whose searchlist should
    be modified.  The user must have read access to another user's
    home world to modify that user's searchlist.

  o Switches:  Creates a Command window and places in it the command:
      Change ("current switch value");

    where the parameter is the switch value of the switch on which
    the cursor is located, whether or not there is a selection.
    Providing a new switch value and promoting the command changes
    the value of the switch.  If the current switch is of Boolean
    type, the command toggles the value of the switch without
    creating a Command window.

  o Text images:  Makes the current text window editable by acquiring
    a write lock on the file associated with the window.  If other
    users or jobs have write locks on the file, the operation will
    fail.  The procedure has no effect on I/O windows.

    The Name parameter specifies which text window should be made
    editable.  The default special name, "<IMAGE>", specifies the
    current image or selection in a library image (if there is one).
    The In_Place parameter specifies whether the current frame should
    be used.  The default, false, specifies that the current frame
    should not be used.

  o Window images:  Moves the cursor to the image of the currently
    designated image, bringing that window onto the screen if
    necessary.  If the type of the designated image discriminates
    between viewing using the Definition command and editing
    using the Edit command, the procedure performs the operations
    associated with executing the Edit command on the designated
    image, unless these operations have already been performed on the
    image.

    The Name parameter specifies which image should be displayed.
    The default is the image on which the cursor is located.  The
    In_Place parameter specifies whether the current window should
    be used to display the image.  The default is false.  The Visible
    parameter specifies whether the specification or the body should
    be displayed.  The default, true, displays the specification.
  @node !Commands.Common.Elide

  procedure Elide (Repeat : Positive := 1);

  Reduces the level of detail displayed in the image for the
  currently designated item.

  This procedure accepts argument prefixes when executed from the
  keyboard to enable multiple levels of detail to be eliminated in a
  single operation.

  Specifically, this procedure has the following effects:

  o Help and job windows:  Selects which set of jobs is displayed in
    the window.  The procedure steps the display from all jobs, to
    all running jobs, to the user's jobs, to the user's running jobs,
    to all commands, to all running commands, to the user's commands,
    to the user's running commands.  The default is all running jobs.
    This procedure has no effect on Help windows.

  o Library images:  Reduces the level of detail displayed for the
    designated object(s).

  o Links:  Selects which type of link is displayed in the window.
    This procedure cycles the display from all links (the default) to
    external links and then to internal links.

  o Menu images:  Decreases the level of detail displayed for the
    selected declaration to the next lower level.  If no declaration
    is selected, the procedure decreases the level of detail for all
    of the declarations in the menu to the next lower level.  The
    levels of detail available, ordered from lowest to highest, are:

    ---Simple names

    ---Full names

    ---Simple names with parameter profiles (the default)

    ---Full names with parameter profiles

    These levels are not circular; that is, expanding has no effect
    once the highest level of detail has been reached, and eliding
    has no effect once the lowest level of detail has been reached.

  o Switches:  Reduces (elides) the number of switches displayed in
    the window.  The window can display all switches in the system
    (the greatest number displayed) or the nondefault switches in the
    file (the least number displayed).  This procedure reduces the
    number displayed to the next smaller set.  Reducing the number
    below the nondefault switches has no effect.

  o Xref images:  Reduces the level of detail displayed in the
    current xref.  This command is the opposite of the Expand
    command.

    Although, by default, an xref displays the full name for each
    using unit, other levels of detail can be displayed using the
    Elide and Expand commands.  These options are:

    ---Full_Names:  Displays the full names of each unit with
       attributes (the default).

    ---Objects:  Displays the unit name with attributes.

    ---Views:  Displays the views using the declaration.

    ---Subsystems:  Displays the subsystems using the declaration.

    Executing the Elide command moves the level of detail down
    the above list; executing the Expand command moves the level
    of detail up the above list.  The list is circular, so if you
    attempt to move down past the bottom, you go to the top; if you
    move up past the top, you go to the bottom.  The current level of
    detail for an xref image is indicated in the banner for the xref.
  @node !Commands.Common.Enclosing

  procedure Enclosing (In_Place : Boolean := False;
                      Library  : Boolean := False);

  Finds the parent or enclosing item of the image in the current
  window and displays that item in a new window.

  Specifically, this procedure has the following effects:

  o Ada images:  Finds the parent or enclosing Ada unit of the
    current window and displays that parent unit in a window.
    This procedure acquires a read lock on the unit.  The In_Place
    parameter specifies whether the current window should be used.
    The Visible parameter specifies whether the specification or body
    should be preferred.  The Library parameter specifies whether the
    resulting image should be a library.

  o Command images:  Finds the major window to which the Command
    window is attached and puts the cursor in it.  The In_Place
    parameter specifies whether the current window should be used.
    The Library parameter specifies whether the enclosing object
    should be a library.

  o Debugger:  Displays the library containing the Command window
    from which the job being debugged was started.

  o Library images:  Finds the parent library unit of the current
    library and displays that parent in a window.  An In_Place
    parameter specifies whether the existing window should be used.
    A Library parameter specifies whether the resulting image should
    be a library rather than the parent body when the parent body is
    not a library.

  o Links:  Finds the world that contains the links that are in the
    current window.  This procedure creates a window that contains
    the listing of that world.

  o Switches:  Finds the directory or world that contains the
    switches that are in the current window.  If the window contains
    session switches, the procedure finds the home world for that
    session.  The In_Place parameter specifies whether the library
    window replaces the switch window.

  o Text images:  Brings up a window that contains an image of the
    library containing the file corresponding to the current text
    window.  For I/O windows, the Enclosing procedure finds the home
    library for the user.

    The In_Place parameter specifies whether the current frame should
    be used.  The default, false, specifies that the current frame
    should not be used.  The Library parameter specifies whether the
    enclosing library should be displayed.  The default is false.

  o Xref images:  Displays the library containing the unit for which
    the xref was created, with the unit selected.
  @node !Commands.Common.Expand

  procedure Expand (Repeat : Positive := 1);

  Increases the level of detail displayed in the image for the
  currently designated item.

  This procedure accepts argument prefixes when executed from the
  keyboard to enable multiple levels of detail to be added in a
  single operation.

  Specifically, this procedure has the following effects:

  o Help and job windows:  Selects which set of jobs is displayed in
    the window.  The procedure steps the display from the user's
    running commands, to the user's commands, to all running
    commands, to all commands, to the user's running jobs, to the
    user's jobs, to all running jobs, to all jobs.  The default is
    all running jobs.  This procedure has no effect on Help windows.

  o Library images:  Increases the level of detail displayed for the
    designated object(s).

  o Links:  Selects which type of link is displayed in the window.
    This procedure cycles the display from internal links to external
    links and then to all links (the default).

  o Menu images:  Increases the level of detail displayed for the
    selected declaration to the next higher level.  If no declaration
    is selected, the procedure expands the level of detail for all
    of the declarations in the menu to the next higher level.  The
    levels of detail available, ordered from lowest to highest, are:

    ---Simple names

    ---Full names

    ---Simple names with parameter profiles (the default)

    ---Full names with parameter profiles

    These levels are not circular; that is, expanding has no effect
    once the highest level of detail has been reached, and eliding
    has no effect once the lowest level of detail has been reached.

  o Switches:  Increases (expands) the number of switches displayed
    in the window.  The window can display all switches in the system
    (the most number displayed) or all nondefault switches in the
    file (the least number displayed).  This procedure increases the
    number displayed to the next larger set.  Increasing the number
    above all switches in the system has no effect.

  o Xref images:  Increases the level of detail displayed in the
    current xref.  This command is the opposite of the Elide command.

    Although, by default, an xref displays the full name for each
    using unit, other levels of detail can be displayed using the
    Expand and Elide commands.  These options are:

    ---Full_Names:  Displays the full names of each unit with
       attributes (the default).

    ---Objects:  Displays the unit name with attributes.

    ---Views:  Displays the views using the declaration.

    ---Subsystems:  Displays the subsystems using the declaration.

    Executing the Elide command moves the level of detail down
    the above list; executing the Expand command moves the level
    of detail up the above list.  The list is circular, so if you
    attempt to move down past the bottom, you go to the top; if you
    move up past the top, you go to the bottom.  The current level of
    detail for an xref image is indicated in the banner for the xref.
  @node !Commands.Common.Explain

  procedure Explain;

  Provides explanatory information regarding the designated item in
  the current window.

  Specifically, this procedure has the following effects:

  o Ada images:  Provides an explanation of the error designated by
    the cursor position in the Ada unit in the current window.  Used
    after syntactic or semantic errors have been discovered, the
    procedure displays an explanation of those errors in the Message
    window.

  o Command images:  Provides an explanation of errors in the command
    in the current window.  Used after syntactic or semantic errors
    have been discovered, the procedure displays an explanation of
    those errors in the Message window.

  o Help and job windows:  Adds an entry to the Help window for the
    designated item in a Help window menu.  This procedure has no
    effect on displays created by What.Jobs.

  o Library images:  Changes the level of detail displayed for the
    designated object(s) in the library.  There are three levels:

    ---Default information

    ---Standard information

    ---Miscellaneous information

    This command cycles through the levels, proceeding down the list
    and cycling back to the top when at the bottom.

  o Links:  Inserts an explanation below the current link that
    explains what units use the linked unit.  This procedure is
    useful for determining what dependencies on links exist.  If
    there already is an explanation explaining the link, this
    procedure removes that explanation.

  o Switches:  Inserts, below the current switch, an explanation of
    that switch.  If an explanation is already there, this procedure
    will remove it.

  o Xref images:  Displays the full name of the currently designated
    unit in the Message window.
  @node !Commands.Common.Format

  procedure Format;

  Formats the current image appropriately for its image type.

  For Ada units, this procedure checks the syntax of the image,
  performs syntactic completion, and pretty-prints again.

  If changes are incomplete fragments, this procedure provides
  syntactic completion and prompting based on the syntax rules for
  the image type, and then it pretty-prints the image again with
  these changes and completions aligned and capitalized properly.

  Specifically, this procedure has the following effects:

  o Ada images:  Formats the text in the current window.  The
    procedure redraws some or all of the image after checking for
    syntactic errors and correcting or prompting for some of the
    syntactic constructs.  If there are syntax errors in the image
    that cannot be corrected, they are marked as errors.

    This procedure adds ending punctuation, including semicolons,
    right parenthesis, closing quotation marks, end loop statements,
    end if statements, and end statements for packages and
    subprograms.  Note that end statements are usually placed as
    close to the end of the source as is legal.

    Some of the behavior of the commands for editing Ada images can
    be tailored with session switches.

    The case of identifiers in formatted Ada images is determined
    by the Keyword_Case library switch.  Allowable values for this
    switch are Upper, Lower, and Capitalize.

    See package Switches in Library Management (LM) for more
    information on library switches.

    Example 1:

  Before the Format procedure:
      procedure Push is begin

  After the Format procedure:
      procedure Push is
      begin
          [statement]
      end Push;

    Example 2:

  Before the Format procedure:
      if case when

  After the Format procedure:
      if [expression] then
          case [expression] is
             when [expression] =>
                 [statement]
          end case;
      end if;

  o Command images:  Formats the text in the current Command window.
    The procedure redraws some or all of the image after checking
    for syntactic errors and correcting or prompting for some of the
    syntactic constructs.  If there are syntactic errors in the image
    that cannot be corrected, they are marked as errors.

    Some of the behavior of the commands for editing commands can be
    tailored with session switches.

    The case of identifiers in formatted Ada images is determined
    by the Keyword_Case library switch.  Allowable values for this
    switch are Upper, Lower, and Capitalize.  Only one of these
    switches should have the value of true.  The switch that is
    true determines how identifiers are displayed after the Format
    operation.

    See package Switches in Library Management (LM) for more
    information on session switches.

    Example 1:

  Before the Format procedure:
      declare
          use Editor, Common, Ada;
      begin
          if
      end;

  After the Format procedure:
      declare
          use editor, Common, Ada;
      begin
          if [expression] then
             [statement]
          end if;
      end;

  o Library images:  Refreshes the library image in the current
    window to the current value of the underlying permanent
    representation and realigns the columns of the image.

    This performs the same operation as the Revert procedure.
  @node !Commands.Common.Insert_File

  procedure Insert_File (Name : String := "<REGION>");

  Inserts the named text file into the current Ada image at the
  current cursor position.

  No semantic analysis of the contents of the file or the resulting
  object is done.

  Specifically, this procedure has the following effects:

  o Ada images:  Copies the contents of the text file specified in
    the Name parameter into the current Ada image at the current
    cursor position.

  o Command images:  Copies the contents of the named text file into
    the Command window at the current cursor position.

  o Text images:  Inserts the named text file into the current Ada
    image at the current cursor position.
  @node !Commands.Common.Promote

  procedure Promote;

  Promotes the designated item to the next higher state.

  Specifically, this procedure has the following effects:

  o Ada images:  Promotes the Ada image in the current window to
    the next higher state.  The procedure changes the state of the
    Ada unit.  The specific effect of this procedure depends on the
    current state of the unit.  If the current state is:

    ---Archived:  The unit is promoted to the source state.

    ---Source:  The unit is promoted to the installed state.

    ---Installed:  The unit is promoted to the coded state.

    ---Coded:  Execution is attempted if the unit is selected.  If
       parameters are required, the prompt for them appears in the
       Command window.

    If the current window is associated with an insertion point
    created by incremental compilation and the elements in the window
    are to be inserted in-line in the parent unit, this procedure
    causes the elements in the window to be inserted in the parent
    and the window is deleted.

  o Command images:  Executes the command by formatting,
    semanticizing, and coding it.  This command is the same as the
    Commit procedure.

  o Library images:  Promotes the selected Ada object to the next
    higher unit state.  The specific effect of this procedure depends
    on the current unit state of the unit.  If the current state is:

    ---Archived:  The unit is promoted to the source state.

    ---Source:  The unit is promoted to the installed state.

    ---Installed:  The unit is promoted to the coded state.

    ---Coded:  If the unit is selected, execution is attempted.  If
       parameters are required, the prompt for them appears in a
       Command window.

  o Menu images:  Promotes the Ada unit containing the designated
    declaration to the next higher state.  This procedure has the
    same effect as executing the Common.Promote command on the Ada
    unit containing the designated declaration.  The specific effect
    of this procedure depends on the current state of the unit.  If
    the current state is:

    ---Archived:  The unit is promoted to the source state.

    ---Source:  The unit is promoted to the installed state.

    ---Installed:  The unit is promoted to the coded state.

    ---Coded:  The procedure has no effect.

  o Switches:  Commits changes to the switches.  Changes to switches
    are made in a temporary area of the Environment.  To make these
    changes permanent and to have them take effect, you must commit
    those changes.

  o Text images:  Commits changes to the image and releases the write
    lock on the underlying file.  Changes to the image are made in
    a temporary area.  This procedure saves those changes, making
    them permanent, by creating a new version of the text file that
    contains the changes.

    The procedure also commits input in I/O windows.  The input,
    along with a terminator or delimiter if necessary, is sent to the
    program that requested it.

  o Window images:  Executes, on the image corresponding to the
    selected line, the Common.Promote procedure specific to that
    image type.  If the image promoted is of Ada type and semantic
    errors are found, the image of the promoted unit is brought onto
    the screen with the errors underlined.

  o Xref images:  Executes the Common.Promote procedure for the
    selected Ada images on the xref.
  @node !Commands.Common.Redo

  procedure Redo (Repeat : Positive := 1);

  Redoes the Repeat changes previously made to an image.

  The Rational Editor maintains histories of the temporary copies
  of some image types as images of these types are changed.  These
  histories allow changes to be undone, going back in time through
  each set of changes to the beginning of time for the image.  Change
  histories can be stepped forward or backward with the Redo and Undo
  procedures, respectively.

  Change histories are retained by the Rational Editor, depending on
  the type of image.  These histories are destroyed or restarted when
  the session ends and at other times, depending on the type of image
  being edited.

  The opposite of this procedure is the Undo procedure.

  Specifically, this procedure has the following effects:

  o Command images:  Recalls commands entered in a Command window
    after the Undo procedure is executed on the Command window.  The
    Rational Editor remembers changes made to command images since
    the Command window was created.  Each execution of the Complete,
    Edit, Demote, and Revert procedures marks another change, as well
    as execution of the command.  The Repeat parameter specifies the
    number of commands to move forward in the history.
  @node !Commands.Common.Release

  procedure Release (Window : String := "<IMAGE>";

  Ends editing on the current image and makes changes permanent.

  This procedure releases any locks the Rational Editor may have in
  the entity being edited, destroys the window, and removes the image
  from the Window Directory.

  This command does an implicit commit of the image.

  Specifically, this procedure has the following effects:

  o Ada images:  Ends the editing of the Ada unit.  The unit is
    unlocked, and any changes to the image are committed (made
    permanent).  This window specified by the Window parameter is
    removed from the screen and from the Window Directory.

  o Command images:  Ends the editing of the command.  The Command
    window is destroyed and removed from the screen.  All history is
    lost.  The Window parameter specifies the window to be released.

  o Debugger:  Deletes the Debugger window if the Debugger has been
    killed.  Otherwise the command has no effect.  This command has
    the same effect as the Abandon procedure.

  o Help and job windows:  Removes the window from the screen for the
    What.Jobs display.  For Help windows, this procedure removes the
    Help window from the screen and from the Window Directory.  This
    procedure has the same effect as the Abandon procedure.

  o Library images:  Ends the editing of the library image.  The
    library image window is removed from the screen and from the
    Window Directory.

  o Links:  Ends the editing of the current set of links.  The window
    is removed from the screen.

  o Menu images:  Ends the editing of the menu.  The window is
    removed from the screen and from the Window Directory.  This
    command has the same effect as the Abandon procedure.  The Window
    parameter specifies which window to release.  The default is the
    current image.

  o Searchlists:  Ends the editing of the searchlist and removes the
    window from the screen.

  o Switches:  Commits changes and ends the editing of the switches.
    The window is removed from the screen after any changes to the
    switches are saved.

  o Text images:  Ends the editing of the text and removes the image
    from the Window Directory.  All changes to the text are made
    permanent before the window is removed from the screen.  A new
    version of the underlying file is created if changes are saved.

    If a job is currently performing input or output on an I/O
    window, the Release procedure will fail.

    The Window parameter specifies which window should be released.
    The default is the current image.

  o Window images:  Ends the editing of the Window Directory by
    removing the Window Directory from the screen.  The Window
    parameter specifies the window to be removed.  The default is the
    current image.  This command has the same effect as the Abandon
    procedure.

  o Xref images:  Ends the editing of the xref image.  The window
    is removed from the screen and from the Window Directory.  This
    command has the same effect as the Abandon procedure.
  @node !Commands.Common.Revert

  procedure Revert;

  Restores the image in the current window to the current committed
  (permanent) value of the entity being edited and discards any
  changes that may have been made to the image.

  Specifically, this procedure has the following effects:

  o Ada images:  Reverts the Ada image in the current window to the
    current value of the underlying permanent representation.

  o Command images:  Redraws the command in the current window.

  o Help and job windows:  Redraws the set of jobs to reflect the
    current state for the What.Jobs display.  This procedure has no
    effect on Help windows.

  o Library images:  Refreshes the library image in the current
    window to the current value of the underlying permanent
    representation and realigns the columns of the image.

    This performs the same operation as the Common.Format procedure.

  o Links:  Redraws the set of links in the current window.  If the
    set of links has been changed by another user or program, the new
    image reflects those changes.

  o Searchlists:  Redraws the searchlist in the current window.  If
    the searchlist has been changed by another user or program, this
    procedure redraws the list to ensure that the image is up to
    date.

  o Switches:  Redraws the switches in the current window.  If the
    switches have been changed by another user or program, this
    procedure redraws the switches to ensure that the image is up to
    date.

  o Text images:  Refreshes the image in the current window with the
    current value of the underlying file.  Note that, if a job is
    writing into a file and the file is concurrently being viewed
    with the Rational Editor, the Revert command can be used to
    update the image to show any new output that has occurred since
    the last Revert procedure.

  o Window images:  Refreshes the image of the Window Directory so
    that the entries in it are current.
  @node !Commands.Common.Semanticize

  procedure Semanticize;

  Checks the image in the current window to ensure that it is correct
  according to the syntax and semantic rules for the type of the
  image and indicates any errors.

  Specifically, this procedure has the following effects:

  o Ada images:  Checks the Ada unit for semantic correctness.  The
    procedure checks for compliance with the semantic rules of the
    Ada language.  Errors discovered during semantic checking are
    underlined.

  o Command images:  Checks the command for semantic correctness.
    The procedure checks for compliance with the semantic rules of
    the Ada language.  Errors discovered during semantic checking are
    underlined.  This procedure must be executed either directly or
    indirectly (by using the Promote procedure) before the Definition
    procedure will execute successfully.

  o Xref images:  Searches each unit in the xref for actual usages
    and deletes any entries for units with no usages.
  @node !Commands.Common.Sort_Image

  procedure Sort_Image (Format : Integer := 1);

  Sorts the display according to the given format.

  Format numbering is specific to the object type.  It is assumed
  that when the Format parameter is assigned the default value of
  1, the display is sorted by increasing values.  When the Format
  parameter has a value of --1, the image will be formatted in
  decreasing value.

  Specifically, this procedure has the following effects:

  o Links:  Selects the order in which to display the set of links.
    This procedure cycles the display from alphabetic by link names
    (the default), to alphabetic by source names, to alphabetic
    internal link names followed by alphabetic external link names,
    and to alphabetic internal source names followed by alphabetic
    external source names.
  @node !Commands.Common.Undo

  procedure Undo (Repeat : Positive := 1);

  Undoes the previous Repeat sets of changes to the current image.

  The Rational Editor maintains histories of the temporary copies
  of some image types as images of these types are changed.  These
  histories allow changes to be undone, going back in time through
  each set of changes to the beginning of time for the image.  Change
  histories can be stepped forward or backward with the Redo and Undo
  procedures, respectively.

  Change histories are retained by the Rational Editor, depending on
  the type of image.  These histories are destroyed or restarted when
  the session ends and at other times, depending on the type of image
  being edited.

  The opposite of this procedure is the Redo procedure.

  Specifically, this procedure has the following effects:

  o Command images:  Recalls changes previously made to a command.
    The Rational Editor remembers changes made to command images
    since the Command window was created, called a history.  Each
    execution of the Edit, Demote, and Revert procedures marks
    another change, as well as each execution of the command.  As
    commands are undone, the last undone command in the history
    becomes the place where new user-entered commands are saved
    in the history.  These changes can be reinstated with the Redo
    procedure.  The Repeat parameter specifies the number of commands
    to move backward in the history.

  o Library images:  Undeletes the selected object.  This procedure
    is similar to the !Commands.Library.Undelete procedure.
  @node !Commands.Common.Write_File

  procedure Write_File (Name : String := ">>FILE NAME<<");

  Writes the contents of the current selection into the named file.

  If no there is no selection, this procedure writes the contents of
  the current image into the named file.

  Specifically, this procedure has the following effects:

  o Command images:  Copies the contents of the selection in the
    Command window to the file specified by the Name parameter.

  o Debugger:  Writes the current contents of the Debugger window
    into the named file.

  o Text images:  Writes the contents of the current selection in the
    named file.  If there is no selection, this procedure writes the
    contents of the current image into the named file.  The previous
    contents of the file are lost.
  @node !Commands.Common.Object

  Package Object contains procedures for making selections based on
  the underlying type-specific structures of images and performing
  basic editing operations (including moving and copying) on these
  selections.  For information on selecting regions of text and
  for procedures for selecting portions of images as text, see EI,
  package Editor.Region.
  @node !Commands.Common.Object.Child

  procedure Child (Repeat : Positive := 1);

  Selects the child of the designated item Repeat number of times,
  each time selecting the child of the child just selected.

  The child is the item at the next lower level, in a syntactic
  sense, from the current item.  The child that encloses the cursor
  is selected unless no such child exists.

  Specifically, this procedure has the following effects:

  o Ada images:  Selects the Repeat child element of the currently
    selected element.  A child element is one of the elements at
    the next lower level, in a syntactic sense, from the currently
    selected element.  If an object at that level has not been
    selected before, the smallest element enclosing the cursor is
    chosen.  If an element at that level has been selected before,
    the selection is turned off.

  o Command images:  Selects a child element of the currently
    selected element.  A child element is one of the images at the
    next lower level, in a syntactic sense, from the current element.
    If an element at that level has not been selected before, the
    element on which the cursor is currently located is chosen.  If
    an element at that level has been selected before, the selection
    is turned off.

  o Debugger:  Selects the Repeat child element of the currently
    selected element.  A child element is one of the elements at
    the next lower level, in a syntactic sense, from the currently
    selected element.  If an object at that level has not been
    selected before, the smallest element enclosing the cursor is
    chosen.  If an element at that level has been selected before, it
    is selected again.

  o Help and job windows:  Selects the job on the line on which the
    cursor is located for the What.Jobs display, if one or more jobs
    are already selected when the procedure is entered.  If there
    is a selection, the procedure leaves the current line selected.
    For Help windows, if the whole Help window is selected, the
    procedure selects the declaration on the line on which the cursor
    is located.  If there is a selection, it leaves the current line
    selected.

  o Library images:  Selects the child of the current selection.
    The procedure selects the line the cursor is on if there are no
    selections or if the cursor is not in the selection.  If there is
    a line selected, the procedure selects the first child of that
    line.  If the selected line has no child, it selects the next
    line.

  o Links:  If no link is selected, the procedure selects the link
    on which the cursor is located.  If a single link is already
    selected, the procedure has no effect.  If all links are already
    selected, the procedure selects the link on which the cursor is
    located.

  o Menu images:  Selects the declaration on the line on which the
    cursor is located.

  o Searchlists:  Selects the component in the searchlist on
    which the cursor is located.  If all components are already
    selected, the procedure selects the component on which the
    cursor is located.  If a single component is already selected,
    the procedure has no effect.  If no component is selected, the
    procedure selects the component on which the cursor is located.

  o Switches:  Selects the switch on which the cursor is located.
    Specifically, if no switch is selected, the procedure selects
    the switch on which the cursor is located.  If a single switch is
    already selected, the procedure has no effect.  If all switches
    are already selected, the procedure selects the switch on which
    the cursor is located.

  o Text images:  Selects the next lower-level item in the
    hierarchical structure of a text image.  The item selected will
    be the one the cursor is in if such an item exists.  If no items
    are selected, the word closest to the cursor is selected.

    The Repeat parameter specifies the number of levels to move
    down in selecting the image.  The default, 1, specifies the next
    lowest level.

  o Window images:  Selects the line on which the cursor is located,
    when the entire image is selected.  When a single line is
    selected, the line is still selected.  When nothing is selected,
    the procedure does nothing.

  o Xref images:  Selects the unit on the line on which the cursor is
    located.
  @node !Commands.Common.Object.Copy

  procedure Copy;

  Copies the selected item to the cursor position.

  Specifically, this procedure has the following effects:

  o Ada images:  Copies the selected element to the cursor position.
    The new copy is in the source state.  No semantic analysis is
    done on the selection in its new location, although a check is
    performed to ensure that a declaration is put in a declarative
    region and a statement is put in a statement region.  Contained
    units of the copied element are not copied.

  o Library images:  Copies the selected object into the image where
    the cursor is located.  The procedure prompts with a Library.Copy
    command in a Command window below the window in which the cursor
    is located.  The From parameter has the name of the selected
    object as the default value and the To parameter has the current
    context as the default value.

  o Links:  Copies a selected link from one set of links to the set of
    links on which the cursor is located.  If the selected link and
    the cursor are both in the same set of links, the procedure has
    no effect.

  o Switches:  Copies a highlighted switch from one set of switches
    to the set of switches on which the cursor is located.  If the
    selected switch and the cursor are both in the same set of
    switches, the procedure has no effect.

  o Text images:  Copies the selected text to the cursor position.
  @node !Commands.Common.Object.Delete

  procedure Delete;

  Deletes the designated item.

  Specifically, this procedure has the following effects:

  o Ada images:  Deletes the selected element.  If other elements
    are dependent on the element because of semantic references
    (from installed or coded units), the deletion fails and a menu
    of the dependent units is displayed in the menu window.  See
    the description of the editing operations on menus in this book
    for more information.  Contained units of the selected element
    are not deleted.  The cursor must be in the selection for the
    operation to succeed.

  o Help and job windows:  Kills the selected job or the job on
    which the cursor is located for the What.Jobs display.  If a
    job is selected, that job is deleted (terminated).  If no job
    is selected, the job on which the cursor is located is deleted.
    Note that if the job is not for the current session and user, the
    command will fail.  In the What.Jobs display, Object.Delete is
    equivalent to Job.Kill.  This procedure has no effect on Help
    windows.

  o Library images:  Deletes the selected object.  If other elements
    are dependent on the element because of semantic references
    (from installed or coded units), the deletion fails, a menu
    of the dependent units is displayed in the menu window, and a
    Library.Delete command with the name of the selected unit as the
    parameter is placed in a Command window.  For more information,
    see the description of the editing operations on menus in this
    book.  Contained units of the selected element are not deleted.
    The cursor must be in the selection for the operation to succeed.

  o Links:  Deletes the selected link.

  o Searchlists:  Deletes from the searchlist the selected component
    or the component on which the cursor is located.

  o Switches:  Deletes the selected switch or the switch on which the
    cursor is located.  A deleted switch assumes a system-defined
    default value.

  o Text images:  Deletes the selected text.

  o Window images:  Performs the Release command on the image
    described by the selected line.  This causes any changes to the
    image to be made permanent and the selected line to be removed
    from the Window Directory.  If no line is selected, the procedure
    fails, producing an error message.
  @node !Commands.Common.Object.First_Child

  procedure First_Child (Repeat : Positive := 1);

  Selects the first child of the designated item Repeat number of
  times.

  The first child is the first one of the set of items at the next
  lower level, in a syntactic sense, from the current item.

  Specifically, this procedure has the following effects:

  o Ada images:  Selects the first child of the currently selected
    element.  The first child is the first one of the set of elements
    at the next lower level, in a syntactic sense, from the currently
    selected element.

  o Command images:  Selects the first child of the currently
    selected element.  The first child is the first one of the set
    of elements at the next lower level, in a syntactic sense, from
    the currently selected element.

  o Debugger:  Selects the first child of the currently selected
    element.  The first child is the first one of the set of elements
    at the next lower level, in a syntactic sense, from the currently
    selected element.

  o Help and job windows:  Selects the first job of the set for the
    What.Jobs display.  For Help windows, this procedure selects the
    first line of the Help window.

  o Library images:  Selects the first child of the current
    selection.  The procedure selects the line the cursor is on if
    there are no selections or if the cursor is not in the selection.
    If there is a line selected, the procedure selects the first
    child of that line.  If the selected line has no child, it
    selects the next line.

  o Links:  Selects the first link in the set of links.

  o Menu images:  Selects the first declaration in the menu.

  o Searchlists:  Selects the first component in the searchlist.

  o Switches:  Selects the first switch of the set.

  o Text images:  Selects the first child of the current selection.
    The first child is the first one at the next lower level in the
    hierarchy of the current selection.

    The Repeat parameter specifies the number of levels to move
    down in selecting the image.  The default, 1, specifies the next
    lowest level.

  o Window images:  Selects the first line of the Window Directory.

  o Xref images:  Selects the first unit in the xref.
  @node !Commands.Common.Object.Insert

  procedure Insert;

  Enables the user to insert a new item.

  Specifically, this procedure has the following effects:

  o Ada images:  Creates an insertion point in installed and coded
    units where statements, declarations, other elements on which
    incremental compilation operations are supported, or an entire
    compilation unit can be inserted into the current element.

  o Library images:  Creates an insertion point in a library where an
    Ada compilation unit can be inserted.

  o Links:  Creates a Command window and places in it the command:
      Insert ("[link=>] source; etc.");

    where the link parameter must be specified to provide a new link.
    Specifying a source for a new link and promoting the command
    inserts a new link with the same simple name as the source unit.
    Multiple links can be inserted with one command by separating
    them with semicolons.

  o Searchlists:  Creates a Command window and places in it the
    command:
      Add (Component => "[STRING-expression]",
           Position => 1,
           Session => "",
           User => "");

    where the first parameter is a string that can specify one
    or more components (separated with commas) and the second
    parameter is the position within the searchlist.  Providing a
    value for the first parameter and promoting the command adds
    the specified component to the searchlist.  The Session and
    User parameters allow the user to specify another session or
    username's searchlist to which to add an entry.

  o Switches:  Creates a Command window and places in it the command:
      Insert ("[Processor.]  Switch := Value;");

    where the parameter must be specified to provide a switch and
    its value.  Specifying a switch and a value for that switch
    and promoting the command inserts or changes a switch value.
    Multiple switches can be inserted with one command by separating
    them with semicolons.  This procedure uses the same format as an
    Options parameter.

  o Window images:  Creates a new Command window below the Window
    Directory and prompts for the Definition command as follows:
      Definition ("");
  @node !Commands.Common.Object.Last_Child

  procedure Last_Child (Repeat : Positive := 1);

  Selects the last child of the designated item Repeat number of
  times.

  The last child is the last one of the set of items at the next lower
  level, in a syntactic sense, from the current item.

  Specifically, this procedure has the following effects:

  o Ada images:  Selects the last child of the currently selected
    element.  The last child is the last one of the set of elements
    at the next lower level, in a syntactic sense, from the currently
    selected element.

  o Command images:  Selects the last child of the currently selected
    element.  The last child is the last one of the set of elements
    at the next lower level, in a syntactic sense, from the currently
    selected element.

  o Debugger:  Selects the last child of the currently selected
    element.  The last child is the last one of the set of elements
    at the next lower level, in a syntactic sense, from the currently
    selected element.

  o Help and job windows:  Selects the last job of the set for the
    What.Jobs display.  For Help windows, this procedure selects the
    last line of the Help window.

  o Library images:  Selects the last child of the current selection.
    If there is no selection in the image or the cursor is not in the
    selection, this procedure selects the current line.  If there is
    a selection, the procedure selects the last child of the current
    selection.  If the selection has no subobjects, it selects the
    next object.

  o Links:  Selects the last link of the set.

  o Menu images:  Selects the last declaration in the menu.

  o Searchlists:  Selects the last component in the searchlist.

  o Switches:  Selects the last switch of the set.

  o Text images:  Selects the last child of the current selection.
    The last child is the last one at the next lower level in the
    hierarchy of the current selection.

    The Repeat parameter specifies the number of levels to move
    down in selecting the image.  The default, 1, specifies the next
    lowest level.

  o Window images:  Selects the last line in the Window Directory.

  o Xref images:  Selects the last unit in the xref.
  @node !Commands.Common.Object.Move

  procedure Move;

  Moves the selected item to the cursor position.

  This procedure moves the current selection to the cursor position
  by copying the item and then deleting the original item.

  Specifically, this procedure has the following effects:

  o Ada images:  Moves the selected element to the cursor position.
    This movement is done by copying the element and then deleting
    the original element.  The new copy is placed in the source
    state.  If other elements are dependent on the element because of
    semantic references (from installed or coded units), the deletion
    fails but the copy succeeds.  Contained units of the selected
    unit are not moved.

  o Library images:  Moves the selected object into the library
    in which the cursor is located.  The procedure prompts with a
    Library.Move command in a Command window below the library in
    which the cursor is located.  The From parameter specifies, as a
    default, the selected object, and the To parameter specifies, as
    a default, the library in which the cursor is located.

  o Links:  Copies a selected link from one set of links to the set of
    links on which the cursor is located.  Currently, the procedure
    copies the link but does not move it.  If the selected link and
    the cursor are both in the same set of links, the procedure has
    no effect.

  o Searchlists:  Moves the selected searchlist component to the
    current cursor position in the current searchlist.

  o Switches:  Moves highlighted switches from one set of switches
    to the set of switches on which the cursor is located.  If the
    selected switch and the cursor are both in the same set of
    switches, the procedure has no effect.

  o Text images:  Moves the selected text to the cursor position.

  @node !Commands.Common.Object.Next

  procedure Next (Repeat : Positive := 1);

  Selects the next item past the designated item Repeat number of
  times.

  The next item is the item at the same level, in a syntactic
  sense, as the designated item that appears immediately after the
  designated item.

  Specifically, this procedure has the following effects:

  o Ada images:  Selects the Repeat next element past the currently
    selected element.  A next element is the element at the same
    level, in a syntactic sense, as the current element that appears
    immediately after the current element.  If no such selection can
    be made, the next element at the enclosing level is selected.

  o Command images:  Selects the Repeat next element past the
    currently selected element.  A next element is the element at
    the same level, in a syntactic sense, as the current element
    that appears immediately after the current element.  If no such
    selection can be made, the next element at the enclosing level is
    selected.

  o Debugger:  Selects the Repeat next element past the currently
    selected element.  A next element is the element at the same
    level, in a syntactic sense, as the current element that appears
    immediately after the current element.  If no such selection can
    be made, the next element at the enclosing level is selected.

  o Help and job windows:  Selects the job that is listed after the
    currently selected job, provided that the cursor is on currently
    selected job, for the What.Jobs display.  If the cursor is not on
    the currently selected job or if no job is already selected, the
    procedure selects the job on which the cursor is located.  If all
    jobs are selected, this procedure produces an error message.

    For Help windows, this procedure selects the next item past
    the current item declaration if the cursor is in the current
    selection; otherwise, it selects the item corresponding to the
    line on which the cursor is located.  If nothing is currently
    selected, the procedure selects the item corresponding to the
    line on which the cursor is located.  If the entire Help window
    is selected, this procedure produces an error message.

  o Library images:  Selects the next object at the same or greater
    level past the currently selected object.

  o Links:  Selects the next link.  If no link is already selected,
    the procedure selects the link on which the cursor is located.
    If all links are selected, this procedure produces an error.

  o Menu images:  Selects the next declaration past the currently
    selected declaration if the cursor is in the current selection;
    otherwise, the procedure selects the declaration corresponding
    to the line on which the cursor is located.  If nothing is
    currently selected, the procedure selects the declaration
    corresponding to the line on which the cursor is located.  The
    Repeat parameter specifies that the Repeat declaration after the
    currently selected declaration is to be selected.

  o Searchlists:  Selects the next component in the searchlist.  If
    no component is already selected, the procedure selects the
    component on which the cursor is located.  If all components are
    selected, this procedure produces an error.

  o Switches:  Selects the next switch.  If no switch is selected,
    the procedure selects the switch on which the cursor is located.
    If all switches are selected, this procedure produces an error.

  o Text images:  Selects the next item after the current selection
    at the same level in the text-image hierarchy.  If there is no
    current selection, the word after the current cursor position is
    selected.

    The Repeat parameter specifies the number of the selection to be
    selected after the current cursor position.

  o Window images:  Selects the next line past the currently selected
    line if the cursor is in the current selection; otherwise, the
    procedure selects the line on which the cursor is located.  If
    nothing is currently selected, the procedure selects the line on
    which the cursor is located.  The Repeat parameter specifies to
    select the Repeat line after the currently selected line.

  o Xref images:  Selects the next unit past the currently selected
    unit if the cursor is in the current selection; otherwise, the
    procedure selects the unit corresponding to the line on which
    the cursor is located.  If nothing is currently selected, the
    procedure selects the unit corresponding to the line on which the
    cursor is located.
  @node !Commands.Common.Object.Parent

  procedure Parent (Repeat : Positive := 1);

  Selects the parent item of the designated item Repeat number of
  times.

  The parent is the item at the next higher level, in a syntactic
  sense, from the designated item that contains the designated item.

  Specifically, this procedure has the following effects:

  o Ada images:  Selects the parent element of the currently selected
    element.  The parent element is the element that contains the
    current element at the next higher level, in a syntactic sense,
    from the current element.

  o Command images:  Selects the parent element of the currently
    selected element.  The parent element is the element that
    contains the current element at the next higher level, in a
    syntactic sense, from the current element.

  o Debugger:  Selects the parent element of the currently selected
    element.  The parent element is the element that contains the
    current element at the next higher level, in a syntactic sense,
    from the current element.

  o Help and job windows:  Selects the job the cursor is on for the
    What.Jobs display.  If a job is already selected and the cursor
    is on the currently selected job, the procedure selects all jobs
    in the set.  If all jobs are already selected, the procedure has
    no effect.

    For Help windows, this procedure selects the item corresponding
    to the line on which the cursor is located if there are no
    selections; otherwise, it selects the entire Help window.  If
    the entire Help window is already selected, the procedure has no
    effect.

  o Library images:  Selects the parent of the current selection.  If
    there is no selection or if the cursor is not in the selection,
    the procedure selects the line on which the cursor is located.

  o Links:  Selects the link on which the cursor is located.  If no
    link is already selected, the procedure selects the link on which
    the cursor is located.  If a link is selected, the procedure
    selects all links in the set.  Otherwise, the procedure has no
    effect.

  o Menu images:  Selects the declaration corresponding to the
    line on which the cursor is located if there are no selections;
    otherwise, the procedure selects the entire menu.

  o Searchlists:  Selects the component in the searchlist on which
    the cursor is located.  If no component is already selected, the
    procedure selects the component on which the cursor is located.
    If a component is selected, the procedure selects all components
    in the set.  Otherwise, the procedure has no effect.

  o Switches:  Selects the switch on which the cursor is located.  If
    no switch is selected, the procedure selects the switch on which
    the cursor is located.  If a switch is selected, the procedure
    selects all switches in the set.  Otherwise, the procedure has no
    effect.

  o Text images:  Selects the next higher-level item in the
    hierarchical structure of a text image.  The item selected is the
    one in which the cursor or current selection is located.  If no
    items are selected, the word closest to the cursor is selected.

    The Repeat parameter specifies the number of levels to move up in
    selecting the image.  The default, 1, specifies the next highest
    level.

  o Window images:  Selects the line on which the cursor is located
    if there are no selections; otherwise, the procedure selects the
    entire Window Directory.

  o Xref images:  Selects the unit corresponding to the line on which
    the cursor is located if there are no selections; otherwise, the
    procedure selects the entire list of units in the xref.
  @node !Commands.Common.Object.Previous

  procedure Previous (Repeat : Positive := 1);

  Selects the previous item before the designated item Repeat number
  of times.

  The previous item is the item at the same level, in a syntactic
  sense, as the designated item that appears immediately before the
  designated item.

  Specifically, this procedure has the following effects:

  o Ada images:  Selects the Repeat previous element before the
    currently selected element.  A previous object is the object
    at the same level, in a syntactic sense, as the current element
    that appears immediately before the current element.  If no such
    selection can be made, the previous element at the enclosing
    level is selected.

  o Command images:  Selects the Repeat previous element before the
    currently selected element.  A previous element is the element
    at the same level, in a syntactic sense, as the current element
    that appears immediately before the current element.  If no such
    selection can be made, the previous element at the enclosing
    level is selected.

  o Debugger:  Selects the Repeat previous element before the
    currently selected element.  A previous object is the object
    at the same level, in a syntactic sense, as the current element
    that appears immediately before the current element.  If no such
    selection can be made, the previous element at the enclosing
    level is selected.

  o Help and job windows:  Selects the job that is listed before
    the currently selected job, provided that the cursor is on the
    currently selected job, for the What.Jobs display.  If the cursor
    is not on the currently selected job or if no job is already
    selected, the procedure selects the job on which the cursor is
    located.  If all jobs are selected, this procedure produces an
    error.

    For Help windows, the procedure selects the previous item before
    the currently selected item, if the cursor is in the current
    selection; otherwise, it selects the item corresponding to the
    line on which the cursor is located.  If nothing is currently
    selected, the procedure selects the item corresponding to the
    line on which the cursor is located.

  o Library images:  Selects the previous object at the same or
    greater level before the currently selected object.

  o Links:  Selects the previous link.  If no link is already
    selected, the procedure selects the link on which the cursor
    is located.  If all links are selected, this procedure produces
    an error.

  o Menu images:  Selects the previous declaration before the
    currently selected declaration if the cursor is in the current
    selection; otherwise, the procedure selects the declaration
    corresponding to the line on which the cursor is located.
    If nothing is currently selected, the procedure selects the
    declaration corresponding to the line on which the cursor
    is located.  The Repeat parameter specifies that the Repeat
    declaration before the currently selected declaration is to be
    selected.

  o Searchlists:  Selects the previous component in the searchlist.
    If no component is already selected, the procedure selects the
    component on which the cursor is located.  If all components are
    selected, this procedure produces an error.

  o Switches:  Selects the previous switch.  If no switch is
    selected, the procedure selects the switch on which the cursor is
    located.  If all switches are selected, this procedure produces
    an error.

  o Text images:  Selects the previous item before the current
    selection at the same level in the text-image hierarchy.  If
    there is no current selection, the word before the current cursor
    position is selected.

    The Repeat parameter specifies the number of the selection to be
    selected before the current cursor position.

  o Window images:  Selects the previous line before the currently
    selected line if the cursor is in the current selection;
    otherwise, the procedure selects the line on which the cursor
    is located.  If nothing is currently selected, the procedure
    selects the line on which the cursor is located.  The Repeat
    parameter specifies to select the Repeat line after the currently
    selected line.

  o Xref images:  Selects the previous unit before the currently
    selected unit if the cursor is in the current selection;
    otherwise, the procedure selects the unit corresponding to the
    line on which the cursor is located.  If nothing is currently
    selected, the procedure selects the unit corresponding to the
    line on which the cursor is located.
  @node !Commands.Text

  This package contains the set of procedures and types provided
  for text object-specific editing.  The commands in package
  !Commands.Common can also be used for text object-specific
  editing.
  @node !Commands.Text.Block

  procedure Block  (All_Windows : Boolean := False);

  Temporarily stops all job output to the current window or to all
  windows, based on the value of the All_Windows parameter.

  The output can be resumed with the Continue procedure.  If the
  window is already blocked, this procedure has no effect.

  If All_Windows is true, all I/O windows, not just the current one,
  are blocked.

  The !Commands.Job.Disable or Job.Kill procedure can also be used to
  stop jobs (see SJM, package Job).
  @node !Commands.Text.Continue

  procedure Continue (Page_Mode   : Boolean := False;
                     All_Windows : Boolean := False);

  Resumes job output to the current window or to all windows that
  have been blocked using the Block procedure, depending on the value
  of the All_Windows parameter.

  If the window is not blocked, this procedure has no effect.  If
  the All_Windows parameter is true, all I/O windows, not just the
  current one, are continued.

  If the Page_Mode parameter is true, the I/O window or windows
  automatically block after an additional page of output has been
  displayed.  At that point, this procedure must be executed again to
  resume output.
  @node !Commands.Text.Create

  procedure Create (Image_Name : String     := ">>IMAGE NAME<<";
                   Kind       : Image_Kind := Text.File);

  Creates a new empty text file in a new window for editing or for
  use by a job performing I/O.

  This procedure can be used in two ways:

  o It can be used to create a text file.  The Image_Name parameter
    specifies the name of the file to be created.  To create a text
    file, the Kind parameter must specify Text.File.  A window is
    created containing the image of the text file when the procedure
    is executed.

  o It can be called from a job to create an I/O window for that
    job.  When used in a job, the Image_Name parameter specifies
    the name that will appear in the window of the job and the I/O
    window created by the job.  The Kind parameter must specify
    Text.Input_Output so that an I/O window is created.  No text file
    is created.

  If the named file exists, its contents are destroyed.  The new file
  created by this procedure is always empty.

  If the kind of image created is a file, then the image name must be
  a legal filename.
  @node !Commands.Text.End_Of_Input

  procedure End_Of_Input;

  Signals the interacting program that no more input will be
  provided, when executed in an I/O window.

  The !Io.Io_Exceptions.End_Error exception is raised if the program
  requests more input.
  @node !Commands.Text.Image_Kind

  type Image_Kind is (File, Input_Output);

  Defines the two kinds of text images.

  This type is used by the Create procedure to specify what kind of
  text image to create.

  File

  Specifies that the procedure using this type will interact with the
  image of a text file.

  Input_Output

  Specifies that the procedure using this type will interact with an
  I/O image.
  @node !Commands.Text.Redirect

  procedure Redirect (To : String := ">>File Name<<");

  Redirects the output associated with the current output window to
  the specified file.

  This procedure is useful when you want to log off and save the
  contents of the current output window.