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: ┃ S T

⟦adabea547⟧ TextFile

    Length: 520671 (0x7f1df)
    Types: TextFile
    Names: »SMU_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.Daemon

 Package Daemon defines a program called the system daemon, which
 periodically runs a set of special jobs serving as system custodians.
 These special jobs, called clients, maintain system efficiency by managing
 the system's internal data structures, disposing of obsolete data, and
 reclaiming storage space.

 System-daemon clients run according to a standard default schedule. Using
 commands from package Daemon, a system manager can run clients
 independently of the schedule, prevent a scheduled client from running,
 and display information about each client.

 Resources from package !Tools.Disk_Daemon specifically control the
 conditions under which the Disk client runs. See the System Manager's
 Guide for information about controlling Disk-client operations through
 resources from package Disk_Daemon.

 Some of the operations in this package are restricted to users with
 operator capability (see package Operator). If this restriction applies,
 it is stated in the reference entry for the command.


 RESOURCES IN PACKAGE DAEMON

 The following classification groups commands in package Daemon by general
 tasks:

 Setting default operations and scheduling during machine initialization:

       Schedule                        Set_Access_List_Compaction
       Set_Consistency_Checking        Set_Log_Threshold
       Snapshot_Finish_Message         Snapshot_Start_Message
       Snapshot_Warning_Message        Threshold_Warnings
       Warning_Interval

 Interactively altering scheduling of operations:

       Collect                         Quiesce
       Run                             Schedule
       Set_Priority                    Show_Log_Thresholds
       Show_Snapshot_Settings          Status

 Getting information about scheduled operations:

       Get_Access_List_Compaction      Get_Consistency_Checking
       Get_Log_Threshold               Get_Size
       Get_Snapshot_Warnings           Get_Warning_Interval
       In_Progress                     Interval
       Last_Run                        Next_Scheduled
       Show_Log_Thresholds             Show_Snapshot_Settings
       Status


 KEY CONCEPTS FOR PACKAGE DAEMON

 The system daemon runs several programs as clients. These system-daemon
 clients periodically perform the following system operations:

 *  Compaction of system data structures

 *  Disk collection

 *  Saving the system state

 *  Saving the system error log

 Other aspects of system-daemon operation are initialized during system
 boot. (Refer to the "System-Daemon Initialization" subsection for more
 information on system-daemon initialization.)

 Note: Refer to the System Manager's Guide for a description of
 system-daemon management, including a description of techniques a system
 manager can use to change or monitor the way disk collection is executed.


 Snapshot Client

 The Snapshot client makes a record, or snapshot, of the current state of
 the Environment. Snapshots are important because, when the system boots,
 the Environment is restored to the state that was recorded by the most
 recent snapshot. Only objects that were committed before the last snapshot
 are preserved.


 Actions Client

 The Actions client manages the data structure that controls simultaneous
 access to objects. This data structure prevents inconsistencies when
 several users or jobs require simultaneous access to an object. By
 default, the Actions client is scheduled to run unobtrusively every two
 hours in the standard Environment.


 Disk Client

 The Disk client is run daily to remove obsolete data from the disks.
 Running the Disk client is also called disk collection. Disk collection is
 run according to schedule and also can be run on an as-needed basis.
 During system initialization, several procedures from package
 Disk_Daemon are called in order to set the disk-collection thresholds for
 the disk volumes. See the System Manager's Guide for more information on
 package Disk_Daemon resources, including information on how to change
 disk-collection thresholds.


 Error_Log Client

 System errors and other messages can be directed to the operator console,
 the stable-storage error log on disk, or both with the
 Daemon.Set_Log_Threshold procedure. Messages in the stable-storage error
 log are not accessible from the Environment until the Error_Log client
 copies the stable-storage error log into a permanent dated file in the
 !Machine.Error_Logs world. (They are accessible, however, from the
 console: at the Kernel: prompt, enter the Show_Error_Log command.)

 Normally, one Environment error-log file is created per day, because the
 Error_Log client runs once a day under the standard schedule. You can
 cause the Error_Log client to run immediately by executing the command:

   Daemon.Run ("Error_Log");

 The name of each file shows the date and time it was created. For example,
 the file created on August 1, 1991, at 4:00 A.M. is named
 Log_91_08_01_At_04_00_01.

 The Error_Log client is normally the last client to run each day. Thus,
 the Environment error-log file that is created on a given day contains
 the messages that were generated on the previous day.


 Object Managers as Clients

 The Environment includes 16 object managers. One of the functions of the
 object managers is to perform compaction that discards deleted objects.
 The object managers are run by the system daemon on a regular
 schedule--either daily or weekly.

         Table 1    Object Managers Run as System-Daemon Clients
              ----------------------------------------------- 
             |         |                              |      |
             |         |                              |Stand |
             |Object   |             Task             |ard   |
             |Manager  |                              |Sched |
             |         |                              |ule   |
              ----------------------------------------------- 
             |         |                              |      |
             |Ada      |Manages the set of objects of |Daily |
             |         |class Ada. Keeps track of the |      |
             |         |parent/child relationships    |      |
             |         |between the Ada units and     |      |
             |         |their subunits. Stores ACL    |      |
             |         |information for Ada units.    |      |
              ----------------------------------------------- 
             |         |                              |      |
             |Archived_|Manages D1-style code views   |Weekly|
             |Code     |and load procs.               |      |
              ---------------------------------------  ------ 
             |         |                              |      |
             |Code_    |Manages R1000 Ada code        |Weekly|
             |Segment  |segments.                     |      |
              ---------------------------------------  ------ 
             |         |                              |      |
             |Configura|Reclaims memory.              |Weekly|
             |ion      |                              |      |
              ---------------------------------------  ------ 
             |         |                              |      |
             |DDB      |Manages the dependency        |Weekly|
             |         |database, which maintains a   |      |
             |         |record of the dependencies    |      |
             |         |between Ada units. Removes    |      |
             |         |obsolete dependencies from the|      |
             |         |database.                     |      |
              ----------------------------------------------- 
             |         |                              |      |
             |Directory|Manages the relationship      |Daily |
             |         |between objects in the di-    |      |
             |         |rectory system, including what|      |
             |         |objects are children of a     |      |
             |         |directory, and default ACL    |      |
             |         |information.                  |      |
              ----------------------------------------------- 
             |         |                              |      |
             |File     |Manages the set of objects of |Daily |
             |         |class File. Stores ACL in-    |      |
             |         |formation for file objects.   |      |
              ----------------------------------------------- 
             |         |                              |      |
             |Group    |Manages groups.               |Weekly|
             |         |                              |      |
              ----------------------------------------------- 
             |         |                              |      |
             |Link     |Manages Ada with connections  |Weekly|
             |         |between worlds.               |      |
              ----------------------------------------------- 
             |         |                              |      |
             |Null_    |Reclaims memory.              |Weekly|
             |Device   |                              |      |
              ----------------------------------------------- 
             |         |                              |      |
             |Pipe     |Is used by kernel (analogous  |Weekly|
             |         |to UNIX pipes).               |      |
              ----------------------------------------------- 
             |         |                              |      |
             |Program_ |Manages the Ada program       |Weekly|
             |Library  |library. (Prior to D3 release:|      |
             |         |associated with each world.)  |      |
              ----------------------------------------------- 
             |         |                              |      |
             |Session  |Manages login sessions.       |Weekly|
             |         |                              |      |
              ----------------------------------------------- 
             |         |                              |      |
             |Tape     |Manages tape devices.         |Weekly|
             |         |                              |      |
              ----------------------------------------------- 
             |         |                              |      |
             |Terminal |Manages terminal port objects.|Weekly|
             |         |                              |      |
              ----------------------------------------------- 
             |         |                              |      |
             |User     |Manages R1000 user accounts.  |Weekly|
             |         |                              |      |
              ----------------------------------------------- 




 Access-List Compaction

 A job's access to worlds, files, Ada units, and certain operations is
 restricted by access control. Access control applies to all jobs: both
 those initiated interactively through command windows and key combinations
 and those initiated programmatically through procedure calls as a
 program executes.

 Access control is determined by an object's access-control list (ACL). One
 of the functions of the system daemon is to perform housekeeping
 maintenance on ACLs. Known as access-list compaction, this becomes
 important when the number of active access-control groups approaches the
 maximum available group numbers.


 Access-Control Groups

 An ACL is a list of groups that are permitted access to an object; these
 groups contain usernames. A job is permitted access to an object only if
 the username of the job's user is a member of a group listed in the
 object's ACL. Note that groups can contain only usernames--not other
 groups.

 Groups are defined either automatically by the Environment or explicitly by
 users through operations from package Operator. Group objects are stored
 in the world !Machine.Groups. Package Operator provides commands for
 creating, modifying, and deleting these group objects. (For more
 information, see package Operator and the Library Management (LM) book.)

 A maximum of 1,000 groups can exist at one time on each R1000 processor.
 The Environment keeps a list of all groups on a machine. Each group in the
 list is numbered. The number for any particular group never changes unless
 it is deleted and then recreated.

 Whenever a user is deleted, the number that was consumed by that group in
 the list of groups is not automatically reclaimed. Instead, the name of
 the group is set to <UNKNOWN_N>, where N is the number for that group.
 Unknown groups appear in access lists when a group that has been deleted
 was previously included in the access list for an object.

 Since the number for a group is not automatically reclaimed when the group
 is deleted, it is possible for a given machine to run out of numbers for
 new groups. If a machine runs out of access-list groups, new groups and
 users cannot be created on that machine until the numbers for obsolete
 groups are reclaimed.


 Reclaiming Access-Control Groups

 To reclaim the numbers for deleted groups, the Ada, File, and Directory
 object managers can be instructed to run access-list compaction.
 Access-list compaction can be performed either through the Daily client or
 immediately, if necessary.

 *  To run access-list compaction through the Daily client on a particular
    day, the Set_Access_List_Compaction procedure should be run before the
    time at which the daemons run (typically about 2 A.M.). Then when the
    daemons run, they will perform access-list compaction.

 *  To run access-list compaction immediately, first run the
    Set_Access_List_Compaction procedure. Then run the Daemon.Run
    procedure for each of the Ada, Directory, and File object managers.

 Note: The Daemon.Set_Access_List_Compaction procedure is executed
 automatically during system initialization. Thus, if the R1000 is booted
 periodically, it may not be necessary to manually execute the
 Set_Access_List_Compaction command.

 After access-list compaction has run, the number for the next available
 group is set to the lowest available number. For example, assume that
 groups corresponding to spaces 1 through 100 exist, and then the groups
 corresponding to spaces 17, 47, and 39 are deleted. During access-list
 compaction, these three spaces are reclaimed, and the next available
 space will be set to 17, rather than 101.


 Determining Available Group Space

 To determine which spaces are available, run the !Commands.System_Mainte-
 nance.Show_Groups command with its parameter set to the default False.
 Show_Groups displays a list of the free group numbers to help you
 determine whether access-list compaction should be run, as shown in Figure
 1.

   Free group map
   --------------
     16
     19 .. 26
     28 .. 52
     54 .. 195
    197 .. 280
    282 .. 284
    286 .. 287
    293 .. 305
    310 .. 1022

 Caution: The Show_Groups procedure, with its parameter set to True, causes
 a group space to be consumed; this group space will no longer be available
 until access-list compaction is performed. To prevent consuming group
 space when running Show_Groups, use the default False parameter setting.
 To determine the next free group number, use the True setting.

 Show_Groups also displays a mapping between groups and their space number,
 as shown in Figure 2.

   Group name map
   --------------
      0  PUBLIC
      1  NETWORK_PUBLIC
      2  PRIVILEGED
      3  RATIONAL
      4  MAILER
      5  SPOOLER
      6  SYSTEM
     18  OPERATOR
     27  GZC
     53  JLS
    196  TRAINING
    306  JLF
    307  RICK
    308  LEC
    309  JUDY


 System-Daemon Initialization

 The system daemons are initialized during system boot; their initial
 schedule (cycle times) is specified in !Machine.Initialization.Rational.
 The standard cycle times are:

 *  Time at which Daily and Weekly clients run: 3:00 A.M. for daily
    clients; 2:30 A.M. for Weekly clients

 *  Snapshot interval: 30 minutes

 *  Snaphot messages: 20-second warning interval; notification of finish

 *  Daemon warning interval: 2 minutes before daily clients

 *  Disk-collection thresholds: site-dependent

 *  Disk-collection threshold warnings: warn when thresholds have been
    passed

 *  System log messages (appear on operator console): only warning,
    problem, and fatal messages

 *  Access-list compaction: all relevant clients perform access-list
    compaction

 You can write procedures or _Start files in the Site or Local world of
 !Machine.Initialization to implement customizations of the system
 daemon, to be processed and executed by the initialization Start
 procedure. See the online documentation in !Machine.Initialization for
 more information.


 @node !Commands.Daemon.Collect

 procedure Collect (Vol      : Volume;
                    Priority : Collection_Priority := 0);

 DESCRIPTION

 Begins disk collection on the specified volume at the specified priority.

 If scheduled disk collection is already in progress, the procedure returns
 immediately with no effect.

 Note that the Collect procedure does not affect scheduling intervals.


 PARAMETERS

 Vol : Volume;

 Specifies the disk drive by disk-drive number. The value 0 specifies all
 volumes.


 Priority : Collection_Priority := 0;

 Specifies the priority for running disk collection. Collection_Priority is
 an integer from -1 through 6. The default, 0, ensures that disk collection
 takes place, potentially affecting system load. The value -1 runs
 collection as a background activity; 6 allocates all resources for disk
 collection. The specified priority is temporary; it affects only the disk
 collection started by the current call to this procedure.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Daemon.Collect (2,0);

 starts disk collection on disk drive 2 at priority 0, which affects system
 load.


 REFERENCES

 subtype Collection_Priority
 procedure Set_Priority
 procedure Threshold_Warnings
 subtype Volume



 @node !Commands.Daemon.Collection_Priority

 subtype Collection_Priority is Integer range -1 .. 6;

 DESCRIPTION

 Specifies the priority for running disk collection.


 ENUMERATIONS

 -1

 Does not guarantee progress in disk collection. This priority runs disk
 collection as a very low-level background activity, using only "spare" CPU
 cycles. If there are none, disk collection will wait indefinitely (does a
 backoff ) until cycles are available or until collection priority is
 increased.                            


 0

 Guarantees progress in disk collection, with a small impact on system
 performance (and user response time). This priority is the same as running
 background jobs.


 2

 Guarantees progress in disk collection and preempts background jobs that
 do not use the highest priority.


 3

 Guarantees progress in disk collection and runs on par with most
 foreground jobs. This priority has a big impact on system performance
 because it is sharing the same priority as most commands.


 4

 Guarantees progress in disk collections and preempts most foreground jobs.
 Editing is still possible, but commands will run very slowly.


 6

 Guarantees progress in disk collection and gives disk collection higher
 priority than user jobs.


 REFERENCES

 procedure Collect
 procedure Set_Priority



 @node !Commands.Daemon.Condition_Class

 type Condition_Class is (Normal, Warning, Problem, Fatal);

 DESCRIPTION

 Specifies how serious an error should be before it is logged in an
 Environment log file in the world !Machine.Error_Logs.

 This type is used with the Set_Log_Threshold procedure.

 The enumerations are listed below in the order of least severe to most
 severe.


 ENUMERATIONS


 Normal

 Specifies messages from the Environment that provide information but do not
 necessarily indicate problems. Normal messages appear in the error log
 preceded by the characters ---.


 Warning

 Specifies situations that are unusual but not necessarily dangerous.
 Warning messages appear in the error log preceded by the characters +++.


 Problem

 Specifies situations that the Environment expects will lead to problems.
 Problem messages appear in the error log preceded by the characters !!!.


 Fatal

 Specifies situations in which the Environment refuses to proceed. The task
 that was the source of the problem is suspended. Fatal messages appear in
 the Environment error log preceded by the characters ***.


 REFERENCES

 procedure Get_Log_Threshold
 type Log_Threshold
 procedure Set_Log_Threshold



 @node !Commands.Daemon.Get_Access_List_Compaction

 function Get_Access_List_Compaction (Client : String := "")
                                     return Boolean;

 DESCRIPTION

 Returns True if any of the specified clients are scheduled to perform
 access-list compaction.

 The clients that can perform access-list compaction are File, Ada, and
 Directory. Access-list compaction is the process of removing nonexistent
 groups from the access lists of objects. Nonexistent groups occur when
 groups are removed from the machine.

 For further information on access-control groups, see package Operator.

 Enabling this feature slows a client's operation.


 PARAMETERS

 Client : String := "";

 Specifies the name of the client to perform access-list compaction. Clients
 are listed in the introduction to this package.


 return Boolean;

 Returns True if any of the specified clients are scheduled to perform
 access-list compaction; otherwise, the function returns False.


 REFERENCES

 procedure Set_Access_List_Compaction
 package Operator



 @node !Commands.Daemon.Get_Consistency_Checking

 function Get_Consistency_Checking (Client : String := "")
                                   return Boolean;

 DESCRIPTION

 Returns True if any of the specified clients are scheduled to perform
 consistency checking.

 Consistency checking performs additional work to ensure that the internal
 state of the system is correct. This operation normally is run only when
 problems are suspected. For the DDB client, this setting may result in
 compaction.

 Enabling this feature slows a client's operation.


 PARAMETERS

 Client : String := "";

 Specifies the name of the client to be queried to determine whether it is
 performing consistency checking. Clients are listed in the introduction
 to this package. The default specifies all clients.


 return Boolean;

 Returns True if any of the specified clients are scheduled to perform
 consistency checking. The default is False. If True, the default is
 restored after the next specified daemon run has completed.


 REFERENCES

 procedure Set_Consistency_Checking



 @node !Commands.Daemon.Get_Log_Threshold

 function Get_Log_Threshold (Kind : Log_Threshold)
                            return Condition_Class;

 DESCRIPTION

 Returns the class of message severity (Normal, Warning, Problem, or Fatal)
 that is handled by the specified kind of log (Console_Print, Log_To_Disk,
 or Commit_Disk).


 PARAMETERS

 Kind : Log_Threshold;

 Specifies the destination for messages. The destination can be
 Console_Print, Log_To_Disk, or Commit_Disk.


 return Condition_Class;

 Returns the class of message by Condition_Class type, including Normal,
 Warning, Problem, and Fatal.


 REFERENCES

 subtype Condition_Class
 type Log_Threshold
 procedure Set_Log_Threshold



 @node !Commands.Daemon.Get_Size

 procedure Get_Size (Client               :     String;
                     Size                 : out Long_Integer;
                     Size_After_Last_Run  : out Long_Integer;
                     Size_Before_Last_Run : out Long_Integer);

 DESCRIPTION

 Displays the current number of disk pages of the data structures compacted
 by the specified client, both before and after the last time the client was
 run.

 This procedure is useful for monitoring the growth curve of the data
 structures that are compacted by the following clients: Ada, DDB,
 Directory, Disk, and File.


 PARAMETERS

 Client : String;

 Specifies the name of the client to be monitored. The Ada, DDB, Directory,
 Disk, and File clients are most relevant to this procedure. All clients
 are listed in the package introduction.


 Size : out Long_Integer;

 Specifies the number of pages currently used by the client's data
 structure.


 Size_After_Last_Run : out Long_Integer;

 Specifies the number of pages used by the client's data structure after the
 client was last run.


 Size_Before_Last_Run : out Long_Integer;

 Specifies the number of pages used by the client's data structure before
 the client was last run.



 @node !Commands.Daemon.Get_Snapshot_Settings

 procedure Get_Snapshot_Settings (Warning        : out Duration;
                                  Start_Message  : out Boolean;
                                  Finish_Message : out Boolean);

 DESCRIPTION

 Returns the current snapshot options.


 PARAMETERS

 Warning : out Duration;

 Specifies the current warning interval (the amount of time between the
 warning and the snapshot).


 Start_Message : out Boolean;

 Specifies whether a message is displayed when the snapshot begins.


 Finish_Message : out Boolean;

 Specifies whether a message is displayed when the snapshot is completed.


 REFERENCES

 procedure Show_Snapshot_Settings
 procedure Snapshot_Finish_Message
 procedure Snapshot_Start_Message
 procedure Snapshot_Warning_Message
 Programming Tools (PT), package Time_Utilities



 @node !Commands.Daemon.Get_Warning_Interval

 function Get_Warning_Interval return Duration;

 DESCRIPTION

 Returns the amount of warning given before each Daily client runs.

 The time between the warning message and the running of the client gives
 the operator time to quiesce it, if needed.


 PARAMETERS

 return Duration;

 Returns the amount of time between the warning and the running of the
 Daily client. The value of Duration is a number of minutes, as defined in
 PT, package Time_Utilities.


 REFERENCES

 procedure Quiesce
 procedure Warning_Interval
 Programming Tools (PT), package Time_Utilities



 @node !Commands.Daemon.In_Progress

 function In_Progress (Client : String) return Boolean;

 DESCRIPTION

 Returns a Boolean value indicating whether the specified client is
 currently running.


 PARAMETERS

 Client : String;

 Specifies the name of the client in question. Clients are listed in the
 introduction to this package.


 return Boolean;

 Returns True when the specified client is running; otherwise, the function
 returns False.


 REFERENCES

 Programming Tools (PT)



 @node !Commands.Daemon.Interval

 function Interval (Client : String) return Duration;

 DESCRIPTION

 Returns the scheduled interval for the specified client.


 PARAMETERS

 Client : String;

 Specifies the name of the client in question. Clients are listed in the
 introduction to this package.


 return Duration;

 Returns the currently scheduled interval for this client, in number of
 seconds.


 REFERENCES

 Programming Tools (PT), package Time_Utilities



 @node !Commands.Daemon.Last_Run

 function Last_Run (Client : String) return Calendar.Time;

 DESCRIPTION

 Returns the last time the specified client was run.


 PARAMETERS

 Client : String;

 Specifies the client. Clients are listed in the introduction to this
 package.


 return Calendar.Time;

 Returns the time the client was last run.


 REFERENCES

 Programming Tools (PT), package Time_Utilities



 @node !Commands.Daemon.Log_Threshold

 type Log_Threshold is (Console_Print, Log_To_Disk, Commit_Disk);

 DESCRIPTION

 Determines the actions that can be taken on a system message.

 The action selected is controlled by the Set_Log_Threshold procedure,
 depending on the Condition_Class type of the message.


 ENUMERATIONS


 Commit_Disk

 Writes messages immediately into the stable-storage error log on the disk.
 These messages are retained if the system fails.


 Console_Print

 Directs messages to the operator console.


 Log_To_Disk

 Directs messages to the stable-storage error log on the disk. These
 messages are not immediately written onto the disk, so they may be lost if
 the system fails before they can be written.


 REFERENCES

 subtype Condition_Class
 procedure Get_Log_Threshold
 procedure Set_Log_Threshold



 @node !Commands.Daemon.Major_Clients

 Major_Clients : constant String := "*";

 DESCRIPTION

 Defines a constant string representing the list of major clients used as
 the default client in the Status procedure.

 Note that if the null string is used in place of Major_Clients, the status
 for all clients is displayed.

 The list of major clients includes: Actions, Ada, DDB, Directory, Disk,
 File, and Snapshot.


 REFERENCES

 procedure Status



 @node !Commands.Daemon.Next_Scheduled

 function Next_Scheduled (Client : String) return Calendar.Time;

 DESCRIPTION

 Returns the time at which the specified client will run.


 PARAMETERS

 Client : String;

 Specifies the name of the client in question. Clients are listed in the
 introduction to this package.


 return Calendar.Time;

 Specifies the next time the client will run.


 REFERENCES

 Programming Tools (PT), package Time_Utilities



 @node !Commands.Daemon.Quiesce

 procedure Quiesce (Client           : String := ">>CLIENT NAME<<";
                    Additional_Delay : Duration := 86_400.0;
                    Response         : String   := "<PROFILE>");

 DESCRIPTION

 Revokes the specified client's schedule and prevents it from running for
 the amount of time specified in the Additional_Delay parameter.

 This procedure is equivalent to executing the Schedule procedure with a
 new value for the First_Run parameter and the existing value for the
 Interval parameter.

 Quiescing only prevents a client from running; it does not stop a client
 that is already running.

 To prevent a client from running indefinitely, use Duration'Last for the
 Additional_Delay parameter.


 PARAMETERS

 Client : String := ">>CLIENT NAME<<";

 Specifies the name of the client to be delayed. Clients are listed in the
 introduction to this package. The default parameter placeholder ">>CLIENT
 NAME<<" must be replaced or an error will result.


 Additional_Delay : Duration := 86_400.0;

 Specifies the amount of delay. The default is one day. See PT,
 Time_Utilities.Seconds type.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Daemon.Quiesce ("Error_Log");

 removes the Error_Log client from the schedule for one day.


 REFERENCES

 function Get_Warning_Interval
 procedure Run
 procedure Schedule
 Programming Tools (PT), package Time_Utilities



 @node !Commands.Daemon.Run

 procedure Run (Client   : String := "Snapshot";
                Response : String := "<PROFILE>");

 DESCRIPTION

 Runs the specified client immediately.

 If the Snapshot client is specified, the Snapshot client will not run until
 after the snapshot warning message interval has elapsed. (See the
 Snapshot_Warning_Message procedure.)

 If the Disk client is specified, disk collection is done in the order of
 the disk with the least remaining space to the disk with the most
 remaining space.

 Note that the Run procedure does not affect scheduling intervals or
 schedule the client for additional runs.


 PARAMETERS

 Client : String := "Snapshot";

 Specifies the client to be run. Clients are listed in the package
 introduction. The default is the Snapshot client. If the null string ("")
 is specified, all clients are run.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Daemon.Run;

 takes a snapshot after the Snapshot_Warning_Message procedure has elapsed.
 The client's scheduling intervals are not affected.


 REFERENCES

 procedure Quiesce
 procedure Schedule
 procedure Snapshot_Warning_Message



 @node !Commands.Daemon.Schedule

 procedure Schedule (Client    : String    := ">>CLIENT NAME<<";
                     Interval  : Duration;
                     First_Run : Duration  := 0.0;
                     Response  : String    := "<PROFILE>");

 DESCRIPTION

 Schedules the specified client to run at regular intervals.

 A Schedule procedure must be executed for each client. The Environment
 daemon cannot run a client unless it has been scheduled. In the standard
 Environment, the client schedules are set to default values. System
 managers can use this command to change a client's schedule.


 PARAMETERS

 Client : String := ">>CLIENT NAME<<";

 Specifies the name of the client to be scheduled. Clients are listed in the
 introduction to this package. The default parameter placeholder
 ">>CLIENT NAME<<" must be replaced or an error will result.


 Interval : Duration;

 Specifies the period of time between runs. Duration'Last means the specified
 client will never run. The value of the Interval parameter is a number of
 seconds or an expression that evaluates to seconds. You can use the
 Minute, Hour, and Day constants from package !Tools.Time_Utilities,
 because they are of the Duration type.


 First_Run : Duration := 0.0;

 Specifies how soon a client runs after the Schedule procedure finishes
 executing. The value of the First_Run parameter is a number of seconds or
 an expression that evaluates to seconds. The default First_Run interval is
 0.0 seconds; that is, the client will run immediately after invocation.
 You can use the Minute, Hour, and Day constants from package
 !Tools.Time_Utilities, because they are of the Duration type. In
 addition, the Time_Utilities.Duration_Until_Next function is useful
 because it returns the number of seconds between the time of execution and
 a specified time of day. This allows the schedule to be independent of the
 time at which the Schedule procedure is executed.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Daemon.Schedule ("Ddb",86_400.0,36_000.0);

 schedules the DDB (dependency database) client to run once a day,
 beginning 10 hours from the time the command was executed.


 REFERENCES

 procedure Quiesce
 procedure Run
 Programming Tools (PT), package Time_Utilities



 @node !Commands.Daemon.Set_Access_List_Compaction

 procedure Set_Access_List_Compaction
                     (Client   : String  := "";
                      On       : Boolean := True;
                      Response : String  := "<PROFILE>");

 DESCRIPTION

 Specifies that access-list compaction should be performed by the specified
 clients.

 The clients that can perform access-list compaction are File, Ada, and
 Directory. Access-list compaction is the process of removing references to
 nonexistent access-control groups from the access lists of objects. When
 groups are removed from a machine, the entry in access lists for that
 group are set to <UNKNOWN_N>, where N is the number of the deleted group.
 The number for that group is not reclaimed until the
 Set_Access_List_Compaction procedure is run and the daemons are then run.

 Access-list compaction performs two functions:

 *  It removes all unknown entries (those that appear as <UNKNOWN_N> from
    access lists.

 *  It sets the next available space number to the lowest available number.

 For further information on groups, see package Operator. For further
 information on access-list compaction, see the introduction to this
 package.

 Enabling this feature slows a client's operation.


 PARAMETERS

 Client : String := "";

 Specifies the name of the client. The default null string specifies all
 clients. The only clients that perform access-list compaction are File,
 Ada, and Directory. When all clients are specified, only those that can
 perform access-list compaction will actually do it.


 On : Boolean := True;

 Specifies whether access-list compaction should be turned on or off.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 REFERENCES

 function Get_Access_List_Compaction
 package Operator



 @node !Commands.Daemon.Set_Consistency_Checking

 procedure Set_Consistency_Checking
                   (Client   : String  := "";
                    On       : Boolean := True;
                    Response : String  := "<PROFILE>");

 DESCRIPTION

 Specifies whether consistency checking should be turned on.

 Consistency checking performs additional work to ensure that the internal
 state of this system is correct. This operation normally is run only when
 problems are suspected.

 Enabling this feature slows a client's operation.


 PARAMETERS

 Client : String := "";

 Specifies the client that should perform consistency checking. Clients are
 listed in the introduction to this package. The default null string
 specifies all clients.


 On : Boolean := True;

 Specifies whether consistency checking should be turned on or off.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 REFERENCES

 function Get_Consistency_Checking



 @node !Commands.Daemon.Set_Log_Threshold

 procedure Set_Log_Threshold (Kind  : Log_Threshold;
                              Level : Condition_Class);

 DESCRIPTION

 Specifies a destination for log messages with a given level of severity.

 By default, Condition_Class type messages of Warning, Problem, and Fatal
 are routed to the operator console. Messages of all kinds are written into
 the stable-storage error log on disk, causing the log to be committed to
 disk.


 PARAMETERS

 Kind : Log_Threshold;

 Specifies a destination for a class of messages. The destination can be
 Console_Print, Log_To_Disk, or Commit_Disk.


 Level : Condition_Class;

 Specifies the severity level of messages by Condition_Class type, including
 Normal, Warning, Problem, and Fatal.


 EXAMPLES

 The command:

   Daemon.Set_Log_Threshold (Log_To_Disk,Normal);

 routes all messages of condition class Normal (or greater) to the error
 log.

 The command:

   Daemon.Set_Log_Threshold (Console_Print,Problem);

 routes all messages of condition classes Problem and Fatal to the operator
 console. Normal or Warning messages do not appear on the operator console.


 REFERENCES

 subtype Condition_Class
 procedure Get_Log_Threshold
 type Log_Threshold
 procedure Show_Log_Thresholds



 @node !Commands.Daemon.Set_Priority

 procedure Set_Priority  (Priority : Collection_Priority := -1);

 DESCRIPTION

 Sets the priority for disk collection on the specified volume.

 Executing this procedure while disk collection is in progress changes the
 priority of the current collection. If disk collection is not in progress
 when the command is executed, the procedure has no effect.

 The Disk client runs at different priorities in response to a number of
 stimuli, as follows:

 *  Schedule procedure: Runs at priority 6.

 *  Run procedure: Runs at priority -1.

 *  Collect procedure: Runs at specified priority.

 *  Over threshold for the disk: Starts at priority 0 and escalates based
    on the number of disks that have reached the threshold.


 PARAMETERS

 Priority : Collection_Priority := -1;

 Specifies the priority for running disk collection. Collection_Priority is
 an integer from -1 through 6. The default, -1, runs collection as a
 background activity. The value 0 ensures that disk collection takes place,
 potentially affecting system load; 6 allocates all resources for disk
 collection.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Daemon.Set_Priority (0);

 sets the priority for disk collection to 0 for all disk volumes.


 REFERENCES

 procedure Collect
 subtype Collection_Priority



 @node !Commands.Daemon.Show_Log_Thresholds

 procedure Show_Log_Thresholds;

 DESCRIPTION

 Displays current log thresholds in an Environment output window.


 EXAMPLES

 The command:

   Daemon.Show_Log_Thresholds;

 displays information, such as the following, in an Environment
 Current_Output window:

   Log Thresholds -- Console = WARNING, Logging = NORMAL, Commit = NORMAL

 This display includes the following categories of information:

 Console

 Corresponds to log threshold Console_Print; shows that messages of
 Warning, Problem, and Fatal class are routed to the operator console.

 Logging

 Corresponds to log threshold Log_To_Disk; shows that messages of all
 classes are written into the stable-storage error log on disk.

 Commit

 Corresponds to log threshold Commit_Disk; shows that messages of all
 classes are written into the stable-storage error log, causing the log to
 be committed to disk.


 REFERENCES

 subtype Condition_Class
 procedure Get_Log_Threshold
 type Log_Threshold
 procedure Show_Log_Thresholds



 @node !Commands.Daemon.Show_Snapshot_Settings

 procedure Show_Snapshot_Settings;

 DESCRIPTION

 Lists the current snapshot-message options, showing the warning-message
 interval and whether or not start and finish messages have been requested.


 EXAMPLES

 The command:

   Daemon.Show_Snapshot_Settings;

 returns the following display:

      Snapshot Settings -- Interval = 02:00.00, Start = TRUE, Finish = TRUE

 The Environment issues a snapshot warning message 2 minutes before each
 snapshot and sends warning messages at the start and finish of each
 snapshot.

 To see the interval between runs, use:

   Daemon.Status ("Snapshot");

 REFERENCES

 procedure Snapshot_Finish_Message
 procedure Snapshot_Start_Message
 procedure Snapshot_Warning_Message
 procedure Status



 @node !Commands.Daemon.Snapshot_Finish_Message

 procedure Snapshot_Finish_Message (On : Boolean := True);

 DESCRIPTION

 Tells the Environment whether or not to send a message informing users
 when a snapshot completes.


 PARAMETERS

 On : Boolean := True;

 Sends, when True, a message such as the following to users after every
 snapshot is completed:

      from SYSTEM: 02:34:34 PM;  Snapshot has completed.

 This message appears in the message window.

 When False, no finishing message is sent to users. The default is True.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Daemon.Snapshot_Finish_Message (False);

 instructs the Environment not to notify users when a snapshot is
 completed.


 REFERENCES

 procedure Show_Snapshot_Settings
 procedure Snapshot_Start_Message
 procedure Snapshot_Warning_Message
 procedure Status



 @node !Commands.Daemon.Snapshot_Start_Message

 procedure Snapshot_Start_Message (On : Boolean := True);

 DESCRIPTION

 Tells the Environment whether or not to send a message informing users
 when a snapshot begins.


 PARAMETERS

 On : Boolean := True;

 Sends, when True, a message such as the following to users as each
 snapshot begins:

      from SYSTEM: 02:31:55 PM;  Snapshot has started

 This message appears in the message window.

 When False, no starting message is sent to users. The default is True.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Daemon.Snapshot_Start_Message (False);

 instructs the Environment not to notify users when a snapshot begins.


 REFERENCES

 procedure Show_Snapshot_Settings
 procedure Snapshot_Finish_Message
 procedure Snapshot_Warning_Message
 procedure Status



 @node !Commands.Daemon.Snapshot_Warning_Message

 procedure Snapshot_Warning_Message (Interval : Duration := 120.0);

 DESCRIPTION

 Sends a warning message to users the specified number of seconds before the
 next snapshot begins.

 When the interval is set to 0.0, no warning message is sent.


 PARAMETERS

 Interval : Duration := 120.0;

 Specifies how soon, in seconds, to send a warning message such as the
 following before a snapshot begins:

      from SYSTEM: 02:29:23 PM;  Snapshot will start in 02:00.000

 This message appears in the message window.

 The default is a 2-minute interval (120.0 seconds). When the Interval
 parameter is set to 0.0, no warning message is sent.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Daemon.Snapshot_Warning_Message (300.0);

 instructs the Environment to warn users of a pending snapshot 5 minutes
 (300.0 seconds) before it is run.


 REFERENCES

 procedure Show_Snapshot_Settings
 procedure Snapshot_Finish_Message
 procedure Snapshot_Start_Message
 procedure Status



 @node !Commands.Daemon.Status

 procedure Status (Client : String := "*");

 DESCRIPTION

 Displays (in an Environment output window) information on the current
 status for the specified client.


 PARAMETERS

 Client : String := "*";

 Specifies the client for which status is requested. The default ("*") is
 the Major_Clients constant. The null string ("") displays the status of
 all clients.

 The command:

   Daemon.Status ("");

 displays the status for all clients. The display typically looks like
 this:

 Client      Next Time       Previous Time   Interval  Size    Post    Pre
 ==========  ==============  ==============  ========  ======  ====== ======
 Actions     06/08/91 11:53  06/08/91 11:23  30:00.00      55      55     55
 Ada         06/09/91 04:40  06/08/91 05:03  01/00:00    2073    2010   2425
 Ddb         06/08/91 04:15  06/08/91 04:19  01/00:00   11213   10899  10899
 Directory   06/08/91 04:30  06/08/91 04:36  01/00:00    5775    5698   6423
 Disk        06/09/91 05:00  06/08/91 06:24  01/00:00  339000  311000 351000
 File        06/08/91 04:45  06/08/91 05:14  01/00:00    1103     980   1219
 Snapshot    06/08/91 12:08  06/08/91 11:10  01:00:00

 This display includes the following categories of information:

 *  Client: The client's name.

 *  Next Time: The time of the client's next scheduled run.

 *  Previous Time: The actual time of the client's most recent previous
    run. Note that the actual time a client runs may not match the
    scheduled time; the client may run later because of system load, how
    long preceding clients run, and so on.

 *  Interval: The interval of time between scheduled runs. The format for
    expressing intervals is as follows:

    -  mm:ss.ff indicates the number of minutes, seconds, and decimal
       fractions of seconds between runs. For example, the Actions client
       runs every 30 minutes, or 30:00.00.

    -  hh:mm:ss indicates the number of hours, minutes, and seconds between
       runs. For example, a client that runs every hour would display
       01:00:00.

    -  dd/hh:mm indicates the number of days, hours, and minutes between
       runs. For example, a client that runs once a day would display
       1/00:00.

 *  Size: The current size, in pages, of the client's data structure.

 *  Post: The size, in pages, of the client's data structure after the last
    run.

 *  Pre: The size, in pages, of the client's data structure just before the
    last run.

 The command:

   Daemon.Status ("Disk");

 checks the status of the client responsible for maintaining the disk data
 structure and returns a display such as the following:

   Client  Next Time       Previous Time   Interval  Size    Post    Pre
   ======= ==============  ==============  ========  ======  ======  ======
   Disk    06/09/91 05:00  06/08/91 06:24  01/00:00  339000  311000  351000
   Vol 1   06/09/91 05:00  06/08/91 06:24  01/00:00  112000   95494  126000
   Vol 2   06/09/91 05:00  06/08/91 06:24  01/00:00   79086   77639   81287
   Vol 3   06/09/91 05:00  06/08/91 06:24  01/00:00   78126   71102   74536
   Vol 4   06/09/91 05:00  06/08/91 06:24  01/00:00   69895   67360   69532

 An asterisk before the volume number indicates that disk collection is
 running and that volume has not yet had collection run for it.


 REFERENCES

 constant Major_Clients
 procedure Show_Snapshot_Settings
 procedure Snapshot_Finish_Message
 procedure Snapshot_Start_Message
 procedure Snapshot_Warning_Message



 @node !Commands.Daemon.Threshold_Warnings

 procedure Threshold_Warnings (On : Boolean := True);

 DESCRIPTION

 Specifies whether messages to all users currently logged into the system
 should be sent when collection thresholds have been passed.


 PARAMETERS

 On : Boolean := True;

 Specifies whether messages should be sent. The default is True. False
 specifies that messages should not be sent.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 REFERENCES

 procedure Collect



 @node !Commands.Daemon.Volume

 subtype Volume is Integer range 0 .. 31;

 DESCRIPTION

 Specifies a disk drive.

 The value 0 specifies all disk drives.

 (The value 0 should not be used in functions, because functions can return
 only a single value.)


 REFERENCES

 procedure Collect



 @node !Commands.Daemon.Warning_Interval

 procedure Warning_Interval (Interval : Duration := 120.0);

 DESCRIPTION

 Sets the amount of warning time users are given before the Daily client
 runs.


 PARAMETERS

 Interval : Duration := 120.0;

 Specifies how soon, in seconds, to send a warning message before the Daily
 client runs. The default is 2 minutes (120 seconds).


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 REFERENCES

 function Get_Warning_Interval



 @node !Commands.Message

 This package contains two utilities for sending messages to the message
 window of one or more users.


 RESOURCES IN PACKAGE MESSAGE

 Sending a message to one or more specified users:    Send
 Sending a message to all users:                      Send_All


 KEY CONCEPTS FOR PACKAGE MESSAGE

 The commands in package Message can be used to send a message string to
 the message window of the specified user or users. The message window is
 the top-most window of a standard Environment terminal device. Users must
 be logged in to receive message strings.

 The commands in this package differ from (and are more limited than) those
 in the Rational Network Mail product, which is documented in the Rational
 Network Mail User's Guide and the Rational Network Mail System Manager's
 Guide.

 Information about preparing and displaying a daily message is given in the
 System Manager's Guide and in the reference entry for the
 !Commands.What.Message command in the Session and Job Management (SJM)
 book.


 @node !Commands.Message.Send

 procedure Send (Who     : String;
                 Message : String);

 DESCRIPTION

 Sends the specified message to one or more specified users.

 A specified user must be logged in to receive the message. If the user is
 not logged in, the message is lost.

 Messages appear in the message window of the specified user or users. The
 message is also displayed on the operator console.


 PARAMETERS

 Who : String;

 Specifies the username of the user who is to receive the message. Multiple
 usernames can be specified using wildcards, set notation, and indirect
 files. The naming expression must be enclosed in quotation marks.


 Message : String;

 Specifies the text of the message. The text must be enclosed in quotation
 marks.


 EXAMPLES

 Assume that user ELF enters the following command:

   Message.Send ("SJL","Are you there?");

 Then the following string appears in the message window of SJL's terminal
 device:

   From ELF: Are you there?


 @node !Commands.Message.Send_All

 procedure Send_All (Message : String);

 DESCRIPTION

 Sends the specified message to all users.

 Only users who are logged in receive the message.

 Messages appear in the message window; the message is also sent to a
 system manager logged into the operator console.


 PARAMETERS

 Message : String;

 Specifies the text of the message. The text must be enclosed in quotation
 marks.


 EXAMPLES

 Assume that ELF enters the following command:

   Message.Send_All ("Who remembers how to abort a job?");

 Then the following message is broadcast to all users who are currently
 logged in:

   From ELF: Who remembers how to abort a job?


 @node !Commands.Operator

 The commands described in this package are used primarily by system
 managers, operators, and Rational technical representatives for
 system-management tasks. All users have access to the Change_Password and
 Create_Session commands.


 RESOURCES IN PACKAGE OPERATOR

 The commands in package Operator fall into several functional groups.
 Types and constants are not included in this list.

 Managing groups for access control:

         Add_To_Group                    Create_Group
         Delete_Group                    Display_Group
         Remove_From_Group

 Managing password policy:

         Get_Minimum_Password_Length     Get_Password_Deadline
         Get_Password_Warning            Get_User_Deadline
         Get_User_Warning                Set_Password_Policy
         Show_Password_Policy

 Managing system resources:

         Disable_Terminal                Disk_Space
         Enable_Terminal                 Force_Logoff
         Get_Login_Limit                 Internal_System_Diagnosis
         Limit_Login                     Set_System_Time
         Show_Login_Limit

 Managing user accounts:

         Change_Password                 Create_Session
         Create_User                     Delete_User

 Overriding access control:

         Enable_Privileges               Privileged_Mode

 Shutting down the system:

         Archive_On_Shutdown             Cancel_Shutdown
         Explain_Crash                   Get_Archive_On_Shutdown
         Get_Shutdown_Interval           Show_Shutdown_Settings
         Shutdown                        Shutdown_Warning


 KEY CONCEPTS FOR PACKAGE OPERATOR

 This section covers the following key concepts for package Operator:

 *  Access-control groups

 *  Operator capability

 *  Password policy

 For information on managing user accounts, shutting down an R1000, and
 managing system resources, see the System Manager's Guide.


 Access-Control Groups

 A job's access to worlds, files, Ada units, and certain operations is
 restricted by access control. Access control applies to all jobs: both
 those initiated interactively through command windows and key combinations
 and those initiated programmatically through procedure calls as a
 program executes.

 Access control is determined by an object's access-control list (ACL). An
 ACL is a list of groups that are permitted access to an object; these
 groups contain usernames. A job is permitted access to an object only if
 the username of the job's user is a member of a group listed in the
 object's ACL. Note that groups can contain only usernames--not other
 groups.

 Groups are defined either automatically by the Environment or explicitly by
 users through operations from package Operator. Group objects are stored
 in the !Machine.Groups world. Package Operator provides commands for
 creating, modifying, and deleting these group objects. Operations from
 packages Access_List and Cmvc_Access_Control grant specific types of access
 to groups. For more information on assigning access to groups, see the
 Library Management (LM) book, introduction to package Access_List, and
 the Project Management (PM) book, introduction to package
 Cmvc_Access_Control.

 The following paragraphs explain the types of access-control groups.


 Username Groups

 When a user account is created, the Environment creates a new username
 group. This group is identified by the unique username assigned to the new
 user. Username groups typically contain only one member: the username of
 the user for whom the account was created. Other usernames can be added to
 a username group through the Add_To_Group command. For example, the
 username Sandy can be added to the username group John. Now both
 usernames, Sandy and John, have access to any object that allows access to
 the username group John.

 Caution: Note that it is possible to delete username groups with the
 Delete_User command. Deleting a username group that contains current users
 will destroy access to any objects with ACLs requiring that group's
 membership.


 Operator Group

 The Environment provides a predefined group called Operator for users who
 perform system-management operations. In addition to specific access rights
 to particular files, Ada units, and worlds, all members of the Operator
 group have operator capability, which allows the execution of Environment
 commands for resource management (see "Operator Capability," below).

 The Operator group for the standard Environment contains only the user
 Operator, but other users can be added.

 The Delete_Group command cannot be used to delete predefined groups such as
 Operator and Privileged. The Delete_User command cannot be used to delete
 predefined users such as Operator.


 Privileged Group

 The Environment provides a predefined group called Privileged for users who
 execute jobs in privileged mode. Privileged mode overrides access control,
 and jobs executed in privileged mode have complete access to all
 Environment objects.

 To execute a job in privileged mode, the Enable_Privileges command must be
 included in the job before the statement that requires privileges.
 Privileged mode is automatically disabled after the job is finished.

 Although enabling privileges for a job allows access to any object, it
 does not allow you to display object images to which you normally do not
 have access. To display such an object, you must first use privileged mode
 to add your username to a group in the object's ACL.

 Members of the Privileged group can execute any Environment command in
 privileged mode, including commands that require operator capability,
 because privileged mode grants access to the
 !Machine.Operator_Capability file (see "Operator Capability," below).

 The Privileged group for the standard Environment contains the user
 Operator, but Operator can be removed, and other users can be added.


 Public and Network_Public Groups

 The Environment provides two predefined groups called Public and
 Network_Public that contain all users on an R1000. When a new username
 is created, that username is automatically added to both groups.

 Group Public can be added to the ACLs of worlds, files, or Ada units to
 permit everyone access to these objects. In open shops, all worlds, files,
 and Ada units can include group Public on their ACLs, effectively giving
 everyone access to everything on a system.

 Group Network_Public is used at sites that use Rational
 Networking--TCP/IP. Adding the Network_Public group to ACLs gives all
 usernames access to objects on other machines belonging to the same
 network.

 Although usernames are added to these groups by default, they can be
 explicitly removed from them with the Remove_From_Group command.


 User-Defined Groups

 Users with operator capability can create groups through package Operator,
 and a user can belong to more than one user-defined group.

 For example, if both John and Sandy require identical access to objects
 used by a particular project called Application, a new group can be
 created containing both John and Sandy; this group might be named
 Application_Members. Access then can be assigned directly to the group
 Application_Members.

 Users can be added to or removed from groups at any time.

 Note: Changes in a user's group membership do not become effective until
 the user logs out and logs back in again.


 Operator Capability

 Certain Environment commands can be executed only by users or jobs that
 have operator capability. These commands, usually found in packages
 Operator, Queue, and System_Backup, generally control Environment
 resources or affect jobs and sessions belonging to other users.

 All members of the Operator group automatically have operator capability
 (see "Operator Group," above). Additional users can be given operator
 capability without being added to the Operator group; this enables
 specific users to use the relevant commands without necessarily having
 access to the worlds, files, and Ada units to which the Operator group has
 access.

 To give a user operator capability, you must grant that user write access
 (W) to the file !Machine.Operator_Capability.

 All successfully executing commands from package Operator requiring
 operator capability and affecting the system state are reported in the
 !Machine.Error_Logs file, and the logged messages include the executing
 user and session, if these are other than System. This log allows a system
 manager to audit which users and what commands have altered the state of
 the system.

 Operator capability should not be confused with privileged mode, which
 enables users to override access control. Whereas privileged mode gives
 users access to objects, operator capability enables users to execute any
 of a specific set of commands.

 Note that users who can enable privileged mode can also give themselves
 operator capability by granting themselves access to the
 !Machine.Operator_Capability file. (See "Privileged Group," above.)


 Procedures Requiring Operator Capability

 In general, operator capability is required only for certain procedures
 and not for functions; it is not required for procedures that merely
 display information. The following list identifies the procedures that
 require operator capability:

 *  Package Daemon:

       Collect                       Quiesce
       Run                           Schedule
       Set_Access_List_Compaction    Set_Consistency_Checking
       Set_Priority                  Snapshot_Finish_Message
       Snapshot_Start_Message        Snapshot_Warning_Message
       Threshold_Warnings            Warning_Interval

 *  Package Job:

       Disable                       Enable
       Kill (when applied to jobs not belonging to the caller)

 *  Package Operator:

       Add_To_Group                  Archive_On_Shutdown
       Cancel_Shutdown               Create_Group
       Create_User                   Delete_Group
       Delete_User                   Disable_Terminal
       Enable_Terminal               Explain_Crash
       Force_Logoff (unless the user performing the operation is
                     the same as the user being forced off)
       Internal_System_Diagnosis     Limit_Login
       Remove_From_Group             Set_Password_Policy
       Set_System_Time               Shutdown
       Shutdown_Warning

 *  Package Queue:

       Add                           Create
       Default                       Destroy
       Disable                       Enable
       Kill_Print_Spooler            Register
       Remove                        Restart_Print_Spooler
       Unregister

 *  Package Scheduler:

       Disable                       Enable
       Set

 *  Package System_Backup:

       Backup                        Backup_Generic
    and anything that instantiates Backup_Generic, such as
    !Commands.Abbreviations.Do_Backup

 *  Package System_Utilities:

       Set_Page_Limit (when applied to jobs not belonging to the caller)

 *  Package Terminal:

       Set_Character_Size               Set_Detach_On_Disconnect
       Set_Disconnect_On_Disconnect     Set_Disconnect_On_Failed_Login
       Set_Disconnect_On_Logoff         Set_Flow_Control
       Set_Input_Rate                   Set_Log_Failed_Logins
       Set_Login_Disabled               Set_Logoff_On_Disconnect
       Set_Output_Rate                  Set_Parity
       Set_Receive_Flow_Control         Set_Receive_Xon_Xoff_Bytes
       Set_Receive_Xon_Xoff_Characters  Set_Stop_Bits
       Set_Terminal_Type                Set_Xon_Xoff_Bytes
       Set_Xon_Xoff_Characters

 *  Procedures in !Commands.System_Maintenance'Spec_View.Units:

       Accept_Tokens                 Donate_Tokens
       Repair_Directory              Show_Directory_Information
       Show_Locks                    Show_Memory_Hogs
       Show_Tasks


 Password Policy

 Using commands from package Operator, the system manager (or other users
 with operator capability) can set a systemwide policy for password length
 and expiration. By requiring users to pick passwords of sufficient length
 and change their passwords with regular frequency, such a policy ensures
 greater system security.


 Minimum Password Length

 By default, login passwords can be zero or more characters. Using the
 Set_Password_Policy command, a system manager can require that new and
 changed passwords be a minimum length. (Existing passwords are not
 affected when the policy is set.)

 Setting a minimum password length causes the Create_User and
 Change_Password commands to reject passwords that contain fewer than the
 required number of characters. For example, if a system manager wanted to
 prevent users from having null passwords, he or she can set the minimum
 password length to 1. Under this policy, new users cannot be created with
 null passwords and existing users cannot change their passwords to null.
 Typical sites require a minimum of 6 to 10 characters.


 Password Change Schedule

 By default, login passwords are valid indefinitely. Using the
 Set_Password_Policy command, a system manager can establish a change
 schedule that specifies when passwords must be changed before they expire.
 All passwords on the system, including the Operator's, are subject to the
 established change schedule. It is not possible to set separate change
 schedules for individual passwords.

 The password change schedule specifies:

 *  The warning interval--the number of days that an unchanged password can
    exist until the user is warned at login to change it.

 *  The deadline interval--the number of days that an unchanged password
    can exist before it expires. (The deadline interval includes the
    warning interval.)

 The warning and deadline intervals for a given password begin when the
 password is created. Each time the password is changed, its "clock" is
 reset and the warning and deadline intervals begin again. For example,
 assume a deadline interval of 21 days and a warning interval of 14 days.
 Then 14 days after a given user's password is created, the following
 message appears at the user's next login:

   Your password is in danger of expiring -- it should be changed.

 This warning message appears at each login for another 7 days, at which
 time the end of the deadline interval is reached. At this point, the
 following message appears when the user attempts to log in:

   Password has expired.

 When a user's password expires, he or she will not be able to log in
 without obtaining a new password. New passwords typically are obtained
 from the system manager, although any user who knows either the expired
 password or the Operator's password can set the new password (see the
 Change_Password command).

 Judgment must be used when determining a reasonable change schedule. The
 shorter the deadline interval, the more often users will have to change
 their passwords, thereby increasing system security but requiring more
 user participation. Similarly, each site must decide how much warning to
 give users before their passwords expire. The greater the difference
 between the warning and deadline intervals, the more warning users get.
 With more days of warning, passwords are less likely to expire while users
 are away on vacation or other absences; with fewer warning days, users are
 less likely to postpone changing their passwords. For many sites, a
 typical deadline interval is 60 days with a warning interval of 46 days
 (leaving 14 days during which the warning message is displayed).


 Basic Steps for Setting Password Policy

 Assume that you are the system manager and that you want to set the
 following password policy:

 *  Login passwords must be at least 6 characters long.

 *  Each login password is valid for a total of 60 days before it must be
    changed. After 46 days, the user receives a warning at each login that
    the password will expire unless it is changed (14 days of warning time
    makes allowance for users who may be on vacation or other leave of
    absence).

 You can use the following steps to establish this password policy. These
 steps apply to R1000s on which user accounts have not yet been created or
 have been created within the last 60 days (see below for a discussion of
 setting password policy without invalidating existing passwords):

 1. Put the policy into effect immediately by entering the
    Set_Password_Policy command with the appropriate values:

      Operator.Set_Password_Policy (Minimum_Length  => 6,
                                    Change_Warning  => 46,
                                    Change_Deadline => 60);

 2. Verify that the correct values were set by entering the
    Show_Password_Policy command with the default value. As a result, the
    current password policy is displayed along with the warning and
    deadline dates that now exist for your password:

      Password change warnings are issued after 46 days
      Passwords must be changed every 60 days

      User      Warning   Deadline
      ----      -------   --------
      Operator  6/14/91    6/28/91

 3. Compare the current date to the deadline date that is displayed for
    your password. If the new password policy has caused your password to
    expire--that is, your password is more than 60 days old--be sure to
    change your password before logging out.

 4. Make the policy permanent by including a call to the
    Set_Password_Policy procedure in an appropriate procedure in the
    !Machine.Initialization.Site or !Machine.Initialization.Local world.

    This step ensures that the desired password policy is reestablished
    each time the system is booted. Omitting this step causes the password
    policy to revert to the default values the next time the system is
    booted. The default values are null minimum password length with
    indefinitely long warning and deadline intervals.


 Setting Password Policy When Old Passwords Already Exist

 On an R1000 with existing user accounts, setting a password policy can
 cause older passwords to expire immediately. For example, assume that on
 6/1/91 you enter the Set_Password_Policy command to establish a 60-day
 deadline interval and 46-day warning interval, as shown in step 1 above.
 Setting this policy will invalidate any passwords that were created or
 changed more than 60 days ago. To determine whether any existing passwords
 are in fact invalidated, you can enter the following command:

   Operator.Show_Password_Policy (For_User => "@"); 

 This command displays the current policy and the warning and deadline
 dates for all user passwords:

   Password change warnings are issued after 46 days
   Passwords must be changed every 60 days

   User      Warning   Deadline
   ----      --------  --------
   Operator   7/07/91   7/21/91
   Anderson   4/12/91   4/26/91
   Chavez     6/10/91   6/24/91
   Yamada     5/14/91   5/28/91

 Note that, if the current date is 6/1/91, the deadline dates for users
 Anderson and Yamada have already passed, so neither user can currently log
 in. At this point, you have several options. If only a few passwords have
 expired, you can change them and notify each affected user of his or her
 new password. If the password policy invalidates a large number of
 passwords, you can "revalidate" them simply by resetting the password
 change schedule to remove the expiration deadline. For example, you can
 enter the following command to cause warnings to be given but not actually
 enforced:

   Operator.Set_Password_Policy
                         (Minimum_Length  => 6,
                          Change_Warning  => 46,
                          Change_Deadline => Operator.Days'Last);

 Doing this gives users with old passwords time to change them before you
 put the full password policy into effect. To decide when to enforce the
 full password policy, use the Show_Password_Policy command periodically
 to monitor the warning dates for all users. When the display shows all
 warning dates in the future, you can reenter the Set_Password_Policy
 command to set the full password policy. Make the policy permanent by
 including a call to the Set_Password_Policy procedure in an appropriate
 procedure in the !Machine.Initialization.Site or !Machine-
 .Initialization.Local world.


 If Everyone's Password Expires . . .

 If everyone's password (including the Operator's) has expired, and if no
 one is currently logged in, the system manager can use the following steps
 to recover:

 1. Obtain a unique login authorization code from the Rational Response
    Center. This authorization code will be valid only for your specific
    machine on the current date.

 2. Attempt to log in under the username Operator, entering the expired
    password at the password prompt. (If this password has been forgotten,
    refer to the "Forgotten Operator Password" subsection below for
    information about how to change the operator password to a new
    password.)

    Another prompt appears requesting the authorization code obtained in
    step 1. For example:

      Enter user name: operator
      Enter password: <old password>

      Operator password has expired. Call Rational for override
      authorization code.

 3. Enter the authorization code at the prompt. Note that it is
    case-sensitive (all uppercase). For example:

      Enter authorization code: 1FF79C650C12E8B

 4. When you are logged in, use the Change_Password command to obtain a new
    password.


 Forgotten Operator Password

 If the password for the special username Operator has been forgotten, the
 system manager must:

 1. Contact the Rational Response Center and obtain the proper
    authorization code. Be prepared to give the cluster ID for your R1000
    to the Response Center. Note that the authorization code obtained from
    the Response Center will be valid until midnight of the day it is
    obtained.

 2. Follow the Response Center instructions to use the following command
    from the operator's console (authorization code is uppercase only):

      Op.Change_Password ("Operator", "AUTH. CODE","new password")

 You will then be able to log into the system as Operator with the new
 password.


 @node !Commands.Operator.Add_To_Group

 procedure Add_To_Group (User     : String := ">>USER NAME<<";
                         Group    : String := ">>GROUP NAME<<";
                         Response : String := "<PROFILE>");

 DESCRIPTION

 Adds one or more specified usernames to one or more groups.

 Note that identities are established at login. Adding or removing a user
 from a group will not be effective until the user's next login.

 To see if the username is already a member of the group, you can use the
 Display_Group command. The username and group name must exist before
 this command is executed.


 PARAMETERS

 User : String := ">>USER NAME<<";

 Specifies one or more usernames to add to the specified group. The default
 parameter placeholder ">>USER NAME<<" must be replaced or an error will
 result. The username must exist before this command is executed.

 Multiple names can be specified using wildcards, set notation, and indirect
 files.

 When an indirect file containing a list of usernames is specified as the
 ">>USER NAME<<" parameter value, the usernames listed in the indirect file
 are automatically resolved to their proper context. This means that a
 system manager does not have to specify the fully qualified pathname of
 each entry in the file.


 Group : String := ">>GROUP NAME<<";

 Specifies one or more group names to which the username should be added.
 The default parameter placeholder ">>GROUP NAME<<" must be replaced or an
 error will result. The specified group names must exist before this command
 is executed.

 Multiple groups can be specified using wildcards, set notation, and
 indirect files. The default is the selection, whether or not the cursor is
 in the selection.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 ERRORS

 If a specified username or group does not exist, the command generates an
 error message.


 EXAMPLES

 The command:

   Operator.Add_To_Group (User  => "Bill",
                          Group => "Engineering");

 adds username Bill to a group called Engineering.

 Both username Bill and group Engineering must exist before this command is
 executed. Bill must log out and log back in again for his membership in
 group Engineering to be in effect.

 The command:

   Operator.Add_To_Group (User  =>"[Phil,Anderson]",
                          Group => "Engineering");

 adds usernames Phil and Anderson to a group called Engineering.

 Usernames Phil and Anderson and group Engineering must exist before this
 command is executed. Phil and Anderson must log out and log back in
 again for their membership in group Engineering to be in effect.


 REFERENCES

 procedure Create_Group
 procedure Create_User
 procedure Delete_Group
 procedure Display_Group
 procedure Remove_From_Group
 Library Management (LM), package Access_List



 @node !Commands.Operator.Archive_On_Shutdown

 procedure Archive_On_Shutdown (On : Boolean := True);

 DESCRIPTION

 Causes certain data structures to be archived in a
 representation-independent form whenever the system is shut down.

 More specifically, this command stores the internal state of the object
 managers. Object managers include Actions, Ada, Archived_Code,
 Code_Segment, Configuration, DDB, Directory, File, Group, Link,
 Null_Device, Pipe, Program_Library, Session, Tape, Terminal, and User.

 When these data structures are archived in representation-independent form,
 they can be restored even if the system is booted with a different release
 of the Environment. (The object-manager state of one release differs from
 and is incompatible with that of another release.)

 Archiving increases the time it takes for the system to shut down and
 reboot, so archiving is recommended only when required by Rational
 technical representatives for installing a new software release.


 PARAMETERS

 On : Boolean := True;

 Specifies, when True, that archiving is included in the system shutdown
 process. The default is True.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 REFERENCES

 function Get_Archive_On_Shutdown
 procedure Show_Shutdown_Settings
 procedure Shutdown



 @node !Commands.Operator.Cancel_Shutdown

 procedure Cancel_Shutdown;

 DESCRIPTION

 Cancels a system shutdown initiated by the Shutdown command.

 This command can be entered at any time during the interval before the
 actual shutdown takes place. When this command is promoted, messages are
 sent to users that shutdown is canceled.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 REFERENCES

 function Get_Shutdown_Interval
 procedure Show_Shutdown_Settings
 procedure Shutdown
 procedure Shutdown_Warning



 @node !Commands.Operator.Change_Password

 procedure Change_Password
                       (User         : String := ">>USER NAME<<";
                        Old_Password : String := "";
                        New_Password : String := "";
                        Response     : String := "<PROFILE>");

 DESCRIPTION

 Changes the specified user's old password to the specified new password.

 The new password must be different from the old password. If the old
 password has been forgotten, the Operator's password can be used in its
 place. Also, after changing your password, you must update any encrypted
 entries in your remote-passwords files, using the Remote_Passwords.Update
 command.

 The specified new password is subject to the current password policy, if
 one has been set (see the Set_Password_Policy command). In particular, if
 the current password policy requires a minimum character length, the
 New_Password value will be rejected if it is too short.


 PARAMETERS

 User : String := ">>USER NAME<<";

 Specifies the name of the user whose password is to be changed. The default
 parameter placeholder ">>USER NAME<<" must be replaced or an error will
 result.


 Old_Password : String := "";

 Specifies the password to be changed. If the old password is not known, the
 Operator's password can be used (that is, the password for the username
 Operator). The default is the null string--in other words, no password.

 Note: If the old password has expired because of the current password
 policy, it can still be specified.


 New_Password : String := "";

 Specifies the new password. The new password must be different from the old
 password. The new password is subject to the minimum password length set
 by the current password policy. The default is the null string--in other
 words, no password.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 ERRORS

 An error is generated if the username is not specified or if the new
 password is identical to the old password.


 EXAMPLES

 The command:

   Operator.Change_Password ("Anderson","Hello","Greetings");

 changes the password for user Anderson from "hello" to "greetings."


 REFERENCES

 function Get_Minimum_Password_Length
 function Get_Password_Deadline
 function Get_Password_Warning
 function Get_User_Deadline
 function Get_User_Warning
 procedure Set_Password_Policy
 procedure Show_Password_Policy



 @node !Commands.Operator.Create_Group

 procedure Create_Group (Group    : String := ">>GROUP NAME<<";
                         Response : String := "<PROFILE>");

 DESCRIPTION

 Creates a new group with the specified name.

 The group cannot already exist. When created, the group has no members.
 Members can be added with the Add_To_Group command.

 A maximum of 1,000 group names is allowed per system. Once this maximum
 has been reached, no further group names can be added. An error message is
 issued if this command is executed after the system has reached the
 maximum allowable number of groups.

 Groups that are no longer needed can be removed with the Delete_Group com-
 mand (use Delete_User to remove username groups). Once the limit has been
 reached, however, access-list compaction must be run before you can create
 new groups. See the introduction to package Daemon for further information
 on access-list compaction.


 PARAMETERS

 Group : String := ">>GROUP NAME<<";

 Specifies the name of the group to be created. The default parameter
 placeholder ">>GROUP NAME<<" must be replaced or an error will result.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 ERRORS

 An error message is issued if this command is executed after the system
 has reached the maximum allowable number of groups.


 EXAMPLES

 The command:

   Operator.Create_Group (Group => "Ada_1_Group");

 creates a new group called Ada_1_Group. New members can be added to the
 group with the Add_To_Group command.


 REFERENCES

 procedure Add_To_Group
 procedure Delete_Group
 procedure Display_Group
 procedure Remove_From_Group
 package Daemon, introduction
 Library Management (LM), package Access_List



 @node !Commands.Operator.Create_Session

 procedure Create_Session (User     : String := ">>USER NAME<<";
                           Session  : String := ">>SESSION NAME<<";
                           Response : String := "<PROFILE>");

 DESCRIPTION

 Creates another session for the specified user.

 Sessions are created as necessary when a user logs into the system. The
 Environment creates the session and manages it for the user. One
 terminal port is assigned to each active session. A single user can have
 more than one active session by logging into the system from more than one
 terminal port and providing a unique session name for each login.

 The Create_Session command allows the system manager or a user to create a
 session for a user without actually logging into the session.


 PARAMETERS

 User : String := ">>USER NAME<<";

 Specifies the name of the user for whom a new session is to be added. The
 default parameter placeholder ">>USER NAME<<" must be replaced or an error
 will result.


 Session : String := ">>SESSION NAME<<";

 Specifies the name to give the new session. The session name must be a
 legal Ada identifier, and no other object of this name should exist in the
 user's home library (!Users.User_Name). The default parameter placeholder
 ">>SESSION NAME<<" must be replaced or an error will result.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 EXAMPLES

 The command:

   Operator.Create_Session ("Anderson","Maintenance");

 creates a new session called Maintenance for user Anderson.


 REFERENCES

 procedure Create_User



 @node !Commands.Operator.Create_User

 procedure Create_User (User     : String  := ">>USER NAME<<";
                        Password : String  := "";
                        Volume   : Natural := 0;
                        Response : String  := "<PROFILE>");

 DESCRIPTION

 Opens an account for the specified user.

 This command creates a username in !Machine.Users. In addition, the
 command creates the world !Users.User_Name, if such a world does not
 already exist. The command also creates a default session, S_1, for the
 username. By default, the username is made a member of groups Public and
 Network_Public.

 A group with the name specified by the User parameter is created and the
 new user is added to this group. Thus, each user has his or her own group
 with at least that user as a member.

 When a new username is created, the access-control list (ACL) for that
 user's world is formed by concatenating the contents of
 !Machine.User_Acl_Suffix and Name=> RCOD, where Name is the group name for
 the newly created username. Similarly, the default ACL for the world is
 formed by concatenating the contents of !Machine.User_Default_Acl_Suffix
 with Name=>RW, where Name is the group name for the newly created
 username. (See the Library Management (LM) book for more information on
 access-control lists and default access-control lists.)

 Links from !Model.R1000 are copied into the new user's home world.

 A new account can be assigned a temporary password. This password is subject
 to the current password policy, if one has been set (see the
 Set_Password_Policy command). In particular, if the current password
 policy requires a minimum character length, the Password value will be
 rejected if it is too short. The user can log in with the temporary
 password and then use the Change_Password command to obtain a secret
 password.


 PARAMETERS

 User : String := ">>USER NAME<<";

 Specifies the username. The name must be a legal Ada simple name and must
 be unique. The default parameter placeholder ">>USER NAME<<" must be
 replaced or an error will result.


 Password : String := "";

 Specifies the initial password. The password can be any arbitrary string.
 This password is subject to the minimum password length set by the
 current password policy. The default is the null string--in other words,
 no password.


 Volume : Natural := 0;

 Specifies the volume in which the user's home world will reside. The
 default, 0, lets the Environment choose the volume that has the most
 available space.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 ERRORS

 If the specified user already exists, an error message is generated.

 A maximum of 1,000 group names is allowed per system. Once this maximum
 has been reached, no further group names can be added. An error message is
 issued if this command is executed after the system has reached the
 maximum allowable number of groups.

 Groups that are no longer needed can be removed with the Delete_Group com-
 mand (use Delete_User for username groups), but deleting groups does not
 make it possible to create new groups once the limit has been reached.
 Access-list compaction must be run to make it possible to create new
 groups. See the introduction to package Daemon for further information
 on access-list compaction.


 EXAMPLES

 The command:

   Operator.Create_User ("Anderson","Andersonnew");

 creates an account for user Anderson on a volume selected by the
 Environment. It assigns password Andersonnew to the account. It also
 creates a home world for the user in !Users.Anderson, sets up the links
 for the world, sets the ACL and default ACL for the world, makes
 Anderson a member of groups Public and Network_Public, creates a group
 called Anderson, and adds the Anderson username to group Anderson.


 REFERENCES

 procedure Add_To_Group
 procedure Change_Password
 procedure Create_Session
 procedure Set_Password_Policy
 procedure Show_Password_Policy
 package Daemon, introduction
 Library Management (LM), package Access_List



 @node !Commands.Operator.Days

 subtype Days is Positive;

 DESCRIPTION

 Defines a type that represents a number of days in a password change
 schedule (see the Set_Password_Policy procedure).


 REFERENCES

 procedure Change_Password
 procedure Set_Password_Policy
 procedure Show_Password_Policy



 @node !Commands.Operator.Delete_Group

 procedure Delete_Group (Group    : String := ">>GROUP NAME<<";
                         Response : String := "<PROFILE>");

 DESCRIPTION

 Deletes the group with the specified name.

 ACL entries that refer to a deleted group are reclaimed during the next
 access-list compaction. See package Daemon for further information on
 access-list compaction.

 A maximum of 1,000 user-created group names is allowed. Once this maximum
 is reached, group names can no longer be added. Deleting groups does not
 make it possible to create new groups once the limit has been reached.
 Access-list compaction must be run to make it possible to create new
 groups. See the introduction to package Daemon for further information
 on access-list compaction.


 PARAMETERS

 Group : String := ">>GROUP NAME<<";

 Specifies the name of the group to be deleted. The default parameter
 placeholder ">>GROUP NAME<<" must be replaced or an error will result.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.

 The following kinds of groups cannot be deleted using this command:

 *  Predefined groups

    These include the Network, Network_Public, Operator, and Privileged
    groups.

 *  Groups that have the same names as existing usernames

    When you execute the Delete_User command, it removes the group
    associated with that user.


 EXAMPLES

 The following command deletes a group called Ada_1_Group:

   Operator.Delete_Group (Group => "Ada_1_Group");

 REFERENCES

 procedure Add_To_Group
 procedure Create_Group
 procedure Delete_User
 procedure Display_Group
 procedure Remove_From_Group
 package Daemon, introduction
 Library Management (LM), package Access_List



 @node !Commands.Operator.Delete_User

 procedure Delete_User (User     : String := ">>USER NAME<<";
                        Response : String := "<PROFILE>");

 DESCRIPTION

 Disables login for the specified user but preserves the user's home world.

 This command also deletes the user's entry from the !Machine.Users world
 and deletes the user's default session, S_1.

 The user's home world can be deleted using commands in package !Commands-
 .Library--for example:

   Library.Destroy ("!Users.User_Name??");

 Make sure that the user is logged out before disabling the user's account.


 PARAMETERS

 User : String := ">>USER NAME<<";

 Specifies the username of the account to be disabled. The default parameter
 placeholder ">>USER NAME<<" must be replaced or an error will result.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.

 The user Operator cannot be deleted with this command.


 ERRORS

 This command fails if executed while the user is logged in.


 EXAMPLES

 The command:

   Operator.Delete_User ("Anderson");

 deletes the account for user Anderson and disables logins under Anderson's
 username. The world !Users.Anderson is preserved.


 REFERENCES

 procedure Create_User
 procedure Delete_Group
 procedure Display_Group
 procedure Remove_From_Group
 package Daemon, introduction
 Library Management (LM), package Access_List



 @node !Commands.Operator.Disable_Terminal

 procedure Disable_Terminal
                        (Physical_Line : Terminal.Port;
                         Response      : String := "<PROFILE>");

 DESCRIPTION

 Disables a previously enabled port for login.

 You can also use the Terminal.Set_Login_Disabled command to prevent the
 Enable_Terminal command from reenabling the port for login.

 If the line is in use, the command will not take effect until the user
 logs out.


 PARAMETERS

 Physical_Line : Terminal.Port;

 Specifies the terminal port to be disabled. This is a number from 0 through
 255.

 On earlier models of the R1000 (Series 100 and 200), ports 16-31 or 16-47
 are RS232 ports, depending on the number of installed RS232 panels. On the
 Series 300 or Series 400 systems, port 16 is the only RS232 port.

 On later models of the R1000 (Series 300 or Series 400), ports 224-255 are
 Telnet ports. Series 200 systems can also have Telnet ports in the range
 224-255 if Rational Networking--TCP/IP has been installed.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 EXAMPLES

 The following command disables port 249:

   Operator.Disable_Terminal (249);
    

 REFERENCES

 procedure Enable_Terminal
 procedure Queue.Devices
 procedure Queue.Disable
 procedure Queue.Enable
 procedure Queue.Remove
 procedure Queue.Unregister
 function System_Utilities.Enabled
 function System_Utilities.Login_Disabled
 package Terminal, introduction
 subtype Terminal.Port
 procedure Terminal.Set_Login_Disabled
 procedure Terminal.Settings



 @node !Commands.Operator.Disk_Space

 procedure Disk_Space;

 DESCRIPTION

 Displays disk data.


 EXAMPLES

 The command:

   Operator.Disk_Space;

 returns a display such as the following:

   Volume  Capacity  Available   Used   % Free
   ======  ========  =========  ======  ======
   1        369120     284196    84924    76
   2        391680     229239   162441    58
   3        391680     274570   117110    70
   4        391680     282619   118661    70

   Total   1553760    1070624   483136    68

 Volume indicates the disk drive. Capacity and Available describe disk
 space in terms of pages of 1 Kb each. Used describes the amount of disk
 space used in terms of pages of 1 Kb each. % Free specifies the percentage
 of disk space that is still unused.

 The bottom row describes totals for all volumes.


 REFERENCES

 procedure Daemon.Collect
 procedure Daemon.Get_Size



 @node !Commands.Operator.Display_Group

 procedure Display_Group (Group    : String := ">>GROUP NAME<<";
                          Response : String := "<PROFILE>");

 DESCRIPTION

 Displays the usernames that are current members of the specified group on
 Io.Current_Output.

 If there is a user with the specified name, the groups of which the user is
 a member are also displayed.


 PARAMETERS

 Group : String := ">>GROUP NAME<<";

 Specifies the name of the group. The default parameter placeholder ">>GROUP
 NAME<<" must be replaced or an error will result.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 EXAMPLES

 The command:

   Operator.Display_Group (Group => "Public");

 results in the following display:

   Contents of group "public"
   ==========================
       user BILL
       user JLS
       user GZC
       user JIM
       user JMK
       user PUBLIC
       user SMP

   User "public" is a member of
   ============================
      group PUBLIC
   

 REFERENCES

 Library Management (LM), procedure Access_List.Default_Display
 Library Management (LM), procedure Access_List.Display



 @node !Commands.Operator.Enable_Privileges

 procedure Enable_Privileges (Enable : Boolean := True);

 DESCRIPTION

 Specifies that privileged mode should be enabled or disabled for the
 current job.

 There is no effect on other jobs for that user or session, current or
 future.

 Jobs executing in privileged mode have complete access to all Environment
 objects.

 For this command to execute successfully, the username must be a member of
 group Privileged. In general, privileged mode should not be enabled unless
 necessary to avoid accidentally doing something that normally would be
 restricted by access control.

 When privileged mode is enabled, all tasks in that job become privileged.
 Execution of the command does not result in any output indicating that
 the username is now executing under privileged mode. Jobs initiated from
 a job with privileges enabled do not become privileged.

 Privileged mode is enabled only for the duration of the job that called
 it. Therefore, it is not possible to enable it permanently for an entire
 session.


 PARAMETERS

 Enable : Boolean := True;

 Specifies, when True, that privileged mode should be enabled for the
 current username and session. When False, this parameter specifies that
 privileged mode should be disabled. Thus, privileged mode can be enabled,
 disabled, and enabled again within the same job, if desired.


 RESTRICTIONS

 If the job is not a member of group Privileged, this command has no
 effect.


 REFERENCES

 "Privileged Group," introduction to this package
 Library Management (LM), package Access_List



 @node !Commands.Operator.Enable_Terminal

 procedure Enable_Terminal (Physical_Line : Terminal.Port;
                            Response      : String := "<PROFILE>");

 DESCRIPTION

 Enables the specified line for Environment login.

 This command fails if the Login_Disabled option has been disabled by the
 Terminal.Set_Login_Disabled command.


 PARAMETERS

 Physical_Line : Terminal.Port;

 Specifies the terminal port to enable for login; Terminal.Port is a number
 from 0 through 255.

 On earlier models of the R1000 (Series 100 and 200), ports 16-31 or 16-47
 are RS232 ports, depending on the number of installed RS232 panels. On the
 Series 300 or Series 400 systems, port 16 is the only RS232 port.

 On later models of the R1000 (Series 300 or Series 400), ports 224-255 are
 Telnet ports. Series 200 systems can also have Telnet ports in the range
 224-255 if Rational Networking--TCP/IP has been installed.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 EXAMPLES

 The following command enables port 249:

   Operator.Enable_Terminal (249);
    

 REFERENCES

 procedure Disable_Terminal
 procedure Queue.Add
 procedure Queue.Devices
 procedure Queue.Disable
 procedure Queue.Enable
 procedure Queue.Register
 function System_Utilities.Enabled
 function System_Utilities.Login_Disabled
 package Terminal, introduction
 subtype Terminal.Port
 procedure Terminal.Set_Login_Disabled
 procedure Terminal.Settings



 @node !Commands.Operator.Explain_Crash

 procedure Explain_Crash;

 DESCRIPTION

 Allows an operator to specify the cause and an explanation for a shutdown
 through current input.

 The cause and explanation are entered in the machine's error log. This
 command is for documenting system crashes or other service interruptions.
 It is an alternative to the corresponding Shutdown command, which
 prompts for a reason and an explanation.

 Input to this command is terminated with End_Of_Input.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.



 @node !Commands.Operator.Force_Logoff

 procedure Force_Logoff
               (Physical_Line  : Terminal.Port;
                Commit_Buffers : Boolean := True;
                Response       : String  := "<PROFILE>");

 DESCRIPTION

 Terminates any session active on the specified line.

 Uncommitted changes to images are saved if the Commit_Buffers parameter is
 True. The user's background jobs (if any) continue to run, and any
 foreground jobs that do not require interactive input are put in the
 background. Foreground jobs that attempt interactive input are killed.


 PARAMETERS

 Physical_Line : Terminal.Port;

 Specifies that the terminal port is a number from 0 through 255. You can
 determine which port by executing the !Commands.What.Users command.


 Commit_Buffers : Boolean := True;

 Specifies whether uncommitted changes the user has made to any images will
 be committed. When True (the default), the changes are saved.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability, unless the user is logging off one of the user's
 own sessions.


 EXAMPLES

 The command:

   Operator.Force_Logoff (249);

 logs off the user currently on port 249. Any uncommitted changes to images
 are saved.



 @node !Commands.Operator.Get_Archive_On_Shutdown

 function Get_Archive_On_Shutdown return Boolean;

 DESCRIPTION

 Returns a Boolean indicating whether archiving on shutdown has been
 enabled by the Archive_On_Shutdown command.


 PARAMETERS

 return Boolean;

 Specifies, when True, that system shutdown archives object managers.


 REFERENCES

 procedure Archive_On_Shutdown



 @node !Commands.Operator.Get_Login_Limit

 function Get_Login_Limit return Positive;

 DESCRIPTION

 Returns the maximum number of users that can be logged in at one time on a
 machine.

 The maximum number is set by the Limit_Login command.


 PARAMETERS

 return Positive;

 Returns the number of concurrent logins.


 REFERENCES

 procedure Limit_Login



 @node !Commands.Operator.Get_Minimum_Password_Length

 function Get_Minimum_Password_Length return Natural;

 DESCRIPTION

 Returns the minimum number of characters required in a valid password.

 This value is set by the Set_Password_Policy command.


 PARAMETERS

 return Natural;

 Returns the minimum number of characters required in a valid password.


 REFERENCES

 procedure Set_Password_Policy



 @node !Commands.Operator.Get_Password_Deadline

 function Get_Password_Deadline return Days;

 DESCRIPTION

 Returns the number of days that an unchanged password can exist before it
 expires.

 This value is the deadline interval of the current password change
 schedule, which is set by the Set_Password_Policy command.


 PARAMETERS

 return Days;

 Returns the number of days that an unchanged password can exist before it
 expires.


 REFERENCES

 procedure Set_Password_Policy



 @node !Commands.Operator.Get_Password_Warning

 function Get_Password_Warning return Days;

 DESCRIPTION

 Returns the number of days that an unchanged password can exist before the
 user is warned at login to change it.

 This value is the warning interval of the current password change
 schedule, which is set by the Set_Password_Policy command.


 PARAMETERS

 return Days;

 Returns the number of days that an unchanged password can exist before the
 user is warned at login to change it.


 REFERENCES

 procedure Set_Password_Policy



 @node !Commands.Operator.Get_Shutdown_Interval

 function Get_Shutdown_Interval return Duration;

 DESCRIPTION

 Returns the current interval that is used by the Shutdown command.

 The interval is set by the Shutdown_Warning command.


 PARAMETERS

 return Duration;

 Returns the number of seconds between entering the Shutdown command and
 the actual shutting down of the system.


 REFERENCES

 procedure Shutdown
 procedure Shutdown_Warning



 @node !Commands.Operator.Get_User_Deadline

 function Get_User_Deadline
             (For_User : String := System_Utilities.User_Name)
                                                return String;

 DESCRIPTION

 Returns the image of the date (MM/DD/YY) on which the specified user's
 current password is scheduled to expire.

 The value returned by this function can be passed to commands in package
 Time_Utilities to obtain a numeric value.


 PARAMETERS

 For_User : String := System_Utilities.User_Name;

 Specifies the name of the user whose password deadline date is to be
 returned. The default value is the user executing the command.


 return String;

 Returns the image of the date (MM/DD/YY) on which the specified user's
 current password is scheduled to expire.


 REFERENCES

 procedure Set_Password_Policy
 procedure Show_Password_Policy



 @node !Commands.Operator.Get_User_Warning

 function Get_User_Warning
             (For_User : String := System_Utilities.User_Name)
                                                return String;

 DESCRIPTION

 Returns the image of the date (MM/DD/YY) on which the specified user will
 start being warned to change his or her password.

 The value returned by this function can be passed to commands in package
 Time_Utilities to obtain a numeric value.


 PARAMETERS

 For_User : String := System_Utilities.User_Name;

 Specifies the name of the user whose password warning date is to be
 returned. The default value is the user executing the command.


 return String;

 Returns the image of the date (MM/DD/YY) on which the specified user will
 start being warned to change his or her password.


 REFERENCES

 procedure Set_Password_Policy
 procedure Show_Password_Policy



 @node !Commands.Operator.Internal_System_Diagnosis

 procedure Internal_System_Diagnosis;

 DESCRIPTION

 Runs the Environment Elaborator Database (EEDB) from an Environment window
 rather than the operator console.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.



 @node !Commands.Operator.Limit_Login

 procedure Limit_Login (Sessions : Positive := Positive'Last);

 DESCRIPTION

 Sets a limit on the number of concurrent user logins for a machine.


 PARAMETERS

 Sessions : Positive := Positive'Last;

 Specifies the maximum number of logins. The default is Positive'Last.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 EXAMPLES

 The following command limits the number of login sessions to 16:

   Operator.Limit_Login (16);


 @node !Commands.Operator.Privileged_Mode

 function Privileged_Mode return Boolean;

 DESCRIPTION

 Returns a Boolean indicating whether privileged mode is enabled for the
 calling job.


 PARAMETERS

 return Boolean;

 Returns True if privileged mode is enabled, or False if it is disabled,
 for the calling job.



 @node !Commands.Operator.Remove_From_Group

 procedure Remove_From_Group
                     (User     : String := ">>USER NAME<<";
                      Group    : String := ">>GROUP NAME<<";
                      Response : String := "<PROFILE>");

 DESCRIPTION

 Removes one or more usernames from one or more groups.

 To determine whether a username is a member of the group before removing
 it, use the Display_Group command.

 Note that identities are established at login. Removing a user from a
 group will not be effective until the user's next login.


 PARAMETERS

 User : String := ">>USER NAME<<";

 Specifies one or more usernames from one or more groups. The default
 parameter placeholder ">>USER NAME<<" must be replaced or an error will
 result.

 Multiple names can be specified using wildcards, set notation, and indirect
 files.

 When an indirect file containing a list of usernames is specified as the
 ">>USER NAME<<" parameter value, the usernames listed in the indirect file
 are automatically resolved to their proper context. This means that a
 system manager does not have to specify the fully qualified pathname of
 each entry in the file.


 Group : String := ">>GROUP NAME<<";

 Specifies one or more group names from which the username should be
 removed. The default parameter placeholder ">>GROUP NAME<<" must be
 replaced or an error will result. The specified group names must exist
 before this command is executed.

 Multiple groups can be specified using wildcards, set notation, and
 indirect files. The default is the selection, whether or not the cursor is
 in the selection.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.

 This command cannot be used to remove users from their own username
 groups.


 EXAMPLES

 The command:

   Operator.Remove_From_Group (User => "Bill",Group =>
                                              "Engineering");

 removes username Bill from the group called Engineering.


 REFERENCES

 procedure Add_To_Group
 procedure Create_Group
 procedure Create_User
 procedure Display_Group



 @node !Commands.Operator.Set_Password_Policy

 procedure Set_Password_Policy
              (Minimum_Length  : Natural := 0;
               Change_Warning  : Days    := Operator.Days'Last;
               Change_Deadline : Days    := Operator.Days'Last);

 DESCRIPTION

 Sets the systemwide policy for password expiration and length.

 By requiring users to pick passwords of sufficient length and to change
 their passwords with regular frequency, such a policy ensures greater
 system security.

 This command allows you to set a minimum password length, which causes the
 Create_User and Change_Password commands to reject passwords that contain
 fewer than the required number of characters.

 This command also allows you to set a password change schedule, which
 specifies:

 *  The warning interval--the number of days that an unchanged password can
    exist before the user is warned at login to change it.

 *  The deadline interval--the number of days that an unchanged password
    can exist before it expires. (The deadline interval includes the
    warning interval.)

 The warning and deadline intervals for a given password begin when the
 password is created. Each time the password is changed, its "clock" is
 reset and the warning and deadline intervals begin again. For a full
 discussion of password change schedules, see the introduction to this
 package.

 Executing this command puts the specified password policy into effect
 immediately. However, the policy will revert to its default values the
 next time the R1000 boots, unless this command is called during machine
 initialization. It is recommended that you test the desired policy
 before putting it into your initialization procedure. In particular, you
 can set the policy and then use the Show_Password_Policy command to
 ensure that you have not caused the Operator's (or other users') passwords
 to expire immediately.


 PARAMETERS

 Minimum_Length : Natural := 0;

 Specifies the minimum acceptable length for a password. The default, 0,
 allows a user to have no password. Typical values for ensuring security
 are 6 to 10 characters.


 Change_Warning : Days := Operator.Days'Last;

 Specifies the warning interval--the number of days that an unchanged
 password can exist before the user is warned at login to change it. The
 warning interval for a given password begins on the day the password was
 created or last changed. The warning interval ends at midnight after the
 specified number of days. At this point, the user receives a warning
 message each time he or she logs in before the password expires. (Thus,
 the number of days of warning is determined by subtracting the value of
 the Change_Warning parameter from the value of the Change_Deadline
 parameter.)


 Change_Deadline : Days := Operator.Days'Last;

 Specifies the deadline interval--the number of days that an unchanged
 password can exist before it expires. The deadline interval for a given
 password begins on the same day as the warning interval--namely, the day
 the password was created or last changed. The deadline interval ends at
 midnight after the specified number of days. When a user's password
 expires, he or she will not be able to log in without obtaining a new
 password. New passwords typically are obtained from the system manager,
 although any user who knows either the expired password or
 the Operator's password can set the new password (see the Change_Password
 command).


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 REFERENCES

 procedure Change_Password
 procedure Create_User
 procedure Show_Password_Policy



 @node !Commands.Operator.Set_System_Time

 procedure Set_System_Time (To_Be    : String := ">>TIME<<";
                            Response : String := "<PROFILE>");

 DESCRIPTION

 Resets the system clock--for example, for changing to or from
 daylight-saving time.

 Because the system clock has an independent power supply (a battery),
 there is no need to reset the clock if the system is powered down.


 PARAMETERS

 To_Be : String := ">>TIME<<";

 Specifies a date, time, or combination of date and time expressed in one of
 the formats listed below. The To_Be parameter consists of 2 through 6
 two-digit numbers delimited by nonnumeric characters. The default
 parameter placeholder ">>TIME<<" must be replaced or an error will result.

 In general, the numbers can be interpreted, because each component of a
 date or time has its own range (for example, 85 is always interpreted as a
 year, because it cannot be anything else).

 In the following examples of allowable times, YY expresses a year, MM
 expresses a month, DD expresses a day, HH expresses an hour, mm expresses
 minutes, and SS expresses seconds:

                  YY/MM/DD HH:mm:SS      MM/DD HH:mm:SS
                  MM/DD/YY HH:mm:SS      MM/DD HH:mm
                  MM/DD/19YY HH:mm:SS    YY/MM/DD
                  YY/MM/DD HH:mm         MM/DD/YY
                  MM/DD/YY HH:mm         HH:mm:SS
                                         HH:mm

 Other allowable time and date formats are described in the Programming
 Tools (PT) book, Time_Utilities.Time_Format and Time_Utilities.Date_Format
 types.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 EXAMPLES

 The command:

   Operator.Set_System_Time ("15:00");

 sets the time to 3:00 P.M. today.

 The command:

   Operator.Set_System_Time ("11/10/91");

 changes the date to November 10, 1991, without changing the time.



 @node !Commands.Operator.Show_Login_Limit

 procedure Show_Login_Limit;

 DESCRIPTION

 Displays the maximum number of concurrent logins on the current output.

 The maximum number of logins can be set by the Limit_Login command.


 EXAMPLES

 The command:

   Operator.Show_Login_Limit;

 displays the following when the login limit is 16:

   It is currently possible for 16 users to be logged in
         

 REFERENCES

 procedure Limit_Login



 @node !Commands.Operator.Show_Password_Policy

 procedure Show_Password_Policy
              (For_User : String := System_Utilities.User_Name);

 DESCRIPTION

 Displays the current password policy, along with the warning and deadline
 dates for the specified user's password.

 The dates are given in the form MM/DD/YY. The warning date is the date on
 which the user will first be notified to change his or her password. The
 deadline date is the date on which the user's unchanged password will
 expire.

 It is recommended that you use this command after setting a new password
 change schedule to determine whether the new schedule has invalidated any
 existing passwords.


 PARAMETERS

 For_User : String := System_Utilities.User_Name;

 Specifies the users for which warning and deadline dates are to be
 displayed. Wildcards can be used to specify more than one user. For
 example, "@" specifies all users on the system. If no password change
 schedule has been set, the For_User parameter is ignored. The default
 value is the user executing the command.


 EXAMPLES

 Assume that user Anderson wants to know the current password policy and
 how it affects his password. To do this, he enters the following command:

   Operator.Show_Password_Policy;

 As a result, a report like the following is displayed:

   Password change warnings are issued after 46 days
   Passwords must be changed every 60 days

   User      Warning   Deadline
   ----      -------   --------
   Anderson  8/12/91    8/26/91
   

 REFERENCES

 procedure Set_Password_Policy



 @node !Commands.Operator.Show_Shutdown_Settings

 procedure Show_Shutdown_Settings;

 DESCRIPTION

 Displays the shutdown settings on the current output.

 Shutdown settings are set by the Shutdown_Warning and Archive_On_Shutdown
 commands.


 EXAMPLES

 The command:

   Operator.Show_Shutdown_Settings;

 produces a message such as the following on the current output:

   Shutdown Interval is 01:00:00; Archive_Enabled = False
   

 REFERENCES

 procedure Archive_On_Shutdown
 procedure Shutdown_Warning



 @node !Commands.Operator.Shutdown

 procedure Shutdown (Reason      : String := "COPS";
                     Explanation : String := "Cause not entered");

 DESCRIPTION

 Shuts down the system after the interval set by the Shutdown_Warning
 command has passed.

 The shutdown cause is specified by the Reason parameter, and the
 explanation is specified by the Explanation parameter. This information is
 entered into the machine's error log.

 The Shutdown command issues several warnings to users. The first warning
 occurs when the command is executed, the next occurs after 3/4 of the
 interval has passed, the next occurs when 3/4 of the remaining time has
 passed, and so on, until the system is shut down. Note that a warning
 interval of 30 seconds or less results in immediate shutdown.

 When the system is shut down, users are logged off, all terminal lines are
 disabled, and a snapshot is taken to preserve the Environment state.


 PARAMETERS

 Reason : String := "COPS";

 Specifies a reason for shutting down the machine. The default, "COPS",
 specifies a customer shutdown. The shutdown does not occur unless the
 reason is valid. The value "?" for this parameter gives a list of valid
 reasons and does not perform the shutdown. The cause is entered into the
 machine's error log.

 Along with COPS, the following reasons are valid: Crash, Hang, Maint,
 Other, and Release. Other codes (CSD, HWC, PMH, PMS, SWC, and UCC) that
 were previously documented in the System Manager's Guide are no longer
 valid.


 Explanation : String := "Cause not entered";

 Specifies an explanation to be entered into the machine's error log. The
 default, "Cause not entered", should be replaced.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.

 The following reason codes are not valid: CSD, HWC, PMH, PMS, SWC, and
 UCC.


 REFERENCES

 procedure Cancel_Shutdown
 procedure Explain_Crash
 procedure Shutdown_Warning



 @node !Commands.Operator.Shutdown_Warning

 procedure Shutdown_Warning (Interval : Duration := 3600.0);

 DESCRIPTION

 Sets the interval between the time the Shutdown command is executed and
 the time the system actually shuts down.

 The Interval parameter also determines when the shutdown warning messages
 are issued. The first message is sent at the beginning of the interval, the
 second is sent after 3/4 of the interval has passed, and so on, until the
 system shuts down.


 PARAMETERS

 Interval : Duration := 3600.0;

 Specifies that the default for the interval is 3,600 seconds, or 1 hour.
 The Interval parameter is rounded to the nearest minute. Less than 1
 minute is rounded to 0.


 RESTRICTIONS

 Execution of this command requires that the user or the executing job have
 operator capability.


 EXAMPLES

 The command:

   Operator.Shutdown_Warning (1800.0);

 sets the interval to 30 minutes. The next time the Shutdown command is
 executed, 30 minutes will pass before the system actually shuts down.



 @node !Commands.Queue

 Package Queue contains commands for printing files and Ada source code, for
 displaying outstanding print requests, and for creating and managing print
 queues.

 You can use package Queue commands directly to configure printers at your
 site. Or you can use the machine-initialization file-driven method. This
 method:

 *  Calls procedures from package Queue to create print queues
    automatically whenever the machine boots.

 *  Enables you to submit print requests to printers that are connected to
    other systems on the same network. (You do this with
    !Commands.Abbreviations.Print instead of Queue.Print.)

 *  Enables you to query the print queues on other systems on the same
    network. (You do this with !Commands.Abbreviations.Display_Queue
    instead of Queue.Display.)

 For more information on implementing the file-driven method, see the online
 documentation in the !Machine.Initialization world.


 RESOURCES IN PACKAGE QUEUE

 The commands in package Queue fall into several functional groups. Types
 and constants are not included in this list.

 Printing files:                      Print, Print_Version

 Displaying print-queue information:  Classes, Devices, Display

 Aborting print operations:           Cancel

 Managing print queues directly:      Add, Create, Default, Destroy, Enable,
                                      Register, Remove

 Reinitializing the print spooler:    Kill_Print_Spooler,
                                      Restart_Print_Spooler


 OVERVIEW OF THE PRINT PROCESS

 You use the Print command to submit one or more objects for printing; the
 Print_Version command allows you to specify a particular version of the
 object for printing.

 When you submit a print request:

 *  A copy of the object to be printed is formatted as specified through the
    various options provided by this package and is then submitted to the
    print spooler.

 *  The print spooler queues the object to the class specified by the user
    in the print request. (A class is a logical grouping of sequential
    print requests that allows these requests to be handled as a set.)

 *  Because each class is typically associated or registered with at least
    one device, the class to which an object is submitted determines the
    device that will handle the print request. A device can be a physical
    device (such as a printer) or a logical device (such as a file).

 *  If the designated device is enabled, the submitted object is printed.
    If the device is disabled, the submitted object remains queued until
    the device is enabled (or the class is reregistered with some other
    enabled device).


 Printer Classes

 The print spooler maintains the relationships among printer classes and
 devices. Users with operator capability can use the Create command to
 create any number of classes for queuing print requests.

 For example, one class can be designated for long batch jobs and another
 class for short urgent jobs, and each of these classes can be associated
 with its own device. Similarly, a separate class can be assigned to each
 user group or department so that requests from certain groups can be
 routed to specific devices, suspended, or given preference as needed.

 A single device can have any number of classes registered with it--for
 example, when several departments use the same printer. Furthermore, a
 single class can be registered with up to six devices. A print request
 submitted to such a class is routed to the first available device.


 Print Queues

 The term print queue refers to any predefined printer class that is
 associated with a particular device. Print requests are queued to a
 printer class as a sequential list, where they wait to be handled by
 the associated device.

 Print queues are created and managed either by using commands from package
 Queue directly or by editing a file called Printer_Configuration in the
 !Machine.Initialization.[Site,Local] worlds.

 Following is the general process for creating print queues using commands
 from package Queue:

 1. Ensure that the print spooler is running (using the
    Restart_Print_Spooler command).

 2. Define a class with the specified name (using the Create command).

 3. Add a device with the specified name (using the Add command).

 4. Associate the class with a device (using the Register command).

 5. Define a default class with the specified name (using the Default
    command).

 6. Make the device available for use (using the Enable command).


 Operator Capability Required for Some Commands

 Certain package Queue commands require that the executing job have
 operator capability. These commands include: Add, Create, Destroy,
 Disable, Enable, Kill_Print_Spooler, Register, Remove,
 Restart_Print_Spooler, and Unregister.


 KEY CONCEPTS FOR PRINTING TEXT

 You can use Print and Print_Version to queue print requests to one of two
 main types of device:

 *  An ASCII device (such as a line printer)

 *  A PostScript device (such as a laser printer)

 Depending on the device you choose and the contents of the file to be
 printed, the Print or Print_Version command may preprocess the file's
 contents before sending it to the device. Preprocessing includes:

 *  Making a print spooler copy of the file

    This means copying the contents of the file directly into the print
    spooler for printing.

 *  Modifying the copy to control various aspects of formatting and
    printing

 Preprocessing is optional for input files queued to an ASCII device. If
 desired, you can request the Print command to modify the input to wrap
 lines, number pages and/or lines, and change the length and width of the
 output pages. Without preprocessing, text is printed exactly as it
 appears in the input file.

 Some amount of preprocessing is normally required for input files queued to
 a PostScript device. PostScript preprocessing ensures that the required
 PostScript instructions are present to drive the device and optionally
 adds instructions to provide header pages, the print date, and filename;
 change the font; change the page orientation; print two up (print two
 logical pages on a single sheet of paper); and so forth.


 Printing Using an ASCII Device

 By default, the Print and Print_Version commands:

 *  Print the user's name on a separate banner page

 *  Print the object name

 *  Print the page number on each page

 *  Wrap lines longer than 80 characters

 You can override these defaults by using the Raw, Original_Raw, or Format
 options. These options permit a user to specify a different banner,
 headers, line length, and other format characteristics. These options are
 described in greater detail below.


 Printing Text with No Additional Formatting

 If you only want to print the text as it appears in the file with no
 additional formatting, you specify either the Raw or Original_Raw
 option. For example, to print preformatted text or binary data, you can
 specify: Options => "Raw". The difference between Raw and Original_Raw
 is:

 *  The Raw option queues a temporary print-spooler copy of the file with no
    preprocessing.

 *  The Original_Raw option is like Raw, except that Original_Raw prints
    directly from the original file, without using disk space to make a
    temporary copy. This option is for use on machines with low disk space.


 Printing Text with Basic Formatting

 If you want to print the text with any kind of basic formatting, you
 specify the Format option with the appropriate suboptions. For example, to
 print a text file with wrapped lines and page numbers, you specify:

   Options => "Format=(Wrap, System_Header)"

 The suboptions of the Format option are shown in Table 1.


                        Table 1   Format Suboptions
               -------------------------------------------- 
              |        |                                   |
              |Suboptio|Effect on Text Format              |
              |n       |                                   |
               -------------------------------------------- 
              |        |                                   |
              |Length  |Specifies total number of printed  |
              |        |lines per page.                    |
               -------------------------------------------- 
              |        |                                   |
              |Numberin|Provides line numbering.           |
              |g       |                                   |
               -------------------------------------------- 
              |        |                                   |
              |System_ |Prints the object name and page    |
              |Header  |number on each page.               |
               -------------------------------------------- 
              |        |                                   |
              |Tab_    |Specifies the number of spaces to  |
              |Width   |use for Tab character.             |
               -------------------------------------------- 
              |        |                                   |
              |Truncate|Truncates lines that are longer    |
              |        |than Width.                        |
               -------------------------------------------- 
              |        |                                   |
              |Width   |Specifies the maximum number of    |
              |        |printable characters per line.     |
               -------------------------------------------- 
              |        |                                   |
              |Wrap    |Wraps lines that are longer than   |
              |        |Width.                             |
               -------------------------------------------- 




 Printing Using a PostScript Device

 If you queue a print request to a PostScript device (such as a laser
 printer), you must specify the Postscript option to request PostScript
 preprocessing. Preprocessing means wrapping some amount of PostScript
 code around the text in the input file. Different code is required,
 depending on the format of the text in the file. The Postscript option
 itself accepts a number of suboptions that specify the amount and kind of
 preprocessing to be done.

 You can request preprocessing for any of five basic text formats by
 specifying the Format suboption of the Postscript option. By default, the
 Format suboption is set so that the Print command automatically chooses
 the appropriate preprocessing, based on the contents of the file.


 Printing a PostScript Program

 If you want to print a PostScript program, request preprocessing for
 PostScript format. A PostScript program is:

 *  A file that is generated by a document-formatting program (for example,
    the Rational Document Formatter)

 *  A file that is generated by a graphics application that produces
    encapsulated PostScript

 Preprocessing for PostScript format allows the PostScript program to be
 executed as expected. Additional preprocessing instructions can be
 specified using suboptions. For example, to print a PostScript file two up
 (two pages per sheet of paper), you specify:

   Options => "Postscript=(Format=Postscript, Twoup)"

 By default, a file containing a PostScript program is printed one up in
 portrait mode, without a date, filename, or outline box around the pages.

 The suboptions of the Postscript option are shown in Table 2.

                      Table 2   Postscript Suboptions
                 ---------------------------------------- 
                |      |                                 |
                |Subopt|Effect on Text Format            |
                |ion   |                                 |
                 ---------------------------------------- 
                |      |                                 |
                |Chatty|Generates a message as each of   |
                |      |multiple files is processed.     |
                 ---------------------------------------- 
                |      |                                 |
                |Date  |Prints the time and date of      |
                |      |queuing on each page.            |
                 ---------------------------------------- 
                |      |                                 |
                |Filena|Prints the filename on each page.|
                |me    |                                 |
                 ---------------------------------------- 
                |      |                                 |
                |Flow  |Prints two up with no gap between|
                |      |consecutive files.               |
                 ---------------------------------------- 
                |      |                                 |
                |Font  |Specifies typeface to be used.   |
                 ---------------------------------------- 
                |      |                                 |
                |Header|Prints a header page that        |
                |      |identifies job.                  |
                 ---------------------------------------- 
                |      |                                 |
                |Outlin|Draws a solid box outline around |
                |es    |each page.                       |
                 ---------------------------------------- 
                |      |                                 |
                |Pages |Specifies the pages to be printed|
                 ---------------------------------------- 
                |      |                                 |
                |Revers|Reverses the order in which pages|
                |ed    |are printed.                     |
                 ---------------------------------------- 
                |      |                                 |
                |Stats |Includes statistics about file   |
                |      |size and print speed in messages.|
                 ---------------------------------------- 
                |      |                                 |
                |Twoup |Prints two pages per sheet of    |
                |      |paper.                           |
                 ---------------------------------------- 
                |      |                                 |
                |Wide  |Prints logical pages in landscape|
                |      |mode.                            |
                 ---------------------------------------- 




 Printing Plain Text from a PostScript Printer

 If you want to print a file from a PostScript printer that contains plain
 text with no PostScript instructions, request preprocessing using the
 Plain_Text print-control formatting option.

 Preprocessing for Plain_Text format allows the text to be printed as it
 appears in the file. By default, additional preprocessing instructions are
 given so that pages are printed two up, an outline box appears around each
 page, the date and filename are printed on each page, pages are numbered,
 and lines are wrapped instead of truncated.

 You can specify additional preprocessing instructions or override the
 defaults using suboptions. For example, to print a Plain_Text format file
 one up with a header page, you specify:

   Options => "Postscript=(Format=Plain_Text, ~Twoup, Header)"

 Plain_Text format suboptions are shown in Table 3.

                      Table 3   Plain_Text Suboptions
                 ---------------------------------------- 
                |      |                                 |
                |Subopt|Effect on Text Format            |
                |ion   |                                 |
                 ---------------------------------------- 
                |      |                                 |
                |Chatty|Generates a message as each of   |
                |      |multiple files is processed.     |
                 ---------------------------------------- 
                |      |                                 |
                |Chop  |Truncates lines at the boundaries|
                |      |of the print area.               |
                 ---------------------------------------- 
                |      |                                 |
                |Date  |Prints the time and date of      |
                |      |queuing on each page.            |
                 ---------------------------------------- 
                |      |                                 |
                |Filena|Prints the filename on each page.|
                |me    |                                 |
                 ---------------------------------------- 
                |      |                                 |
                |Flow  |Prints two up with no gap between|
                |      |consecutive files.               |
                 ---------------------------------------- 
                |      |                                 |
                |Font  |Specifies typeface to be used.   |
                 ---------------------------------------- 
                |      |                                 |
                |Header|Prints a header page that        |
                |      |identifies job.                  |
                 ---------------------------------------- 
                |      |                                 |
                |Number|Prints a page number on each     |
                |      |page.                            |
                 ---------------------------------------- 
                |      |                                 |
                |Outlin|Draws a solid box outline around |
                |es    |each page.                       |
                 ---------------------------------------- 
                |      |                                 |
                |Pages |Specifies the pages to be printed|
                 ---------------------------------------- 
                |      |                                 |
                |Revers|Reverses the order in which pages|
                |ed    |are printed.                     |
                 ---------------------------------------- 
                |      |                                 |
                |Rules |Draws faint, dashed lines on     |
                |      |every other line of output.      |
                 ---------------------------------------- 
                |      |                                 |
                |Size  |Specifies the point size of the  |
                |      |type.                            |
                 ---------------------------------------- 
                |      |                                 |
                |Spacin|Combines with Size to specify    |
                |g     |vertical spacing of each line.   |
                 ---------------------------------------- 
                |      |                                 |
                |Stats |Includes statistics about file   |
                |      |size and print speed in messages.|
                 ---------------------------------------- 
                |      |                                 |
                |Twoup |Prints two pages per sheet of    |
                |      |paper.                           |
                 ---------------------------------------- 
                |      |                                 |
                |Wide  |Prints logical pages in landscape|
                |      |mode.                            |
                 ---------------------------------------- 




 Printing Ada Source Code

 If you want a hard copy of Ada source, request preprocessing for Fancy
 format. For example:

   Options => "Postscript=(Format=Fancy)"

 When Fancy format is used, the input object must be either a syntactically
 correct Ada unit or a file that contains the text of a syntactically
 correct Ada unit.

 Preprocessing for Fancy format causes Ada reserved words to be printed in
 a bold typeface and comments to be italicized. Otherwise, the Fancy format
 is preprocessed the same as Plain_Text, so that pages are printed two
 up, an outline box appears around each page, and so forth.

 You can specify additional preprocessing instructions or override the
 defaults using the suboptions listed for Plain_Text format.


 Printing a Letter

 If you want to print a letter or other correspondence that does not
 contain PostScript instructions, request preprocessing for Letter
 format. For example:

   Options => "Postscript=(Format=Letter)"

 Preprocessing for Letter format is similar to Plain_Text in that it allows
 the text to be printed as it appears in the file. However, the default
 preprocessing instructions are different, so that pages of a letter are
 printed one up without an outline box, date, filename, or page number on
 each page.

 You can specify additional preprocessing instructions or override the
 defaults using the suboptions listed for Plain_Text format.


 Printing a Bitmapped Image

 If you want to print a file that contains a bitmapped image, request
 preprocessing for the Image format. For example:

   Options => "Postscript=(Format=Image)"

 The bitmapped image is assumed to be of the form described in the "Format
 of a Bitmapped Image" subsection, below.

 You can specify additional preprocessing instructions when specifying the
 Image option by using the suboptions shown in Table 4.

                         Table 4   Image Suboptions
             ----------------------------------------------- 
            |      |                                        |
            |Subopt|Effect on Text Format                   |
            |ion   |                                        |
             ----------------------------------------------- 
            |      |                                        |
            |Aspect|Specifies the aspect ratio of the image.|
             ----------------------------------------------- 
            |      |                                        |
            |Captio|Specifies text to be printed below the  |
            |n     |image.                                  |
             ----------------------------------------------- 
            |      |                                        |
            |Chatty|Generates a message as each of multiple |
            |      |files is processed.                     |
             ----------------------------------------------- 
            |      |                                        |
            |Distor|Magnifies the image to fill the box     |
            |t     |defined by Width and Height.            |
             ----------------------------------------------- 
            |      |                                        |
            |Dx,Dy |Specifies the offset from the previous  |
            |      |image coordinate to the coordinate for  |
            |      |the next image.                         |
             ----------------------------------------------- 
            |      |                                        |
            |Epilog|Specifies PostScript code to be sent to |
            |      |the printer after the image is printed. |
             ----------------------------------------------- 
            |      |                                        |
            |Height|Specifies the maximum height for the    |
            |      |image.                                  |
             ----------------------------------------------- 
            |      |                                        |
            |Prolog|Specifies PostScript code to be sent to |
            |      |the printer before the image is printed.|
             ----------------------------------------------- 
            |      |                                        |
            |Wide  |Prints logical pages in landscape mode. |
             ----------------------------------------------- 
            |      |                                        |
            |Width |Specifies the maximum width for the     |
            |      |image.                                  |
             ----------------------------------------------- 
            |      |                                        |
            |X,Y   |Specifies coordinates of the first of   |
            |      |multiple images.                        |
             ----------------------------------------------- 




 Format of a Bitmapped Image

 When the Image option is specified, the Print or Print_Version command
 assumes that the input file contains a bitmapped image in the following
 format:

 *  An initial Ascii.Nul character.

 *  A short header. The header contains six 4-byte (8 bits per byte) fields
    in the following order:

    -  Width: number of pixels in one row of the image.

    -  Height: number of rows in the image.

    -  Depth: number of bits of grayscale per pixel. This value can be only
       1 or 4.

    -  Ax: Ax/Ay defines the aspect ratio width to height of each pixel. If
       the image is to be rendered at Xf pixels per inch horizontally, its
       height will be scaled
       Xf * (Ay/Ax) pixels per inch vertically.

    -  Ay: See description of Ax.

    -  Filler: must be zero.

 *  Grayscale information for the image.

    Grayscale information starts with the pixel data for the pixel in the
    upper-left corner of the image. Additional pixel data is presented row
    by row, left to right. Pixel data is packed eight or two pixels per
    byte, depending on the Depth specified. Each row must start on a byte
    boundary. Thus, "padding" must be added if Width multiplied by Depth is
    not a multiple of 8.


 Additional PostScript Printing Capabilities

 When printing a PostScript format file on a PostScript device--that is,
 when Options => "Postscript=(Format=Postscript)"--the Print command will
 recognize the following instructions embedded in the input file:

 %%ASCII naming expression

 This instruction specifies one or more files to be printed without further
 interpretation by PostScript. Any PostScript commands within the named
 files are ignored. The version of PostScript supported through this
 option is Adobe 1.0.

 %%BINARY naming expression

 This instruction specifies one or more files to be printed as strings of
 hexadecimal numbers. The %%BINARY command should be preceded by PostScript
 code that will prepare the printer to receive hexadecimal output. The
 version of PostScript supported through this option is Adobe 1.0.

 When printing a file of any format except Image on a PostScript
 device--that is, when the input file is of Postscript, Plain_Text, Letter,
 or Fancy format--the Print command will recognize the following
 instruction embedded in the input file:

 %%INCLUDE naming expression

 This instruction specifies one or more files to be opened and processed as
 if they were part of the input file. The named files can contain %%INCLUDE
 commands, which can be nested as many as ten levels deep. The version of
 PostScript supported through this option is Adobe 1.0.


 Specifying Default Format Options

 You can specify a default format for printed text by setting the
 Queue.Banner, Queue.Footer, Queue.Header, and Queue.Options session
 switches. The values of these switches are used when the Print and
 Print_Version commands have default values for the Banner, Footer, Header,
 and Options parameters, respectively. Setting these switches eliminates
 the need to reenter an often-used option or series of options directly
 into the Print or Print_Version commands.

   PROCESSOR  SWITCH    TYPE             VALUE
   ---------------------------------------------------------------------
   . . .
   Queue . Banner      : String         := "<user_id>"
   . . .
   Queue . Footer      : String         := ""
   . . .
   Queue . Header      : String         := ""
   . . .
   Queue . Options     : String         := "Format=>(Wrap, System_Header)"
   . . .

 If the Print or Print_Version command is used to print text files or Ada
 source from an ASCII device, all four session switches can be used to
 control the default output. If the text or Ada source is printed from a
 PostScript printer, only the Queue.Options session switch applies. These
 differences are discussed in separate sections below.


 Default Formatting for ASCII Devices

 If you enter the Print or Print_Version command to submit a print request
 to an ASCII device, and you use default parameter values, the command will
 take its basic formatting information from the Queue.Banner, Queue.Footer,
 Queue.Header, and Queue.Options session switches. In the standard
 Environment, these switches will cause the specified file or Ada image to be
 printed with:

 *  A banner showing the username

 *  No footer

 *  No header

 *  Wrapped lines and page numbers

 You can specify any banner, footer, and header text to the first three of
 these session switches. You can also set the Queue.Options session
 switch to be any valid option string that uses any of the suboptions shown
 in Table 1.


 Default Formatting for PostScript Devices

 You can use the Queue.Options session switch to specify a valid option
 string that uses any of the Postscript suboptions given in Tables 2, 3,
 and 4.

 For example, when the Queue.Options session switch is set as shown below,
 the Print command with a default Options parameter prints a text file or
 Ada image two up (two pages per sheet) from a PostScript printer:

   Queue.Options : String:=  Options => "PostScript=(Format=PostScript,
   Twoup)"


 @node !Commands.Queue.Add

 procedure Add (Device  : String := "";
                Options : String := "XON_XOFF");

 DESCRIPTION

 Adds a device to the system with the specified device name.

 This command allows you to add a device and to specify the kind of
 protocol required between print jobs (if any). Devices must be added
 before they can be registered using the Register command.


 PARAMETERS

 Device : String := "";

 Specifies the device by physical line number. The line number takes the
 form Terminal_N, where N is the number of the port through which the
 device communicates to the R1000.

 When the Ftp option is specified, the Device parameter must be the name of
 an Environment file; see the Ftp option, below. It is recommended that you
 put the device file in the !Machine.Queues.Ftp library.


 Options : String := "XON_XOFF";

 Specifies the type of protocol required by the device being added. The
 default is XON_XOFF.

 The following list summarizes the options accepted by the Add command. De-
 scriptions of each option are given after this list:

                Dtr           Ftp     Host
                Laser_Comm    Rts     Socket
                Xon_Xoff


 *  Dtr

    Not implemented; reserved for future development.


 *  Ftp

    A Boolean option. When True, specifies that print requests be sent using
    FTP to the directory and machine referenced by the device. Each print
    request is sent as a separate file. Once the files are on the other
    machine, you can use that machine's print commands or tools to print
    the files.

    When you specify the Ftp option, you must also specify the Device
    parameter with the name of an R1000 file that contains, on separate
    lines, the network name of the destination machine, the full pathname
    of the destination directory, a suffix to be appended to the filename
    (leave a blank line if no suffix is to be appended), and the pathname of
    an Environment remote-passwords file.

    The destination machine can be any computer system, typically a
    workstation.

    The directory pathname must have syntax appropriate to the destination
    machine and must have trailing punctuation that permits the name of
    the transferred print-request file to be appended.

    The specified suffix can be used by print tools to identify which files to
    print. (This is useful when several devices send files to the same
    directory.)

    The remote-passwords file must contain a username and password suitable
    for accessing the destination machine. It is recommended that you put
    the remote-passwords file in the !Machine.Queues.Ftp library. (See the
    Session and Job Management (SJM) book, package Remote_Passwords.)

    Only one of the following options can be specified for a given device:
    Ftp, Host, Rts, or Xon_Xoff.


 *  Host=>device name

    Specifies that a Telnet connection is to be formed with device name for
    each print request. This connection has standard flow control
    (XON_XOFF) and is broken after the request has been processed. Device
    name is the network's name for the device (as known by the
    Transport_Name_Map or the Name_Server).

    You can use the Socket option to specify a socket other than the TCP/IP
    default. If the Socket option is omitted, the standard TCP/IP socket
    (0,23) is used.

    Only one of the following options can be specified for a given device:
    Ftp, Host, Rts, or Xon_Xoff.


 *  Laser_Comm

    A Boolean option. When True, specifies that the device is a PostScript
    printer. To determine whether your printer requires this option, see
    the manual for your printer.


 *  Rts

    A Boolean option. When True, specifies standard flow control (XON_XOFF)
    with RTS protocol used between print requests.

    This option resolves contention problems when two machines share a
    common device.

    Only one of the following options can be specified for a given device:
    Ftp, Host, Rts, or Xon_Xoff.


 *  Socket=>socket number

    Specifies the socket through which the Telnet connection should be made
    through the Host option. For example:

    "host=>lab_print,socket=>(5,10)"

    If the Host option is specified and the Socket option is omitted, the
    standard TCP/IP socket (0,23) is used. The Socket option is ignored if
    the Host option has not been specified.


 *  Xon_Xoff

    A Boolean option. When True, specifies standard flow control (XON_XOFF)
    as the communications protocol.

    Only one of the following options can be specified for a given device:
    Ftp, Host, Rts, or Xon_Xoff.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Queue.Add ("terminal_21");

 adds a line printer called Terminal_21, using XON_XOFF protocol.

 The command:

   Queue.Add
       (Device  => "terminal_255",
        Options => "laser_comm,host=>mktg_laser,socket=>(0,24)");

 adds a Telnet device called Terminal_255, which is a laser printer.


 REFERENCES

 procedure Enable
 procedure Register
 procedure Remove



 @node !Commands.Queue.All_Classes

 All_Classes : constant Class_Name := "all";

 DESCRIPTION

 Defines a constant that represents all defined classes.



 @node !Commands.Queue.All_Spooler_Devices

 All_Spooler_Devices : constant String := "all";

 DESCRIPTION

 Defines a constant that represents all devices registered with at least one
 class.

                                                                           

 @node !Commands.Queue.Cancel

 procedure Cancel (Request_Id : Positive);

 DESCRIPTION

 Cancels the specified print request.

 This command cancels requests whether or not those requests have started
 to print. The value of the Request_Id parameter can be obtained with the
 Display command.

 Although the cancel request will complete quickly, the actual canceling
 can take several minutes before the print spooler removes/terminates the
 request.


 PARAMETERS

 Request_Id : Positive;

 Specifies the number assigned to the print request.


 REFERENCES

 procedure Display



 @node !Commands.Queue.Classes

 procedure Classes (Which        : Class_Name := "all";
                    Show_Devices : Boolean    := True);

 DESCRIPTION

 Displays information about the specified classes.


 PARAMETERS

 Which : Class_Name := "all";

 Specifies the class for which information is requested. The default is all
 classes. Users on installations that use Rational Networking--TCP/IP to
 connect multiple R1000 systems can query other machines on the network.
 Thus, the name can specify a machine name of the form !!Machine_Name,
 where Machine_Name is the name of a machine--for example, !!M1.


 Show_Devices : Boolean := True;

 Specifies whether to display information on devices as well as on classes.
 The default is True.


 EXAMPLES

 The command:

   Queue.Classes;

 produces a display such as the following:

   Class    Device(s)
   ======  ============
   DAISY   TERMINAL_252
   MLASER  TERMINAL_253
   APPLE   TERMINAL_250
   LP      TERMINAL_251
   QMS     TERMINAL_254

 This display shows that classes are associated with PostScript printers
 using Telnet ports in the range 250 . . 255.



 @node !Commands.Queue.Class_Name

 subtype Class_Name is String;

 DESCRIPTION

 Defines the form of a name assigned to a given set of devices.

 Any class name that you enter is converted to uppercase.

 This subtype can contain the name of a machine, using the format
 !!Machine_Name, where Machine_Name is the name of another machine on the
 same network. For example, !!M1.LP is the class LP on machine M1.

 The remote machine name can be used only to query and print on remote ma-
 chines. It cannot be used to change the configuration of the print spooler
 on remote machines.



 @node !Commands.Queue.Create

 procedure Create (Class : Class_Name := "");

 DESCRIPTION

 Creates a class with the specified name.


 PARAMETERS

 Class : Class_Name := "";

 Specifies the case-insensitive name for the class being created. The
 default is no name. You cannot use a remote machine name to create a class
 on a remote machine.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Queue.Create ("laser");

 creates a class called Laser.


 REFERENCES

 procedure Destroy
 procedure Register



 @node !Commands.Queue.Default

 procedure Default (Class : Class_Name := "");

 DESCRIPTION

 Specifies a new default class for all Environment print requests.

 The command sets the default class to the specified class and prints a
 message in the message window. If the default parameter value is used, the
 command simply prints the name of the current default class in the message
 window.

 The class must exist before it can be made the default class. Use the
 Create command to create classes.

 You can also assign a remote class as the default class, so that the
 default causes jobs to be queued on a remote machine.


 PARAMETERS

 Class : Class_Name := "";

 Specifies a new default name. If the default value is used, the only effect
 of this command is to display the current default class. For example,
 executing:

   Queue.Default (Class => "");

 produces a message in an Environment output window similar to:

   The default class is "<printer class>".

 where printer class is the name of the default class for the current
 system.

 Users on installations that use Rational Networking--TCP/IP to connect
 multiple R1000 systems can specify other machines on the network. Thus a
 remote machine name can be specified to set the default (for the current
 R1000) to be a remote class. This remote class name can be specified or, if
 omitted, allowed to default to the default class on the remote R1000. For
 example, the command:

   Queue.Default ("!!M1.newclass");

 specifies Newclass, on an R1000 named M1, as the default class for all
 local print requests. The command:

   Queue.Default ("!!M1");

 specifies the default class for a remote R1000 named M1 to be the default
 class for the current system.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability. Other users can execute this command to display the default
 class in the message window.


 REFERENCES

 procedure Create



 @node !Commands.Queue.Destroy

 procedure Destroy (Class   : Class_Name := "";
                    Reroute : Class_Name := "");

 DESCRIPTION

 Removes the specified class and routes existing requests for that class to
 another class.


 PARAMETERS

 Class : Class_Name := "";

 Specifies the name of the class to be removed. The default is no name.


 Reroute : Class_Name := "";

 Specifies a class for routing. Print requests spooled to the removed class
 are routed to this class. The default is to route requests to the default
 class. A remote machine name cannot be specified to destroy a class on a
 remote machine.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Queue.Destroy ("lp","newclass");

 removes LP from the list of active classes and routes all requests for LP
 to Newclass.

 The command:

   Queue.Destroy ("lpr3");

 removes LPR3 from the list of active classes and routes all requests for
 LPR3 to the default class.


 REFERENCES

 procedure Create
 procedure Unregister



 @node !Commands.Queue.Devices

 procedure Devices (Which        : String  := "all";
                    Show_State   : Boolean := True;
                    Show_Classes : Boolean := True);

 DESCRIPTION

 Displays information about the specified devices.


 PARAMETERS

 Which : String := "all";

 Specifies the device for which information is requested. The default is to
 show information about all devices. A remote machine name can be specified.


 Show_State : Boolean := True;

 Requests information on the current state of the devices, whether enabled
 or disabled. The default is True.


 Show_Classes : Boolean := True;

 Specifies whether to display information on classes associated with the
 displayed devices. The default is True.


 EXAMPLES

 The command:

   Queue.Devices;

 produces a listing such as the following:


 Device       Protocol                  Characteristics  State     Classes
 ============ ========================= ===============  ========  =======
 TERMINAL_40  XON_XOFF                  Laser_Comm       Disabled  (none)
 TERMINAL_32  RTS                                        Disabled  (none)
 TERMINAL_255 TELNET (PostScript (0,23))                 Enabled   LP

 This display shows three devices. Two are disabled and have no associated
 classes. Terminal_255, however, is enabled and is associated with class
 LP.



 @node !Commands.Queue.Disable

 procedure Disable (Device    : String  := "";
                    Immediate : Boolean := False);

 DESCRIPTION

 Disables the specified device.

 Depending on the value of the Immediate parameter, the command disables
 the specified device either before or after the current print request has
 finished on that device. If the Immediate parameter is False (the default),
 the command waits until the current print request has completed. If
 Immediate is True, the device is disabled immediately and the
 interrupted print request is placed back on the print queue to be
 reprinted when possible.

 This command cannot be used to disable a terminal device used to log into
 the Environment; you must use the Operator.Disable_Terminal command
 instead. This is important when a system manager is attempting to create a
 print queue for the same port currently configured for user login. The
 Enable command will not execute properly if you first attempt to disable
 the user login port by executing the Disable command.


 PARAMETERS

 Device : String := "";

 Specifies the device by physical line number. The line number takes the
 form Terminal_N, where N is the number of the port to which the device is
 attached.


 Immediate : Boolean := False;

 Specifies whether to allow the current print request to finish before the
 device is disabled. If the Immediate parameter is False (the default), the
 command waits until the current print request has completed. If Immediate
 is True, the device is disabled immediately and the interrupted print
 request is placed back on the print queue to be reprinted when possible.
 The Disable command will return quickly; however, it can take several
 minutes before the interrupted job is requeued and the device disabled.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Queue.Disable ("Terminal_255",True);

 disables the device connected to Telnet port 255. Because of the parameter
 value True, the device is disabled immediately. Any print request that is
 actually printing when this command is executed is placed on the print
 queue again.

 The command:

   Queue.Disable ("Terminal_255");

 disables the device connected to Telnet port 255. Because the default
 parameter value is False, the print request currently on this device must
 complete before the device is disabled.


 REFERENCES

 procedure Add
 procedure Enable



 @node !Commands.Queue.Display

 procedure Display (Class : Class_Name := "all");

 DESCRIPTION

 Displays the print requests currently queued in the specified class.

 The display appears in the current output window. If there are no queued
 requests, a message to this effect appears in the message window.

 The display shows the identification number for each request. Use the
 appropriate number in the Request_Id parameter when using the Cancel
 command.


 PARAMETERS

 Class : Class_Name := "all";

 Specifies the class for which the contents are to be displayed. The default
 is to display the contents of all classes. Users on installations that use
 Rational Networking--TCP/IP to connect multiple R1000 systems can query
 other machines on the network. Thus, the name can specify a machine name
 of the form !!Machine_Name, where Machine_Name is the name of a
 machine--for example, !!M1.


 EXAMPLES

 The command:

   Queue.Display;

 produces a display such as the following in the current output window:

      ID   Time   State  Class    User        Object
      ==  =====  ======  =====  ========  ===================
      20  17:54  Queued   LP    OPERATOR  !USERS.OPERATOR.LOG

 In this example, the state of the print request is queued because the
 device associated with the class LP is disabled. When a print request is
 currently being processed by an enabled device, the state of the request
 is active.


 REFERENCES

 procedure Cancel



 @node !Commands.Queue.Enable

 procedure Enable (Device : String := "all");

 DESCRIPTION

 Enables the specified device.

 The default is to enable All_Spooler_Devices (all registered devices).


 PARAMETERS

 Device : String := "all";

 Specifies the device by physical line number. The line number takes the
 form Terminal_N, where N is the number of the port to which the device is
 attached. The default is all devices.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability.

 This procedure fails if the port is already enabled for login.


 EXAMPLES

 The command:

   Queue.Enable ("Terminal_254");

 enables the spooler device for Telnet port 254.

 Note, however, that port 254 cannot be simultaneously enabled for login.
 To check if port 254 is already enabled for login, use:

   Io.Echo (System_Utilities.Enabled (254));

 If this returns True, use:

   Operator.Disable_Terminal (Physical_Line => 254,
                              Response      => "<PROFILE>");

 to disable it for login before using Queue.Enable.


 REFERENCES

 procedure Add
 procedure Disable



 @node !Commands.Queue.Kill_Print_Spooler

 procedure Kill_Print_Spooler;

 DESCRIPTION

 Stops the print spooler.

 This command disables all spooler devices, prevents additional print
 requests, and prevents the successful completion of any queue operations
 requiring this machine. The print spooler can be restarted with the
 Restart_Print_Spooler command.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability.


 REFERENCES

 procedure Restart_Print_Spooler



 @node !Commands.Queue.Print

 procedure Print (Name    : String := "<IMAGE>";
                  Options : String := "<DEFAULT>";
                  Banner  : String := "<DEFAULT>";
                  Header  : String := "<DEFAULT>";
                  Footer  : String := "<DEFAULT>";)

 DESCRIPTION

 Queues the specified objects for printing.

 You can specify one or more objects by naming, by selection, or by placing
 the cursor in a window containing the object's images.

 You can print text files, Ada units, and library listings. To print images
 from output windows or images of other kinds of objects, such as a switch
 file, you must: copy the object's image into a text file, commit the file,
 and then print the new text file.

 The default action is to queue the print request to the device associated
 with the default class and then notify when the jobs are complete. The
 message window echoes all print requests, unless the switches are set
 differently in the user's switch file.

 The Options parameter allows you to change the printout format or to
 request multiple copies of your print request.


 PARAMETERS

 Name : String := "<IMAGE>";

 Specifies the name of the object to be sent to the print queue. This
 parameter can use special names and wildcards to specify a set of objects.
 The default is the current selection or image.

 You can specify a text file, an Ada unit, or a library (which prints a list
 of the library's contents). If you specify a file or an Ada unit using
 the current image, the most recently committed version is printed.
 Therefore, the printout will differ from the actual image on the screen if
 that image contains uncommitted changes.


 Options : String := "<DEFAULT>";

 Specifies options for controlling the appearance of printed text. A
 complete description of this parameter is given below. Also refer to the
 "Key Concepts for Printing Text" section for an overview of how to use the
 Print command to control the format of printed text.

 The default value of the Options parameter is the special value
 "<DEFAULT>", which sets the parameter to the value of the Queue.Options
 session switch. If the current session-switch file is not accessible, the
 parameter is given the value "Format=>(Wrap, System_Header)".

 The Print command accepts the following options; descriptions of each
 option are given below:

      Banner_Page_User_Text     Class       Copies
      Format                    Notify      Original_Raw
      Postscript                Raw         Spool_Each_Item

 You must specify one of the following four options to specify basic
 processing before the text is sent to the device: Format, Postscript, Raw,
 or Original_Raw.

 The Format and Postscript options each accept a set of suboptions
 (enclosed in parentheses) that further specify how text preprocessing is
 to be done.

 The Format option accepts the following suboptions; descriptions of each
 suboption are given under the Format option:

            Length           Numbering       System_Header
            Tab_Width        Truncate        Width
            Wrap

 The Postscript option accepts the following suboptions; descriptions of
 each suboption are given under the Postscript option:

            Aspect        Border          Caption
            Chatty        Chop            Date
            Distort       Dx              Dy
            Epilog        Filename        Flow
            Font          Format          Header
            Height        Number          Outlines
            Pages         Prolog          Reversed
            Rules         Size            Spacing
            Twoup         Wide            Width
            X             Y

 Note that the Postscript option can take a Format suboption: do not
 confuse this suboption with the Format option described above.

 The remaining alphabetic reference describes the Print options and their
 suboptions in detail.


 *  Banner_Page_User_Text=string

    Specifies a string (with a maximum of 60 characters) that will be
    printed on the banner page, if there is one. The string specified by
    this option is printed beneath the string specified by the Banner
    parameter and above the system-generated information.

    This option is currently implemented only for print requests that are
    directed to ASCII devices such as line printers (see the Format
    option).


 *  Class=class name

    Specifies the name of the class to which the print request is queued.
    The class determines the device that will handle the print request.
    Note that the specified class must exist for the print request to be
    queued; furthermore, the class must be associated with an enabled
    device for the queued job to actually print. If this option is not
    specified, the default class is used.


 *  Copies=positive integer

    Specifies the number of copies to be printed. Copies are generated one
    at a time, and other jobs may intervene between copies. The default is
    one copy.
                                                                           

 *  Format=(Format suboptions)

    Specifies that the input file is to be preprocessed for a conventional
    ASCII device, such as a line printer. Only one of the four
    options--Format, Postscript, Raw, or Original_Raw--can be specified for
    any print request.

    The Format option accepts suboptions that specify preprocessing
    details. Suboptions must be separated by commas and enclosed in
    parentheses--for example, Format=>(Wrap, Width=77).


    -  Length=positive integer

       Specifies the total number of printed lines per page, including
       headers and footers. The default length is 60 lines.

       The number of lines in the body text for each page is automatically
       adjusted to accommodate any combination of a one-line header, a
       one-line footer, or a system page header. However, if you specify a
       multiple-line header or footer, you must decrease the Length value
       for every additional line beyond the expected one. That is,
       embedded linefeeds in a header or footer are printed but not
       counted.


    -  Numbering

       A Boolean suboption. When True, provides line numbering. The default
       is False.


    -  System_Header

       A Boolean suboption. When True, prints the system page header on
       each page. The system header is the name of the object and a page
       number. If there is a user-specified header, the system page header
       appears above it.
       The default is False.


    -  Tab_Width=natural number

       Specifies the number of spaces with which to replace a Tab character
       (Ascii.Ht). The default is 8. A value of 0 specifies no
       replacement.


    -  Truncate

       A Boolean suboption. When True, truncates lines that are longer than
       Width. The default is False.

       The Truncate suboption is ignored if the Wrap suboption is True.


    -  Width=positive integer

       Specifies the maximum number of printable characters per line. The
       Wrap and Truncate options specify what to do with lines that are
       longer than Width. The default width is 80 columns.


    -  Wrap

       A Boolean suboption. When True, wraps lines that are longer than
       Width (see the Width suboption). The default is False.

       If the Numbering suboption is True, the wrapped portions of wrapped
       lines do not receive a new line number. Setting Wrap to True causes
       the Truncate suboption to be ignored.


 *  Notify=literal

    Specifies how you will be notified of a completed print request. By
    default, an informative message is sent to the message window, even
    from remote requests.

    None                 Causes no notification to be given.

    Message              Causes a message to be displayed in the message
                         window.

    Mail                 Not currently implemented.


 *  Original_Raw

    A Boolean option. When True, specifies that text is to be printed as it
    appears in the file, with no preprocessing. The default is False. This
    option is useful for large amounts of preformatted text or binary data.
    Only one of the four options--Format, Postscript, Raw, or Original_Raw
    --can be specified for any print request.

    The Original_Raw option is normally used when the print request is sent
    to an ASCII device. However, Original_Raw can be used for a print
    request that is sent to a PostScript device, provided that the input
    file is ready to print without preprocessing--that is, if it already
    contains sufficient PostScript code to drive the printer.

    The Original_Raw option differs from the Raw option in that
    Original_Raw prints the original file directly, whereas Raw queues a
    temporary print-spooler copy of the file. Because Original_Raw prints
    without using the disk space for a print-spooler copy, this option is
    useful on machines low on disk space or when large files need to be
    printed.

    When Original_Raw is used, each file is spooled separately, a message is
    sent when printing is complete, and the default banner page is printed
    (for ASCII devices only), regardless of the values of the
    Spool_Each_Item, Notify, and Banner_Page_User_Text options.


 *  Postscript=(Postscript suboptions)

    Specifies that the input file is to be preprocessed for a PostScript
    device. Only one of the four options--Format, Postscript, Raw, or
    Original_Raw--can be specified for any print request.

    The Postscript option accepts suboptions that specify preprocessing
    details. Suboptions must be separated by commas and enclosed in
    parentheses--for example, Postscript=>(Format=Fancy, Header).

    Different preprocessing is required, depending on the format of the
    text in the input file. Accordingly, the Format suboption allows you to
    specify the file format for which you want preprocessing to be done.
    Preprocessing is available for five basic file formats--Plain_Text,
    Letter, Fancy, Image, and Postscript program.

    Other suboptions allow you to request additional preprocessing or
    override default preprocessing for a given format. Thus, the value of
    the Format suboption determines which of the remaining suboptions can
    be specified.

    If the Format suboption specifies Plain_Text, Letter, or Fancy
    format--for example, Postscript=>(Format=Plain_Text)--you can specify
    these suboptions:

         Chatty        Chop         Date
         Filename      Flow         Font
         Header        Number       Outlines
         Pages         Reversed     Rules
         Size          Spacing      Twoup
         Wide

    If the Format suboption specifies Postscript format--for example,
    Postscript=> (Format=PostScript)--you can specify these suboptions:

         Chatty        Date      Filename
         Flow          Font      Header
         Outlines      Pages     Reversed
         Twoup         Wide

    If the Format suboption specifies Image format--for example,
    Postscript=> (Format=Image)--you can specify these suboptions:

         Aspect        Caption     Chatty
         Distort       Dx          Dy 
         Epilog        Height      Prolog
         Wide          Width       X
         Y


    -  Aspect=floating-point number

       Applies only to Image format. Specifies the aspect ratio of the
       image. The default is 0.0 inches, which specifies to print the image
       in its current size.


    -  Border

       Same as the Outlines suboption.


    -  Caption=text

       Applies only to Image format. Specifies text to be printed below the
       image. The default text is the filename containing the image.


    -  Chatty

       A Boolean suboption; applies to all formats. When True, generates
       messages as each file is accessed for printing. When False, generates
       messages only after all the files have been printed or under error
       conditions. The default is True.


    -  Chop

       A Boolean suboption; applies only to Plain_Text, Letter, and Fancy
       formats. When True, truncates long input lines at the boundaries of
       the area in which text can be printed (7.5 inches by 10 inches).

       When False, causes a line longer than the line length defined by the
       Spacing and Size suboptions to be broken. For either Plain_Text or
       Letter format, the line is broken at the rightmost blank within the
       permitted line length. For Fancy format, the line is broken at the
       permitted line length. In either case, the excess text is printed on
       the next line, justified with the right margin. The default is False.


    -  Date

       A Boolean suboption; applies to all formats except Image. When True,
       prints the time and date at the time of queuing in the lower-left
       corner of each page, outside the outline box, if any. When the
       format is Plain_Text, this suboption defaults to True. When the
       format is Postscript, this suboption defaults to False.


    -  Distort

       A Boolean suboption; applies only to Image format. When True,
       magnifies the image to fill the box defined by Width and Height. When
       False, the image is magnified as large as possible while retaining
       the aspect ratio of the image. The default is False.


    -  Dx=floating-point number

       Applies only to Image format. Works with the Dy suboption to specify
       the offset between the coordinates of the current and next image.
       See the Dy suboption for details.


    -  Dy=floating-point number

       Applies only to Image format. Works with the Dx suboption to specify
       the offset between the coordinates of the current and next image. Dx
       is added
       to the X coordinate for each successive image until the resulting
       coordinate would be outside the bounds of the paper, at which time X
       is reset to its original value and Dy is added to the Y coordinate.
       When the Y coordinate exceeds the bounds of the paper, a new page is
       started at the original X, Y coordinates.

       The Dx and Dy suboptions are typically used to specify the size and
       orientation of laser-printer paper whose dimensions are other than
       8.5 by 11 inches. For example, if you are using a laser printer that
       has 8.5- by 18-inch paper, and the image is to be printed in
       portrait mode, you specify Postscript=> (format=image, dx=8.5,
       dy=18.0, ~wide). In landscape mode, you specify Postscript=>
       (format=image, dx=18, dy=8.5, wide).


    -  Epilog=Postscript instructions

       Applies only to Image format. Specifies PostScript code to be sent to
       the printer after each image is printed.


    -  Filename

       A Boolean suboption; applies to all formats except Image. When True,
       prints the full name of the file in the upper-left corner of each
       page, outside the outline box, if any. When the format is
       Plain_Text, this suboption defaults
       to True. When the format is Postscript, this suboption defaults to
       False.


    -  Flow

       A Boolean suboption; applies to all formats except Image. When True,
       causes pages to be printed two up and causes each file to start on
       the right half of
       a sheet wherever possible. (Setting the Flow suboption to True
       forces the Twoup suboption to be True and the Reversed suboption to
       be False.)

       When False, causes every file to start on a new sheet of paper. The
       default is False.


    -  Font=font name

       Applies to all formats except Image. Specifies the typeface to be
       used when printing the file. Any built-in PostScript font can be
       specified.

       If font name begins with the slash character (/ ), the named font
       must already reside on the printer. If font name does not begin with
       the slash character (/ ), then font name must name a file that
       contains the PostScript code for a downloadable font. The file is
       downloaded to the printer before any files are processed by
       PostScript.

       The specified font name must use spelling and capitalization
       identical to the name by which the printer knows the font. Thus, if
       the printer knows the font name as Courier, the name cannot be
       specified as COURIER.


    -  Format=literal

       Specifies the format for which the input file will be preprocessed.
       The default value is Automatic, which causes the Print command to
       determine the format by inspecting the contents of the input file.

       The value of the Format suboption determines which of the remaining
       suboptions can be specified.

       Automatic            Causes the Print command to determine the
                            format to use by inspecting the contents of the
                            input file.

                            If the file begins with the % character,
                            preprocessing for Postscript format is done
                            (see the Postscript literal below).

                            If the file begins with the Ascii.Nul character,
                            preprocessing for Image format is done (see the
                            Image literal below).

                            If the file begins with any other character,
                            preprocessing for Plain_Text format is done
                            (see the Plain_Text literal below).

       Fancy                Requests preprocessing for Fancy format. You
                            specify Fancy format if you want to print a
                            hard copy of Ada source. The input object must
                            be either a syntactically correct Ada unit or a
                            file that contains the text of a syntactically
                            correct Ada unit.

                            Preprocessing for Fancy format causes Ada
                            reserved words to be printed in a bold typeface
                            and comments to be italicized. Otherwise, the
                            Fancy format is preprocessed the same as
                            Plain_Text, so that pages are printed two up,
                            an outline box appears around each page, and so
                            on.

                            You can specify additional preprocessing
                            instructions or override the defaults using the
                            suboptions listed above for Plain_Text format.

       Image                Requests preprocessing for Image format. You
                            specify Image format if you want to print a file
                            containing a bitmapped image whose file format
                            is described in the introduction to this
                            package. You can specify additional
                            preprocessing instructions using the
                            suboptions listed for Image format.

       Letter               Requests preprocessing for Letter format. You
                            specify Letter format if you want to print a
                            letter or other correspondence that does not
                            contain PostScript instructions.

                            Preprocessing for Letter format is similar to
                            Plain_Text in that it allows the text to be
                            printed as it appears in the file. However,
                            Letter format differs from Plain_Text in that
                            the pages of a letter are printed one up, with
                            long lines truncated, and without an outline
                            box, date, filename, or page number on each
                            page. That is, Letter format automatically sets
                            the Chop suboption to True and following
                            suboptions to False: Twoup, Outlines, Date,
                            Filename, and Number.

                            You can specify additional preprocessing
                            instructions or override the defaults using the
                            suboptions listed above for Plain_Text format.

       Plain_Text           Requests preprocessing for Plain_Text format.
                            You specify Plain_Text format if you want to
                            print a file that contains plain text with no
                            PostScript instructions.

                            Preprocessing for Plain_Text format allows the
                            text to be printed character for character as
                            it appears in the file. By default, additional
                            preprocessing instructions are given so that
                            pages are printed two up, an outline box
                            appears around each page, the date and filename
                            are printed on each page, pages are numbered,
                            and lines are wrapped instead of truncated.

                            You can specify additional preprocessing
                            instructions or override the defaults using the
                            suboptions listed above for Plain_Text format.

       Postscript           Requests preprocessing for Postscript format.
                            You specify Postscript format if you want to
                            print a file containing a PostScript program. A
                            PostScript program is a file generated by a
                            document-formatting program like the Rational
                            Document Formatter or by a graphics
                            application that produces encapsulated
                            PostScript.

                            You can specify additional preprocessing
                            instructions using the suboptions listed above
                            for Postscript format.


    -  Header

       A Boolean suboption; applies to all formats except Image. When True,
       prints a header page that identifies the file and contains information
       concerning its printing. The default is False.


    -  Height=floating-point number

       Applies only to Image format. Specifies the maximum height allowed
       for the image.

       The default values for Width and Height specify a full-page image:

               Wide suboption    Height suboption    Width suboption
                   value             default             default
         
               True (landscape)    8.0 inches          10.5 inches
               False (portrait)   10.5 inches           8.0 inches


    -  Number

       A Boolean suboption; applies only to Plain_Text, Letter, and Fancy
       formats. When True, causes a page number to be printed in the
       upper-right corner of each page, outside the outline box, if there
       is one. The numbering starts at 1 for each file printed. The default
       is True.


    -  Outlines

       A Boolean suboption; applies to all formats except Image. When True,
       draws a solid outline box around the text for each page.
       Alternatively, this suboption can be specified as Border. When the
       format is Plain_Text, this suboption defaults to True. When the
       format is Postscript, this suboption defaults to False.


    -  Pages=positive integer or positive integer..positive integer

       Applies to all formats except Image. Specifies the pages to be
       printed. The first logical page in the file is page 1. When a single
       integer value is specified, that single page is printed. When a range
       is specified (for example, pages= 20..24), that range of logical
       pages is printed. The default is to print all pages in the file.


    -  Prolog=>text

       Applies only to Image format. Specifies PostScript code to be sent to
       the printer before each image is printed.


    -  Reversed

       A Boolean suboption; applies to all formats except Image. When True,
       reverses the order in which pages are printed, so that the last
       logical page is printed first. When False, the pages are printed in
       the order in which they appear in the file. The default is True.

       You can use the Reversed option to ensure that pages are stacked in
       the printer's output tray in the correct order (that is, the first
       page is on the top and the last page is on the bottom). Set the
       Reversed option to False if your printer already stacks pages as
       desired; otherwise, use the default value.


    -  Rules

       A Boolean suboption; applies only to Plain_Text, Letter, and Fancy
       formats. When True, draws faint, dashed lines on every other line of
       the output. The default is False.


    -  Size=Integer

       Applies only to Plain_Text, Letter, and Fancy formats. The Size
       suboption specifies the point size of the type. The default size is
       11-point type.

       The Size suboption is used together with the Spacing suboption
       below. See the Spacing suboption for further details.


    -  Spacing=Integer

       Applies only to Plain_Text, Letter, and Fancy formats. The Spacing
       suboption specifies the number of points of vertical spacing for each
       line. The default spacing is Size + 1 (or, when the defaults are
       used, 12).

       The Size and Spacing suboptions determine the number of lines per
       page and the number of characters per line:

            Wide suboption   Number of lines     Number of characters
                 value          per page               per line

            True (landscape)   540/Spacing           1200/Size
            False (portrait)   720/Spacing            900/Size

       Thus, by default, a page in portrait mode has 60 lines of
       81-character-wide output.


    -  Twoup

       A Boolean suboption; applies to all formats except Image. When True,
       prints two logical pages per physical sheet of paper. When False,
       pages are printed with a single page per sheet of paper. When the
       format is Plain_Text, this suboption defaults to True. When the
       format is Postscript, this suboption defaults to False.


    -  Wide

       A Boolean suboption; applies to all formats. When True, prints
       logical pages in landscape mode (the logical page is oriented
       horizontally so that the lines of text are parallel to the longer
       side of the page). When False, prints pages in portrait mode (with
       the logical page oriented vertically so that lines of text are
       parallel to the shorter side of the page). The default is False.

       Note that the orientation of the sheet of paper depends on the value
       of both Twoup and Wide. One portrait-mode page is printed on a
       vertically oriented sheet of paper (that is, ~Twoup, ~Wide); two
       portrait-mode pages are printed on a horizontally oriented sheet of
       paper (that is, Twoup, ~Wide).


    -  Width=floating-point number

       Applies only to Image format. Specifies the maximum width allowed for
       the image. The default values for Width and Height specify a
       full-page image:

           Wide suboption    Height suboption      Width suboption
                value            default              default

          True (landscape)     8.0 inches           10.5 inches
          False (portrait)    10.5 inches            8.0 inches


    -  X=floating-point number

       Applies only to Image format. Works with the Y suboption to specify
       the coordinates of the lower-left corner (also known as the origin)
       of the first image. The default coordinate is (0.25,0.25), which is a
       point 1/4 inch from the lower-left corner of the page.


    -  Y=floating-point number

       Applies only to Image format. Works with the X suboption to specify
       the coordinates of the lower-left corner (also known as the origin)
       of the first image. The default coordinate is (0.25,0.25), which is a
       point 1/4 inch from the lower-left corner of the page.


 *  Raw

    A Boolean option. When True, specifies that text is to be printed as it
    appears in the file, with no preprocessing. The default is False. This
    option is useful for preformatted text or binary data. Only one of the
    four options--Format, Postscript, Raw, or Original_Raw--can be
    specified for any print request.

    The Raw option is normally used when the print request is sent to an
    ASCII device. However, Raw can be used for a print request that is
    sent to a PostScript device, provided that the input file is ready to
    print without preprocessing--that is, if it already contains sufficient
    PostScript code to drive the printer.

    The Raw option differs from the Original_Raw option in that Raw queues
    a temporary print-spooler copy of the file, whereas Original_Raw prints
    the original file directly. Original_Raw should be used for machines
    that are low on disk space or when large files need to be printed.

    When the Raw option is used, you can use the Banner parameter and
    Banner_Page_User_Text option to produce a banner page (for ASCII
    devices only); all other options are turned off.


 *  Spool_Each_Item

    A Boolean option. When True, multiple files submitted in a single Print
    command are queued as separate jobs. Spooling files separately is
    useful when you have many large files to print and you want to allow
    other users' jobs to intervene. When this option is False, multiple
    files are spooled as a single job. The default is False.

    When files are spooled separately to an ASCII device, each file has its
    own banner page, provided that the Banner parameter has been
    specified. When files are spooled separately to a PostScript device, each
    file has its own header page, provided that the Header suboption has
    been specified.


 Banner : String := "<DEFAULT>";

 Specifies the string that appears on the single banner page that precedes
 the printout. Banner pages are currently implemented only for print
 requests that are directed to ASCII devices such as line printers; this
 option is ignored if PostScript formatting is specified. The string you
 supply is truncated at 11 characters. If the null string is specified, a
 banner page will not be generated. The Banner_Page_User_Text option
 allows you to add banner text beyond 11 characters.

 The special name "<DEFAULT>" refers to the banner that is specified in the
 username's session-switch file; the username of the user executing the
 Print command is used as the banner if no banner text has been specified in
 the switch file.


 Header : String := "<DEFAULT>";

 Specifies that a line of text is to appear at the top of each page of the
 printout. This parameter is currently implemented only for print requests
 that are directed to ASCII devices such as line printers (see the Format
 option). Any nonnull string (including blank characters) constitutes a 
 user-specified header. A blank line is automatically inserted below the
 user-specified header to separate the header text from the printout.

 If the System_Header option has been specified using the Options parameter,
 in addition to the user-specified header, then the system header appears
 first, followed by the user-specified header.

 The user-specified header can be wider than the width of the text file
 specified by the Width option; however, a lengthy header is not wrapped
 automatically. You must include linefeeds in a header if you want it to
 wrap onto multiple lines.

 The number of lines in the body text for each page is automatically
 adjusted to accommodate any combination of a one-line header, a one-line
 footer, or a system page header. However, if you specify a multiple-line
 header, you must decrease the Length value for every header line beyond
 the expected one.

 The special name "<DEFAULT>" refers to the header that is specified in the
 username's session-switch file.


 Footer : String := "<DEFAULT>";

 Specifies a line of text that appears at the bottom of each page of the
 printout. This parameter is currently implemented only for print requests
 that are directed to ASCII devices such as line printers; it is ignored if
 PostScript formatting is specified (see the Format option).

 Any nonnull string (including blank characters) constitutes a
 user-specified footer. A blank line is automatically inserted above the
 user-specified footer to separate the footer text from the printout.

 The user-specified footer can be longer than the Width option; however, a
 lengthy footer is not wrapped automatically. You must include linefeeds in
 a footer if you want it to wrap onto multiple lines.

 The number of lines in the body text for each page is automatically
 adjusted to accommodate any combination of a one-line header, a one-line
 footer, or a system page header. However, if you specify a multiple-line
 footer, you must decrease the Length value for every footer line beyond
 the expected one.

 The special name "<DEFAULT>" refers to the footer that is specified in the
 username's session-switch file.


 EXAMPLES

 The command:

   Queue.Print
     (Name    => "output_samples",
      Options => "copies=2,format => (truncate,system_header)",
      Banner  => "dept 04",header => "December 9, 1991");

 prints two copies of the object Output_Samples, with Dept 04 on the banner
 page and the date appearing under the system page header. Lines longer
 than 80 characters are truncated.

 The request to print Output_Samples is queued to the default class, and a
 message such as the following appears in the message window:

   Request number 58 has been queued

 A further message in the message window notifies the user when the job is
 complete. The user would also be notified if the request were made on a
 remote machine.


 REFERENCES

 procedure Print_Version
 Session and Job Management (SJM), Session Switches



 @node !Commands.Queue.Print_Version

 procedure Print_Version (The_Version : Directory.Version;
                          Options     : String := "<DEFAULT>";
                          Banner      : String := "<DEFAULT>";
                          Header      : String := "<DEFAULT>";
                          Footer      : String := "<DEFAULT>");

 DESCRIPTION

 Queues the specified object version for printing, allowing customization of
 the printout page format.

 The default is to assume the device associated with the default class and
 to notify when the jobs are complete. The message window echoes all print
 requests.

 The Print_Version command uses the Options parameter to allow you to
 change the printout format or to request multiple copies for your print.


 PARAMETERS

 The_Version : Directory.Version;

 Specifies the version of the object to be sent to the print queue.


 Options : String := "<DEFAULT>";

 Specifies the options to be used in formatting output. At the beginning of
 this package is a list of the options available for use to format output
 in the Options parameter. Note that the Options parameter uses the special
 name "<DEFAULT>". When this special name is used, the system looks in the
 session-switch file for the options set in the Queue.Options switch. If the
 switch file is not accessible, the system uses the options "Format=>(Wrap,
 System_Header)". These options are not provided and must be respecified if
 the options are specified by substituting an option string for the
 "<DEFAULT>" special name. One of the following three options must be
 specified: Original_Raw, Raw, or Format. Unless otherwise specified in the
 Options parameter, the Boolean options Original_Raw, Raw, and Spool-
 _Each_Item are False. The other options take the defaults described in
 detail in the reference entry for the Print command.


 Banner : String := "<DEFAULT>";

 Specifies the string that appears on the single banner page that precedes
 the printout. This option is ignored if PostScript formatting is
 specified. The string you supply is truncated at 11 characters. If the null
 string is specified, a banner page will not be generated. The special name
 "<DEFAULT>" refers to the banner set in the username's session-switch file
 (or the username if one is not specified).


 Header : String := "<DEFAULT>";

 Specifies a line of text that appears at the top of each page of the
 printout. This option is ignored if PostScript formatting is specified. Any
 nonnull string (including blank characters) constitutes a user-specified
 header. A blank line is automatically inserted below the user-specified
 header to separate the header text from the printout.

 If the Options parameter requests a system page header in addition to the
 user-specified header, then the system header appears first, followed by
 the user-specified header.

 The user-specified header can be longer than the Width option; however, a
 lengthy header is not wrapped automatically. You must include linefeeds in
 a header if you want it to wrap onto multiple lines.

 The number of lines in the body text for each page is automatically
 adjusted to accommodate any combination of a one-line header, a one-line
 footer, or a system page header. However, if you specify a multiple-line
 header, you must decrease the Length value for every header line beyond
 the expected one. The special name "<DEFAULT>" refers to the header set in
 the username's session-switch file.


 Footer : String := "<DEFAULT>";

 Specifies a line of text that appears at the bottom of each page of the
 printout. This option is ignored if Postscript formatting is specified. Any
 nonnull string (including blank characters) constitutes a user-specified
 footer. A blank line is automatically inserted above the user-specified
 footer to separate the footer text from the printout.

 The user-specified footer can be longer than the Width option; however, a
 lengthy footer is not wrapped automatically. You must include linefeeds in
 a footer if you want it to wrap onto multiple lines.

 The number of lines in the body text for each page is automatically
 adjusted to accommodate any combination of a one-line header, a one-line
 footer, or a system page header. However, if you specify a multiple-line
 footer, you must decrease the Length value for every footer line beyond
 the expected one. The special name "<DEFAULT>" refers to the footer set in
 the username's session-switch file.


 REFERENCES

 procedure Print
 Session and Job Management (SJM), Session Switches



 @node !Commands.Queue.Register

 procedure Register (Device : String     := "";
                     Class  : Class_Name := "");

 DESCRIPTION

 Registers the specified device with the print spooler and associates the
 specified device with the specified class.

 The specified device and class must already exist (see the Create and Add
 procedures).

 More than one class can be registered to a single device, and a single
 class can be registered to more than one device. When one class is registered
 to multiple devices, print requests submitted to that class are handled by
 the first available device.


 PARAMETERS

 Device : String := "";

 Specifies the device by physical line number. The line number takes the
 format Terminal_N, where N is the number of the port to which the device
 is attached. The default is no device.


 Class : Class_Name := "";

 Specifies the class to be associated with the device. The default is no
 class. The class must already exist (see the Create procedure). A remote
 machine name cannot be used to register a class with a remote system.
 Registering must be performed on the same machine as the class to be
 registered for that machine.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Queue.Register ("Terminal_250","lp");

 registers class LP with the device using port 250. If the device using
 port 250 is the only device associated with class LP, then all requests to
 class LP are routed to this device.


 REFERENCES

 procedure Add
 procedure Create
 procedure Unregister



 @node !Commands.Queue.Remove

 procedure Remove (Device    : String  := "";
                   Immediate : Boolean := False);

 DESCRIPTION

 Removes the device from the print spooler.

 The value of the Immediate parameter determines whether the procedure
 waits until the current print request has finished before removing the
 device. If Immediate is False (the default), the procedure waits for the
 device to finish processing the current print request. If Immediate is
 True, the device is removed immediately, and the interrupted print request
 is requeued.

 The Remove command effectively reverses all aspects of the Enable and
 Register commands. The Remove procedure disables this device, dissociates
 it from its classes, and then removes the device from the print spooler.
 (Note that the Unregister command dissociates a device from a class but
 leaves the device known to the print spooler.)


 PARAMETERS

 Device : String := "";

 Specifies the device by physical line number. The line number takes the
 form Terminal_N, where N is the number of the port to which the device is
 attached. The default is no physical line number.


 Immediate : Boolean := False;

 Specifies whether the command waits until the current print request has
 finished before removing the device. If False (the default), the procedure
 waits for the device to finish processing the current print request. If
 True, the device is removed immediately and the interrupted print request
 is requeued.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Queue.Remove ("Terminal_250",True);

 removes the device on physical line 250 from the spooler. Because of the
 value True, the device is removed immediately.

 The command:

   Queue.Remove ("Terminal_250");

 removes the device on physical line 250 from the spooler. Because of the
 default value False, the print request currently printing on device 250
 completes before the device is removed.


 REFERENCES

 procedure Add
 procedure Enable
 procedure Register



 @node !Commands.Queue.Restart_Print_Spooler

 procedure Restart_Print_Spooler;

 DESCRIPTION

 Starts or restarts the print spooler.

 If the spooler is already running, this command has no effect. The spooler
 must be running to successfully execute any queue operation.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability.



 @node !Commands.Queue.Unregister

 procedure Unregister (Device : String     := "";
                       Class  : Class_Name := "");

 DESCRIPTION

 Dissociates the device from the specified class.

 The Unregister command reverses the Register command. The Unregister com-
 mand dissociates a device from a class but leaves the device known to the
 print spooler. (Note that the Remove procedure disables the device,
 dissociates it from its classes, and then removes the device from the
 print spooler.)


 PARAMETERS

 Device : String := "";

 Specifies the device by physical line number. The line number takes the
 form Terminal_N, where N is the number of the port to which the device is
 attached. The default is no physical line number.


 Class : Class_Name := "";

 Specifies a class that is registered to the device. The default is no
 class. A remote machine name cannot be specified to unregister a device on
 a remote machine.


 RESTRICTIONS

 Execution of this command requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Queue.Unregister ("Terminal_250","lp");

 dissociates class LP from the device using port 250.


 REFERENCES

 procedure Add
 procedure Create
 procedure Destroy
 procedure Register



 @node !Commands.Scheduler

 The medium-term scheduler tracks jobs and regulates their access to CPU,
 memory, and disk resources. The procedures in package Scheduler monitor
 and fine-tune the scheduler's allocation of resources to jobs. By
 fine-tuning the scheduler, the user can cause it to devote resources to
 improving the performance of interactive jobs or increasing the
 throughput of batch jobs. See the Session and Job Management (SJM) book
 for more information about controlling jobs.


 RESOURCES IN PACKAGE SCHEDULER

 The commands in this package fall into the following functional groups:

 Individual jobs:

             Disable                   Disk_Waits
             Enable                    Enabled
             Get_Cpu_Priority          Get_Cpu_Time_Used
             Get_Job_Attribute         Get_Job_Descriptor
             Get_Job_Kind              Get_Job_State
             Get_Wsl_Limits            Job_Descriptor
             Job_Kind                  Job_State
             Set_Job_Attribute         Set_Wsl_Limits
             Traverse_Job_Descriptor   Use_Default_Wsl_Limits
             Working_Set_Size

 System activity:

             Get_Disk_Wait_Load        Get_Run_Queue_Load
             Get_Withheld_Task_Load    Load_Factor

 Scheduler settings:

             Display                   Get
             Set                       State


 KEY CONCEPTS FOR PACKAGE SCHEDULER

 The settings for the medium-term scheduler are typically set by the
 initialization procedure in world Rational. These values should be
 sufficient; see your Rational technical representative if you want to use
 different settings.

 The operations that set values in this package require that the job
 executing the procedure have operator capability. Operations that display
 values do not require any special access.

 With the Set procedure, the user can set values for the various scheduler
 parameters that enable, disable, and adjust CPU scheduling, memory
 scheduling, disk scheduling, and background job streams. (Each of these
 topics is discussed in its own section below.) With the Display procedure,
 the user can display the current values for the scheduler parameters.

 The State procedure displays indexes of overall system activity such as
 run load, disk wait load, withheld task load, and number of available
 memory pages. The following commands also return specific information about
 system activity:

        Get_Disk_Wait_Load
        Get_Withheld_Task_Load
        Get_Run_Queue_Load

 Package Scheduler also provides procedures and functions that allow the
 user to enable, disable, and get information about individual jobs. The
 Disable and Enable procedures suspend and resume a given job. The State
 procedure displays information about resource allocation to individual
 jobs, and the Display procedure displays information specifically about
 jobs on the background job streams. Along with the State and Display
 procedures, the following commands return specific information about
 individual jobs:

        Display                         Get_Cpu_Priority
        Get_Cpu_Time_Used               Get_Job_Kind
        Get_Job_State                   Get_Wsl_Limits
        State


 Jobs

 A job is a set of Ada tasks that act together. A job is initiated each
 time the user edits an object or executes a command. For scheduling
 purposes, some jobs are associated with (or mapped to) others. For
 example, the aggregate of jobs initiated by editing images and objects
 within a single session are scheduled as a single job.


 Job Numbers

 Whenever a job starts or is created, it is assigned a unique Job_Id (job
 identification number), which is a number from 0 through 255. The
 procedures in package Scheduler manipulate jobs by job number, or Job_Id.
 Thus, jobs and job numbers are often referred to as Job_Id in the
 description of individual commands.


 Foreground and Background Jobs

 Jobs are divided into two major classes for purposes of allocating
 resources:

 *  Foreground jobs are typically highly interactive and require fast
    response. They are allocated the majority of system resources, and the
    scheduler attempts to guarantee that each foreground job makes
    satisfactory progress.

 *  Background jobs are batch jobs and do not require especially fast
    response. They are allocated the remaining resources after foreground
    jobs are handled. The scheduler does not attempt to guarantee that each
    background job makes progress.

 The treatment of foreground and background jobs is described more
 precisely under "CPU Scheduling," below.


 Job Kinds

 Within the general division of foreground and background, jobs are
 allocated resources according to their kind. In some cases, a job's kind
 is determined internally by the Environment; in other cases, it is
 determined by the user. The user can use the Get_Job_Kind function to
 determine a given job's kind.

 The kinds of jobs are:

 *  Core-editor (Ce) jobs include operations for editing images--for
    example, commands that control the cursor or search for strings. The
    Environment determines precisely which operations count as core-editor
    jobs.

 *  Object-editor (Oe) jobs include operations for debugging programs and
    for editing structured objects--for example, commands that select
    objects. The Environment determines precisely which operations count
    as object-editor jobs.

 *  Attached jobs are commands entered by users that are not core-editor or
    object-editor operations. While an attached job executes, the
    message-window banner displays ...running and the terminal is
    unavailable for other operations.

 *  Detached jobs result either from interrupting an attached job using
    [Control] [G] (the Job.Interrupt procedure) or from entering a command
    using [Control] [Promote] (the Command.Spawn procedure). The terminal
    can be used for other operations while detached jobs execute.

 *  Server jobs are background jobs that must always have resources
    available when needed--for example, the print spooler. The user can
    designate a job as a server using the Set_Job_Attribute procedure.

 *  Terminated jobs are not allocated any resources. A terminated job
    remains in the system until its job number is reused for another job.

 (Note that all job kinds are defined as enumerations of the Job_Kind type.)

 Job kinds are related to job classes as follows:

 *  Core-editor and object-editor jobs are allocated foreground resources.

 *  Detached jobs and servers are allocated background resources.

 *  Attached jobs receive foreground resources until a certain amount of
    time has elapsed, after which attached jobs receive background
    resources. (The time limit on attached jobs is determined by the
    Foreground_Time_Limit scheduler parameter, which the user can set
    using the Set procedure.) Having a time limit on foreground jobs
    induces users to run long jobs in the background, rather than depleting
    foreground resources.


 Job States

 Jobs typically pass through various states: Run, Idle, Wait, Disabled, and
 Queued. These states are enumerations of the Job_State type. The user can
 use the Get_Job_State function to determine a given job's current state.

 Foreground and background jobs alternate between the Run and Wait states
 as they execute:

 *  A job in the Run state (also called a running job) is either currently
    consuming CPU time or eligible to consume CPU time. That is, at any
    given time, there may be several running jobs, of which only one is
    actually using CPU time while the rest wait their turn.

 *  A job in the Idle state is not executing. It uses no CPU time and has
    no unblocked tasks. For example, jobs that are waiting for I/O or
    that have all tasks blocked are in the Idle state. Also, jobs such as
    the print spooler are in the Idle state until a request arrives.

 *  A job in the Wait state (also called a withheld job is temporarily
    ineligible for CPU time. The scheduler puts a job in the Wait state if:

    -  The job has already used more than its share of CPU time and the
       system load is too high.

    -  The job is waiting for disk resources and the disk wait load is too
       high.

    -  The job is using pages of memory that are needed to replenish the
       reserve supply of available pages.

 *  A withheld job returns to the Run state when the scheduler determines
    that the job is eligible for resources again.

 *  A job in the Disabled state is not executing. It has been rendered
    ineligible for CPU time by users or programs executing the
    !Commands.Job.Disable procedure or the Scheduler.Disable procedure.

 *  The Queued state is relevant for certain kinds of background
    jobs--namely, all detached jobs and those attached jobs that have
    passed the Foreground_Time_Limit. Jobs such as these are queued for
    resources on one of several background job streams (see "Background
    Job Streams," below). However, because only a restricted number of jobs
    on each stream can be in the Run or Wait state at a time, the remaining
    jobs are put in the Queued state. In other words, a job in the Queued
    state is a job that is waiting on a background job stream until the
    executing jobs ahead of it have completed or have been moved onto
    another stream.


 Scheduling Review Interval

 The scheduler makes scheduling decisions every 100 milliseconds. (These
 100-millisecond intervals are called review intervals.) At the end of
 every review interval, the scheduler reviews the actual usage of
 resources during the last 100 milliseconds and then, based on the actual
 usage, decides whether to withhold jobs during the next 100 milliseconds
 to keep resource usage within certain limits. Note that the scheduler does
 not actually control the allocation of resources, but rather it monitors
 and adjusts resource consumption to maintain a balance among different
 kinds of jobs. The scheduler itself is not subject to scheduling; it uses
 0.5-1% of CPU resources.

 The following subsections give a partial description of the scheduler's
 effect on CPU scheduling, memory scheduling, and disk scheduling. These
 subsections contain the information the user needs about the scheduler in
 order to set the scheduler parameters using the Set procedure.


 CPU Scheduling

 CPU time is distributed among foreground and background jobs, with
 preference given to foreground jobs. Because foreground jobs need to make
 consistent progress with the best possible performance, CPU time is made
 available first to foreground jobs and then to background jobs. However,
 to prevent foreground jobs

 from consuming all CPU resources, a minimum percentage of CPU time can be
 designated for background jobs. This minimum percentage is determined by
 the Percent_For_Background scheduler parameter, which the user can set
 using the Set procedure. (Note that even though some CPU time is
 guaranteed, background jobs will not make progress unless they also have
 disk and memory resources.)

 If there are no background jobs, foreground jobs can receive the CPU time
 that was reserved for background jobs. Similarly, background jobs can
 receive more than their reserved CPU time, provided that no foreground
 jobs need time.


 Foreground Jobs

 The scheduler follows separate policies for scheduling the CPU time that
 is allocated to foreground and background jobs. To ensure consistent
 progress for all foreground jobs, the scheduler attempts to give each
 session that has foreground jobs an equal share of the foreground CPU
 time. That is, if two users have foreground jobs, each user's session is
 given half of the available foreground CPU time. In contrast, individual
 background jobs are given CPU time according to their Ada task priority
 and to their placement on a background job stream (see "Background
 Jobs," below).

 Foreground CPU scheduling applies to core-editor jobs, object-editor jobs,
 and attached jobs. However, to discourage users from running long jobs in
 the foreground, the scheduler can be adjusted to give foreground
 resources to attached jobs only for a limited time. (The time limit is set
 by the Foreground_Time_Limit scheduler parameter.) After the foreground
 time limit has expired for an attached job, the job is subject to
 background CPU scheduling.

 To schedule foreground time equitably, the scheduler does the following at
 the end of each review interval:

 1. Determines how much foreground CPU time each job has used during the
    current review interval.

 2. Calculates the ideal CPU usage for each job, giving a fair share to
    each session that had foreground jobs during the interval.

 3. Compares the actual usage to the ideal usage and determines whether the
    job has used more or less time than it should have. The foreground
    budget for each job is credited or debited accordingly.

 4. Decides whether to withhold a job for the next interval. A job is
    withheld (put in the Wait state) if both of the following are true:

    a. The job has accumulated an overall debt in its foreground budget
       (that is, the value of the job's foreground budget is negative).

    b. The run load exceeds a preset level.

 5. Decides whether to release jobs that were withheld from previous
    intervals and return them to the Run state. A job is released after it
    has accumulated enough credit in its foreground budget over one or more
    review intervals to make up for whatever debt it has previously
    incurred.

 Run Load

 The run load is the average number of tasks that require CPU time during a
 review interval. Tasks are counted if they are currently consuming CPU
 time or are eligible to consume CPU time. Withheld and idle tasks are
 not reflected in the run load. The run load is averaged over a review
 interval and then multiplied by 100 so that it appears as an integer. For
 example, if an average of 1.3 tasks are in the Run state, the run load is
 130.

 The scheduler uses the run load to determine whether or not a job can be
 withheld after that job has used more than its share of CPU time. The
 user can specify the minimum run load at which the scheduler can withhold
 jobs by using the Set procedure to set the Withhold_Run_Load parameter.

 Number of Withheld Jobs

 By default, the scheduler can withhold only one additional job at the end
 of a given review interval, no matter how many jobs are eligible for
 withholding after that interval. (However, there is no restriction on the
 total number of withheld jobs at any given time, because multiple withheld
 jobs can accumulate after a number of intervals.) The user can permit the
 scheduler to withhold more than one job per review interval by changing
 the value for the Withhold_Multiple_Jobs scheduler parameter to True. (See
 the Set procedure.)

 Foreground Budget

 As a job uses more or less than its fair share of CPU time, the job's
 foreground budget is debited or credited accordingly at the end of each
 review interval. The value of a job's budget at the end of a given
 interval therefore represents the net debt or credit accumulated over
 successive intervals. If, on the balance, the job has used more than its
 allocated time, its budget value is negative. For a withheld job, this
 negative value expresses how much time the job must accumulate over sub-
 sequent intervals in order to be released and returned to the Run state.
 If, on the other hand, the job has used less than its overall allocated
 time, its budget value is positive. A positive budget value prevents the
 job from being withheld and expresses how much extra time the job can
 use before going into debt. If the job has used exactly as much time as it
 was allocated, the budget value breaks even at 0.

 The scheduler imposes a limit on the amount of accumulated credit or debt
 a job can have. That is, no matter how much extra time a job has used,
 there is a maximum overall debt that the job can incur. Consequently, if
 the job is withheld, there is a limit to the amount of credit it has to
 accumulate before it can run again. Similarly, no matter how little time
 the job used relative to its allotment, there is a maximum overall
 credit that the job can earn. Consequently, there is a limit to how much
 extra time the job can use before going into debt.

 The user can adjust the credit and debit limits on the foreground budget
 by using the Set procedure to set the Max_Foreground_Budget and
 Min_Foreground_Budget scheduler parameters, respectively. The wider the
 range between the Max_Foreground_Budget and Min_Foreground_Budget
 values, the more sensitive the scheduler is to giving jobs equal time.
 When the range is narrower, the distribution of CPU time is less equal.


 Background Jobs

 As a group, background jobs (detached jobs, servers, and aged attached
 jobs) are guaranteed a percentage of CPU time, as determined by the
 Percent_For_Background scheduler parameter. However, the scheduler does
 not track the amount of time used by each background job, nor does the
 scheduler attempt to ensure that each job is allotted a fair share of the
 available CPU time. Instead, the allocation of CPU time is determined by
 Ada task priorities.


 Background Job Streams

 Without a guarantee of equal CPU time, it is possible for a single
 long-running background job to block a number of shorter jobs. To avoid
 this, background job streams can be set up to queue long-running jobs to
 expedite shorter jobs. Only two kinds of background jobs are subject to
 queuing on the background job streams--namely, detached jobs and attached
 jobs that have run longer than the Foreground_Time_Limit. Servers are not
 subject to queuing on these streams.

 By default, there is one background job stream, although the user can
 arbitrarily set up streams by using the Set procedure to set the
 Background_Streams scheduler parameter. The Display procedure displays
 information about each background job stream.

 Job-Stream Time Limits

 Each background job stream has an associated time limit, which specifies
 the maximum amount of elapsed time a job can run on that stream. If a job
 that is running on a stream has not yet finished when the time limit is
 reached, the job is queued onto the next stream.

 For example, the user could set up three streams with the following time
 limits:

        Stream 1: 2 minutes
        Stream 2: 5 minutes
        Stream 3: 20 minutes

 With these limits, a job queued on stream 1 can run for 2 minutes. If the
 job has not finished within that time, it is queued onto stream 2, where it
 waits its turn to run. (Meanwhile, another job on stream 1 can now run.)
 Once the job is eligible to run on stream 2, it can run for 5 more
 minutes. If the job requires more than 5 minutes, it is queued onto stream
 3, so that subsequent jobs on stream 2 can run. Once the job is eligible
 to run on stream 3, it can run for another 20 minutes. If the job requires
 even more time, it is moved to the bottom of the queue on stream 3. After
 the jobs ahead of it have finished or have been requeued, the job gets
 another 20 minutes, and so on.

 The time limits for each stream are determined by the Stream_Time
 parameter (see the Set procedure).

 Note that a job on a job stream uses temporary disk space that is not
 reclaimed until the job is done. Allowing many jobs to accumulate on
 multiple job streams can cause a shortage of disk space. If the
 Stream_Time value for a job stream is low, jobs on that stream are more
 likely to be requeued before they can finish. A high Stream_Time value
 permits jobs to complete without being requeued.

 Number of Runnable Jobs on a Stream

 Each stream has an associated prescribed number of jobs that can be
 running at a given time. These numbers are specified by the Stream_Jobs
 parameter (see the Set procedure). If a job stream contains more jobs than
 are permitted to run at a given time, the excess jobs are put in the
 Queued state to wait until the jobs ahead of them are finished or requeued
 to the next stream.

 For example, if the Stream_Jobs value for a stream is 2, then only two
 jobs on that stream can be in the Run or Wait state at a time. Therefore,
 if ten jobs are on that stream, eight jobs must be in the Queued state.

 Strict Stream Policy

 Although the Stream_Jobs parameter specifies a prescribed number of
 runnable jobs per stream, the actual number of running jobs on each stream
 is also determined by the presence or absence of strict stream policy.
 When strict stream policy is in effect, the Stream_Jobs value for a given
 stream is always the maximum number of jobs that can run concurrently on
 that stream. In contrast, when strict stream policy is not in effect, the
 number of jobs on a given stream can exceed the relevant Stream_Jobs
 value, provided that other streams are empty. However, although the
 distribution of runnable jobs across streams is affected, the total number
 of jobs running on all streams taken together cannot exceed the total of
 the Stream_Jobs values for all the streams.

 For example, under strict stream policy, a system with three streams might
 have the following Stream_Jobs values:

       Stream 1: 2 jobs
       Stream 2: 1 job
       Stream 3: 1 job

 If jobs are queued in all three streams, a maximum of four jobs can be
 running--specifically, only the first two jobs in stream 1, the first job in
 stream 2, and the first job in stream 3. If streams 1 and 3 are empty, the
 maximum number of running jobs across all streams is only one, because
 stream 2 has a value of 1. Strict stream policy prohibits extra jobs from
 running on stream 2, no matter how many jobs are queued.

 If strict stream policy is not in effect, then the maximum number of
 running jobs is always four, even when some streams are empty. That is, if
 streams 1 and 3 are empty, up to four jobs can run on stream 2, because
 the empty streams contribute their Stream_Jobs values to the nonempty
 stream.

 The following Stream_Jobs values make sense only if strict stream policy
 is not in effect:

       Stream 1: 3 jobs
       Stream 2: 0 jobs
       Stream 3: 0 jobs

 If strict stream policy were in effect, jobs queued on streams 2 and 3
 would never run, because their Stream_Jobs values are 0. However, because
 strict stream policy is not in effect (by default), jobs queued on streams
 2 or 3 can run whenever stream 1 has fewer than three jobs in its queue.

 Strict stream policy is controlled by the value of the
 Strict_Stream_Policy scheduler parameter.


 Memory Scheduling

 Each job uses pages of main memory while executing. On most R1000 systems,
 the memory size is either 32,768 or 65,536 pages, each of which contains
 1,024 bytes. The number of pages in memory is defined by the
 !Lrm.System.Memory_Size constant.

 The scheduler dynamically adjusts the allocation of memory to give pages
 to jobs that need more and to reclaim pages from jobs that need fewer. The
 number of pages used by a job is called the job's job working set size. To
 prevent any one job

 from consuming a disproportionate amount of memory resources, the
 scheduler places a limit on each job's working set size. This limit,
 called the job working set limit, is the maximum number of pages a job can
 use without penalty.

 Jobs started by the Environment or by the system daemon have fixed working
 set limits. The user can specify these working set limits by setting the
 Environment_Wsl and Daemon_Wsl scheduler parameters, respectively. In
 contrast, the working set limit for each user job is determined
 dynamically. When a job is created, it is given an initial working set
 limit, which is adjusted at regular intervals to ensure adequate
 allocation of pages to all jobs.

 The value of a job's initial working set limit depends on what kind of job
 it is (see "Job Kinds," above). The values of scheduler parameters such as
 Min_Ce_Wsl, Min_Oe_Wsl, and so on determine the initial working set limit
 for each kind of job.

 At the end of every review interval, the scheduler checks each job's
 working set size. If the job's working set size exceeds its working set
 limit, the scheduler increases the job's limit by a fixed number of
 pages. The user can specify this number by setting the Wsl_Growth_Factor
 scheduler parameter.

 The scheduler tries to keep each job's working set limit close to its
 working set size. Therefore, in addition to automatically increasing the
 working set limit ten times a second, the scheduler automatically
 decreases each job's working set limit every 5 seconds. The limit is
 decreased by a fixed number of pages, which the user can specify by setting
 the Wsl_Decay_Factor scheduler parameter.

 The growth and decay of the working set limits for each kind of job are
 kept within a range of values that are specified by scheduler parameters.
 For example, the lowest possible working set limit for core-editor jobs is
 determined by the Min_Ce_Wsl parameter (which is also the value of the
 initial working set limit). The highest possible working set limit for
 core-editor jobs is determined by Max_Ce_Wsl. Similarly, the range for
 object-editor working set limits is determined by Min_Oe_Wsl and
 Max_Oe_Wsl, and so on for attached jobs, detached jobs, and servers. These
 parameters can be used to give preference to some kinds of jobs over
 others. For example, the default values for Max_Detached_Wsl and Max_At-
 tached_Wsl give background user jobs more than twice as much memory as
 foreground user jobs. The user can temporarily override the maximum and
 minimum working set limits for a given job by using the Set_Wsl_Limits
 procedure.

 The scheduler reserves a number of pages for distribution among jobs that
 need more memory. If the number of available pages falls below a given
 limit, the scheduler withholds jobs as needed and contributes the freed
 pages to the reserve. The user can specify the minimum number of pages
 kept on reserve by setting the Minimum_Available_Memory scheduler
 parameter.


 Page Withdrawal

 During every review interval, the scheduler withdraws a fixed number of
 pages from memory. Withdrawn pages are earmarked for possible removal from
 the jobs that are using them. However, a withdrawn page is not actually
 taken away from a job unless that job exceeds its working set limit during
 the review interval.

 Withdrawing pages serves two purposes, namely:

 *  To help account for pages that are shared by multiple jobs. When a
    shared page is withdrawn, its use is charged to the first job to request
    it again. Accurately accounting for the use of shared pages is
    necessary for determining the working set size of each job.

 *  To earmark pages from overallocated jobs for potential use by
    underallocated jobs. If a job exceeds its working set limit, the excess
    pages are withdrawn so that they can be allocated to other jobs.

 The user can specify the number of pages withdrawn per review interval by
 setting the Page_Withdrawal_Rate scheduler parameter.


 Disk Scheduling

 The scheduler measures disk activity through an index called the disk wait
 load. The disk wait load is the average number of tasks waiting on disk
 operations, including page faults and disk I/O operations. The disk wait
 load is averaged over an internally determined interval of time and then
 multiplied by 100, so that it is expressed as an integer. For example, if
 an average of 1.5 tasks are waiting for pages from disk at a given time,
 the disk wait load is 150.

 The scheduler regulates disk activity by monitoring the disk wait load and
 withholding one or more jobs when the load exceeds a certain limit. The
 user can set this limit by setting the Max_Disk_Load scheduler parameter.
 The user can also ensure a minimum level of disk activity by setting the
 Min_Disk_Load scheduler parameter. Together, the Max_Disk_Load and
 Min_Disk_Load parameters define a range of acceptable stress on the disks.
 The wider the range, the less sensitive the scheduler is to changes in the
 disk wait load.


 @node !Commands.Scheduler.Cpu_Priority


 subtype Cpu_Priority is Natural range 0 .. 6;

 DESCRIPTION

 Identifies priority of access to CPU resources.

 A Cpu_Priority of 0 is the lowest; a Cpu_Priority of 6 is the highest. The
 higher a job's priority, the more CPU time the job gets. Background jobs
 have a Cpu_Priority of 0; foreground jobs have a Cpu_Priority of 6. (Values
 1 through 5 are reserved for future Environment implementations.)



 @node !Commands.Scheduler.Disable

 procedure Disable (Job : Job_Id);

 DESCRIPTION

 Suspends temporarily the job with the specified Job_Id.

 A disabled job can be resumed with the Enable procedure.


 PARAMETERS

 Job : Job_Id;

 Specifies the job number.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 REFERENCES

 procedure Enable



 @node !Commands.Scheduler.Disk_Waits

 function Disk_Waits (Job : Job_Id) return Long_Integer;

 DESCRIPTION

 Returns the number of disk waits the specified job has had since last
 initialized.

 A disk wait occurs whenever a job has to wait for disk resources. The
 number of disk waits is derived from a combination of page faults and disk
 I/O operations. A high number of disk waits indicates heavy disk activity;
 a low number indicates light disk activity.


 PARAMETERS

 Job : Job_Id;

 Specifies the job number.


 return Long_Integer;



 Returns the number of disk waits.



 @node !Commands.Scheduler.Display

 procedure Display (Show_Parameters : Boolean := True;
                    Show_Queues     : Boolean := True);

 DESCRIPTION

 Displays the current values for the scheduler parameters along with
 information about background job streams in the current output window.

 For each background job stream, this procedure displays the value of the
 Stream_Time parameter, a list of the jobs currently in the stream, and
 the number of minutes each job has been in the stream. An asterisk next to
 a job indicates that the job is currently running--that is, it has job
 state Run. A job without an asterisk has job state Queued.

 The user can change the values for the scheduler parameters by using the
 Set procedure.


 PARAMETERS

 Show_Parameters : Boolean := True;

 Specifies, when true, a display of the current values for the scheduler
 parameters.


 Show_Queues : Boolean := True;

 Specifies, when true, a display of background job-stream information.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 EXAMPLES

 The command:

   Scheduler.Display (True,False);

 produces a display such as the following:

   Cpu_Scheduling    : Enabled
   Disk_Scheduling   : Disabled
   Memory_Scheduling : Enabled

   Percent_For_Background         : 20%
   Min_ and Max_Foreground_Budget :-250 .. 250 milliseconds
   Withhold_Run_Load              : 130
   Withhold_Multiple_Jobs         : FALSE

   Environment_Wsl           : 11000 pages
   Daemon_Wsl                : 200 pages
   Min_ and Max_Ce_Wsl       : 150 .. 500 pages
   Min_ and Max_Oe_Wsl       : 75 .. 750 pages
   Min_ and Max_Attached_Wsl : 50 .. 4000 pages
   Min_ and Max_Detached_Wsl : 50 .. 5000 pages
   Min_ and Max_Server_Wsl   : 75 .. 1000 pages
   Min_Available_Memory      : 1024 pages
   Wsl_Decay_Factor          : 50 pages/5 seconds
   Wsl_Growth_Factor         : 50 pages/100 milliseconds
   Page_Withdrawal_Rate      : 1*640 pages/second

   Min_ and Max_Disk_Load : 200 .. 250

   Foreground_Time_Limit   : 300 seconds
   Background_Streams      : 3
   Strict_Stream_Policy    : FALSE
   Stream_Time and _Jobs 1 : 2 minutes, 3 jobs
   Stream_Time and _Jobs 2 : 58 minutes, 1 job
   Stream_Time and _Jobs 3 : 50 minutes, 0 jobs

 The command:

   Scheduler.Display (False,True);

 produces a display such as the following in the current output window:

      Stream 1          2:00
         252   9:14
       * 223   8:00
         253   3:46
       * 219   3:29
         238   0:48
      Stream 2          58:00
       * 220   5:00
         261   2:49
      Stream 3          0:00
       * 222   2:00
         254   1:26

 This display shows five jobs in stream 1, of which two are currently
 running and the rest are queued. The job that has been in that stream the
 longest is listed first and has been there for 9 minutes and 14 seconds.
 The display also shows running and queued jobs in streams 2 and 3.


 REFERENCES

 procedure Set



 @node !Commands.Scheduler.Enable

 procedure Enable (Job : Job_Id);

 DESCRIPTION

 Resumes the execution of the specified disabled job.


 PARAMETERS

 Job : Job_Id;

 Specifies the job number.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 REFERENCES

 procedure Disable



 @node !Commands.Scheduler.Enabled

 function Enabled (Job : Job_Id) return Boolean;

 DESCRIPTION

 Returns a Boolean indicating whether the specified job is currently enabled
 for execution.


 PARAMETERS

 Job : Job_Id;

 Specifies the job number.


 return Boolean;



 Returns True when the job is enabled.



 @node !Commands.Scheduler.Get

 function Get (Parameter : String) return Integer;

 DESCRIPTION

 Returns the current value for the specified scheduler parameter.

 The names and possible values of the scheduler parameters are listed under
 the Set procedure.


 PARAMETERS

 Parameter : String;

 Specifies any of the strings listed under the Set procedure.


 return Integer;

 Returns the current value for the specified scheduler parameter.


 REFERENCES

 procedure Set



 @node !Commands.Scheduler.Get_Cpu_Priority

 function Get_Cpu_Priority (Job : Job_Id) return Cpu_Priority;

 DESCRIPTION

 Returns the priority at which the specified job is currently running.

 The value ranges from 0 (lowest) through 6 (highest). The higher the
 priority, the more CPU time the job gets.


 PARAMETERS

 Job : Job_Id;

 Specifies the job number.


 return Cpu_Priority;

 Returns the priority at which the specified job is currently running.



 @node !Commands.Scheduler.Get_Cpu_Time_Used

 function Get_Cpu_Time_Used (Job : Job_Id) return Milliseconds;

 DESCRIPTION

 Returns the number of milliseconds of CPU time used by the specified job
 since that job began.


 PARAMETERS

 Job : Job_Id;

 Specifies the job number.


 return Milliseconds;

 Returns the amount of CPU time in milliseconds.



 @node !Commands.Scheduler.Get_Disk_Wait_Load

 procedure Get_Disk_Wait_Load (Last_Sample     : out Load_Factor;
                               Last_Minute     : out Load_Factor;
                               Last_5_Minutes  : out Load_Factor;
                               Last_15_Minutes : out Load_Factor);

 DESCRIPTION

 Returns the average number of tasks waiting for pages from disk.

 The number is averaged over each of four sampling intervals: 100
 milliseconds, 1 minute, 5 minutes, and 15 minutes. Each average is
 multiplied by 100, so that it appears as an integer.


 PARAMETERS

 Last_Sample : out Load_Factor;

 Specifies disk wait load averaged over the last 100 milliseconds.


 Last_Minute : out Load_Factor;

 Specifies disk wait load averaged over the last minute.

                                                                           
 Last_5_Minutes : out Load_Factor;

 Specifies disk wait load averaged over the last 5 minutes.


 Last_15_Minutes : out Load_Factor;

 Specifies disk wait load averaged over the last 15 minutes.



 @node !Commands.Scheduler.Get_Job_Attribute

 function Get_Job_Attribute (Job       : Job_Id;
                             Attribute : String  := "Kind")
                                            return String;

 DESCRIPTION

 Returns the attributes for a job as described in the Set_Job_Attribute
 procedure.


 PARAMETERS

 Job : Job_Id;

 Specifies the job number.


 Attribute : String := "Kind";

 Specifies the attribute to be checked. The only attribute currently
 supported is "Kind", which returns an image of an enumeration of the
 Job_Kind type.


 return String;

 Returns a string representing an enumeration of the Job_Kind type.


 EXAMPLES

 The following program segment illustrates the use of the Get_Job_Attribute
 function to display the job attribute for user job number 244:

      ...
         A: Scheduler.Job_Id := 244;
      begin
         Io.Put(Scheduler.Get_Job_Attribute(Job=>A,Attribute=>"Kind"));
      end;  


 REFERENCES

 procedure Set_Job_Attribute



 @node !Commands.Scheduler.Get_Job_Descriptor

 function Get_Job_Descriptor (Job : Job_Id) return Job_Descriptor;

 DESCRIPTION

 Returns the current value of a job's statistics.


 PARAMETERS

 Job : Job_Id;

 Specifies the job number.


 return Job_Descriptor;

 Returns a record of the Job_Descriptor type. See the Job_Descriptor type
 for further information about the contents of that record.


 REFERENCES

 type Job_Descriptor



 @node !Commands.Scheduler.Get_Job_Kind

 function Get_Job_Kind (Job : Job_Id) return Job_Kind;

 DESCRIPTION

 Returns the current Job_Kind type of the specified job.

 This function specifies one of the six kinds of jobs defined by the Job_Kind
 type: Ce (core editor), Oe (object editor), Attached, Detached, Server, or
 Terminated. The scheduler follows a different scheduling policy for each
 of these job kinds.


 PARAMETERS

 Job : Job_Id;

 Specifies the job number.


 return Job_Kind;

 Returns one of the six kinds of job defined by the Job_Kind type, as listed
 above.



 @node !Commands.Scheduler.Get_Job_State

 function Get_Job_State (Job : Job_Id) return Job_State;

 DESCRIPTION

 Returns the current Job_State type of the specified job.

 This function returns one of the five job states defined by the Job_State
 type: Run, Wait, Idle, Disabled, or Queued. Job_State reflects how the
 scheduler has disposed of a job--that is, whether the job is earmarked for
 running or is considered unrunnable for some reason.


 PARAMETERS

 Job : Job_Id;

 Specifies the job number.


 return Job_State;

 Returns one of the five job states defined by the Job_State type, as listed
 above.



 @node !Commands.Scheduler.Get_Run_Queue_Load

 procedure Get_Run_Queue_Load (Last_Sample     : out Load_Factor;
                               Last_Minute     : out Load_Factor;
                               Last_5_Minutes  : out Load_Factor;
                               Last_15_Minutes : out Load_Factor);

 DESCRIPTION

 Returns the number of runnable, unblocked tasks, averaged over each of
 four sampling intervals: 100 milliseconds, 1 minute, 5 minutes, and 15
 minutes.

 Runnable tasks are neither withheld nor idle, but they are either
 currently consuming CPU time or eligible to consume CPU time.

 Each average is multiplied by 100, so that it appears as an integer.


 PARAMETERS

 Last_Sample : out Load_Factor;

 Specifies the run queue load averaged over the last 100 milliseconds.


 Last_Minute : out Load_Factor;

 Specifies the run queue load averaged over the last minute.


 Last_5_Minutes : out Load_Factor;

 Specifies the run queue load averaged over the last 5 minutes.


 Last_15_Minutes : out Load_Factor;

 Specifies the run queue load averaged over the last 15 minutes.


 REFERENCES

 Session and Job Management (SJM), procedure What.Load



 @node !Commands.Scheduler.Get_Withheld_Task_Load

 procedure Get_Withheld_Task_Load
                             (Last_Sample     : out Load_Factor;
                              Last_Minute     : out Load_Factor;
                              Last_5_Minutes  : out Load_Factor;
                              Last_15_Minutes : out Load_Factor);

 DESCRIPTION

 Returns the number of tasks that are withheld from running, averaged over
 each of four sampling intervals: 100 milliseconds, 1 minute, 5 minutes,
 and 15 minutes.

 Each average is multiplied by 100, so that it appears as an integer.

 A task (job) is withheld from running if it is consuming more than its
 share of resources or if it has been queued or disabled.


 PARAMETERS

 Last_Sample : out Load_Factor;

 Specifies the number of withheld tasks averaged over the last 100
 milliseconds.


 Last_Minute : out Load_Factor;

 Specifies the number of withheld tasks averaged over the last minute.


 Last_5_Minutes : out Load_Factor;

 Specifies the number of withheld tasks averaged over the last 5 minutes.


 Last_15_Minutes : out Load_Factor;

 Specifies the number of withheld tasks averaged over the last 15 minutes.



 @node !Commands.Scheduler.Get_Wsl_Limits

 procedure Get_Wsl_Limits (Job      :     Job_Id;
                           Min, Max : out Natural);

 DESCRIPTION

 Returns the minimum and maximum working set limits that are currently in
 effect for the specified job.

 These limits may be the temporary limits set by the Set_Wsl_Limits
 procedure, or they may be the limits defined by the relevant scheduler
 parameters (Min_ and Max_Ce_Wsl, Min_ and Max_Oe_Wsl, and the like), which
 are described under the Set procedure and in the introduction to this
 package.


 PARAMETERS

 Job : Job_Id;

 Specifies the number of the job whose minimum and maximum working set
 limits the user wants to see.


 Min : out Natural;

 Returns the current minimum working set limit for the given job.


 Max : out Natural;

 Returns the current maximum working set limit for the given job.


 REFERENCES

 procedure Set_Wsl_Limits
 procedure Use_Default_Wsl_Limits



 @node !Commands.Scheduler.Job_Descriptor

 type Job_Descriptor is
     record
         The_Cpu_Priority            : Cpu_Priority;
         The_State                   : Job_State;
         The_Disk_Waits              : Long_Integer;
         The_Time_Consumed           : Milliseconds;
         The_Working_Set_Size        : Natural;
         The_Working_Set_Limit       : Natural;
         The_Milliseconds_Per_Second : Natural;
         The_Disk_Waits_Per_Second   : Natural;
         The_Maps_To                 : Job_Id;
         The_Kind                    : Job_Kind;
         The_Made_Runnable           : Long_Integer;
         The_Total_Runnable          : Long_Integer;
         The_Made_Idle               : Long_Integer;
         The_Made_Wait               : Long_Integer;
         The_Wait_Disk_Total         : Long_Integer;
         The_Wait_Memory_Total       : Long_Integer;
         The_Wait_Cpu_Total          : Long_Integer;
         The_Min_Working_Set_Limit   : Long Integer;
         The_Max_Working_Set_Limit   : Long Integer;
      end record;

 DESCRIPTION

 Specifies a record that contains information returned by many of the
 functions in this package.

 This is a convenient way of storing all of the available information for a
 particular job.

 The_Cpu_Priority component

 Contains the priority at which the specified job is currently running, as
 returned by the Get_Cpu_Priority function. Specifies the value range, from
 0 (lowest) through 6 (highest). The higher the priority, the more CPU time
 the job gets.

 The_State component

 Contains the current job state of the specified job, as returned by the
 Get_Job_State function. Specifies one of the five job states defined by the
 Job_State type: Run, Wait, Idle, Disabled, or Queued. Job state reflects
 how the scheduler has disposed of the job--that is, whether the job is
 earmarked for running or is considered unrunnable for some reason.

 The_Disk_Waits component

 Contains the number of disk waits the specified job has had since last
 initialized, as returned by the Disk_Waits function. A disk wait occurs
 whenever the job has to wait for disk resources. The number of disk waits
 is derived from a combination of page faults and disk I/O operations. A
 high number of disk waits indicates heavy disk activity; a low number
 indicates light disk activity.

 The_Time_Consumed component

 Returns the number of milliseconds of CPU time used by the specified job
 since that job began.

 The_Working_Set_Size component

 Contains the number of pages of memory used by the specified job, as
 returned by the Working_Set_Size function.

 The_Working_Set_Limit component

 Contains the limit that the scheduler places on the job's working set
 size. This limit is the maximum number of pages the job can use without
 penalty. The working set limit for the user job is determined dynamically.
 When the job is created, it is given an initial working set limit, which
 is adjusted at regular intervals to ensure adequate allocation of pages to
 all jobs.

 The value of the job's initial working set limit depends on the kind of
 job it is. The values of scheduler parameters such as Min_Ce_Wsl,
 Min_Oe_Wsl, and so on determine the initial working set limit for the
 job.

 The_Milliseconds_Per_Second component

 Contains the number of milliseconds of CPU time the job has used in the
 last 5-second evaluation interval, as shown in the CPU MS/S field of the
 display resulting from execution of the State procedure.

 The_Disk_Waits_Per_Second component

 Contains the number of disk waits the job had in the last 5-second
 evaluation interval, as shown by the Disk DW/S field of the display
 resulting from execution of the State procedure.

 The_Maps_To component

 Contains the core editor (if any) the job is grouped with for CPU
 scheduling purposes, as shown by the Map To field of the display
 resulting from execution of the State procedure.

 The_Kind component

 Contains the policy used by the scheduler to allocate resources to the
 job, as in the Job_Kind type.

 In general, Ce, Oe, and Attached jobs are interactive and require enough
 resources for constant forward progress. Detached jobs (and aged Attached
 jobs) are not interactive and therefore do not require a constant supply
 of resources.

 The_Made_Runnable component

 Contains the number of times the job entered the Run state. For further
 information, see "Job Kinds" in the introduction to this package.

 The_Total_Runnable component

 Contains the number of times the job was available to enter the Run state.
 For further information, see "Job Kinds" in the introduction to this
 package.

 The_Made_Idle component

 Contains the number of times the job entered the Idle state. For further
 information, see "Job Kinds" in the introduction to this package.

 The_Made_Wait component

 Contains the number of times the job entered the Wait state. For further
 information, see "Job Kinds" in the introduction to this package.

 The following three components give information about why the job went
 into the Wait state.

 The_Wait_Disk_Total component

 Contains the number of times the job entered the Wait state because it was
 waiting for disk space.

 The_Wait_Memory_Total component

 Contains the number of times the job entered the Wait state because it was
 waiting for memory.

 The_Wait_Cpu_Total component

 Contains the number of times the job entered the Wait state because it was
 waiting for CPU time.

 The_Min_Working_Set_Limit component

 Contains the minimum working set limit that is currently in effect for the
 specified job.

 This limit may be the temporary limit set by the Set_Wsl_Limits procedure,
 or it may be the limit defined by the relevant scheduler parameters
 (Min_Ce_Wsl, Min_Oe_Wsl, and the like), which are described under the
 Set procedure and in the introduction to this package.

 The_Max_Working_Set_Limit component

 Returns the maximum working set limits that are currently in effect for
 the specified job.

 This limit may be the temporary limit set by the Set_Wsl_Limits procedure,
 or it may be the limit defined by the relevant scheduler parameters
 (Max_Ce_Wsl, Max_Oe_Wsl, and the like), which are described under the
 Set procedure and in the introduction to this package.


 REFERENCES

 function Get_Job_Descriptor
 procedure Set
 procedure State
 generic formal procedure Traverse_Job_Descriptors.Put



 @node !Commands.Scheduler.Job_Id

 subtype Job_Id is Machine.Job_Id;

 DESCRIPTION

 Specifies the form of Job_Id.

 Job_Ids are assigned uniquely for each instance of system activity.
 Job_Ids are often referred to as job numbers.



 @node !Commands.Scheduler.Job_Kind

 type Job_Kind is (Ce, Oe, Attached, Detached, Server, Terminated);

 DESCRIPTION

 Determines the policy used by the scheduler to allocate resources to a
 job.

 In general, Ce, Oe, and Attached jobs are interactive and require enough
 resources for constant forward progress. Detached jobs (and aged Attached
 jobs; see the Attached enumeration, below) are not interactive and
 therefore do not require a constant supply of resources.


 ENUMERATIONS


 Attached

 Specifies that the job is a foreground job; the message-window banner
 displays ...running while an Attached job executes. An Attached job is
 scheduled to receive its share of the foreground CPU time until the
 Foreground_Time_Limit is reached. (Foreground_Time_Limit is set using the
 Set procedure.) After the time limit is reached, the job is aged. The term
 aged means that although it is still attached, the job receives a smaller
 amount of CPU time and is subject to queuing in the background job
 streams, as if it were detached.


 Ce

 Specifies that the job (a core editor) is scheduled to receive its share of
 foreground CPU time.


 Detached

 Specifies that the job is running in the background, either started in the
 background by the !Commands.Command.Spawn procedure or put there by the
 !Commands.Job.Interrupt procedure. A Detached job is eligible to receive
 CPU time, although it generally receives less CPU time than an Attached
 job. A Detached job is subject to queuing on a background job stream.


 Oe

 Specifies that the job (an object editor) is scheduled to receive its share
 of foreground CPU time.


 Server

 Specifies that the job is a Server, which is a background job that must
 always have resources available to it when it needs them. An example of a
 Server is the print spooler. A Server is allocated the resources of a
 background job; however, unlike other background jobs, a Server is not
 subject to queuing in the background job streams, so that it is always
 eligible to run.


 Terminated

 Specifies that the job has completed. A Terminated job remains until its
 number (Job_Id) is reused for another job.



 @node !Commands.Scheduler.Job_State

 type Job_State is (Run, Wait, Idle, Disabled, Queued);

 DESCRIPTION

 Indicates how the scheduler has disposed of a job--that is, whether or not
 the job is eligible for CPU time.

 This information is displayed in the S column of the !Commands.What.Users
 display.


 ENUMERATIONS


 Disabled

 Specifies that the job is ineligible for CPU time because an external agent
 has disabled it, for example, using the !Commands.Job.Disable procedure or
 the Scheduler.Disable procedure.


 Idle

 Specifies that the job uses no CPU time and has no unblocked tasks. For
 example, the print spooler remains Idle until called.


 Queued

 Specifies that the job is in a background job stream but not currently in
 the Run or Wait (withheld) state. A Queued job is a background job that is
 ineligible for CPU time until one or more other jobs have completed.


 Run

 Specifies that the job is eligible for CPU time, providing its priority is
 high enough.


 Wait

 Specifies that the job has been withheld from running by the scheduler. (A
 withheld job is temporarily ineligible for CPU time.) The scheduler puts
 a job in the Wait state if:

 *  The job has already used more than its share of CPU time and the system
    load is too high.

 *  The job is waiting for pages from disk and the disk wait load is too
    high.



 @node !Commands.Scheduler.Load_Factor

 subtype Load_Factor is Natural;

 DESCRIPTION

 Defines a representation for the load on the system.

 When multiplied by 100, the load factor is the number of tasks waiting in
 a queue. For example, for a given interval, if an average of 1.3 tasks are
 waiting for a page from disk, then the disk wait load is 130.



 @node !Commands.Scheduler.Milliseconds

 subtype Milliseconds is Long_Integer;

 DESCRIPTION

 Defines a way of representing an amount of time in milliseconds.



 @node !Commands.Scheduler.Set

 procedure Set (Parameter : String    := "";
                Value     : Integer);

 DESCRIPTION

 Sets the specified scheduler parameter to the specified value.

 The Set procedure allows the user to set one parameter at a time. The
 executing job must have operator capability.
                                                                           
 The user can change scheduler parameters to adjust aspects of CPU
 scheduling, memory scheduling, disk scheduling, and background job
 streams. The descriptions of the scheduler parameters below assume that
 the user has read the introduction to this package for general
 information about the scheduler.

 The Display procedure displays the current values for scheduler
 parameters. The user can also use the Get function to get the current
 value for a given scheduler parameter.


 PARAMETERS

 Parameter : String := "";

 Specifies the scheduler parameter whose value is to be set. The acceptable
 string names for these parameters are listed in the following tables. In
 addition, the value "defaults" restores all parameters to their default
 values.


 Value : Integer;

 Specifies integer values for scheduler parameters. The acceptable values
 are listed in the following tables.

 There are scheduler parameters for adjusting CPU scheduling, memory
 scheduling, disk scheduling, and background job streams. The following
 tables summarize the string names of these parameters, their possible
 values, and their default values. The parameters are discussed in greater
 detail following the tables.

                  Table 1    Scheduler Parameters for CPU
              ---------------------------------------------- 
             |              |           |    |              |
             |              |           |Defa|              |
             |Parameter     |Range of   |ult |Description   |
             |              |Values     |Valu|              |
             |              |           |e   |              |
              ---------------------------------------------- 
             |              |           |    |              |
             |Cpu_Scheduling|0 or 1     |1   |Specifies     |
             |              |(off or on)|    |whether to    |
             |              |           |    |disable (0)   |
             |              |           |    |or enable (1) |
             |              |           |    |CPU           |
             |              |           |    |scheduling.   |
              ---------------------------------------------- 
             |              |           |    |              |
             |Percent_For_  |0..90      |20  |Specifies the |
             |Background    |(percent)  |    |minimum       |
             |              |           |    |percentage of |
             |              |           |    |CPU allo-     |
             |              |           |    |cated to      |
             |              |           |    |background    |
             |              |           |    |jobs.         |
              ---------------------------------------------- 
             |              |           |    |              |
             |Min_          |-5000..0   |-250|Specifies the |
             |Foreground_   |(millisecon|    |maximum debt  |
             |Budget        |ds)        |    |that a job's  |
             |              |           |    |foreground    |
             |              |           |    |budget can    |
             |              |           |    |show.         |
              ---------------------------------------------- 
             |              |           |    |              |
             |Max_          |0..5000    |250 |Specifies the |
             |Foreground_   |(millisecon|    |maximum credit|
             |Budget        |ds)        |    |that a job's  |
             |              |           |    |foreground    |
             |              |           |    |budget can    |
             |              |           |    |show.         |
              ---------------------------------------------- 
             |              |           |    |              |
             |Withhold_Run_ |0..900     |130 |Specifies the |
             |Load          |(Load_     |    |minimum run   |
             |              |Factor)    |    |load at which |
             |              |           |    |the scheduler |
             |              |           |    |can withhold  |
             |              |           |    |jobs.         |
              ---------------------------------------------- 
             |              |           |    |              |
             |Withhold_     |0 or 1     |0   |Specifies     |
             |Multiple_Jobs |(False or  |    |whether or not|
             |              |True)      |    |multiple      |
             |              |           |    |additional    |
             |              |           |    |jobs can be   |
             |              |           |    |withheld at a |
             |              |           |    |time.         |
              ---------------------------------------------- 



                 Table 2    Scheduler Parameters for Memory
              ---------------------------------------------- 
             |              |           |    |              |
             |              |           |Defa|              |
             |Parameter     |Range of   |ult |Description   |
             |              |Values     |Valu|              |
             |              |           |e   |              |
              ---------------------------------------------- 
             |              |           |    |              |
             |Memory_       |0 or 1     |1   |Specifies     |
             |Scheduling    |(off or on)|    |whether to    |
             |              |           |    |disable (0)   |
             |              |           |    |or enable (1) |
             |              |           |    |memory        |
             |              |           |    |scheduling.   |
              ---------------------------------------------- 
             |              |           |    |              |
             |Environment_  |1..memory  |1100|Specifies the |
             |Wsl           |size       |0   |working set   |
             |              |(pages)    |    |limit for the |
             |              |           |    |Environment.  |
              ---------------------------------------------- 
             |              |           |    |              |
             |Daemon_Wsl    |1..memory  |200 |Specifies the |
             |              |size       |    |working set   |
             |              |(pages)    |    |limit for jobs|
             |              |           |    |started by the|
             |              |           |    |system daemon.|
              ---------------------------------------------- 
             |              |           |    |              |
             |Min_Ce_Wsl    |1..max_ce_ |150 |Specifies the |
             |              |wsl        |    |minimum       |
             |              |           |    |working set   |
             |              |           |    |limit for     |
             |              |           |    |core-         |
             |              |           |    |editor jobs.  |
              ---------------------------------------------- 
             |              |           |    |              |
             |Max_Ce_Wsl    |min..memory|500 |Specifies the |
             |              |size       |    |maximum       |
             |              |           |    |working set   |
             |              |           |    |limit for     |
             |              |           |    |core-         |
             |              |           |    |editor jobs.  |
              ---------------------------------------------- 
             |              |           |    |              |
             |Min_Oe_Wsl    |1..max_oe_ |75  |Specifies the |
             |              |wsl        |    |minimum       |
             |              |           |    |working set   |
             |              |           |    |limit for     |
             |              |           |    |object-editor |
             |              |           |    |jobs.         |
              ---------------------------------------------- 
             |              |           |    |              |
             |Max_Oe_Wsl    |min..memory|750 |Specifies the |
             |              |size       |    |maximum       |
             |              |           |    |working set   |
             |              |           |    |limit for     |
             |              |           |    |object-editor |
             |              |           |    |jobs.         |
              ---------------------------------------------- 
             |              |           |    |              |
             |Min_Attached_ |1..max_    |50  |Specifies the |
             |Wsl           |attached_  |    |minimum       |
             |              |wsl        |    |working set   |
             |              |           |    |limit for     |
             |              |           |    |attached jobs.|
              ---------------------------------------------- 
             |              |           |    |              |
             |Max_Attached_ |min..memory|2000|Specifies the |
             |Wsl           |size       |    |maximum       |
             |              |           |    |working set   |
             |              |           |    |limit for     |
             |              |           |    |attached jobs.|
              ---------------------------------------------- 
             |              |           |    |              |
             |Min_Detached_ |1..max_    |50  |Specifies the |
             |Wsl           |detached_  |    |minimum       |
             |              |wsl        |    |working set   |
             |              |           |    |limit for     |
             |              |           |    |detached jobs.|
              ---------------------------------------------- 
             |              |           |    |              |
             |Max_Detached_ |min..memory|4000|Specifies the |
             |Wsl           |size       |    |maximum       |
             |              |           |    |working set   |
             |              |           |    |limit for     |
             |              |           |    |detached jobs.|
              ---------------------------------------------- 
             |              |           |    |              |
             |Min_Server_Wsl|1..max_    |75  |Specifies the |
             |              |server_wsl |    |minimum       |
             |              |           |    |working set   |
             |              |           |    |limit for     |
             |              |           |    |servers.      |
              ---------------------------------------------- 
             |              |           |    |              |
             |Max_Server_Wsl|min..memory|1000|Specifies the |
             |              |size       |    |maximum       |
             |              |           |    |working set   |
             |              |           |    |limit for     |
             |              |           |    |servers.      |
              ---------------------------------------------- 
             |              |           |    |              |
             |Min_Available_|0..memory  |1024|Specifies the |
             |Memory        |size       |    |minimum number|
             |              |(pages)    |    |of pages of   |
             |              |           |    |memory that   |
             |              |           |    |should always |
             |              |           |    |be available  |
             |              |           |    |for           |
             |              |           |    |distribution. |
              ---------------------------------------------- 
             |              |           |    |              |
             |Wsl_Decay_    |0..2000    |50  |Specifies the |
             |Factor        |(pages)    |    |amount by     |
             |              |           |    |which a user  |
             |              |           |    |job's work-   |
             |              |           |    |ing set limit |
             |              |           |    |is decreased  |
             |              |           |    |every 5       |
             |              |           |    |seconds.      |
              ---------------------------------------------- 
             |              |           |    |              |
             |Wsl_Growth_   |0..2000    |50  |Specifies the |
             |Factor        |(pages)    |    |amount by     |
             |              |           |    |which a user  |
             |              |           |    |job's work-   |
             |              |           |    |ing set limit |
             |              |           |    |is increased. |
              ---------------------------------------------- 
             |              |           |    |              |
             |Page_         |0..64      |1   |Specifies the |
             |Withdrawal_   |(640       |    |rate at which |
             |Rate          |pages/     |    |pages are     |
             |              |second)    |    |withdrawn     |
             |              |           |    |from memory.  |
              ---------------------------------------------- 



                  Table 3    Scheduler Parameters for Disk
              ---------------------------------------------- 
             |              |           |    |              |
             |              |           |Defa|              |
             |Parameter     |Range of   |ult |Description   |
             |              |Values     |Valu|              |
             |              |           |e   |              |
              ---------------------------------------------- 
             |              |           |    |              |
             |Disk_         |0 or 1     |1   |Specifies     |
             |Scheduling    |(off or on)|    |whether to    |
             |              |           |    |disable (0)   |
             |              |           |    |or enable (1) |
             |              |           |    |disk          |
             |              |           |    |scheduling.   |
              ---------------------------------------------- 
             |              |           |    |              |
             |Max_Disk_Load |positive   |250 |Specifies the |
             |              |(Load_     |    |maximum       |
             |              |Factor)    |    |acceptable    |
             |              |           |    |disk wait load|
             |              |           |    |before jobs   |
             |              |           |    |are withheld. |
              ---------------------------------------------- 
             |              |           |    |              |
             |Min_Disk_Load |positive   |200 |Specifies the |
             |              |(Load_     |    |minimum       |
             |              |Factor)    |    |acceptable    |
             |              |           |    |disk wait     |
             |              |           |    |load.         |
              ---------------------------------------------- 



         Table 4    Scheduler Parameters for Background Job Streams
              ---------------------------------------------- 
             |              |           |    |              |
             |              |           |Defa|              |
             |Parameter     |Range of   |ult |Description   |
             |              |Values     |Valu|              |
             |              |           |e   |              |
              ---------------------------------------------- 
             |              |           |    |              |
             |Foreground_   |positive   |1800|Specifies how |
             |Time_Limit    |(seconds)  |    |long an       |
             |              |           |    |attached job  |
             |              |           |    |can run be-   |
             |              |           |    |fore it gets  |
             |              |           |    |allocated     |
             |              |           |    |background    |
             |              |           |    |resources.    |
              ---------------------------------------------- 
             |              |           |    |              |
             |Background_   |positive   |3   |Specifies the |
             |Streams       |(streams)  |    |number of     |
             |              |           |    |background job|
             |              |           |    |streams.      |
              ---------------------------------------------- 
             |              |           |    |              |
             |Stream_Time N |1..43200   |2,8,|Specifies the |
             |              |(minutes)  |50  |time limit    |
             |              |           |    |associated    |
             |              |           |    |with the job  |
             |              |           |    |stream        |
             |              |           |    |numbered N.   |
             |              |           |    |Each stream   |
             |              |           |    |has its own   |
             |              |           |    |default.      |
              ---------------------------------------------- 
             |              |           |    |              |
             |Stream_Jobs N |0..5       |2,1,|Specifies the |
             |              |(jobs)     |0   |number of jobs|
             |              |           |    |that can be   |
             |              |           |    |running on the|
             |              |           |    |job streams   |
             |              |           |    |numbered N.   |
             |              |           |    |(Each stream  |
             |              |           |    |has its own   |
             |              |           |    |default.)     |
              ---------------------------------------------- 
             |              |           |    |              |
             |Strict_Stream_|0 or 1     |0   |Specifies     |
             |Policy        |(False or  |    |whether strict|
             |              |True)      |    |stream policy |
             |              |           |    |is in effect  |
             |              |           |    |(True) or not |
             |              |           |    |(False).      |
              ---------------------------------------------- 




 Parameters for CPU Scheduling
 

 Cpu_Scheduling

 Specifies whether to enable or disable CPU scheduling independently of
 memory or disk scheduling. When CPU scheduling is disabled, all jobs are
 run according to Ada task priorities; no attempt is made to guarantee
 equal time to each foreground job. The value of Cpu_Scheduling is either 0
 (disabled) or 1 (enabled). The default value is 1 (enabled).
 

 Percent_For_Background

 Specifies the minimum percentage of the CPU that is allocated to background
 jobs. The default value, 20, means that at least 20% of the CPU can be
 used by the background job stream at any time.
 

 Min_Foreground_Budget

 Specifies the limit on how much accumulated debt a job's foreground budget
 can show. Excess debt is ignored.

 The value of Min_Foreground_Budget is a negative number of milliseconds
 from -5,000 through 0. The default value is -250 milliseconds.
 

 Max_Foreground_Budget

 Specifies the limit on how much accumulated credit a job's foreground
 budget can show. Excess credit is ignored. The wider the range between
 Max_ and Min_Foreground_Budget, the more sensitive the scheduler is to
 giving jobs equal time.

 The value of Max_Foreground_Budget is a positive number of milliseconds
 from 0 through 5,000. The default value is 250 milliseconds.
 

 Withhold_Run_Load

 Specifies the minimum run load at which the scheduler is permitted to
 withhold jobs. The higher the value, the more heavily loaded the system
 must be before the scheduler can withhold a job for exceeding its
 allocated time.

 The value for Withhold_Run_Load must be an integer from 0 through 900. The
 default value for Withhold_Run_Load is 130. The run load value is the
 average number of tasks that are eligible to run, multiplied by 100.
 

 Withhold_Multiple_Jobs

 Specifies whether the scheduler is restricted to withholding only one more
 job per review interval (in addition to any jobs that were withheld on
 previous intervals). When the value for Withhold_Multiple_Jobs is 1
 (True), the scheduler can withhold multiple jobs in response to
 oversubscribed CPU resources. When the value is 0 (False), the scheduler
 can withhold at most one job at the end of a single interval.

 The default value for Withhold_Multiple_Jobs is 0 (False).


 Parameters for Memory Scheduling
 

 Memory_Scheduling

 Specifies whether to enable or disable memory scheduling independently of
 CPU or disk scheduling. The value of Memory_Scheduling is either 0
 (disabled) or 1 (enabled). The default value is 1 (enabled).
 

 Environment_Wsl

 Specifies the working set limit for the Environment. A higher value gives
 the Environment more pages, so that there are fewer pages for daemon and
 user jobs. A lower value gives the Environment fewer pages, so that there
 are more pages for daemon and user jobs.

 The value for Environment_Wsl is an integer from 0 to the number of pages
 in main memory. However, if the user specifies a value that is too high to
 leave adequate resources for other jobs, an error message is displayed.
 The default value for Environment_Wsl is 11,000.
 

 Daemon_Wsl

 Specifies the working set limit for jobs started by the system daemon (see
 package Daemon). A higher value gives the daemon more pages, so that there
 are fewer pages for the Environment and user jobs. A lower value gives the
 daemon fewer pages, so that there are more pages for the Environment and
 user jobs.

 The value for Daemon_Wsl is an integer from 0 to the number of pages in
 main memory. However, if the user specifies a value that is too high to
 leave adequate resources for other jobs, an error message is displayed.
 The default value for Daemon_Wsl is 200.

 
 Min_Ce_Wsl,Min_Oe_Wsl,Min_Attached_Wsl,Min_Detached_Wsl,Min_Server_Wsl

 Specifies the minimum working set limit for the following kinds of jobs:
 core editor (Ce), object editor (Oe), Attached, Detached, and Server,
 respectively. That is, when a job's working set limit is decreased by
 Wsl_Decay_Factor, that working set limit cannot fall below the value set
 by the appropriate parameter. The value for each parameter also determines
 the initial working set limit that is given to each kind of job upon
 creation.

 The value for each parameter is an integer number of pages from 1 to the
 value of the corresponding Max_ parameter (see below). For a given job, the
 Set_Wsl_Limits procedure temporarily overrides the minimum working set
 limit set by any of these parameters.

 
 Max_Ce_Wsl, Max_Oe_Wsl, Max_Attached_Wsl, Max_Detached_Wsl, Max_Server_Wsl

 Specifies the maximum working set limit for the following kinds of jobs:
 core editor (Ce), object editor (Oe), Attached, Detached, and Server,
 respectively. That is, when a job's working set limit is increased by
 Wsl_Growth_Factor, that working set limit cannot exceed the value set by
 the appropriate parameter. These parameters can be used to give
 preference to some kinds of jobs over others. For example, the default
 values for Max_Detached_Wsl and Max_Attached_Wsl give background user
 jobs twice as much memory as foreground user jobs.

 The value for Max_Ce_Wsl is an integer number of pages from the value of
 the corresponding Min_ parameter (see above) to the memory size. For a
 given job, the Set_Wsl_Limits procedure temporarily overrides the maximum
 working set limit set by any of these parameters.
 

 Min_Available_Memory

 Specifies the minimum number of pages that should always be available to
 the scheduler for dynamic distribution among jobs. If the number of
 reserve pages falls below the minimum, the scheduler withholds jobs from
 running.

 If the value is large, more pages are reserved and fewer pages are
 actually being used, possibly resulting in performance decrease. If the
 value is small, fewer pages are reserved, so that memory is more fully
 utilized.

 The value of Min_Available_Memory is an integer number of pages from 0
 through 2,000. The default value for Min_Available_Memory is 1,024.
 

 Wsl_Decay_Factor

 Specifies the amount by which a user job's working set limit is
 automatically decreased every 5 seconds.

 The value for Wsl_Decay_Factor is an integer number of pages from 0
 through 2,000. The default value for Wsl_Decay_Factor is 50.
 

 Wsl_Growth_Factor

 Specifies the amount by which a user job's working set limit is
 automatically increased if the job's working set size has exceeded the
 working set limit during a review interval.

 The value for Wsl_Growth_Factor is an integer number of pages from 0
 through 2,000. The default value for Wsl_Growth_Factor is 50.
 

 Page_Withdrawal_Rate

 Specifies the rate at which pages are withdrawn from memory. A higher Page-
 _Withdrawal_Rate means that the scheduler makes more passes through memory
 during a given period of time, so that pages are withdrawn more
 frequently. Therefore, when the Page_Withdrawal_Rate is high, the
 scheduler can charge pages to jobs with more accuracy and can check large
 jobs for reclaimable pages more frequently. However, the increased
 activity may degrade the scheduler's performance.

 The value for Page_Withdrawal_Rate is an integer from 0 through 64. This
 value designates a multiple of the following unit rate: 640 pages per
 second. When Page_Withdrawal_Rate is 0, no pages are withdrawn. When
 Page_Withdrawal_Rate is 1 (the default value), then the scheduler passes
 through memory at a rate of 1 X 640 pages per second. At this rate, the
 scheduler makes a complete pass every 51.2 seconds.


 Parameters for Disk Scheduling

 
 Disk_Scheduling

 Specifies whether to enable or disable disk scheduling independently of CPU
 or memory scheduling. The value of Disk_Scheduling is either 0 (disabled)
 or 1 (enabled). The default value is 1.
 

 Max_Disk_Load

 Specifies the maximum acceptable disk wait load before the scheduler
 withholds jobs that are waiting for disk resources. The disk wait load is
 the number of tasks waiting to read or write a page from disk, averaged
 over an interval of time and multiplied by 100.

 Specifies whether to enable or disable disk scheduling independently of CPU
 or memory scheduling. The value of Disk_Scheduling is either 0 (disabled)
 or 1 (enabled). The default value is 1.

 A high Max_Disk_Load value permits increased disk activity; with more jobs
 waiting on the disk, performance for individual jobs may decrease. A low
 Max_Disk_Load value restricts disk availability; with fewer jobs waiting
 on the disk, more jobs are withheld and performance for individual running
 jobs may improve. Together, the Max_Disk_Load and Min_Disk_Load
 parameters define a range of acceptable stress on the disks. The wider
 the range, the less sensitive the scheduler is to changes in the disk wait
 load.

 The value for Max_Disk_Load is a positive integer that must be greater
 than the value for Min_Disk_Load. The default value for Max_Disk_Load is
 250 (that is, an average of 2.5 tasks waiting for disk resources at any
 given time). See also the Get_Disk_Wait_Load procedure and the Load_Factor
 subtype.

 
 Min_Disk_Load

 Specifies the minimum acceptable disk wait load before action is taken. If
 the disk wait load falls below the limit specified by Min_Disk_Load, the
 scheduler releases withheld jobs that were waiting for disk resources.

 The value for Min_Disk_Load is a positive integer that must be greater
 than the value for Max_Disk_Load. The default value for Min_Disk_Load is
 200 (that is, an average of two tasks waiting for disk resources at any
 given time). See also the Get_Disk_Wait_Load procedure and the Load_Factor
 subtype.

 
 Parameters for Background Job Streams                                      

 
 Foreground_Time_Limit

 Specifies how long, in seconds, an attached job can run before it is
 allocated background job resources and is subject to queuing on
 background job streams. To give more preference to foreground jobs, use a
 higher value. To encourage users to run long jobs in the background, use a
 lower value.

 The default value for Foreground_Time_Limit is 1,800 seconds (30 minutes).

 
 Background_Streams

 Specifies the number of background job streams. When there are multiple job
 streams, they are numbered from 1 to the value of Background_Streams.

 The default for Background_Streams is 3.

 
 Stream_Time N

 Specifies the time limit, in minutes, associated with the job stream
 numbered N. Stream_Time limits the time elapsed since a job began running
 on job stream N.

 Note that allowing many jobs to remain queued on job streams may cause a
 shortage of disk space. Jobs are more likely to be requeued before they
 finish if the Stream_Time value for a stream is low, whereas a high
 Stream_Time value permits jobs to run to completion without being
 requeued.

 The value for each Stream_Time parameter is a number of minutes from 1
 through 43,200. The default values for Stream_Times 1 through 3 are 2, 8,
 and 50 minutes, respectively.
 

 Stream_Jobs N

 Specifies the number of jobs that can be running on the job stream numbered
 N.

 The value for each Stream_Jobs parameter is an integer from 0 through 5. A
 value of 0 makes sense only if the value of Strict_Stream_Policy is 0
 (False). The default values for Stream_Jobs 1 through 3 are 2, 1, and 0,
 respectively.
 

 Strict_Stream_Policy

 Specifies whether strict stream policy is in effect (True) or not (False).

 The value for Strict_Stream_Policy is either 0 (False) or 1 (True). The
 default is 0.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 REFERENCES

 procedure Display
 function Get
 procedure Get_Disk_Wait_Load
 subtype Load_Factor



 @node !Commands.Scheduler.Set_Job_Attribute

 procedure Set_Job_Attribute (Job       : Job_Id;
                              Attribute : String  := "Kind";
                              Value     : String  := "Server");

 DESCRIPTION

 Permits the user to change a job attribute.


 PARAMETERS

 Job : Job_Id;

 Specifies the number of the job.


 Attribute : String := "Kind";

 Specifies the attribute. Currently the only attribute supported is "Kind",
 which permits the user to specify which kind of job the current job should
 be. This is useful in specifying jobs as servers.


 Value : String := "Server";

 Specifies the value for the attribute. The default sets the job kind to a
 server.

 The allowable values are the string representations of the enumerations of
 the Job_Kind type: Ce, Oe, Attached, Detached, Server, and Terminated.



 @node !Commands.Scheduler.Set_Wsl_Limits

 procedure Set_Wsl_Limits (Job      : Job_Id;
                           Min, Max : Natural);

 DESCRIPTION

 Sets temporary minimum and maximum working set limits that apply only to
 the specified job.

 For the duration of that job, these temporary limits override the limits
 defined by the relevant scheduler parameters (Min_ and Max_Ce_Wsl, Min_ and
 Max_Oe_Wsl, and the like), which are described under the Set procedure and
 in the introduction to this package. Note that, while the job is running,
 the user can use the Use_Default_Wsl_Limits procedure to revert to the
 limits that are defined by the scheduler parameters.


 PARAMETERS

 Job : Job_Id;

 Specifies the number of the job whose minimum and maximum working set
 limits the user wants to set.


 Min : Natural;

 Specifies the temporary minimum working set limit for the given job. This
 value must be greater than 0 and less that the value of Max.


 Max : Natural;

 Specifies the temporary maximum working set limit for the given job. This
 value must be greater than the value of Min and less than the memory size.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 REFERENCES

 procedure Get_Wsl_Limits
 procedure Set
 procedure Use_Default_Wsl_Limits



 @node !Commands.Scheduler.State

 procedure State;

 DESCRIPTION

 Displays the current scheduler state.


 EXAMPLES

 The command:

   Scheduler.State;

 produces a display such as the following:

 Job   K/S/P  Stat     CPU      CPU   Disk   Disk    WSet   WSet  Map   Run
               Age   Seconds    MS/S  DW/S   Waits   Size  Limit   To  Ratio
 -----------------------------------------------------------------------------
   4   A/R/0  ++++  23149.914   23.8   0.0  ++++++  11001  11000       1.00
   5   A/R/0  ++++  32280.679    0.0   0.0    5867    112    200       1.00
 147   C/I/6  3604  00353.021    0.0   0.0   11980    143    150       0.96
 152   C/R/6    19  00316.611   21.4   0.0    2557    147    150       0.98
 160   T/I/6  ++++  00001.235    0.0   0.0      12      1      0       0.91
 162   A/R/6    18  00000.928    0.0   0.0      12    284    300  152  1.00
 163   T/I/6  ++++  00046.213    0.0   0.0     855      8      0       0.99
 164   T/I/6  ++++  00001.113    0.0   0.0       7      1      0       0.65
 170   T/I/6  ++++  00014.207    0.0   0.0    1259      1      0       0.98
 171   T/I/6  ++++  00013.352    0.0   0.0     226      2      0       0.97
 174  *S/I/0  ++++  00000.026    0.0   0.0       2      6     50       1.00
 . . .
 247  *S/I/0  1443  00005.098    0.0   0.0     556      5     75       1.00
 248   C/I/6  ++++  00006.159    0.0   0.0     275      2     10       1.00
 249   C/I/6  ++++  00008.703    0.0   0.0     378      4     10       1.00
 250   C/I/6  ++++  00005.858    0.0   0.0     215      2     10       1.00
 251  *S/I/0  2090  00971.451    0.0   0.0     102     47     75       1.00
 252   C/I/6  ++++  00004.739    0.0   0.0     239      3     10       1.00
 253   C/I/6  ++++  00008.264    0.0   0.0     520      2     10       1.00
 254   T/I/6  ++++  00000.348    0.0   0.0      17      3      0       0.80
 255   C/I/6  ++++  00000.892    0.0   0.0     125      1     10       1.00

   Run Queue Load     => 3.07, 1.31, 1.25, 1.27
   Disk Wait Load     => 0.00, 0.01, 0.01, 0.01
   Withheld Task Load => 0.00, 0.04, 0.04, 0.04
   Available Memory   => 19593 pages

 The first part of the display lists each job by number along with the
 resources that have currently been allocated to it.

 The values that are displayed for each job include:

 Job                     Specifies the job number.                  

 K/S/P                   Shows the job's Kind, State, and Priority. Values
                         for Kind and State are indicated by their first
                         initial (see Job_Kind type and Job_State type). An
                         asterisk before Kind indicates that the job is
                         being allocated background job resources.
 
 Stat Age                Shows how long, in tenths of a second, a job has
                         been in its current state. A series of plus signs
                         indicates that the time has exceeded the display's
                         range.
 
 CPU Seconds             Shows the total amount of CPU time, in seconds,
                         the job has used since it began.
 
 CPU MS/S                Shows the number of milliseconds of CPU time a job
                         has used in the last 5-second evaluation interval.
 
 Disk DW/S               Shows the number of disk waits a job had in the
                         last 5-second evaluation interval.
 
 Disk Waits              Shows the total number of disk waits a job has had
                         since it began.
 
 WSet Size               Shows the job's current working set size, which is
                         the number of pages of memory that the job is
                         using.
 
 WSet Limit              Shows the current working set limit on the job's
                         working set size.
 
 Map To                  Shows what core editor (if any) the job is grouped
                         with for CPU scheduling purposes.
 
 Run Ratio               Shows the percentage of time the job has run, as
                         compared with the total amount of time the job has
                         either run or been withheld. A value of 1.00 means
                         that the job has never been withheld.


 The next second part of the display shows the various load averages
 computed over four intervals: the last 100 milliseconds, the last minute,
 the last 5 minutes, and the last 15 minutes. (These values are also
 returned by the Get_Run_Queue_Load, Get_Disk_Wait_Load, and
 Get_Withheld_Task_Load procedures.)

 The last line displays the number of currently available pages of reserved
 memory.


 REFERENCES

 procedure Get_Disk_Wait_Load
 procedure Get_Run_Queue_Load
 procedure Get_Withheld_Task_Load



 @node !Commands.Scheduler.Traverse_Job_Descriptors

 generic
     with procedure Put (Descriptor : Job_Descriptor);

 procedure Traverse_Job_Descriptors (First, Last : Job_Id);

 DESCRIPTION

 Calls the generic formal procedure Put to display the job descriptors once
 for each job in the range First .. Last.

 This procedure is used to get a consistent, efficient snapshot of the
 statistics of one or more jobs. For further information about the
 information returned, see the Job_Id subtype.


 PARAMETERS

 First : Job_Id;

 Specifies the number of the first job.


 Last : Job_Id;

 Specifies the number of the last job.



 @node !Commands.Scheduler.Traverse_Job_Descriptors.Put

 procedure Put (Descriptor : Job_Descriptor);

 DESCRIPTION

 Writes the descriptors for the Traverse_Job_Descriptors procedure.

 This procedure is called once by the Traverse_Job_Descriptors procedure
 for each job in the range specified in the call to the
 Traverse_Job_Descriptors procedure.


 PARAMETERS

 Descriptor : Job_Descriptor;

 Specifies the information to be written. See the Job_Descriptors type for
 further information.



 @node !Commands.Scheduler.Use_Default_Wsl_Limits

 procedure Use_Default_Wsl_Limits (Job : Job_Id);

 DESCRIPTION

 Cancels the temporary minimum and maximum working set limits that were set
 by the Set_Wsl_Limits procedure for the specified job.

 While the job is running, this procedure allows the user to revert to the
 limits that are defined by the relevant scheduler parameters (Min_ and
 Max_Ce_Wsl, Min_ and Max_Oe_Wsl, and the like). These limits are described
 under the Set procedure and in the introduction to this package.


 PARAMETERS

 Job : Job_Id;

 Specifies the number of the job for which the default minimum and maximum
 working set limits should be in effect.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 REFERENCES

 procedure Get_Wsl_Limits
 procedure Set
 procedure Set_Wsl_Limits



 @node !Commands.Scheduler.Working_Set_Size

 function Working_Set_Size (Job : Job_Id) return Natural;

 DESCRIPTION

 Returns the number of pages of memory used by the specified job.


 PARAMETERS

 Job : Job_Id;

 Specifies the number of the job.


 return Natural;

 Returns the number of pages of memory used by the specified job.


 RESTRICTIONS

 Execution of this function requires that the executing job have operator
 capability.



 @node !Commands.System_Backup

 The procedures in package System_Backup can be used alone or as part of
 customized procedures to save the Environment state on a regular basis.
 Regular backups ensure that the Environment can be restored with minimal
 loss after a catastrophic system or Environment failure.

 See the System Manager's Guide for more information on the actual steps
 used to take and restore backups, including how to:

 *  Answer a tape-mount request displayed on the operator console following
    the promotion of the Backup command

 *  Assign volume identifiers

    Volume identifiers can be assigned using the Format_Tape procedure
    (described in package Tape) or when responding to a tape-mount request.

 *  Choose among multiple tape-mount requests

 Also refer to the System Manager's Guide for descriptions of other tape
 operations that allow system managers to transfer binary files between
 R1000s using tape (using the Archive.Save and Archive.Restore commands)
 and for information on how to make a DFS (diagnostic file system) backup.


 RESOURCES IN PACKAGE SYSTEM_BACKUP

 The commands in package System_Backup fall into these functional groups:

 Taking a backup: Backup

 Creating a customized backup procedure: Backup_Generic

 Listing previous backups: History


 KEY CONCEPTS FOR PACKAGE SYSTEM_BACKUP

 The Backup command provided in this package can initiate a backup
 immediately or after some specified amount of time, but it cannot perform
 any system adjustments before or after the backup. Therefore, system
 managers normally use commands such as the
 !Commands.Abbreviations.Do_Backup command, which are implemented using the
 Backup_Generic procedure provided in this package. Using instantiations of
 Backup_Generic allows system managers to delay the backup to a specified
 time and to send messages or suspend various system settings for the
 duration of the backup.

 Execution of some of the operations in this package requires that you or
 the executing job have operator capability. This requirement is noted in
 the reference entry if it applies.


 Varieties of Backups

 Regardless of whether the Backup or the Backup_Generic procedure is used,
 the backup process copies the entire Environment onto tape. The three
 varieties of backup are full, primary, and secondary :

 *  Full: Saves the complete Environment, including all user data and
    system information. Full backups are complete and self-sufficient. A
    full backup must be the first backup taken after the system has been
    restored from backup tapes.

 *  Primary: Saves any changes since the last full backup. A primary backup
    cannot be the first backup on a restored system.

 *  Secondary: Saves any changes since the last primary backup. A secondary
    backup cannot be the first backup on a restored system.

 Multiple primary backups can be based on a single full backup; however,
 only one of these primaries can be restored with the full backup.

 Similarly, multiple secondary backups can be based on a single primary
 backup, but only one of these secondaries can be restored with the full
 and primary backup.


 Structure of Backup Tapes

 All varieties of backup write two kinds of information onto tape:

 *  Backup index, which records the system structure

 *  Data, which is all information contained in the Environment

 When backups are taken on 9-track tape drives, the backup index is written
 on a separate tape (also called a blue tape in previous Environment
 releases). When backups are taken on 8-millimeter tape drives, the backup
 index is written immediately following the data on the last data-tape
 cartridge.


 Restoring Backups

 During startup, the system determines whether recovery is needed and asks
 whether you want to proceed with recovery. If you proceed with recovery,
 the system requests the tape containing the backup index so that it can
 initialize the disks. The system then requests the appropriate data tapes
 and loads the data.

 You can recover from a set of backups that includes both full and
 incremental backups only if all the backups are properly "linked" to each
 other. That is:

 *  The secondary backup (if any) must be based on the primary backup in
    the set.

 *  The primary backup must be based on the full backup in the set.

 You can verify these "linkages" by using the History command to look at
 the Taken At and Based On timestamps for each backup.

 After a system is recovered from backup tapes, the next backup taken must
 be a full backup.


 @node !Commands.System_Backup.Backup

 procedure Backup (Variety : Kind := System_Backup.Full);

 DESCRIPTION

 Makes a backup of the specified kind (Full, Primary, or Secondary).

 The default is Full. Note that after a system is recovered from backup
 tapes, the next backup must be a full backup.

 This command is normally not used; instead, most sites use commands such
 as !Commands.Abbreviations.Do_Backup, which instantiate the generic
 procedure Backup_Generic from this package.


 PARAMETERS

 Variety : Kind := System_Backup.Full;

 Specifies a full, primary, or secondary backup. The default is Full.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.

 Backups and disk collection cannot be run at the same time.

 If you have begun a backup and disk collection needs to begin, the backup
 will be terminated by default. To change this default, use the
 !Tools.Disk_Daemon.Set_Backup_Killing (False) procedure, which causes
 the last data tape to be written before disk collection can begin.

 If the disk daemon is running and a backup is attempted, disk collection
 must complete before the backup can begin.

 For further information, see the System Manager's Guide.


 EXAMPLES

 The following command starts a full backup immediately:

   System_Backup.Backup (Full);
 

 REFERENCES

 generic procedure Backup_Generic



 @node !Commands.System_Backup.Backup_Generic

 generic
     with procedure Backup_Starting  (Is_Full        : Boolean);
     with procedure Backup_Finishing (Was_Successful : Boolean);

 procedure Backup_Generic (Variety    : Kind;
                           Wait_Until : String);

 DESCRIPTION

 Provides a more complete form of the Backup procedure.

 The Backup_Generic procedure itself is not used interactively; rather, it
 is instantiated and called with customizable backup commands such as
 !Commands.Abbreviations.Do_Backup. (See the System Manager's Guide for
 more information about this command.)

 A customizable backup command can pass parameters to the Backup_Generic
 procedure to specify:

 *  The kind of backup to be performed (full, primary, or secondary)

 *  The time at which the backup is to begin

 The backup tape can be mounted at any time after the instantiation is
 called and before the backup is scheduled to begin.

 The Backup_Generic procedure provides two formal procedures that can be
 instantiated to set various system characteristics for the duration of
 the backup:

 *  The Backup_Starting formal procedure executes just before the actual
    backup is scheduled to begin.

 *  The Backup_Finishing formal procedure executes immediately after the
    backup finishes.

 Because the !Commands.Abbreviations.Do_Backup command provides a standard
 instantiation for this generic procedure, users do not have to instantiate
 it themselves. However, if desired, a system manager can edit the body
 of !Commands.Abbreviations.Do_Backup to change the standard
 instantiation of the two formal procedures.

 Commands that instantiate and call Backup_Generic require operator
 capability.


 PARAMETERS

 Variety : Kind;

 Specifies a full, primary, or secondary backup.


 Wait_Until : String;

 Specifies the amount of time to wait before starting a backup.


 REFERENCES

 generic formal procedure Backup_Generic.Backup_Finishing
 generic formal procedure Backup_Generic.Backup_Starting



 @node !Commands.System_Backup.Backup_Generic.Backup_Finishing

 procedure Backup_Finishing (Was_Successful : Boolean);

 DESCRIPTION

 Executes immediately after the backup finishes.

 In an instantiation of Backup_Generic, you can use the Backup_Finishing
 procedure to restore various system characteristics that were changed
 just for the duration of the backup.

 In the instantiation provided by the standard
 !Commands.Abbreviations.Do_Backup command, the Backup_Finishing
 procedure restores memory scheduling and snapshot warnings according to
 the settings saved by Backup_Starting.

 If desired, a system manager can edit the body of
 !Commands.Abbreviations.Do_Backup to change the standard instantiation
 of the Backup_Finishing procedure. For example, Backup_Finishing can be
 used to send mail to inform users when the backup has completed.


 PARAMETERS

 Was_Successful : Boolean;

 Specifies whether a backup was successful. If the backup was successful,
 this parameter is set to True.


 REFERENCES

 generic procedure Backup_Generic



 @node !Commands.System_Backup.Backup_Generic.Backup_Starting

 procedure Backup_Starting (Is_Full : Boolean);

 DESCRIPTION

 Executes just before the backup is scheduled to begin.

 In an instantiation of Backup_Generic, you can use the Backup_Starting and
 Backup_Finishing procedures to change various system characteristics
 just for the duration of the backup.

 In the instantiation provided by the standard
 !Commands.Abbreviations.Do_Backup command, the Backup_Starting
 procedure:

 *  Broadcasts a message to all users informing them that a backup is
    beginning

 *  Saves the current memory scheduler and snapshot settings

 *  Turns off memory scheduling and snapshot warnings

 If desired, a system manager can edit the body of
 !Commands.Abbreviations.Do_Backup to change the standard instantiation
 of the Backup_Starting procedure. For example, Backup_Starting can be used
 to turn off disk collection (be sure to use Backup_Finishing to turn on
 disk collection again). This will prevent disk collection from interfering
 with the backup.

 Note: Turning off disk collection is recommended only for backups made on
 the 8-millimeter tape drive, because such backups require significantly
 less time than those made on 9-track tape drives. In any case, turning off
 disk collection is not recommended if the disks are very full.


 PARAMETERS

 Is_Full : Boolean;

 Specifies whether a backup is full or incremental. If the backup is full,
 this parameter is set to True.


 REFERENCES

 generic procedure Backup_Generic



 @node !Commands.System_Backup.History

 procedure History (Entry_Count       : Positive := 10;
                    Full_Backups_Only : Boolean  := False;
                    Tape_Information  : Boolean  := False);

 DESCRIPTION

 Lists the specified number of previous backups.

 By default, this procedure displays history for the ten most recent full,
 primary, and secondary backups. You can use the Full_Backups_Only
 parameter to limit the display to entries for full backups.

 In a backup history display, entries for primary and secondary backups are
 both labeled Incremental Backup. You can distinguish them by looking at
 their timestamps, as follows (see also "Examples," below):

 *  Primary backups are based on full backups; hence, the entry for a
    primary backup contains a Based On date that is identical to the date
    on which the relevant full backup was taken.

 *  Secondary backups are based on primary backups; hence, the entry for a
    secondary backup contains a Based On date that is identical to the
    date on which the relevant primary backup was taken.


 PARAMETERS

 Entry_Count : Positive := 10;

 Specifies the number of the most recent backups that should be included in
 the display.


 Full_Backups_Only : Boolean := False;

 Specifies, when True, that only information on full backups be displayed.
 When False (the default), the display includes information about primary
 and secondary backups as well.


 Tape_Information : Boolean := False;

 Specifies, when True, that the Environment list (in Current_Output) the
 first data tape involved in each backup.


 EXAMPLES

 The command:

   System_Backup.History (Entry_Count       => 10,
                          Full_Backups_Only => False,
                          Tape_Information  => False);

 displays information about the last ten full, primary, and/or secondary
 backups. A portion of this display is shown below:

   Incremental Backup 371 Taken At 11-JUL-91 09:58:35 Based On 09-JUL-91
   07:43:19
     Blue Tape Vol Name => BACKUP, 11-JUL-91 09:55:19 3
     Blue Tape Vol Id   => 020900
     Data Tape Vol Name => BACKUP, 11-JUL-91 09:55:19 3
     Data Tape Vol Id   => 020900
   Incremental Backup 370 Taken At 09-JUL-91 07:43:19 Based On 06-JUL-91
   08:56:25
     Blue Tape Vol Name => BACKUP, 09-JUL-91 07:40:22 3
     Blue Tape Vol Id   => 024300
     Data Tape Vol Name => BACKUP, 09-JUL-91 07:40:22 3
     Data Tape Vol Id   => 024300
   Full Backup 369 Taken At 06-JUL-91 08:56:25
     Blue Tape Vol Name => BACKUP, 06-JUL-91 08:49:22 3
     Blue Tape Vol Id   => 029900
     Data Tape Vol Name => BACKUP, 06-JUL-91 08:49:22 3
     Data Tape Vol Id   => 029900

   ...

   Full Backup 362 Taken At 22-JUN-91 07:45:47
     Blue Tape Vol Name => BACKUP, 22-JUN-91 07:41:51 3
     Blue Tape Vol Id   => 028700
     Data Tape Vol Name => BACKUP, 22-JUN-91 07:41:51 3
     Data Tape Vol Id   => 028700

 This display of backup history shows full, primary, and secondary backups:

 *  Incremental Backup 370 is a primary backup that is based on Full Backup
    369 (the Based On timestamp of the incremental is the same as the Taken
    At date of the full backup).

 *  Incremental Backup 371 is a secondary backup that is based on the
    primary Incremental Backup 370 (the Based On timestamp of the former is
    the same as the Taken At date of the latter).

 Note that the term Blue Tape refers to the tape containing the backup
 index. In the above example, each Blue Tape Vol Id has the same volume
 identifier as its corresponding Data Tape Vol Id entry. This indicates that
 the backup index was written on the same tape as the system data, which is
 true for all single-volume backups written using an 8-millimeter tape
 drive.

 In contrast, a system backup history for a system with a 9-track tape
 drive will show different volume identifiers for the corresponding Blue
 Tape Vol Id and Data Tape Vol Id entries. This occurs because using a
 9-track tape drive causes the backup index and system data to be written
 on physically separate tapes (see "Structure of Backup Tapes," in the
 introduction to this package).


 REFERENCES

 System Manager's Guide



 @node !Commands.System_Backup.Id

 subtype Id is Natural;

 DESCRIPTION

 Specifies the identifier assigned to a backup tape during the backup
 operations.



 @node !Commands.System_Backup.Kind

 type Kind is (Full, Primary, Secondary);

 DESCRIPTION

 Specifies the kind of backup to be taken with the Backup procedure.


 ENUMERATIONS


 Full

 Records the complete state of the Environment--a complete backup.


 Primary

 Records changes in the Environment state since the last full backup--an
 incremental backup.


 Secondary

 Records changes in the Environment since the last primary backup--an
 incremental backup.



 @node !Tools.System_Utilities

 Package System_Utilities offers a set of capabilities for obtaining
 information about various system characteristics. In general, these
 characteristics cannot be altered with procedures in this package.
 Instead, use packages Operator, Scheduler, and Terminal in this book and
 package !Commands.Job in the Session and Job Management (SJM) book.
 Other characteristics are controlled by the Environment and cannot be
 changed explicitly.


 RESOURCES IN PACKAGE SYSTEM_UTILITIES

 Package System_Utilities is used for gathering information. The commands
 in this package fall into the following functional groups.


 Obtaining User Information

                Home_Library       Last_Login
                Last_Logout        Logged_In
                User               User_Name


 Obtaining Session Information

                Error_Name         Get_Session
                Image              Input_Name
                Logged_In          Output_Name
                Session            Session_Id
                Session_Name       Terminal
                User               User_Name

 Related types:

                Image              Object
                Session_Iterator   Version


 Obtaining Job Information

                Cpu                Elapsed
                Get_Job            Get_Page_Counts
                Get_Session        Job_Name
                Priority           Set_Page_Limit

 Related types:

                Job_Id             Job_Iterator


 Obtaining Terminal-Device Information

                Terminal_Columns   Terminal_Lines
                Terminal_Type
                    


 Obtaining Terminal-Port Information

 Disconnect or login characteristics:

          Detach_On_Disconnect          Disconnect_On_Disconnect
          Disconnect_On_Failed_Login    Disconnect_On_Logoff
          Enabled                       Log_Failed_Logins
          Login_Disabled                Logoff_On_Disconnect

 Data traffic:

          Input_Count                   Output_Count

 RS232 ports:

          Character_Size                Input_Rate
          Flow_Control                  Output_Rate
          Parity                        Receive_Flow_Control
          Receive_Xon_Xoff_Bytes        Receive_Xon_Xoff_Characters
          Stop_Bits                     Xon_Xoff_Bytes
          Xon_Xoff_Characters

 Terminal port object:

                Terminal           Terminal_Name

 Related types:

                Byte_String        Character_Bits_Range
                Parity_Kind        Stop_Bits_Range
                Terminal_Iterator
                           


 Obtaining System Information

 Software version:              System_Boot_Configuration

 Disk blocks:                   Bad_Block_List

 Tape devices:                  Tape_Name

 Hardware circuit boards:       Get_Board_Info

 Time since last system boot:   System_Up_Time

 Related types:

                All_Bad_Blocks     Bad_Block_Kinds
                Block_List         Manufacturers_Bad_Blocks
                Retargeted_Blocks  Tape

                                

 Obtaining Information through Iteration Operations

 Iteration capability is provided by the following functions and
 procedures:

                Done               Init
                Next               Value

 Related Types:

                Job_Id             Job_Iterator
                Session_Id         Session_Iterator
                Terminal_Iterator


 KEY CONCEPTS FOR PACKAGE SYSTEM_UTILITIES

 The resources in package System_Utilities supply information about the
 system to procedures and functions defined in packages Operator, Scheduler,
 Tape, and Terminal. Refer to the documentation for these packages in this
 book for instructions on common system-management tasks for setting,
 modifying, or displaying system characteristics.

 System managers and other tool builders can use resources in package
 System_Utilities to implement specialized utilities that need
 information about the objects discussed in this section. Some possible
 applications are suggested in this package introduction and in the
 reference entries.


 Environment Entities Accessed by System_Utilities

 Users access the Environment through terminal devices that are connected
 to the main system through a terminal port. Each user logs in with a
 predefined username ; this login begins a session for the user. From this
 session, the user executes commands that cause jobs to run in the session.

 Package System_Utilities returns information about the following:

 *  Users

 *  Sessions

 *  Jobs

 *  Terminal ports

 *  Terminal devices

 *  Tape devices

 *  Other system hardware


 Users

 Before users can log in and use the facilities of the Rational
 Environment, they must have an account granting access to a user object.
 Existing users with operator capability can create a new user object for
 another person using the Operator.Create_User procedure.

 Users are associated with a username group, a home world (sometimes called
 a home library), an access list (ACL) for that world, and a password.

 Once a user logs into an Environment session, the user can execute jobs
 (see below).

 Table 1 describes the information about users that can be obtained with
 System_Utilities functions.

                   Table 1    Obtaining User Information
              ---------------------------------------------- 
             |                                   |          |
             |Type of Information                |Function  |
             |                                   |Name      |
              ---------------------------------------------- 
             |                                   |          |
             |Version or object that represents a|User      |
             |specified user                     |          |
              ---------------------------------------------- 
             |                                   |          |
             |Username associated with the       |User_Name |
             |specified session                  |          |
              ---------------------------------------------- 
             |                                   |          |
             |Fully qualified pathname of the hom|Home_     |
             |world (commonly called the home    |Library   |
             |library) of a specified user       |          |
              ---------------------------------------------- 
             |                                   |          |
             |Whether a specified user is        |Logged_In |
             |currently logged in                |          |
              ---------------------------------------------- 
             |                                   |          |
             |Time and date that a specified user|Last_Login|
             |last logged into the Environment   |          |
              ---------------------------------------------- 
             |                                   |          |
             |Time and date that a specified user|Last_     |
             |last logged out of the Environment |Logout    |
              ---------------------------------------------- 



 Table 2 describes the types defined in System_Utilities that access or
 return information about user objects.

         Table 2    Types, Subtypes, and Constants for User Objects
              ---------------------------------------------- 
             |                                   |          |
             |Type of Information                |Resource  |
              ---------------------------------------------- 
             |                                   |          |
             |Defines a representation for a     |type      |
             |version of a directory object      |Version   |
              ---------------------------------------------- 
             |                                   |          |
             |Defines the representation for an  |type      |
             |object in the directory system     |Object    |
              ---------------------------------------------- 



 See package Operator in this book and package Access_List in the Library
 Management (LM) book for more information about username groups, access
 lists, and specific commands that use the System_Utilities functions for
 user objects.


 Sessions

 A session provides a custom-tailored Environment workspace when a user
 logs in. The user connects to a session through a terminal port. It is
 possible for a session to continue to run and remain connected to the
 terminal port even after a user's terminal device disconnects from the
 terminal port, and it is possible for a user to be logged into more than
 one session at a time. It is not possible for a user to be logged into the
 same session from more than one port at the same time.

 When a user is created by the Operator.Create_User command, a default
 session named S_1 is created in the user's home world. Additional sessions
 can be created by a user during login. A single user can have more than
 one active session by logging into the system more than once and providing
 a unique session name for each login.

 Note that the resources in System_Utilities use the session ID, a unique
 identification number, rather than the session name, for specifying
 sessions.

 Table 3 describes information about sessions that can be obtained with
 System_Utilities functions.

                  Table 3    Obtaining Session Information
              ---------------------------------------------- 
             |                                   |          |
             |Type of Information                |Function  |
             |                                   |Name      |
              ---------------------------------------------- 
             |                                   |          |
             |Session ID                         |Get_      |
             |                                   |Session   |
              ---------------------------------------------- 
             |                                   |          |
             |Name of a specified session (a     |Session_  |
             |string that the user enters)       |Name      |
              ---------------------------------------------- 
             |                                   |          |
             |Username of the user associated    |User_Name |
             |with the specified session         |          |
              ---------------------------------------------- 
             |                                   |          |
             |Version or object that represents a|Session   |
             |specified session                  |          |
              ---------------------------------------------- 
             |                                   |          |
             |Whether a specified user is logged |Logged_In |
             |into a specified session           |          |
              ---------------------------------------------- 
             |                                   |          |
             |Version or object that represents  |User      |
             |the user for a specified session   |          |
              ---------------------------------------------- 
             |                                   |          |
             |Terminal-port number, terminal-port|Terminal  |
             |version, or terminal-port object   |          |
             |for a specified session            |          |
              ---------------------------------------------- 
             |                                   |          |
             |Pathname of the standard error     |Error_Name|
             |filename for the specified session |          |
              ---------------------------------------------- 



 Table 4 describes the types used to describe sessions.

                 Table 4    Types, Subtypes, and Constants
              ---------------------------------------------- 
             |                                  |           |
             |Type of Information               |Resource   |
              ---------------------------------------------- 
             |                                  |           |
             |Defines an integer representation |subtype    |
             |for sessions                      |Session_Id |
              ---------------------------------------------- 
             |                                  |           |
             |Defines an iterator for iterating |type       |
             |over all sessions on a system     |Session_   |
             |                                  |Iterator   |
              ---------------------------------------------- 
             |                                  |           |
             |Defines a representation for a    |type       |
             |version of a directory object     |Version    |
              ---------------------------------------------- 
             |                                  |           |
             |Defines the representation for an |type Object|
             |object in the directory system    |           |
              ---------------------------------------------- 




 Jobs

 Within each session, the user can create multiple jobs to execute programs
 and commands. A job consists of one or more commands that are executed
 together. Each job is separately scheduled and can have its own scheduler
 priority and page limits. Users can create jobs implicitly when a command
 window is executed or explicitly with the !Commands.Program.Run_Job and
 Create_Job procedures.

 The job ID, or job number, identifies Environment jobs; this identifier is
 displayed by the What.Jobs and What.Users commands.

 The System_Utilities commands Get_Page_Count and Set_Page_Limit
 respectively get and set the job page limit that is allowed for a
 particular job. This limit is 8,000 pages by default and is a combination
 of the pages allowed from memory and disk. It is possible for users to
 create jobs that accidentally consume too much disk space. To prevent
 runaway jobs, make users aware of page limits and how to control them (see
 your System Manager's Guide).

 Note that the Set_Page_Limit procedure is the only System_Utilities
 procedure that can directly alter system characteristics (a job can call
 this procedure at any time to change the job page limit).

 Table 5 describes additional information that is available about jobs
 through System_Utilities functions.

                    Table 5    Obtaining Job Information
              ---------------------------------------------- 
             |                                   |          |
             |Type of Information                |Function  |
             |                                   |Name      |
              ---------------------------------------------- 
             |                                   |          |
             |Job identifier for the current job |Get_Job   |
              ---------------------------------------------- 
             |                                   |          |
             |Priority of the specified job      |Priority  |
              ---------------------------------------------- 
             |                                   |          |
             |Amount of CPU time that the        |Cpu       |
             |specified job has consumed         |          |
              ---------------------------------------------- 
             |                                   |          |
             |Elapsed time that the specified job|Elapsed   |
             |has existed                        |          |
              ---------------------------------------------- 



 Table 6 lists the types, subtypes, and constants defined in
 System_Utilities for jobs.

                         Table 6    Job Information
              ---------------------------------------------- 
             |                                   |          |
             |Type of Information                |Resource  |
              ---------------------------------------------- 
             |                                   |          |
             |Defines an integer representation  |subtype   |
             |for a job                          |Job_Id    |
              ---------------------------------------------- 
             |                                   |          |
             |Defines an iterator for iterating  |type      |
             |over all the jobs on a system      |Job_      |
             |                                   |Iterator  |
              ---------------------------------------------- 




 Terminal Ports

 The R1000 communicates with terminals, workstations, printers, and modems
 through either RS232 asynchronous serial ports or Telnet TCP/IP network
 ports. Both types of ports are represented in the Environment as port
 objects.

 Commands in package Terminal access or modify a subset of settings for
 port objects. Other settings for port objects are located elsewhere in the
 Environment and are managed by other resources--for example, the network
 resources are described in the Rational Networking--TCP/IP Reference
 Manual.

 Package System_Utilities provides extensive function support that is used
 by the commands in packages Terminal and Operator.

 The following tables contain information about RS232 ports that can be
 obtained with System_Utilities.

 Tables 7 through 10 describe the kinds of information you can obtain
 using functions from System_Utilities. Table 11 describes the types that
 support these functions.

                Table 7    Obtaining RS232-Port Information
              ---------------------------------------------- 
             |                                   |          |
             |Type of Information                |Function  |
             |                                   |Name      |
              ---------------------------------------------- 
             |                                   |          |
             |Number of data bits that represent |Character_|
             |each character processed through a |Size      |
             |port                               |          |
              ---------------------------------------------- 
             |                                   |          |
             |Number of stop bits that frame each|Stop_Bits |
             |character processed through a port |          |
              ---------------------------------------------- 
             |                                   |          |
             |Type of parity checking assigned to|Parity    |
             |a specified port                   |          |
              ---------------------------------------------- 
             |                                   |          |
             |Input-data transmission rate of a  |Input_Rate|
             |specified port                     |          |
              ---------------------------------------------- 
             |                                   |          |
             |Output-data transmission rate of a |Output_   |
             |specified port                     |Rate      |
              ---------------------------------------------- 
             |                                   |          |
             |Transmit flow control assigned to a|Flow_     |
             |port                               |Control   |
              ---------------------------------------------- 
             |                                   |          |
             |Receive flow control assigned to a |Receive_  |
             |port                               |Flow_     |
             |                                   |Control   |
              ---------------------------------------------- 
             |                                   |          |
             |Specified character codes assigned |Receive_  |
             |for XON/XOFF on receive flow       |Xon_Xoff_ |
             |control                            |Characters|
              ---------------------------------------------- 
             |                                   |          |
             |Specified byte codes assigned for  |Receive_  |
             |XON/XOFF on receive flow control   |Xon_Xoff_ |
             |                                   |Bytes     |
              ---------------------------------------------- 
             |                                   |          |
             |Specified character codes assigned |Xon_Xoff_ |
             |for XON/XOFF on transmit flow      |Characters|
             |control                            |          |
              ---------------------------------------------- 
             |                                   |          |
             |Specified byte codes assigned for  |Xon_Xoff_ |
             |XON/XOFF on transmit flow control  |Bytes     |
              ---------------------------------------------- 



        Table 8    Obtaining Terminal-Port Login-Enabled Information
              ---------------------------------------------- 
             |                                   |          |
             |Type of Information                |Function  |
             |                                   |Name      |
              ---------------------------------------------- 
             |                                   |          |
             |Whether a specified port is enabled|Enabled   |
             |for login                          |          |
              ---------------------------------------------- 
             |                                   |          |
             |Whether a specified port is disable|Disabled  |
             |for login (note that a port        |          |
             |disabled through package Terminal  |          |
             |or during machine initialization   |          |
             |cannot be enabled using            |          |
             |Operator.Enable_Login)             |          |
              ---------------------------------------------- 

                                                                           


         Table 9    Obtaining Terminal-Port Disconnect Information
              ---------------------------------------------- 
             |                                   |          |
             |Type of Information                |Function  |
             |                                   |Name      |
              ---------------------------------------------- 
             |                                   |          |
             |Whether a specified R1000 port     |Disconnect|
             |should respond to an incoming      |_On_      |
             |disconnect signal by transmitting a|Disconnect|
             |return disconnect signal           |          |
              ---------------------------------------------- 
             |                                   |          |
             |Whether a specified R1000 port     |Disconnect|
             |should respond to repeated login   |_On_      |
             |failures by disconnecting          |Failed_   |
             |                                   |Login     |
              ---------------------------------------------- 
             |                                   |          |
             |Whether a specified R1000 port     |Disconnect|
             |should respond to a logoff by      |_On_Logoff|
             |disconnecting                      |          |
              ---------------------------------------------- 
             |                                   |          |
             |Whether a specified R1000 port     |Log_Off_  |
             |should respond to a remote         |On_       |
             |disconnect by logging off any      |Disconnect|
             |associated session still running on|          |
             |the port                           |          |
              ---------------------------------------------- 
             |                                   |          |
             |Whether a specified port is set to |Log_      |
             |keep a log of failed logins        |Failed_   |
             |                                   |Logins    |
              ---------------------------------------------- 



 For a complete discussion of the different RS232, connection, and login
 characteristics, see the introduction to package Terminal.

 Table 10 lists the functions that return the number of characters input or
 output from a specified port since the system was booted.

                Table 10    Terminal-Port Traffic Information
              ---------------------------------------------- 
             |                                   |          |
             |Type of Information                |Function  |
             |                                   |Name      |
              ---------------------------------------------- 
             |                                   |          |
             |Return the number of characters    |Input_    |
             |input from the specified port since|Count     |
             |the system was booted              |          |
              ---------------------------------------------- 
             |                                   |          |
             |Return the number of characters    |Output_   |
             |output from the specified port sinc|Count     |
             |the system was booted              |          |
              ---------------------------------------------- 



 Table 11 lists the types, subtypes, and constants used to define ports.

                Table 11    Terminal-Port Traffic Information
             ----------------------------------------------- 
            |                                 |             |
            |Type of Information              |Resource     |
             ----------------------------------------------- 
            |                                 |             |
            |Defines a string of 8-bit bytes  |subtype      |
            |                                 |Byte_String  |
             ----------------------------------------------- 
            |                                 |             |
            |Defines the allowed number of bit|subtype      |
            |that represent a character       |Character_   |
            |                                 |Bits_Range   |
             ----------------------------------------------- 
            |                                 |             |
            |Defines the allowed kinds of     |type         |
            |parity checking used by the      |Parity_Kind  |
            |system and terminal devices      |             |
            |connected to a port              |             |
             ----------------------------------------------- 
            |                                 |             |
            |Defines an integer representation|subtype Port |
            |for the Telnet and RS232 ports on|             |
            |a system                         |             |
             ----------------------------------------------- 
            |                                 |             |
            |Defines an iterator type for     |type         |
            |iterating through all Telnet and |Terminal_    |
            |RS232 ports                      |Iterator     |
             ----------------------------------------------- 




 Terminal Devices

 Users log into the Environment through terminal devices connected to
 login-enabled terminal ports. Common terminal devices are workstations,
 PCs, and dumb terminals. Dumb terminals typically display only one
 Environment session at a time. Workstations and PCs running either the X
 Window System with the Rational X Interface, or Microsoft Windows with
 the Rational Windows Interface, can display multiple Environment sessions
 in separate terminal-emulator windows (the Rational X Interface and the
 Rational Windows Interface are terminal emulators that run under the
 corresponding graphical user interfaces).

 Table 12 describes information about terminal devices that can be obtained
 with System_Utilities.

                  Table 12    Terminal-Device Information
             ----------------------------------------------- 
            |                                 |             |
            |Type of Information              |Function Name|
             ----------------------------------------------- 
            |                                 |             |
            |Width in columns and length in   |Terminal_    |
            |lines of the Environment display |Columns,     |
            |associated with the specified por|Terminal_    |
            |                                 |Lines        |
             ----------------------------------------------- 
            |                                 |             |
            |Name of the output driver that is|Terminal_Type|
            |associated with a terminal device|             |
             ----------------------------------------------- 



 Note: Be careful not to confuse objects in the Environment that have names
 based on the word terminal with the concept of terminal devices--with the
 exception of Terminal_Type objects and the display-size functions
 identified in this section, most of the objects involving the word terminal
 refer to terminal ports, not terminal devices.


 Tape Devices

 ANSI tape devices are supported by package Tape. Tape objects are located
 in !Machine.Devices.

 See package Tape, the System Manager's Guide, and package Archive in the
 Library Management (LM) book for more information on using tape devices.

 Table 13 describes the support that package System_Utilities provides for
 tape devices.

                    Table 13    Tape-Device Information
              ---------------------------------------------- 
             |                              |               |
             |Type of Information           |Resource       |
              ---------------------------------------------- 
             |                              |               |
             |Returns the pathname of the   |function       |
             |tape object in the library    |Tape_Name      |
             |system associated with the    |               |
             |specified drive               |               |
              ---------------------------------------------- 
             |                              |               |
             |Defines the possible tape     |subtype Tape   |
             |drives for the system         |               |
              ---------------------------------------------- 




 System Hardware

 Package System_Utilities contains several utility functions that return
 information about the system configuration, as described in Table 14.

                       Table 14    System Information
              ---------------------------------------------- 
             |                              |               |
             |Type of Information           |Function Name  |
              ---------------------------------------------- 
             |                              |               |
             |Software release number       |System_Boot_   |
             |                              |Configuration  |
              ---------------------------------------------- 
             |                              |               |
             |List of bad disk blocks at    |Bad_Block_List |
             |time of manufacture           |               |
              ---------------------------------------------- 
             |                              |               |
             |Hardware circuit-board        |Get_Board_Info |
             |information                   |               |
              ---------------------------------------------- 
             |                              |               |
             |Time since system was last    |System_Up_Time |
             |booted                        |               |
              ---------------------------------------------- 




 Identifiers, Names, Objects, and Versions

 Package System_Utilities reveals different types of information on users,
 sessions, jobs, terminal ports, terminal devices, and tape devices.
 Although not every type of information applies to all of these, the
 categories are:

 *  Identifiers (IDs) for sessions, jobs, terminal ports, and tapes

 *  Names

 *  Objects for sessions, users, and terminal ports

 *  Versions for sessions, users, and terminal ports


 IDs for Sessions, Jobs, Terminal Ports, and Tapes

 Sessions, jobs, ports, and tapes are identified by the system through IDs,
 as shown in Table 15.

            Table 15    IDs for Sessions, Jobs, Ports, and Tapes
                         ----------------------- 
                        |        |     |        |
                        |To      |Type |Range   |
                        |Represen|     |        |
                        |t       |     |        |
                         ----------------------- 
                        |        |     |        |
                        |Sessions|Sessi|0 .. 2  |
                        |        |on_Id|** 24 - |
                        |        |     |1       |
                         ----------------------- 
                        |        |     |        |
                        |Jobs    |Job_ |4 .. 255|
                        |        |Id   |        |
                         ----------------------- 
                        |        |     |        |
                        |Ports   |Port |0 ..    |
                        |        |     |1024    |
                         ----------------------- 
                        |        |     |        |
                        |Tapes   |Tape |0 .. 3  |
                         ----------------------- 



 Many of the System_Utilities functions return IDs or take IDs as
 parameters. IDs are also displayed online by commands such as What.Users
 and What.Jobs.


 Names

 Names are represented by character strings. These strings are often a
 partial or full directory pathname or an Ada name.

                             Table 16    Names
              ---------------------------------------------- 
             |                                   |          |
             |To Represent                       |Function  |
             |                                   |Name      |
              ---------------------------------------------- 
             |                                   |          |
             |Name of a session: S_1             |Session_  |
             |                                   |Name      |
              ---------------------------------------------- 
             |                                   |          |
             |Name of a job indicated by a job   |Job_Name  |
             |ID: Comp.Promote                   |          |
              ---------------------------------------------- 
             |                                   |          |
             |Name of the user who created a     |User_Name |
             |session: Anne                      |          |
              ---------------------------------------------- 
             |                                   |          |
             |Pathname of the tape object in the |Tape_Name |
             |library system associated with a   |          |
             |drive: !Machine.Devices.Tape_0     |          |
              ---------------------------------------------- 
             |                                   |          |
             |Pathname of the Standard_Error     |Error_Name|
             |filename for the indicated session:|          |
             |!Machine.Users.Anne                |          |
              ---------------------------------------------- 
             |                                   |          |
             |Pathname of the Standard_Input     |Input_Name|
             |filename for the indicated session:|          |
             |!Users.Anne.S_1                    |          |
              ---------------------------------------------- 
             |                                   |          |
             |Pathname of the Standard_Output    |Output_   |
             |filename for the indicated session:|Name      |
             |!Users.Anne.S_1                    |          |
              ---------------------------------------------- 
             |                                   |          |
             |Pathname of the terminal object for|Terminal_ |
             |a port:                            |Name      |
             |!Machine.Devices.Terminal_242      |          |
              ---------------------------------------------- 
             |                                   |          |
             |Name of the terminal type          |Terminal_ |
             |associated with a terminal attached|Type      |
             |to a port: Xsun4                   |          |
              ---------------------------------------------- 
             |                                   |          |
             |Pathname of the home library for a |Home_     |
             |user: !Users.Anne                  |Library   |
              ---------------------------------------------- 
             |                                   |          |
             |Pathname of the indicated version  |Image     |
              ---------------------------------------------- 




 Objects for Sessions, Users, and Terminal Ports

 Object is a subtype of type !Implementation.Directory.Object, which is an
 implementation detail of the R1000 library system. An object defines a
 representation for an activity or entity in the Environment. Certain
 procedure or function interfaces may require specifying an object
 parameter.


 Versions for Sessions, Users, and Terminal Ports

 Version is a subtype of type !Implementation.Directory.Version, which is
 an implementation detail of the R1000 library system. The Environment
 maintains multiple versions for each object in the directory system.
 Version numbers are assigned by the Environment when each version is
 created. Certain procedure or function interfaces may require specifying a
 version parameter.

 See the Library Management (LM) book for more information on versions.


 Iteration Capabilities

 Package System_Utilities provides functions, types, and procedures for
 implementing programmatic iteration over jobs, sessions, and terminal
 ports. Iteration is the sequencing through a collection of items:
 operations can be applied to each item in turn. By combining these
 resources, you can create a tool that first obtains an entire set of
 objects and then examines each individual object in the set for a
 particular characteristic. Three different iteration capabilities are
 discussed below:

 *  Session

 *  Job

 *  Terminal port


 Session Iteration

 Session iteration collects all of the sessions running on a system, often
 for additional processing by job or terminal-port iterators.

 You define a session-iterator variable of type Session_Iterator and
 initialize it through the Init procedure. The iterator is initialized with
 all the sessions active at the time the Init procedure was called.

 The following excerpt of Ada code illustrates session iteration:

   declare
       package Su renames System_Utilities;
       Iterator_Variable : Su.Session_Iterator;
       For_Session : Su.Session_Id;
   begin
       Su.Init (Iterator_Variable);
       while not Su.Done (Iterator_Variable) loop
           For_Session := Su.Value (Iterator_Variable);
           Whatever_Process (For_Session);
           Su.Next (Iterator_Variable);
       end loop;
   end;


 Job Iteration

 Job iteration is a powerful tool for system management. For example, a
 tool based on job iteration could handle runaway jobs that were consuming
 large quantities of memory.

 You define a job-iterator variable of type Job_Iterator and initialize it
 through the Init procedure. The iterator is initialized with all jobs
 active for a particular session, at the time that the Init procedure was
 called. Note that when used with job iteration, the Init procedure
 includes a parameter for session IDs: the default is the session ID for
 the current session. Job iterators are often implemented nested within
 session iterators, to collect all jobs running on a system.

 The following short example illustrates how job iteration can be combined
 with session iteration:

   procedure Iteration_Example_Jobs is
       package Su renames System_Utilities;
       Iterator_Variable_For_Session : Su.Session_Iterator;
       Iterator_Variable_For_Job : Su.Job_Iterator;
       For_Job : Su.Job_Id;
   begin
       Su.Init (Iterator_Variable_For_Session);
       while not Su.Done (Iterator_Variable_For_Session) loop
           Su.Init (Iterator_Variable_For_Job);
           while not Su.Done (Iterator_Variable_For_Job) loop
               For_Job := Su.Value (Iterator_Variable_For_Job);
               Whatever_Process (For_Job);
               Su.Next (Iterator_Variable_For_Job);
           end loop;

           Su.Next (Iterator_Variable_For_Session);
       end loop;
   end Iteration_Example_Jobs;


 Terminal-Port Iteration

 A terminal-port iterator is defined and initialized with the
 Terminal_Iterator type and the Init procedure. The iterator is initialized
 with all of the terminal ports represented in the Environment by port
 objects. (Port objects are defined in !Machine.Devices.Terminal_N
 objects, where N is the number of the corresponding hardware port. See
 package Terminal for more information on port objects.)

 Terminal-port iteration is useful for classifying the state of a
 collection of ports. For example, terminal-port iteration can locate ports
 set with certain attributes, such as those enabled for login.
 Terminal-port iteration also can be used with the Input_Count and
 Output_Count functions to identify inactive user sessions. Terminal-port
 iteration uses essentially the same procedural structure as described
 above for session and job iteration.


 @node !Tools.System_Utilities.All_Bad_Blocks

 All_Bad_Blocks : constant Bad_Block_Kinds := 3;

 DESCRIPTION

 Defines a value that indicates all bad disk blocks.


 REFERENCES

 type Bad_Block_Kinds
 function Bad_Block_List
 constant Manufacturers_Bad_Blocks
 constant Retargeted_Blocks



 @node !Tools.System_Utilities.Bad_Block_Kinds

 type Bad_Block_Kinds is new Long_Integer range 0 .. 7;

 DESCRIPTION

 Defines the kinds of bad disk blocks.

 A block is a logical unit of disk space of a certain size, and each block
 has a physical address on the disk. A bad block is a block containing
 areas of physical disk media in which the integrity of data storage cannot
 be guaranteed. Package System_Utilities contains several constants that
 are used to represent the physical addresses of known bad blocks on a
 specific disk:

 *  All_Bad_Blocks

 *  Manufacturers_Bad_Blocks

 *  Retargeted_Blocks


 REFERENCES

 constant All_Bad_Blocks
 function Bad_Block_List
 constant Manufacturers_Bad_Blocks
 constant Retargeted_Blocks



 @node !Tools.System_Utilities.Bad_Block_List

 function Bad_Block_List
              (For_Volume : Natural;
                     Kind : Bad_Block_Kinds := Retargeted_Blocks)
                                               return Block_List;

 DESCRIPTION

 Returns a list of bad disk blocks of the specified kind on the specified
 disk volume.

 This function is called by the Show_Bad_Blocks procedure, which is imple-
 mented in !Tools.System_Availability.System_Report. (See the System
 Manager's Guide for information about generating reports of manufacturer's
 bad blocks.)


 PARAMETERS

 For_Volume : Natural;

 Specifies the disk volume for which to get the bad-block information.


 Kind : Bad_Block_Kinds := Retargeted_Blocks;

 Specifies the kind of bad blocks to get.


 return Block_List;

 Returns the desired list of bad disk blocks. If the volume or kind of bad
 block is illegal, a null array will be returned.


 ERRORS

 If the volume or kind of bad disk block is illegal, a null array will be
 returned; no exceptions will be raised.


 REFERENCES

 constant All_Bad_Blocks
 type Block_List
 constant Manufacturers_Bad_Blocks
 constant Retargeted_Blocks



 @node !Tools.System_Utilities.Block_List

 type Block_List is array (Natural range <>) of Integer;

 DESCRIPTION

 Defines the type used to represent a list of bad disk blocks.


 REFERENCES

 function Bad_Block_List



 @node !Tools.System_Utilities.Byte_String

 subtype Byte_String is System.Byte_String;

 DESCRIPTION

 Defines an array of 8-bit bytes, forming the basic unit of transmission and
 reception to and from input/output devices.


 REFERENCES

 type !Lrm.System.Byte_String



 @node !Tools.System_Utilities.Character_Bits_Range

 subtype Character_Bits_Range is Integer range 5 .. 8;

 DESCRIPTION

 Defines the allowed values for the number of bits in a character.

 The number of bits in a character depends on the character set that the
 terminal device uses. Normally this is eight bits for a terminal device
 used to access the Environment. Other kinds of terminal devices may
 require different values.



 @node !Tools.System_Utilities.Character_Size

 function Character_Size (Line : Port := System_Utilities.Terminal)
                                      return Character_Bits_Range;

 DESCRIPTION

 Returns the number of bits used for each character for the specified port.

 To set the Character_Bits_Range for a port, see the
 Terminal.Set_Character_Size procedure.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the port number of the port through which the session is logged in.


 return Character_Bits_Range;

 Returns the number of bits per character.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 procedure Terminal.Set_Character_Size



 @node !Tools.System_Utilities.Cpu

 function Cpu (For_Job : Job_Id := System_Utilities.Get_Job)
                                            return Duration;

 DESCRIPTION

 Returns the CPU time that the specified job has consumed.

 This function returns the time that the specified job has used during its
 execution. By default, the function returns the CPU time of the current
 job.


 PARAMETERS

 For_Job : Job_Id := System_Utilities.Get_Job;

 Specifies the job for which to calculate the CPU time. The default returns
 the CPU time of the current job.


 return Duration;

 Returns the CPU time.


 EXAMPLES

 The following example illustrates a programmatic interface to the CPU
 function:


   procedure Job_Cpu_Time (For_Job : Job_Id :=
                           System_Utilities.Get_Job) is
       package Su renames System_Utilities;
       package Tu renames Time_Utilities;
   begin
       Io.Echo ("CPU time for " & Job_Name (For_Job) &
                ": " & Tu.Image (Su.Cpu (For_Job)));
   end Job_Cpu_Time;
          

 REFERENCES

 function Elapsed
 function Get_Job
 package Time_Utilities



 @node !Tools.System_Utilities.Detach_On_Disconnect

 function Detach_On_Disconnect
                    (Line : Port := System_Utilities.Terminal)
                                               return Boolean;

 DESCRIPTION


 This option is not implemented: any value returned by this function is
 undefined.


 REFERENCES

 procedure Terminal.Set_Detach_On_Disconnect



 @node !Tools.System_Utilities.Disconnect_On_Disconnect

 function Disconnect_On_Disconnect
                 (Line : Port := System_Utilities.Terminal)
                                            return Boolean;

 DESCRIPTION

 Determines whether the disconnect-on-disconnect option is enabled for the
 specified port.

 See package Terminal for more information on this option.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the port number of the port through which the current session is logged
 in.


 return Boolean;

 Returns True if the option is currently enabled for the specified port
 number; otherwise, the function returns False.


 REFERENCES

 procedure Terminal.Set_Disconnect_On_Disconnect



 @node !Tools.System_Utilities.Disconnect_On_Failed_Login

 function Disconnect_On_Failed_Login
                 (Line : Port := System_Utilities.Terminal)
                                            return Boolean;

 DESCRIPTION

 Determines whether the disconnect-on-failed-login option is enabled for
 the specified port.

 See package Terminal for more information on this option.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the port number of the port through which the current session is logged
 in.


 return Boolean;

 Returns True if the option is currently enabled for the port; otherwise,
 the function returns False.


 REFERENCES

 procedure Terminal.Set_Disconnect_On_Failed_Login



 @node !Tools.System_Utilities.Disconnect_On_Logoff

 function Disconnect_On_Logoff
                        (Line : Port := System_Utilities.Terminal)
                                                   return Boolean;

 DESCRIPTION

 Determines whether the disconnect-on-logoff option is enabled for the
 specified port.

 See package Terminal for more information on this option.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the port number of the port through which the current session is logged
 in.


 return Boolean;

 Returns True if the option is currently enabled for the port; otherwise,
 the function returns False.


 REFERENCES

 procedure Terminal.Set_Disconnect_On_Logoff



 @node !Tools.System_Utilities.Done

 function Done (Iter : Job_Iterator) return Boolean;

 function Done (Iter : Session_Iterator) return Boolean;

 function Done (Iter : Terminal_Iterator) return Boolean;

 DESCRIPTION

 Checks whether an iterator has cycled through all of the members in a
 collection of jobs, sessions, or terminal ports.

 The Done, Init, Next, and Value functions and procedures are used together
 to form an iterator. Specific iterators are defined by the Job_Iterator,
 Session_Iterator, and Terminal_Iterator types.

 The session iterator iterates through all of the active sessions that are
 running on the Environment when the Init procedure was called.

 The job iterator filters out inactive jobs when the Value function, the
 Done function, and the Next procedure are called. Specifically, the Done
 function yields True only if active jobs remain when it is called. For
 example, an iterator that initially contained seven active jobs following
 the execution of the Init procedure might complete after only four jobs
 were checked by the Next procedure, because the other three jobs completed
 before they were checked.

 The terminal iterator iterates through the terminal ports defined in the
 !Machine.Devices library.

 Refer to the "Iteration Capabilities" subsection in the introduction to
 this package for more information and examples showing how to use
 iteration.


 PARAMETERS

 Iter : Job_Iterator;

 Specifies a job iterator.


 Iter : Session_Iterator;

 Specifies a session iterator.


 Iter : Terminal_Iterator;

 Specifies a terminal iterator.


 return Boolean;

 Returns the value True when the iteration is complete; otherwise, the
 function returns False.


 REFERENCES

 procedure Init
 type Job_Iterator
 procedure Next
 type Session_Iterator
 type Terminal_Iterator
 function Value



 @node !Tools.System_Utilities.Elapsed

 function Elapsed (For_Job : Job_Id := System_Utilities.Get_Job)
                                                return Duration;

 DESCRIPTION

 Returns the elapsed time that the specified job has existed.

 This function returns the time that the specified job has been in
 existence. By default, the function returns the elapsed time of the
 current job.

 Note: The elapsed time for job 4 (the system) is the elapsed time since
 the system was booted.


 PARAMETERS

 For_Job : Job_Id := System_Utilities.Get_Job;

 Specifies the job whose elapsed time is desired. The default is the elapsed
 time of the current job.


 return Duration;

 Returns the elapsed time.


 EXAMPLES

 The following example illustrates a call to the Elapsed function:

   procedure Job_Elapsed_Time (For_Job : Job_Id :=
                               System_Utilities.Get_Job) is
       package Su renames System_Utilities;
       package Tu renames Time_Utilities;
   begin
       Io.Echo (Tu.Image (Su.Elapsed (For_Job)) &
                " elapsed for " & Job_Name (For_Job));
   end Job_Elapsed_Time;
   

 REFERENCES

 function Cpu
 function Get_Job
 Programming Tools (PT), package Time_Utilities



 @node !Tools.System_Utilities.Enabled

 function Enabled (Line : Port := System_Utilities.Terminal)
                                             return Boolean;

 DESCRIPTION

 Checks whether the specified port is enabled for logging into the
 Environment.

 The setting for a port can be changed. To enable or disable login for a
 port, use the Operator.Enable_Terminal procedure.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number to be checked. The default is the port number
 associated with the current session.


 return Boolean;

 Returns the value True when the specified port is enabled for login;
 otherwise, the function returns False.


 REFERENCES

 procedure Operator.Enable_Terminal



 @node !Tools.System_Utilities.Error_Name

 function Error_Name
      (For_Session : Session_Id := System_Utilities.Get_Session)
                                                  return String;

 DESCRIPTION

 Returns the fully qualified pathname of the Standard_Error filename for the
 indicated session.

 If this file is opened using the I/O packages in the Environment, the
 output goes to an Environment output window. This function can be used,
 for example, to return the correct filename in an application that
 redirects error output for a job to an Environment output window.


 PARAMETERS

 For_Session : Session_Id := System_Utilities.Get_Session;

 Specifies the session for which the filename is to be computed. The default
 specifies that the filename for the current session is returned.


 return String;

 Returns the filename.



 @node !Tools.System_Utilities.Flow_Control

 function Flow_Control (Line : Port := System_Utilities.Terminal)
                                                   return String;

 DESCRIPTION

 Determines whether software flow control is used for controlling the flow
 of data transmitted to the terminal device on the specified port.

 A device such as a terminal or a printer attached to an R1000 port can
 control the flow of data transmitted to it from the R1000 in two ways:

 *  Hardware flow control: The flow of data is stopped when the device
    turns off the Clear To Send (CTS) modem control signal. The flow is
    restarted when the CTS signal is turned on.

 *  Software flow control: The flow of data is stopped when the device
    sends the XOFF byte or character. The flow is restarted when the XON
    byte or character is sent.

 The type of transmission flow control used for the port can be changed by
 using the Terminal.Set_Flow_Control procedure or by changing a hardware
 switch setting in the RS232 distribution panel (note that this second
 option applies only to Series 200 systems).


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the port number associated with the current session.


 return String;

 Returns the method used for controlling the flow of data transmitted to
 the device. Legal values are: NONE and XON_XOFF.

 *  NONE: Indicates that there is no software flow control for the port and
    that there may or may not be CTS hardware flow control for the port.
    Since CTS hardware flow control is enabled or disabled by changing a
    hardware switch setting in the RS232 distribution panel (applicable
    only to Series 200 systems), the setting of this hardware switch must
    be checked to determine if hardware flow control is enabled when this
    function returns NONE.

 *  XON_XOFF: Indicates that software flow control is enabled for the port,
    and the R1000 will stop transmitting when it receives an XOFF character
    or byte.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 function Receive_Flow_Control
 procedure Terminal.Set_Flow_Control



 @node !Tools.System_Utilities.Get_Board_Info

 function Get_Board_Info (Board : Natural) return String;

 DESCRIPTION

 Returns information about the specified hardware circuit board in the
 system.

 This function is called by the Show_Machine_Information procedure, which
 is implemented in !Tools.System_Availability.System_Report. (See the
 System Manager's Guide for information about generating reports showing
 board information.)


 PARAMETERS

 Board : Natural;

 Specifies the hardware circuit board about which to determine information.


 return String;

 Returns information about the board.



 @node !Tools.System_Utilities.Get_Job

 function Get_Job return Job_Id;

 DESCRIPTION

 Returns the job identification number of the current job.


 PARAMETERS

 return Job_Id;

 Returns the job identification number of the current job--that is, the job
 that called this function.



 @node !Tools.System_Utilities.Get_Page_Counts

 procedure Get_Page_Counts
               (Cache_Pages : out Natural;
                Disk_Pages  : out Natural;
                Max_Pages   : out Natural;
                For_Job     : Job_Id := System_Utilities.Get_Job);

 DESCRIPTION

 Gets the virtual-memory page counts for the specified job (each page is
 1,024 bytes).

 See the following references for information on page limits:

 *  To change the default page limit for a specific job, see the
    Set_Page_Limits procedure.

 *  For a definition of page limits and virtual-memory pages, see the "Job
    Page Limit" subsection in Chapter 3 of the Library Management (LM)
    book.

 *  For more information about the page limits for a job that elaborates an
    Ada unit containing the Page_Limit pragma, see Appendix F for the R1000
    Target in the Ada LRM.

 *  For more information about the page limits for a job compiled with a
    specific setting of the R1000_Cg.Page_Limit library switch, see package
    Switches in the Library Management (LM) book.

 *  For more information about changing the default page limit set by the
    Default_Job_Page_Limit session switch, see package Switches in the
    Session and Job Management (SJM) book.


 PARAMETERS

 Cache_Pages : out Natural;

 Returns the number of pages presently in main memory for the job.


 Disk_Pages : out Natural;

 Returns the number of pages that have disk space allocated for them.


 Max_Pages : out Natural;

 Returns the limit on the number of pages the job is allowed to create.


 For_Job : Job_Id := System_Utilities.Get_Job;

 Specifies the job for which to count the pages. By default, pages will be
 counted for the job that calls this procedure.


 REFERENCES

 function Get_Job
 procedure Set_Page_Limit



 @node !Tools.System_Utilities.Get_Session

 function Get_Session return Session_Id;

 function Get_Session (For_Job : Job_Id) return Session_Id;

 DESCRIPTION

 Returns the session identifier for either the job that executed the call to
 the function or the job indicated in the optional For_Job parameter.


 PARAMETERS

 For_Job : Job_Id;

 Specifies the job for which to determine the session identifier.


 return Session_Id;

 Returns the session identifier for either the job that executed the call to
 the function or the job indicated in the optional For_Job parameter.



 @node !Tools.System_Utilities.Home_Library

 function Home_Library (User : String := User_Name) return String:

 DESCRIPTION

 Returns the fully qualified pathname of the home library for the specified
 user.

 By default, this function returns the home library for the user associated
 with the current session.


 PARAMETERS

 User : String := User_Name;

 Specifies the simple name of the user for which the home library is to be
 determined.


 return String;

 Returns the fully qualified pathname of the home library for the indicated
 user.



 @node !Tools.System_Utilities.Image

 function Image (Version : Directory.Version) return String;

 DESCRIPTION

 Returns the fully qualified pathname for the indicated version of session,
 terminal-port, or user objects.

 Note that versions for these objects are returned by the Session,
 Terminal, and User functions.


 PARAMETERS

 Version : Directory.Version;

 Specifies the version for which the name is to be computed.


 return String;

 Returns the fully qualified pathname for the indicated version.


 REFERENCES

 function Session
 function Terminal
 function User



 @node !Tools.System_Utilities.Init

 procedure Init (Iter        : out Job_Iterator;
                 For_Session :     Session_Id := Get_Session);

 procedure Init (Iter : out Session_Iterator);

 procedure Init (Iter : out Terminal_Iterator);

 DESCRIPTION

 Initializes an iterator to iterate over all of the members in a collection
 of jobs, sessions, or terminal ports.

 The Done, Init, Next, and Value functions and procedures are used together
 to form an iterator. Specific iterators are defined by the Job_Iterator,
 Session_Iterator, and Terminal_Iterator types.

 The session iterator iterates through all of the active sessions that are
 running on the Environment when the Init procedure was called. If one or
 more sessions are active, the Value function returns the first session
 using the current value of the iterator. If no sessions are active, the
 Done function returns the value True using the current value of the
 iterator.

 When one or more jobs exist in the session, the Value function returns the
 first job using the current value of the iterator. When no jobs exist in
 the session, the Done function returns the value True using the current
 value of the iterator.

 The job iterator filters out inactive jobs when the Value function, the
 Done function, and the Next procedure are called. Specifically, the Done
 function yields True only if active jobs remain when it is called. For
 example, an iterator that initially contained seven active jobs following
 the execution of the Init procedure might complete after only four jobs
 were checked by the Next procedure, because the other three jobs
 completed.

 Terminal iterators are initialized to iterate over the terminal ports
 defined in the !Machine.Devices library. When one or more terminal ports
 are known, the Value function returns the first terminal port using the
 current value of the iterator. When no terminal ports are known, the Done
 function returns the value True using the current value of the iterator.

 Refer to the "Iteration Capabilities" subsection in the introduction to
 this package for more information and examples showing how to use
 iteration.


 PARAMETERS

 Iter : out Job_Iterator;

 Specifies the iterator.


 For_Session : Session_Id := Get_Session;

 Specifies the session for which the iterator should be created. The default
 is the calling session.


 Iter : out Session_Iterator;

 Specifies the iterator.


 Iter : out Terminal_Iterator;

 Specifies the iterator.


 REFERENCES

 function Done
 type Job_Iterator
 procedure Next
 type Session_Iterator
 type Terminal_Iterator
 function Value



 @node !Tools.System_Utilities.Input_Count

 function Input_Count (Line : Port := System_Utilities.Terminal)
                                            return Long_Integer;

 DESCRIPTION

 Returns the number of characters input from the specified port since the
 system was booted.

 Input from the port that has not been read by a session or user program is
 not counted as input.

 This function can be used, for example, to create an application that
 automatically logs out inactive user sessions. Such an application can use
 the Input_Count and Output_Count functions to determine whether any
 characters have recently been typed or output on the port for each
 session.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the input count is desired. The default
 is the port number associated with the current session.


 return Long_Integer;

 Returns the number of characters input from the specified port since the
 system was booted.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 function Output_Count



 @node !Tools.System_Utilities.Input_Name

 function Input_Name
                (For_Session : Session_Id :=
                 System_Utilities.Get_Session) return String;

 DESCRIPTION

 Returns the fully qualified pathname of the Standard_Input filename for the
 indicated session.

 If this file is opened using the I/O packages in the Environment, the input
 comes from an Environment input window. This function could be used, for
 example, in an application that redirects input for a job from an
 Environment input window (the correct filename would be needed to perform
 the redirection).


 PARAMETERS

 For_Session : Session_Id := System_Utilities.Get_Session;

 Specifies the session for which the filename is to be computed. The default
 is the current session.


 return String;

 Returns the fully qualified pathname of the file.



 @node !Tools.System_Utilities.Input_Rate

 function Input_Rate (Line : Port := System_Utilities.Terminal)
                                                 return String;

 DESCRIPTION

 Returns the input rate of the specified port.

 This function returns a string that contains the input rate of the
 specified port. By default, the function returns the input rate for the
 port through which the current session is logged in. This value can be
 changed with the Terminal.Set_Input_Rate procedure.

 Legal values for the input rate are:

   DISABLE       BAUD_50       BAUD_75       BAUD_110
   BAUD_134_5    BAUD_150      BAUD_200      BAUD_300
   BAUD_600      BAUD_1200     BAUD_1800     BAUD_2400
   BAUD_4800     BAUD_9600     BAUD_19200    EXT_REC_CLK

 The input rate EXT_REC_CLK is the value returned for Telnet ports. In
 general, this value indicates that the input rate of the data is
 determined by an external clock (and is not under local control). For a
 Telnet port, this means that the data transmission rate is not
 configurable. In this case, it is either the transmission rate of the
 Telnet port (10 Mbits per second) or the transmission rate at the remote
 end of the transmission (whichever of these two values is smaller).


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port for which the input rate is desired. The default is the
 port through which the current session is logged in.


 return String;

 Returns the input rate. Legal values are defined above.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 procedure Terminal.Set_Input_Rate



 @node !Tools.System_Utilities.Job_Id

 subtype Job_Id is Machine.Job_Id range 4 .. 255;

 DESCRIPTION

 Defines a representation for a job.

 Jobs are identified by a Job_Id number assigned by the Environment. Jobs
 are manipulated by procedures described in the Session and Job Management
 (SJM) book, package Job.


 REFERENCES

 Session and Job Management (SJM), package Job



 @node !Tools.System_Utilities.Job_Iterator

 type Job_Iterator is private;

 DESCRIPTION

 Defines a type that allows iterating over all jobs in a specified session.

 Objects of the Job_Iterator type contain all of the information necessary
 to iterate through all of the jobs in an active session (an active session
 is currently logged in to the system). The type is used with the Init and
 Next procedures and the Value and Done functions. Refer to the "Iteration
 Capabilities" subsection in the introduction to this package for more
 information about the job iterator.


 REFERENCES

 function Done
 procedure Init
 procedure Next
 type Session_Iterator
 type Terminal_Iterator
 function Value



 @node !Tools.System_Utilities.Job_Name

 function Job_Name (For_Job : Job_Id := System_Utilities.Get_Job)
                                                   return String;

 DESCRIPTION

 Returns the job name of the indicated job.

 This name appears in the job-name portion of the job header displayed in
 an Environment output window when a job is executed. The form of this job
 name is determined by the values of the session switches controlling the
 format of the job name (at the time the owner of the job executed it).

 If the job is not currently running, the Constraint_Error exception is
 raised.


 PARAMETERS

 For_Job : Job_Id := System_Utilities.Get_Job;

 Specifies the job for which to get the name. The default is the current
 job.


 return String;

 Returns the symbolic name of the indicated job.


 ERRORS

 The Constraint_Error exception is raised if the job is not currently
 running.



 @node !Tools.System_Utilities.Last_Login

 function Last_Login (User    : String;
                      Session : String := "") return Calendar.Time;

 DESCRIPTION

 Returns the calendar time at which the specified user logged into the
 specified session.

 By default, this function returns the time at which the user last logged
 into any session.


 PARAMETERS

 User : String;

 Specifies the simple name for the user.


 Session : String := "";

 Specifies the simple name for the session. The default value specifies that
 the last time the user logged into any session is to be computed.


 return Calendar.Time;

 Returns the time at which the user logged into the specified session.


 EXAMPLES

 The following example contains a call to the Last_Login function:

   procedure User_Last_Login (For_User : String :=
                                 System_Utilities.User_Name
                                 (System_Utilities.Get_Session)) is
       package Su renames System_Utilities;
       package Tu renames Time_Utilities;
   begin
       Io.Echo (For_User & " Last logged in on " &
                Tu.Image (Tu.Convert_Time (Su.Last_Login
                                                     (For_User))));
   end User_Last_Login;
   

 REFERENCES

 function Last_Logout
 package Calendar
 package Time_Utilities



 @node !Tools.System_Utilities.Last_Logout

 function Last_Logout (User    : String;
                       Session : String := "")
                       return Calendar.Time;

 DESCRIPTION

 Returns the calendar time at which the specified user logged out of the
 specified session.

 By default, this function returns the time at which the user last logged
 out of any session.


 PARAMETERS

 User : String;

 Specifies the simple name for the user.


 Session : String := "";

 Specifies the simple name for the session. The default value specifies that
 the last time the user logged out of any session is to be computed.


 return Calendar.Time;

 Returns the time at which the user logged out of the specified session.


 EXAMPLES

 The following example contains a call to function Last_Logout:

   procedure User_Last_Logout (For_User : String :=
                                 System_Utilities.User_Name
                                 (System_Utilities.Get_Session)) is
       package Su renames System_Utilities;
       package Tu renames Time_Utilities;
   begin
       Io.Echo (For_User & " Last logged out on " &
                Tu.Image (Tu.Convert_Time (Su.Last_Logout
                                                     (For_User))));
   end User_Last_Logout;
   

 REFERENCES

 function Last_Login
 package Calendar
 package Time_Utilities



 @node !Tools.System_Utilities.Log_Failed_Logins

 function Log_Failed_Logins (Line : Port :=
                             System_Utilities.Terminal)
                                        return Boolean;

 DESCRIPTION

 Determines whether the log-failed-logins option is enabled for the
 specified port.

 See package Terminal for more information on this option.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the number of the port through which the current session is logged in.


 return Boolean;

 Returns True if the option is currently enabled for the port; otherwise,
 the function returns False.


 REFERENCES

 procedure Terminal.Set_Log_Failed_Logins



 @node !Tools.System_Utilities.Logged_In

 function Logged_In (User    : String;
                     Session : String := "") return Boolean;

 DESCRIPTION

 Determines whether the specified user is logged into the specified session.

 By default, this function determines whether the specified user is logged
 into any session.


 PARAMETERS

 User : String;

 Specifies the simple name for the user.


 Session : String := "";

 Specifies the simple name for the session. The default value specifies that
 the check should be made to determine whether the user is logged into any
 session.


 return Boolean;

 Returns True if the user is logged in; otherwise, the function returns
 False.



 @node !Tools.System_Utilities.Login_Disabled

 function Login_Disabled (Line : Port := System_Utilities.Terminal)
                                                    return Boolean;

 DESCRIPTION

 Determines whether login is disabled for the specified port.

 When login is disabled, the function returns True. (Note that when login
 is disabled, the Operator.Enable_Terminal command fails for the specified
 port number.)

 See package Terminal for more information on disabling login for a port.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the number of the port through which the current session is logged in.


 return Boolean;

 Returns True if login is currently disabled for the port; otherwise, the
 function returns False.


 REFERENCES

 procedure Operator.Enable_Terminal
 procedure Terminal.Set_Login_Disabled



 @node !Tools.System_Utilities.Logoff_On_Disconnect

 function Logoff_On_Disconnect (Line : Port :=
                                System_Utilities.Terminal)
                                           return Boolean;

 DESCRIPTION

 Determines whether the logoff-on-disconnect option is enabled for the
 specified port.

 See package Terminal for more information on this option.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the number for which the information is desired. The default is
 the number of the port through which the current session is logged in.


 return Boolean;

 Returns True if the option is currently enabled for the port; otherwise,
 the function returns False.


 REFERENCES

 procedure Terminal.Set_Logoff_On_Disconnect



 @node !Tools.System_Utilities.Manufacturers_Bad_Blocks

 Manufacturers_Bad_Blocks : constant Bad_Block_Kinds := 1;

 DESCRIPTION

 Defines a value that indicates manufacturer-designated bad disk blocks.


 REFERENCES

 type Bad_Block_Kinds
 function Bad_Block_List
 constant Retargeted_Blocks



 @node !Tools.System_Utilities.Next

 procedure Next (Iter : in out Job_Iterator);

 procedure Next (Iter : in out Session_Iterator);

 procedure Next (Iter : in out Terminal_Iterator);

 DESCRIPTION

 Steps the iterator to point to the next element in the collection of jobs,
 sessions, or terminal ports.

 The Done, Init, Next, and Value functions and procedures are used together
 to form an iterator. Specific iterators are defined by the Job_Iterator,
 Session_Iterator, and Terminal_Iterator types.

 Refer to the "Iteration Capabilities" subsection in the introduction to
 this package for more information and examples showing how to use
 iteration.


 PARAMETERS

 Iter : in out Job_Iterator;

 Specifies the job iterator to be stepped.


 Iter : in out Session_Iterator;

 Specifies the session iterator to be stepped.


 Iter : in out Terminal_Iterator;

 Specifies the terminal-port iterator to be stepped.


 REFERENCES

 function Done
 procedure Init
 type Job_Iterator
 type Session_Iterator
 type Terminal_Iterator
 function Value



 @node !Tools.System_Utilities.Object

 subtype Object is Directory.Object;

 DESCRIPTION

 Defines a representation for an activity or entity in the Environment.

 Object is a subtype of type !Implementation.Directory.Object, which is an
 implementation detail of the R1000 library system. Certain procedure or
 function interfaces may require specifying an object parameter.


 REFERENCES

 subtype Version



 @node !Tools.System_Utilities.Output_Count

 function Output_Count (Line : Port := System_Utilities.Terminal)
                                             return Long_Integer;

 DESCRIPTION

 Returns the number of characters output to the specified port since the
 system was booted.

 An example application is a utility that automatically logs out inactive
 user sessions by using the Output_Count and Input_Count functions to
 determine whether any characters have recently been entered from or sent
 to a terminal device.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the number of the port through which the current session is logged in.


 return Long_Integer;

 Returns the output count in characters.


 REFERENCES

 function Input_Count
 function Terminal



 @node !Tools.System_Utilities.Output_Name

 function Output_Name
       (For_Session : Session_Id := System_Utilities.Get_Session)
                                                   return String;

                                                                           

 DESCRIPTION

 Returns the fully qualified pathname of the Standard_Output filename for the
 indicated session.

 If this file is opened using the I/O packages in the Environment, the
 output is sent to an Environment output window. This function can be used,
 for example, in an application that redirects output from a job to an
 Environment output window (the correct filename is needed to perform the
 redirection).


 PARAMETERS

 For_Session : Session_Id := System_Utilities.Get_Session;

 Specifies the session for which the filename is to be computed. The default
 is the current session.


 return String;

 Returns the filename.


 REFERENCES

 function Get_Session



 @node !Tools.System_Utilities.Output_Rate

 function Output_Rate (Line : Port := System_Utilities.Terminal)
                                                  return String;

 DESCRIPTION

 Returns the output rate of the specified port.

 This function returns a string that contains the output rate of the
 specified port. By default, the function returns the output rate for the
 port through which the current session is logged in. This value can be
 changed by using the Terminal.Set_Output_Rate procedure.

 Legal values for the output rate are:

   DISABLE       BAUD_50       BAUD_75       BAUD_110
   BAUD_134_5    BAUD_150      BAUD_200      BAUD_300
   BAUD_600      BAUD_1200     BAUD_1800     BAUD_2400
   BAUD_4800     BAUD_9600     BAUD_19200    EXT_REC_CLK

 The output rate EXT_REC_CLK is the value returned for Telnet ports. In
 general, this value indicates that the output rate of the data is
 determined by an external clock (and is not under local control). For a
 Telnet port, this means that the data-transmission rate is not
 configurable. In this case, it is either the transmission rate of the
 Telnet port (10 Mbits per second) or the transmission rate at the remote
 end of the transmission (whichever of these two values is less).


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the number of the port through which the current session is logged in.


 return String;

 Returns the output rate. Legal values are defined above.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 function Terminal
 procedure Terminal.Set_Output_Rate



 @node !Tools.System_Utilities.Parity

 function Parity (Line : Port := System_Utilities.Terminal)
                                        return Parity_Kind;

 DESCRIPTION

 Returns the kind of parity checking for the specified port.

 This function is used by the Terminal.Set_Parity procedure to control the
 kind of parity checking used between terminal devices connected directly
 to the R1000's RS232 ports.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the number of the port through which the current session is logged in.


 return Parity_Kind;

 Returns the parity kind.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 type Parity_Kind
 function Terminal
 procedure Terminal.Set_Parity



 @node !Tools.System_Utilities.Parity_Kind

 type Parity_Kind is (None, Even, Odd);

 DESCRIPTION

 Defines the allowed values for the kind of parity checking performed by the
 system and terminal.

 You can specify no parity, odd parity, or even parity for characters
 received and transmitted by an RS232 port. If an odd or even parity is
 selected, each transmitted character contains a parity bit that
 maintains either an odd or even number of 1 bits in the character. For
 example, if the character represented by 0100101
 is to be transmitted using even parity, a 1 is added in the eighth bit to
 make 10100101, which contains an even number of 1 bits. If odd parity were
 used, the eighth bit would be 0 to make 00100101, which contains an odd
 number of 1 bits.

 Parity is used to detect errors affecting an odd number of bits. (This is
 true regardless of whether even or odd parity is specified). If an even
 number of bits is affected, the error will not be detected. For example,
 if 01001011 is transmitted (even parity) but 01111011 is received, the
 error will not be detected, because the character still contains an even
 number of 1 bits. In modern serial communications, parity checking is
 commonly omitted. Some terminal devices, however, may be set for even or
 odd parity, and the port on the R1000 must be set to match.


 ENUMERATIONS


 Even

 Specifies that even parity checking be performed. This means that all bits
 transmitted for a single character, including the parity bit, will be an
 even number of 1s.


 None

 Specifies no parity checking.


 Odd

 Specifies that odd parity checking be performed. This means that all bits
 transmitted for a single character, including the parity bit, will be an
 odd number of 1s.


 REFERENCES

 function Parity
 procedure Terminal.Set_Parity



 @node !Tools.System_Utilities.Port

 subtype Port is Natural range 0 .. 4 * 16 * 16;

 DESCRIPTION

 Defines a representation for the Telnet and RS232 ports on the system.

 Each terminal device is connected to a specific port on the system; the
 specific port is assigned a value of this type. For each port there is a
 corresponding terminal object listed in the !Machine.Devices library
 with the name Terminal_N, where N is a port number.

              Table 17    Series 100-400 Hardware Port Assignments
         -------------------------------------------------------------- 
        |    |     |     |     |     |                                 |
        |    |Serie|Serie|Serie| Seri|                                 |
        |Port|s    |s    |s    | s   |               Notes             |
        |s   |100  |200  |300  | 400 |                                 |
         -------------------------------------------------------------- 
        |    |     |     |     |     |                                 |
        |1   |RS232|RS232|RS232| RS23| Used for operator console to    |
        |    |     |     |     |     | provide VT100-compatible, line- |
        |    |     |     |     |     | oriented Environment interface. |
        |    |     |     |     |     | Required to start machine.      |
         -------------------------------------------------------------- 
        |    |     |     |     |     |                                 |
        |2-15|Reser|Reser|Reser| Rese| Reserved for internal hardware  |
        |    |ved  |ved  |ved  | ved | use.                            |
         -------------------------------------------------------------- 
        |    |     |     |     |     |                                 |
        |16  |RS232|RS232|RS232| RS23| Typically used for operator's   |
        |    |     |     |     |     | Environment terminal to provide |
        |    |     |     |     |     | screen-oriented interface. On th|
        |    |     |     |     |     | Series 300, this port is labeled|
        |    |     |     |     |     | "External Modem." On the 400, it|
        |    |     |     |     |     | is labeled "Comm Port."         |
         -------------------------------------------------------------- 
        |    |     |     |     |     |                                 |
        |17- |RS232|RS232|Unuse| Unus| On the Series 100 and 200, the  |
        |47  |     |     |d    | d   | available range of ports (17-32 |
        |    |     |     |     |     | or 17-47) depends on how many   |
        |    |     |     |     |     | serial-communications panels    |
        |    |     |     |     |     | are installed. Typically, these |
        |    |     |     |     |     | ports are assigned to login     |
        |    |     |     |     |     | terminals, printers, and other  |
        |    |     |     |     |     | applications such as CDF        |
        |    |     |     |     |     | interfaces.                     |
         -------------------------------------------------------------- 
        |    |     |     |     |     |                                 |
        |48- |RS232|Unuse|Unuse| Unus| Ports 48-79 are available only o|
        |223 |     |d    |d    | d   | the Series 100, and only when   |
        |(48-|     |     |     |     | additional serial-communications|
        |79) |     |     |     |     | panels are installed. Ports     |
        |    |     |     |     |     | 80-223 are not available.       |
         -------------------------------------------------------------- 
        |    |     |     |     |     |                                 |
        |224-|Telne|Telne|Telne| Teln| Available as an upgrade on Serie|
        |255 |t    |t    |t    | t   | 100 and 200 machines; standard o|
        |    |upgra|upgra|     |     | Series 300 and 400 machines. The|
        |    |de   |de   |     |     | standard machine initialization |
        |    |     |     |     |     | for the current Environment     |
        |    |     |     |     |     | release configures ports 235-249|
        |    |     |     |     |     | as login ports.                 |
         -------------------------------------------------------------- 



 Also see package Queue for more information on the ports used to
 communicate with printers.

 Some Environment commands accept the port number as a parameter (for exam-
 ple: Flow_Control, Operator.Enable_Terminal, and Operator.Force_Logoff).
 Other commands display port numbers associated with jobs and logged-in
 users (for example: What.Users and What.Jobs). Ports can be opened for I/O
 by opening objects named !Machine.Devices.Terminal_N, where N is a port
 number.


 REFERENCES

 function Terminal
 package Terminal



 @node !Tools.System_Utilities.Priority

 function Priority (For_Job : Job_Id := System_Utilities.Get_Job)
                                                  return Natural;

 DESCRIPTION

 Returns the priority of the specified job.

 This function returns the CPU priority for the specified job. The
 priorities are defined in package Scheduler. By default, the function
 returns the priority of the current job.


 PARAMETERS

 For_Job : Job_Id := System_Utilities.Get_Job;

 Specifies the job for which the priority is desired. The default is the
 current job.


 return Natural;

 Returns the CPU priority of the specified job.


 REFERENCES

 function Scheduler.Get_Cpu_Priority



 @node !Tools.System_Utilities.Receive_Flow_Control

 function Receive_Flow_Control (Line : Port :=
                                System_Utilities.Terminal)
                                            return String;

 DESCRIPTION

 Determines what method, if any, is used for controlling the flow of data
 received from the device on the specified port.

 Certain devices use flow control to prevent data overruns. Some devices
 support hardware flow control (CTS receiving, RTS or DTR transmitting) and
 some devices support software flow control (through XON and XOFF
 transmissions).


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port to be checked for flow control. The default is the port
 number of the port through which the current session is logged in.


 return String;

 Returns the method used for controlling the flow of data received from the
 device.

 Four types of receive flow control are available:

 *  NONE: Indicates that there is no software or hardware flow control for
    the line.

 *  XON_XOFF: Indicates that software flow control is enabled for the line.
    This value indicates that the device should stop transmitting when it
    receives an XOFF from the Rational system and can resume transmission
    when it receives
    an XON.

 *  RTS: Indicates that hardware flow control based on the RTS modem
    control signal is enabled for the line. This value indicates that the
    device should stop transmitting when the Rational system switches the
    RTS modem control signal
    to "off" and can resume transmission when the signal is switched to
    "on."

 *  DTR: Indicates that hardware flow control based on the DTR modem
    control signal is enabled for the line. This value indicates that the
    device should stop transmitting when the Rational system switches the
    DTR modem control signal to "off" and can resume transmission when the
    signal is switched to "on."


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 procedure Terminal.Set_Receive_Flow_Control



 @node !Tools.System_Utilities.Receive_Xon_Xoff_Bytes

 function Receive_Xon_Xoff_Bytes (Line : Port :=
                                  System_Utilities.Terminal)
                                         return Byte_String;

 DESCRIPTION

 Returns the two-byte string that contains the XON and XOFF characters for
 the receiving side of the specified port.

 This function returns a byte string with two bytes in it. The XON byte,
 the first byte, enables transmitting. The XOFF byte, the second byte,
 disables transmitting. These bytes are used for terminal devices that do
 not have hardware flow control.

 The bytes can be changed by using the Terminal.Set_Receive_Xon_Xoff_Bytes
 procedure.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port for which the information is desired. The default is the
 number of the port through which the current session logged in.


 return Byte_String;

 Returns the two-byte string containing the XON and XOFF bytes.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 procedure Terminal.Set_Receive_Xon_Xoff_Bytes



 @node !Tools.System_Utilities.Receive_Xon_Xoff_Characters

 function Receive_Xon_Xoff_Characters
                  (Line : Port := System_Utilities.Terminal)
                                  return String;

 DESCRIPTION

  Returns the two-character string that contains the XON and XOFF
 characters for the receive side of the specified port.

 This function returns a string with two characters in it. XON, the first
 character, enables transmitting. XOFF, the second character, disables
 transmitting. These characters are used for terminal devices that do not
 have hardware flow control.

 The characters can be changed by using the Terminal.Set_Receive_Xon_Xoff-
 _Characters procedure.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the port number of the port through which the current session is logged
 in.


 return String;

 Returns the two characters.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 procedure Terminal.Set_Receive_Xon_Xoff_Characters



 @node !Tools.System_Utilities.Retargeted_Blocks

 Retargeted_Blocks : constant Bad_Block_Kinds := 2;

 DESCRIPTION

 Defines a value that indicates retargeted disk blocks.


 REFERENCES

 constant All_Bad_Blocks
 type Bad_Block_Kinds
 function Bad_Block_List
 constant Manufacturers_Bad_Blocks



 @node !Tools.System_Utilities.Session

 function Session (For_Session : Session_Id :=
                                 System_Utilities.Get_Session)
                                                  return Version;

 function Session (For_Session : Session_Id :=
                                 System_Utilities.Get_Session)
                                                  return Object;

 DESCRIPTION

 Returns the version or object for the specified session.

 By default, the value for the current session is returned.


 PARAMETERS

 For_Session : Session_Id := System_Utilities.Get_Session;

 Specifies the session for which the version or object is desired. The
 default is the current session.


 return Version;



 Returns the directory version.


 return Object;



 Returns the directory object.


 REFERENCES

 subtype Object
 subtype Version



 @node !Tools.System_Utilities.Session_Id

 subtype Session_Id is Machine.Session_Id;

 DESCRIPTION

 Defines a representation for a user's session.

 A session is referenced by the Environment through a corresponding
 Session_Id. Sessions are created when a user logs into the system, and
 they are permanent objects in the user's home library unless they are
 explicitly deleted or destroyed.



 @node !Tools.System_Utilities.Session_Iterator

 type Session_Iterator is private;

 DESCRIPTION

 Defines a type that allows iterating over all sessions currently active in
 the Environment (that is, all sessions currently logged into the
 system).

 Objects of the Session_Iterator type contain all of the information
 necessary to iterate over all of the sessions. The type is used with the
 Init and Next procedures and the Value and Done functions. Refer to the
 "Iteration Capability" subsection in the introduction to this package for
 more information about the session iterator.


 REFERENCES

 function Done
 procedure Init
 type Job_Iterator
 procedure Next
 type Terminal_Iterator
 function Value



 @node !Tools.System_Utilities.Session_Name

 function Session_Name
       (For_Session : Session_Id := System_Utilities.Get_Session)
                                                   return String;

 DESCRIPTION

 Returns the name of the specified session.

 This function returns a string that contains the simple name of the
 specified session. By default, the function returns the name of the
 current session.


 PARAMETERS

 For_Session : Session_Id := System_Utilities.Get_Session;

 Specifies the session for which the name is desired. The default is the
 current session.


 return String;



 Returns the simple pathname name of the session (S_1).


 REFERENCES

 function Session
 subtype Session_Id



 @node !Tools.System_Utilities.Set_Page_Limit

 procedure Set_Page_Limit (Max_Pages : Natural;
                           For_Job   : Job_Id  :=
                           System_Utilities.Get_Job);

 DESCRIPTION

 Sets the upper limit for the virtual-memory pages created by the specified
 job (each page is 1,024 bytes).

 When a job begins, it is assigned a default page limit. By default, a job
 is allowed to create 8,000 pages. This default is determined by the value
 of the Session.Default_Job_Page_Limit session switch. Refer to the
 Session and Job Management (SJM) book for more information on this switch.

 If a job is elaborating Ada units, up to twice the maximum default page
 limit can be specified by these units through the Page_Limit pragma or the
 R1000_Cg.Page_Limit library switch. Refer to package Switches in the
 Library Management (LM) book for more information this switch and pragma.

 If a job attempts to create additional pages beyond the maximum page
 limit, the Storage_Error exception will be raised.

 Operator capability is required to set the page limit for jobs of users
 different from the caller.

 Note that the limit does not apply to the pages of files that the job is
 accessing; it applies only to data and stack space used by a job.


 PARAMETERS

 Max_Pages : Natural;
                                                                           

 Specifies the maximum number of pages that can be created by the job. In
 some cases, the job can create up to twice the maximum page limit before
 getting a storage error.


 For_Job : Job_Id := System_Utilities.Get_Job;

 Specifies the job for which to set the page limit. By default, the limit
 will be set for the calling job.


 ERRORS

 If a job attempts to create additional pages beyond the maximum page
 limit, the Storage_Error exception will be raised. This exception may not
 be raised immediately, but in the worst case the job will not be able to
 create more than twice the maximum page limit before getting a storage
 error.


 REFERENCES

 procedure Get_Page_Counts



 @node !Tools.System_Utilities.Stop_Bits

 function Stop_Bits (Line : Port := System_Utilities.Terminal)
                                    return Stop_Bits_Range;

 DESCRIPTION

 Returns the number of stop bits being used by the terminal device
 connected to the specified port.

 The Stop_Bits_Range value can be changed by using the
 Terminal.Set_Stop_Bits procedure.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the number of the port through which the current session is logged in.


 return Stop_Bits_Range;



 Returns the number of stop bits.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 subtype Stop_Bits_Range
 procedure Terminal.Set_Stop_Bits



 @node !Tools.System_Utilities.Stop_Bits_Range

 subtype Stop_Bits_Range is Integer range 1 .. 2;

 DESCRIPTION

 Defines the allowed values for the number of stop bits.

 Stop bits are part of the RS232 protocol used to communicate between a
 terminal device and the system. The number of stop bits is determined by
 the requirements of the terminal device.


 REFERENCES

 function Stop_Bits
 procedure Terminal.Set_Stop_Bits



 @node !Tools.System_Utilities.System_Boot_Configuration

 function System_Boot_Configuration return String;

 DESCRIPTION

 Returns the name of the Environment software configuration that the system
 is running.

 This is the same name that is printed in the message window when users log
 into the Environment.


 PARAMETERS

 return String;



 Returns the name of the software configuration.



 @node !Tools.System_Utilities.System_Up_Time

 function System_Up_Time return Calendar.Time;

 DESCRIPTION

 Returns the calendar time when the system was last booted.


 PARAMETERS

 return Calendar.Time;



 Returns the time when the system was last booted.


 EXAMPLES

 The following example procedure calls the System_Up_Time function and
 displays the return value:

   procedure When_System_Booted is
       package Su renames System_Utilities;
       package Tu renames Time_Utilities;
   begin
       Io.Echo ("System last booted on " &
                Tu.Image (Tu.Convert_Time (Su.System_Up_Time)));
   end When_System_Booted;

 REFERENCES

 Programming Tools (PT), package Calendar
 Programming Tools (PT), package Time_Utilities



 @node !Tools.System_Utilities.Tape

 subtype Tape is Natural range 0 .. 3;

 DESCRIPTION

 Defines the possible tape drives for the system.



 @node !Tools.System_Utilities.Tape_Name

 function Tape_Name (Drive : Tape := 0) return String;

 DESCRIPTION

 Returns the pathname of the tape object in the library system associated
 with the specified drive.


 PARAMETERS

 Drive : Tape := 0;

 Specifies the tape drive for which the pathname is desired.


 return String;



 Returns the pathname of the tape object associated with the specified tape
 drive.



 @node !Tools.System_Utilities.Terminal


 function Terminal (For_Session : Session_Id :=
                                  System_Utilities.Get_Session)
                                                   return Port;

 function Terminal (For_Session : Session_Id :=
                                  System_Utilities.Get_Session)
                                                return Version;

 function Terminal (For_Session : Session_Id :=
                                  System_Utilities.Get_Session)
                                                 return Object;

 DESCRIPTION

 Returns the port number, the version of the port, or the port object
 associated with the current session.

 By default, the value for the current session is returned.

 Each terminal device is connected to a specific port on the system. For
 more information about these ports, see the reference entry for subtype
 Port and the introduction to package Terminal in this book.


 PARAMETERS

 For_Session : Session_Id := System_Utilities.Get_Session;

 Specifies the session for which the port number, version, or object is
 desired. The default is the current session.


 return Port;



 Returns the port number. (See the reference entry for subtype Port.)


 return Version;



 Returns the directory version of the port.


 return Object;



 Returns the directory object of the port.


 REFERENCES

 subtype Object
 subtype Port
 subtype Version
 package Terminal



 @node !Tools.System_Utilities.Terminal_Columns

 function Terminal_Columns (Line : Port :=
                            System_Utilities.Terminal)
                                     return Natural;

 DESCRIPTION

 Returns the width (in columns) of the Environment display that is
 associated with the specified port.

 This function is especially useful for determining the size of an RWI or
 RXI window. (RXI is the Rational X Interface, which provides Environment
 terminal emulators within the X Window System; RWI is the Rational
 Windows Interface, which provides Environment terminal emulators within
 Microsoft Windows.)


 PARAMETERS

 Line : Port := System_Utilities.Terminal

 Specifies the number of the port to be queried. The default is the number
 of the port through which the current session is logged in.


 return Natural;



 Returns the number of columns in the Environment display associated with
 the specified port.


 REFERENCES

 function Terminal_Lines



 @node !Tools.System_Utilities.Terminal_Iterator

 type Terminal_Iterator is private;

 DESCRIPTION

 Defines a type for iterating through all Telnet and RS232 port numbers that
 exist on a system.

 Each number (returned from the Value function) can be translated to an
 object name, using the Terminal_Name function.

 This type is used with the Init and Next procedures and the Value and Done
 functions. Refer to the "Iteration Capability" subsection in the
 introduction to this package for more information about the terminal
 iterator.


 REFERENCES

 function Done
 procedure Init
 type Job_Iterator
 procedure Next
 type Session_Iterator
 function Value



 @node !Tools.System_Utilities.Terminal_Lines

 function Terminal_Lines (Line : Port :=
                            System_Utilities.Terminal)
                                     return Natural;

 DESCRIPTION

 Returns the length (in lines) of the Environment display that is
 associated with the specified port.

 This function is especially useful for determining the size of an RXI or
 RWI window. (RXI is the Rational X Interface, which provides Environment
 terminal emulators within the X Window System; RWI is the Rational
 Windows Interface, which provides Environment terminal emulators within
 Microsoft Windows.)


 PARAMETERS

 Line : Port := System_Utilities.Terminal

 Specifies the number of the port to be queried. The default is the port
 number of the port through with the current session is logged in.


 return Natural;



 Returns the number of lines in the Environment display associated with the
 specified port.


 REFERENCES

 function Terminal_Columns



 @node !Tools.System_Utilities.Terminal_Name

 function Terminal_Name (Line : Port := System_Utilities.Terminal)
                                                    return String;

 DESCRIPTION

 Returns the fully qualified pathname of the terminal-port object for the
 specified port.

 Terminal-port objects are contained in !Machine.Devices.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port for which the pathname is desired. The default is the
 port number of the terminal-port object associated with the current
 session.


 return String;



 Returns the fully qualified pathname of the terminal-port object-for
 example: !Machine.Devices.Terminal_245.



 @node !Tools.System_Utilities.Terminal_Type

 function Terminal_Type (Line : Port := System_Utilities.Terminal)
                                                    return String;

 DESCRIPTION

 Returns the name of the terminal type in use by the specified port.

 This value can be changed by using the Terminal.Set_Terminal_Type
 procedure; this has little benefit, however, since only the output driver
 for the terminal type is changed--other elements of the terminal type,
 such as the key bindings, remain unaffected. See package Terminal for more
 information.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the port number of the port through which the current session is logged
 in.


 return String;



 Returns the name for the terminal type associated with the specified port.

 Note that if the Terminal.Set_Terminal_Type procedure was executed before
 a call to Terminal_Type function, the return value will not reflect a
 consistent terminal type, since only the output driver, and not the key
 binding, is changed by Terminal.Set_Terminal_Type.


 REFERENCES

 procedure Terminal.Set_Terminal_Type



 @node !Tools.System_Utilities.User

 function User (For_Session : Session_Id :=
                              System_Utilities.Get_Session)
                                            return Version;

 function User (For_Session : Session_Id :=
                              System_Utilities.Get_Session)
                                             return Object;

 DESCRIPTION

 Returns the version or object that represents the user for the specified
 session.

 By default, the function returns the user for the current session.


 PARAMETERS

 For_Session : Session_Id := System_Utilities.Get_Session;

 Specifies the session for which the user is desired. The default returns
 the user for the current session.


 return Version;



 Returns the directory version of a user corresponding to the specified
 session.


 return Object;



 Returns the directory object of a user corresponding to the specified
 session.



 @node !Tools.System_Utilities.User_Name

 function User_Name (For_Session : Session_Id :=
                     System_Utilities.Get_Session)
                                return String;

 DESCRIPTION

 Returns the username of the user who created the specified session.

 This function returns a string that contains the simple name of the user
 who created the specified session. By default, the function returns the
 username for the current session.


 PARAMETERS

 For_Session : Session_Id := System_Utilities.Get_Session;

 Specifies the session for which the username is desired. The default is the
 current session.


 return String;



 Returns the username.



 @node !Tools.System_Utilities.Value

 function Value (Iter : Job_Iterator) return Job_Id;

 function Value (Iter : Session_Iterator) return Session_Id;

 function Value (Iter : Terminal_Iterator) return Natural;

 DESCRIPTION

 Returns the current iterator value for the element in a collection of
 sessions, jobs, or terminal ports.

 The Done, Init, Next, and Value functions and procedures are used together
 to form an iterator. Specific iterators are defined by the Job_Iterator,
 Session_Iterator, and Terminal_Iterator types.

 Refer to the "Iteration Capabilities" subsection in the introduction to
 this package for more information and examples showing how to use
 iteration.


 PARAMETERS

 Iter : Job_Iterator;

 Specifies the iterator for which the job identifier is desired.


 return Job_Id;



 Returns the job identifier.


 Iter : Session_Iterator;

 Specifies the iterator for which the session identifier is desired.


 return Session_Id;



 Returns the session identifier.


 Iter : Terminal_Iterator;

 Specifies the iterator for which the terminal number is desired.


 return Natural;



 Returns the terminal number.


 REFERENCES

 function Done
 procedure Init
 type Job_Iterator
 procedure Next
 type Session_Iterator
 type Terminal_Iterator



 @node !Tools.System_Utilities.Version

 subtype Version is Directory.Version;

 DESCRIPTION

 Defines a type for a version.

 Version is a subtype of type !Implementation.Directory.Version, which is
 an implementation detail of the R1000 library system. The Environment
 maintains multiple versions for each object in the directory system.
 Version numbers are assigned by the Environment when each version is
 created. Certain procedure or function interfaces may require specifying a
 version parameter.

 See the Library Management (LM) book for more information on versions.



 @node !Tools.System_Utilities.Xon_Xoff_Bytes

 function Xon_Xoff_Bytes (Line : Port := System_Utilities.Terminal)
                                                return Byte_String;

 DESCRIPTION

 Returns the two-byte string that contains the XON and XOFF bytes for the
 transmitting side of the specified port.

 This function returns a byte string with two bytes in it. The XON byte,
 the first byte, enables transmitting. The XOFF byte, the second byte,
 disables transmitting. These bytes are used for terminal devices that do
 not have hardware flow control, and they vary with different kinds of
 terminal devices. These bytes can be changed using the
 Terminal.Set_Xon_Xoff_Bytes procedure.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the port number of the port through which the current session is logged
 in.


 return Byte_String;

 Returns the two bytes.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 function Receive_Xon_Xoff_Bytes
 function Xon_Xoff_Characters
 procedure Terminal.Set_Xon_Xoff_Bytes



 @node !Tools.System_Utilities.Xon_Xoff_Characters

 function Xon_Xoff_Characters (Line : Port :=
                               System_Utilities.Terminal)
                                           return String;

 DESCRIPTION

 Returns the two-character string that contains the XON and XOFF characters
 for the transmitting side of the specified port.

 This function returns a string with two characters in it. XON, the first
 character, enables transmitting. XOFF, the second character, disables
                                                                           

 transmitting. These characters are used for terminal devices that do not
 have hardware flow control, and they vary depending on the kind of
 terminal device. The characters can be changed using the
 Terminal.Set_Xon_Xoff_Characters procedure.


 PARAMETERS

 Line : Port := System_Utilities.Terminal;

 Specifies the port number for which the information is desired. The default
 is the number of the port through which the current session is logged in.


 return String;



 Returns the two characters.


 RESTRICTIONS

 This function returns valid information only for RS232 ports.


 REFERENCES

 function Receive_Xon_Xoff_Characters
 function Xon_Xoff_Bytes
 procedure Terminal.Set_Xon_Xoff_Characters



 @node !Commands.Tape

 Package Tape commands can be used to build, read, write, or display the
 labels from standard ANSI tapes, to unload or rewind tapes, and to display
 the hexadecimal and ASCII contents of any tapes. These commands are
 listed below.


 RESOURCES IN PACKAGE TAPE

 The commands in this package fall into the following functional groups:

 Displaying the contents of a tape: Display_Tape

 Processing an ANSI-labeled tape:  Examine_Labels, Format_Tape, Read, Write

 Unloading and rewinding a tape:   Rewind, Unload


 KEY CONCEPTS FOR PACKAGE TAPE

 Package Tape commands can be used for either 8-millimeter or 9-track tapes
 (also called tape volumes or volumes).

 Refer to the System Manager's Guide for definitions of the following terms:

 *  Record formats (fixed-length, variable-length, and spanned)

 *  ANSI-labeled tape formats (straight and chained)

 *  Unlabeled tapes

 *  Tape labels

 *  Block length

 *  Single-volume and multivolume file sets (one or more files recorded
    contiguously over one or more tapes)

 *  Volume-set names

 Also refer to the System Manager's Guide for a description of tape
 operations, including how to:

 *  Answer a tape-mount request displayed on the operator console

    Depending on whether or not the tape drive is already allocated to the
    user's session, some package Tape commands require the operator or
    system manager to respond to a tape-mount request.

 *  Choose among multiple tape-mount requests

 *  Assign volume identifiers (used to uniquely identify each tape volume)

 *  Choose the proper tape format when transferring information between an
    R1000 and some other system, such as a VAX

 *  Read multivolume sets generated by a non-R1000 system

 *  Transfer binary files between R1000s (using the Archive.Save and
    Archive.Restore commands)

 *  Make a DFS backup or a system backup

 Finally, the Rational Software Library Catalog offers other, more
 specialized tape utilities that can, for example, read tapes written in
 UNIX tar format.


 Processing ANSI-Labeled Tapes

 Several package Tape commands are used to process ANSI-labeled tapes. For
 example, you can:

 *  Create an ANSI-labeled tape using the Format_Tape command

 *  Examine ANSI tape labels using the Examine_Labels command

 *  Read and write ANSI-labeled tapes using the Read and Write commands


 Displaying the Contents of Non-ANSI Tapes

 The Display_Tape command allows you to display the contents of any tape,
 in both ASCII and hexadecimal notation.


 Transferring Data between Systems by Tape

 The Read and Write commands are useful when transferring information
 between two different kinds of systems that are not connected by a network
 (for example, when transferring files between a VAX and the R1000).

 However, these commands process only files that can be manipulated by
 package Io, which excludes such objects as activities, switch files,
 session objects, DIANA structures, and so on. In addition, these commands
 do not preserve the original names and classes of Environment objects. To
 move other files or objects between R1000 systems that are not connected by
 a network, or to preserve the original names and classes of objects when
 moving them, use the Archive.Save and Archive.Restore commands.

 To create backup tapes for restoring data onto the same machine or a new
 machine, see the System Manager's Guide.


 Other Tape Operations

 The Rewind command allows you to rewind a tape from a remote location and
 leave the tape drive online.

 The Unload command allows you to rewind a tape, unload it, and leave the
 tape drive offline.


 @node !Commands.Tape.Display_Tape

 procedure Display_Tape (Drive             : Natural := 0;
                         Marks_To_Skip     : Integer := 0;
                         Records_To_Skip   : Integer := 0;
                         Blocks_To_Display : Natural := 10);

 DESCRIPTION

 Produces hexadecimal and ASCII displays of the contents of a specified
 portion
 of tape in an Environment output window.

 This command can display the contents of both unlabeled tapes (which do
 not have volume identifiers) and labeled tapes (which do have volume
 identifiers).

 Unless the tape drive is already allocated to the user's session, a
 tape-mount request is displayed on the operator console following the
 promotion of this command. The operator or system manager is usually
 responsible for responding to this tape-mount request. Refer to the System
 Manager's Guide for more information on how to respond to a tape-mount
 request.


 Positioning the Tape

 This command allows you to specify what area of the tape to display,
 relative to its current position. If the tape drive is already allocated
 to your session, successive promotions of this command do not rewind the
 tape. This allows you to display adjoining portions of the tape.

 You can position the tape before displaying its contents by skipping tape
 marks, tape records, or both.

 A tape mark divides the tape into logical segments. For example, an
 ANSI-labeled tape might have the form:

 <labels> <tape_mark> <user data> <tape_mark> <labels> <tape_mark> . . .

 Here, tape marks separate user data from tape labels. Two consecutive tape
 marks typically indicate the logical end of the tape.

 Note: A tape record is another name for a tape block, and it has nothing
 to do with logical file records.

 In the above example, the labels and user data each consist of one or more
 tape blocks.

 If both marks and records are specified, marks are skipped first and then
 records are skipped. Marks and records can be specified either forward from
 the current position (positive parameter values) or backward from the
 current position (negative parameter values).

 When skipping from tape mark to tape mark, the tape controller does not read
 the intervening tape blocks; when skipping tape blocks, it reads the
 blocks before skipping them. Therefore, when given the choice of
 traversing a tape by skipping either tape marks or tape blocks, it is much
 faster to move the tape using Marks_To_Skip rather than Records_To_Skip.


 PARAMETERS

 Drive : Natural := 0;

 Specifies from which tape drive to display the contents of a tape. The
 default is drive 0.


 Marks_To_Skip : Integer := 0;

 Specifies the number of tape marks to skip. Negative values move the tape
 backward and positive values move the tape forward.

 The default for this parameter is to skip no marks.


 Records_To_Skip : Integer := 0;

 Specifies the number of tape blocks to skip. Negative values move the tape
 backward and positive values move the tape forward.

 The tape controller reads each tape block as it skips from one to tape
 block to another. If a tape mark is encountered while skipping from one
 tape block to another, the Display_Tape procedure halts the tape where the
 tape mark is encountered and displays the message Tape Mark Encountered.

 The default for this parameter is to skip no tape blocks.


 Blocks_To_Display : Natural := 10;

 Specifies the number of tape blocks to display. When zero tape blocks are
 specified, the tape moves to a position specified by one or both of the
 Records_To_Skip and Marks_To_Skip parameter(s), no error is generated,
 and no tape blocks are displayed.

 The default for this parameter is to display 10 blocks.


 RESTRICTIONS

 The Environment supports a maximum tape-block size of 4,096 bytes.


 EXAMPLES

 The command:

   Tape.Display_Tape (Drive             => 0,
                      Marks_To_Skip     => 0,
                      Records_To_Skip   => 0,
                      Blocks_To_Display => 10);

 displays 10 tape blocks from the current position of the tape, unless a
 tape mark is encountered before 10 blocks are read. The data is displayed
 in hexadecimal on the left; ASCII character equivalents are displayed on
 the far right. Unprintable ASCII characters (for example, null characters)
 are represented by periods. For example:

   Block 1,  Length 80 (50)
       0  454F 4631 564D 5346 524D 5454 532E 5458  EOF1VMSFRMTTS.TX
      10  5420 2020 2030 3239 3730 3030 3030 3130  T    02970000010
      20  3030 3330 3030 3130 3020 3931 3135 3120  003000100 91151
      30  3030 3030 3020 3030 3030 3031 5231 3030  00000 000001R100
      40  303A 5630 3031 2E30 3020 2020 2020 2020  0:V001.00

   Block 2,  Length 80 (50)
       0  454F 4632 4430 3230 3438 3030 3531 3620  EOF2D0204800516
      10  2020 2020 2020 2020 2020 2020 2020 2020
      20  2020 2020 2020 2020 2020 2020 2020 2020
      30  2020 3030 2020 2020 2020 2020 2020 2020    00
      40  2020 2020 2020 2020 2020 2020 2020 2020

   Tape Mark Encountered

 This display shows two tape blocks and a Tape Mark Encountered message.
 The two tape blocks correspond to end-of-file labels; the Tape Mark
 Encountered message indicates that a tape mark has been encountered and
 that, therefore, no further blocks are displayed.



 @node !Commands.Tape.Error

 Error : exception;

 DESCRIPTION

 Defines an exception that is raised by several procedures in this package
 when errors occur.



 @node !Commands.Tape.Examine_Labels

 procedure Examine_Labels
                      (Vol_Id             : String  := "";
                       Vol_Set_Name       : String  := "";
                       To_Operator        : String  := "Thank You";
                       Volume_Labels_Only : Boolean := True);

 DESCRIPTION

 Displays the labels from the specified ANSI-formatted tape in an
 Environment output window.

 This command is useful when trying to identify an unmarked ANSI tape. The
 Volume_Labels_Only parameter can be set to False to provide additional
 information about the contents of the tape by displaying other labels on
 the tape. For example, file labels contain information such as the tape's
 record format.

 A tape-mount request is displayed on the operator console following the
 promotion of this command. The operator or system manager is usually
 responsible for responding to this tape-mount request. Refer to the System
 Manager's Guide for more information on how to respond to a tape-mount
 request.


 PARAMETERS

 Vol_Id : String := "";

 Specifies the volume identifier for the tape whose labels are to be
 displayed.

 The specified string is either padded on the right with blanks to a length
 of six characters or truncated on the right to shorten it to six
 characters, as appropriate. The resulting string must either be blank or
 exactly match the tape's existing volume identifier; otherwise, an error
 is generated and no labels are displayed.


 Vol_Set_Name : String := "";

 Specifies the name of the volume set to be examined. The default specifies a
 blank volume identifier. This information is used only as part of the
 operator's tape-mount request; it is not verified against the tape's
 existing volume-set name.


 To_Operator : String := "Thank You";

 Specifies a message to be displayed on the operator console following the
 promotion of this command. This provides a way for the user to send
 additional information to the operator or system manager about which
 tape to mount.


 Volume_Labels_Only : Boolean := True;

 Specifies whether to examine all the labels on the tape or only the volume
 labels. The default specifies that only volume labels are to be displayed.


 EXAMPLES

 The following command displays only the tape's volume labels:

   Tape.Examine_Labels (Vol_Id             => "",
                        Vol_Set_Name       => "",
                        To_Operator        => "Thank you",
                        Volume_Labels_Only => True);

 A typical output looks like this:

   Volume Labels
    Volume Id: 029700
    Accessibility: ' '
    Owner_Id:
                       2020 2020 2020 2020 2020 2020 2020

 The following command displays all tape labels (volume, file, and
 end-of-file labels):

   Tape.Examine_Labels (Vol_Id             => "",
                        Vol_Set_Name       => "",
                        To_Operator        => "Thank you",
                        Volume_Labels_Only => False);

 A typical output looks like this:

   Volume Labels
    Volume Id: 029700
    Accessibility: ' '
    Owner_Id:
                       2020 2020 2020 2020 2020 2020 2020

   File Labels
    File Identifier: INDEX.MAP
    File Set Identifier: 029700
    File Sequence Number: 1 File Section Number: 1
    Generation Number: 1 Generation Version Number: 0
    Creation Date: 05/31/91
    Expiration Date: 01/01/01
    Accessibility: ' '
    System Code: R1000:V001.00
    Record Format: VARIABLE_LENGTH
    Block Length: 2048
    Record Length: 516
    Reserved Field:
                       2020 2020 2020 2020 2020 2020 2020 2020
                       2020 2020 2020 2020 2020 2020 2020 2020
                       2020 20
    Buffer Offset: 0
    . . .
   End Of File Labels
    Block Count: 1
   File Labels
    File Identifier: INDEX.MAP
    File Set Identifier: 029700
    File Sequence Number: 6 File Section Number: 1
    Generation Number: 1 Generation Version Number: 0
    Creation Date: 05/31/91
    Expiration Date: 01/01/01
    Accessibility: ' '
    System Code: R1000:V001.00
    Record Format: VARIABLE_LENGTH
    Block Length: 2048
    Record Length: 516
    Reserved Field:
                       2020 2020 2020 2020 2020 2020 2020 2020
                       2020 2020 2020 2020 2020 2020 2020 2020
                       2020 20
    Buffer Offset: 0


 @node !Commands.Tape.Format_Tape

 procedure Format_Tape (Drive  : Natural := 0;
                        Vol_Id : String  := "");

 DESCRIPTION

 Initializes the tape on the specified drive by formatting it with ANSI
 labels that contain the specified volume identifier.

 This command is useful for sites that choose to follow a strict ANSI
 policy by assigning a unique volume identifier to each tape at the time
 the tape is initialized. Refer to the System Manager's Guide for more
 information on how to assign volume identifiers using this strategy.

 Unless the tape drive is already allocated to the user's session, a
 tape-mount request is displayed on the operator console following the
 promotion of this command. The operator or system manager is usually
 responsible for responding to this tape-mount request. Refer to the System
 Manager's Guide for more information on how to respond to a tape-mount
 request.


 PARAMETERS

 Drive : Natural :=0;

 Specifies on which tape drive to format the tape. The default is drive 0.


 Vol_Id : String := "";

 Specifies a standard six-character ANSI volume identifier with which to
 label the tape.

 The specified string is either padded on the right with blanks to a length
 of six characters or truncated on the right to shorten it to six
 characters, as appropriate. For example, if the null string (the default)
 is specified, then the volume identifier consists of six blanks and the tape
 is treated as an unlabeled tape during the tape-mount request.



 @node !Commands.Tape.Read

 procedure Read (Volume      : String;
                 Directory   : String := "$";
                 Options     : String := "R1000 Add_New_Line";
                 To_Operator : String := "Thank You";
                 Response    : String := "<PROFILE>");

 DESCRIPTION

 Reads an ANSI-formatted tape and copies its contents into the specified
 directory.

 Files read from an ANSI tape into an Environment directory are always
 restored as objects of class File.

 A tape-mount request is displayed on the operator console following the
 promotion of this command. The operator or system manager is usually
 responsible for responding to this tape-mount request. Refer to the System
 Manager's Guide for more information on how to respond to a tape-mount
 request.


 Recreating Ada Units from Source Files

 Tape files that contain Ada source can be parsed and restored to the
 Environment as Ada units using the Compilation.Parse command. This applies
 to tape files that:

 *  Were written by a foreign host (such as a VAX/VMS system)

 *  Contain Ada source in nonbinary form (for example, tapes written using
    the Write command)


 PARAMETERS

 Volume : String;

 Specifies the volume identifier of the tape that is being read.

 The specified string is either padded on the right with blanks to a length
 of six characters or truncated on the right to shorten it to six
 characters, as appropriate. The resulting string must either be blank or
 exactly match the tape's existing volume identifier; otherwise, an error
 is generated and the tape is not read.


 Directory : String := "$";

 Specifies the Environment directory destination for the files being read.
 The default is the enclosing directory. This directory must already exist;
 it cannot be created by specifying a new directory name when promoting
 this command. Also, a remote directory cannot be specified.


 Options : String := "R1000 Add_New_Line";

 Specifies options that can be used when reading tapes, as described below.


 *  Add_New_Line

    Specifies whether to add an ASCII newline character following each
    record read from tape. Without this option, bytes are copied from tape
    as a continuous stream of characters.


 *  Format= literal

    Specifies the format in which the tape was written. The format can be
    specified as, for example, R1000 or as Format = R1000. Valid formats
    are:

    R1000                Specifies a tape formatted for an R1000 system
                         (this is the default).

    MV                   Specifies a tape formatted for a Data General MV
                         system.

    VAX/VMS              Specifies a tape formatted for a VAX/VMS system.


 To_Operator : String := "Thank You";

 Specifies a message to be displayed on the operator console following the
 promotion of this command. This provides a way for the user to send
 additional information to the operator or system manager about which
 tape to mount.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 This command can read only files that can be manipulated by package Io, and
 it reads them only as objects of class File.

 To move other files or objects between R1000s using tape, or to preserve
 the original names and classes of objects when moving them, use the
 Archive.Save and Archive.Restore commands.

 Caution: Since the Read procedure reads all files into one directory, this
 data will not be distributed across all disks. Use caution when reading a
 tape that contains enough data to completely fill a single disk.


 EXAMPLES

 The command:

   Tape.Read (Volume    => "070501",
              Directory => "!users.thales",
              Options   => "vax/vms");

 reads the tape with the specified ANSI volume label. The files on the tape
 are read to the directory !Users.Thales. The VAX/VMS value for the Options
 parameter informs the Environment that the tape was written as a
 VAX/VMS-compatible ANSI tape.

 Suppose the tape read by the command shown above contains two tape files
 named Vmsfrmtts.Txt and Vtextfild.Ada. If these tape files are read into an
 empty !User.Thales directory, the directory would then look like this:

   !Users.Thales
     Index_Map        : File;
     Vmsfrmtts_Txt    : File;
     Vtextfild_Ada    : File;

 In this example, notice that along with the two tape files, a file named
 Index.Map is also read from the tape. The Write command creates this
 Index.Map file. Notice also that the filenames differ between the tape and
 the directory; see the Write command for additional information.


 REFERENCES

 procedure Write
 Library Management (LM), package Archive



 @node !Commands.Tape.Rewind

 procedure Rewind (Drive : Natural := 0);

 DESCRIPTION

 Rewinds the specified tape unit and leaves it online and loaded at the
 beginning-of-tape marker.

 Unless the tape drive is already allocated to the user's session, a
 tape-mount request is displayed on the operator console following the
 promotion of this command. The operator or system manager is usually
 responsible for responding to this tape-mount request. Refer to the System
 Manager's Guide for more information on how to respond to a tape-mount
 request.


 PARAMETERS

 Drive : Natural := 0;

 Specifies the tape drive whose tape is be rewound. The default is drive 0.



 @node !Commands.Tape.Unload

                                                                           

 procedure Unload (Drive : Natural := 0);

 DESCRIPTION

 Rewinds and unloads the specified tape and takes the tape drive offline.

 Unless the tape drive is already allocated to the user's session, a
 tape-mount request is displayed on the operator console following the
 promotion of this command. The operator or system manager is usually
 responsible for responding to this tape-mount request. Refer to the System
 Manager's Guide for more information on how to respond to a tape-mount
 request.


 PARAMETERS

 Drive : Natural := 0;

 Specifies the tape drive whose tape is to be unloaded. The default is drive
 0.



 @node !Commands.Tape.Write

 procedure Write (Files       : String := "$@";
                  Volume      : String := "";
                  Options     : String := "R1000 Text_Files";
                  To_Operator : String := "Thank You";
                  Response    : String := "<PROFILE>");

 DESCRIPTION

 Copies the specified Environment objects onto a tape as ANSI tape files.

 A tape-mount request is displayed on the operator console following the
 promotion of this command. The operator or system manager is usually
 responsible for responding to this tape-mount request. Refer to the System
 Manager's Guide for more information on how to respond to a tape-mount
 request.

 This command can process any Environment object that can be written by
 package Io. This includes Ada source files, text files, data files, and so
 on. It excludes objects such as activities, switch files, session objects,
 underlying DIANA structures, and so on. A request to write these
 excluded objects does not cause the tape operation to abort, but the
 objects are not written to tape and a message to that effect is placed in
 the log.


 Identifying Environment Objects Written onto Tape

 When Environment objects are written onto tape using the Write command, a
 naming algorithm converts the object names to new tape-file identifiers.
 These tape-file identifiers are generated to be unique and in a valid format
 for the destination system. For example, file identifiers generated for
 VAX/VMS systems are restricted to 9 characters; file identifiers generated
 for all other formats (including the R1000 format) are restricted to 17
 characters. The final tape-file identifier might bear little resemblance to
 the original object name.

 These tape-file identifiers are stored, each followed by its original object
 name, in a new tape file named Index.Map. This file is written as the last
 file on the tape.

 When tape files are read onto another system-for example, when they are
 read onto a VAX or are read onto another R1000 using the Read
 command-these tape-file identifiers, rather than the original object names,
 are used as their new names.

 A user can use the Index.Map file's one-to-one mapping between the original
 object names and their corresponding tape-file identifiers to manually give
 each object its original object name. Alternatively, a user could create a
 short program that uses the Index.Map file to programmatically rename each
 object.


 PARAMETERS

 Files : String := "$@";

 Specifies the objects to write onto tape. All objects that can be written
 by package Io can be written onto tape using the Write command. All
 objects are written as ANSI tape files regardless of their state or type at
 the time the command is promoted. Files contained in a remote directory
 cannot be specified.

 The default, $@, specifies that all objects in the enclosing directory are
 to be written onto tape.


 Volume : String := "";

 Specifies a standard six-character ANSI volume identifier with which to
 label the tape.

 The specified string is either padded on the right with blanks to a length
 of six characters or truncated on the right to shorten it to six
 characters, as appropriate.

 If the resulting string matches the tape's existing volume identifier, the
 identifier is not changed on the tape.

 If the resulting string is blank, then the tape-mount request will include
 a prompt for a new volume identifier.


 Options : String := "R1000 Text_Files";

 Specifies options that can be used when writing tapes, as described below.


 *  Block_Length=positive integer

    Specifies the block length for the tape. Tape blocks are written in the
    range 18 .. 4,096 bytes. (Rational has extended the maximum tape-block
    length to twice the ANSI-standard maximum of 2,048 bytes.)

    The default tape-block length is 2,048 bytes.

    See the Record_Format option for restrictions.


 *  Format=literal

    Specifies the format in which the tape is to be written. The format can
    be specified as, for example, R1000 or as Format = R1000. Valid tape
    formats are:

    R1000                Formats the tape for an R1000 system (this is the
                         default).

    MV                   Formats the tape for an MV system.

    VAX/VMS              Formats the tape for a VAX/VMS system.


 *  Label=string

    Specifies an optional part of the label written to the volume header.
    This allows the user to label the user's own tape, where string is the
    tape label. The default is to write no label.


 *  Record_Format=literal

    Specifies the ANSI record format. The record format can be specified as,
    for example, Fixed_Length or as Record_Format = Fixed_Length. Valid
    record formats are:

    Fixed_Length              Writes tapes with fixed-length records. The
                              length of the records is specified by the
                              Record_Length option. The Record_Length value
                              must be less than or equal to the
                              Block_Length value.

    Variable_Length           Writes tapes with variable-length records
                              (this is the default). The maximum record
                              length is specified by the Record_Length
                              option. The Record_Length value must be less
                              than or equal to the Block_Length value.

    Spanned                   Writes logical records that are larger than
                              the maximum block size. The maximum record
                              size is specified by the Record_Length option.


 *  Record_Length=positive integer

    Specifies the maximum record length for the tape. The default is 512
    bytes. See the Record_Format option for restrictions.


 *  Text_Files

    A Boolean option, its presence specifies that all objects written onto
    tape must contain only characters (as defined by the Ada specification
    for package Text_Io), line terminators, and page terminators. Objects
    written onto tape when this option is True cannot contain control
    characters. Each line of the file is written as a record on the tape.
    The implication is that text files written onto tape when this option is
    specified can then be read from tape without error according to the same
    rules as those used by the Text_Io.Get_Line procedure.

    If this option is not specified, it is assumed False. In this case, each
    object is written onto tape as a continuous string of characters.


 To_Operator : String := "Thank You";

 Specifies a message to be displayed on the operator console following the
 promotion of this command. This provides a way for the user to send
 additional information to the operator or system manager about which
 tape to mount.


 Response : String := "<PROFILE>";

 Specifies how to respond to errors, where to send log messages, and what
 activity to use during the execution of this command. By default, this
 command uses the response characteristics specified in the job response
 profile for the current job. For other values accepted by this parameter,
 see Parameter-Value Conventions in the Reference Summary (RS) book.


 RESTRICTIONS

 This command writes only files that can be manipulated by package Io (or
 only by Text_Io, if the Text_Files option is True). This excludes such
 objects as activities, switch files, session objects, DIANA structures, and
 so on. These other kinds of objects are skipped, and a warning is
 generated in the log file.

 To move other files or objects between R1000s using tape, or to preserve
 the original names and classes of objects when moving them, use the
 Archive.Save and Archive.Restore commands.


 EXAMPLES

 Example 1

 Given the following directory:

   !Users.Thales.The_Directory
         Works         : Ada (Pack_Spec);
         Works         : Ada (Pack_Body);
           .Get_String : Ada (Func_Body);
           .Part_1     : Ada (Proc_Body);

 the following command:

   Tape.Write ("!Users.Thales.The_Directory.@");

 writes onto tape all the objects contained in Thales.The_Directory. All
 dependent Ada units (in this example, everything in package Works) are
 included. Each unit included on the tape is written as a separate file.
 Because all of the default values for the Options parameter are used, the
 tape written is an R1000 tape with variable-length records (each having
 a length of 512 bytes or fewer), no label, and a default block length of
 2,048 bytes.


 Example 2

 Suppose the objects shown in the following directory are written onto tape
 for a VAX/VMS system:

   !Documentation.Tape_Test_Library
     Text_File_Ada            : Coded Ada (Procedure_Spec);
     Vms_Format_Test_File_Txt : File (Text);

 The Index.Map file written onto tape looks like this:

   INDEX.MAP
   !DOCUMENTATION.TAPE_TEST_LIBRARY.INDEX_MAP'V(3)
   VTEXTFILD.ADA
   !DOCUMENTATION.TAPE_TEST_LIBRARY.TEXT_FILE_ADA'SPEC'V(2)
   VMSFRMTTS.TXT
   !DOCUMENTATION.TAPE_TEST_LIBRARY.VMS_FORMAT_TEST_FILE_TXT'V(5)

 The Index.Map file lists the name of each tape file (including the Index.Map
 file followed by the fully qualified pathname of the Environment object from
 which each tape file was derived.


 REFERENCES

 procedure Read
 Library Management (LM), package Archive



 @node !Commands.Terminal

 The R1000 communicates with terminals, workstations, printers, and modems
 through either RS232 asynchronous serial ports or Telnet TCP/IP network
 ports. Both types of ports are represented in the Environment as port
 objects.

 Commands in package Terminal access or modify a subset of settings for
 port objects. Other settings for port objects are located elsewhere in the
 Environment and are managed by other resources; for example, the network
 resources are described in the Rational Networking-TCP/IP Reference
 Manual.


 RESOURCES IN PACKAGE TERMINAL

 The commands in this package fall into the following functional groups:

 Controlling disconnects and login attempts on both Telnet and RS232 ports:

        Set_Detach_On_Disconnect            Set_Disconnect_On_Disconnect
        Set_Disconnect_On_Failed_Login      Set_Disconnect_On_Logoff
        Set_Log_Failed_Logins               Set_Login_Disabled
        Set_Logoff_On_Disconnect

 Changing output drivers on both Telnet and RS232 ports: Set_Terminal_Type

 Displaying port settings on both Telnet and RS232 ports: Current, Settings

 Configuring RS232 ports:

        Set_Character_Size            Set_Flow_Control
        Set_Input_Rate                Set_Output_Rate
        Set_Parity                    Set_Receive_Flow_Control
        Set_Receive_Xon_Xoff_Bytes    Set_Receive_Xon_Xoff_Characters
        Set_Stop_Bits                 Set_Xon_Xoff_Bytes
        Set_Xon_Xoff_Characters

 These resources are described in alphabetical order following the package
 introduction.


 KEY CONCEPTS FOR CONFIGURING PORTS

 Hardware ports are represented in the Environment as port objects. A
 subset of port objects are represented in !Machine.Devices.Terminal_N
 objects (where N is the number of the corresponding hardware port). This
 subset can be accessed and modified either through interactive commands in
 package Terminal or through the file-driven machine-initialization method.

 The following subsections are intended for system managers:

 *  "Identifying R1000 Hardware Ports for Environment Access" describes the
    distribution of hardware ports on the various R1000-series machines.

 *  "Checking the Current Settings for a Port" shows how to display the
    settings of a specified port.

 *  "Configuring System Ports" identifies the file-driven method for
    configuring the hardware ports during the boot process.

 *  "Modifying Disconnect and Login Behavior for a Port" describes this
    behavior and shows how to interactively modify port behavior with
    package Terminal commands.

 *  "Configuring RS232 Ports" describes RS232 settings and shows how to
    interactively modify these settings with package Terminal commands.


 Identifying R1000 Hardware Ports for Environment Access

 The R1000 has two types of hardware ports for terminal access:

 *  Telnet ports

 *  RS232 asynchronous serial ports

 Most package Terminal commands accept the Line parameter. This parameter
 is of type Port, and it identifies the physical port number. The Line
 parameter defaults to the number of the port through which your current
 session is logged in.

 Table 1 summarizes the distribution of both types of ports on the
 various series of R1000s.

              Table 1    Series 100-400 Hardware Port Assignments
         -------------------------------------------------------------------- 
        |     |      |      |      |      |                                  |
        |     |Series|Series|Series|Series|                                  |
        |Ports|      |      |      |      |                Notes             |
        |     |100   |200   |300   | 400  |                                  |
         -------------------------------------------------------------------- 
        |     |      |      |      |      |                                  |
        |1    |RS232 |RS232 |RS232 | RS23 | Used for operator console to     |
        |     |      |      |      |      | provide VT100-compatible, line-  |
        |     |      |      |      |      | oriented Environment interface.  |
        |     |      |      |      |      | Required to start machine.       |
         -------------------------------------------------------------------- 
        |     |      |      |      |      |                                  |
        |2-15 |Reser |Reser |Reser | Reser| Reserved for internal hardware   |
        |     |ved   |ved   |ved   | ved  | use.                             |
         ---- --------------------------------------------------------------- 
        |     |      |      |      |      |                                  |
        |16   |RS232 |RS232 |RS232 | RS23 | Typically used for operator's    |
        |     |      |      |      |      | Environment terminal to provide  |
        |     |      |      |      |      | screen-oriented interface. On the|
        |     |      |      |      |      | Series 300, this port is labeled |
        |     |      |      |      |      | "External Modem." On the 400, it |
        |     |      |      |      |      | is labeled "Comm Port."          |
         ---- --------------------------------------------------------------- 
        |     |      |      |      |      |                                  |
        |17-  |RS232 |RS232 |Unused|Unused| On the Series 100 and 200, the   |
        |47   |      |      |      |      | available range of ports (17-32  |
        |     |      |      |      |      | or 17-47) depends on how many    |
        |     |      |      |      |      | serial-communications panels     |
        |     |      |      |      |      | are installed. Typically, these  |
        |     |      |      |      |      | ports are assigned to login      |
        |     |      |      |      |      | terminals, printers, and other   |
        |     |      |      |      |      | applications such as CDF         |
        |     |      |      |      |      | interfaces.                      |
         ---- --------------------------------------------------------------- 
        |     |      |      |      |      |                                  |
        |48-  |RS232 |Unused|Unused|Unused| Ports 48-79 are available only on|
        |223  |      |      |      |      | the Series 100, and only when    |
        |(48- |      |      |      |      | additional serial-communications |
        |79)  |      |      |      |      | panels are installed. Ports      |
        |     |      |      |      |      | 80-223 are not available.        |
         ---- --------------------------------------------------------------- 
        |     |      |      |      |      |                                  |
        |224- |Telnet|Telnet|Telnet|Telnet| Available as an upgrade on Series|
        |255  |      |      |      |      | 100 and 200 machines; standard on|
        |     |up    |up    |      |      | Series 300 and 400 machines. The |
        |     |grade |grade |      |      | standard machine initialization  |
        |     |      |      |      |      | for the current Environment      |
        |     |      |      |      |      | release configures ports 235-249 |
        |     |      |      |      |      | as login ports.                  |
         ---- --------------------------------------------------------------
              
              
              
 Also see package Queue for more information on the ports used to
 communicate with printers.
              
              
 Checking the Current Settings for a Port

 To see the current settings for any port, execute the command:

   Settings (Line => n);

 where n is the desired port number.

 This command sends the following type of report to Current_Output:

   Terminal Settings for Port 16
   -----------------------------
   Terminal Type                  = RATIONAL
   Input Baud Rate                = BAUD_9600
   Output Baud Rate               = BAUD_9600
   Parity                         = NONE
   Stop_Bits                      = 2
   Char_Size                      = CHAR_8
   Flow Control for Transmit Data = NONE
   Flow Control for Receive Data  = NONE
   Login_Disabled                 = FALSE
   Log_Failed_Logins              = FALSE
   Disconnect_On_Failed_Login     = FALSE
   Disconnect_On_Logoff           = FALSE
   Logoff_On_Disconnect           = FALSE
   Disconnect_On_Disconnect       = FALSE


 Configuring System Ports

 There are two methods for configuring ports on the R1000:

 *  Initialization during system boot

 *  Interactive changes

 Both the package introduction and the command references for package
 Terminal provide useful background information about port settings,
 independent of which method you use.


 Initialization During System Boot

 During system initialization, Telnet and RS232 ports are automatically
 configured by machine-initialization procedures as user login ports or for
 communication with some other device--such as a printer or a modem. The
 !Machine.Initialization.Local.Terminal_Configuration file tells the
 Environment how to enable and configure ports for login.

 Permanent changes to default settings are best implemented through the
 Terminal_Configuration file. You can edit this file at any time to change
 the port settings. The changes take effect the next time you boot the
 R1000, or immediately if you execute the
 !Machine.Initialization.Rational.Terminals command.

 For more information on implementing a Terminal_Configuration file and other
 machine-initialization activities, see the online documentation in the
 !Machine.Initialization world and the System Manager's Guide.


 Interactive Changes

 Package Terminal commands are available to system managers for making
 interactive changes to port configurations. Note that changes to RS232
 hardware configurations made through package Terminal will be deactivated
 when the machine reboots, unless these changes are included in the
 Terminal_Configuration file.

 The following subsections show how to configure ports interactively.


 Modifying Disconnect and Login Behavior for a Port

 You can set the connection behavior and login status of serial and network
 ports interactively through commands in package Terminal and package
 Operator. All of these commands require operator capability.


 Enabling and Disabling Login for a Port

 Users log into the Environment with terminals and workstations by
 connecting to ports enabled for login. If a port is enabled for login,
 however, it cannot be enabled for a print queue or be connected to a CDF
 interface.

 You can make a port available or unavailable for login by using the
 Operator.Enable_Terminal and Operator.Disable_Terminal commands.

 To prevent a port from being enabled by the Operator.Enable_Terminal
 command, execute the command:

   Terminal.Set_Login_Disabled (Line     => n,
                                Disabled => True);

 where n is the number of the port to disable.


 Setting Disconnect Behavior for a Port

 You can set the way the R1000 responds to disconnect signals received from
 remote ports and whether or not the port should disconnect on logoffs or
 failed logins. Unless reset by machine initialization at reboot, these
 settings persist across boots.

 The following list shows how to use commands to set the different types of
 disconnect behavior:

 *  Disconnect on disconnect: Certain brands of communications equipment
    that pool RS232 ports permit ports to be reallocated only after all of
    the following conditions are met:

    1. The terminal user finishes with the port.

    2. A disconnect is sent to the R1000 by switching DCD to off.

    3. The R1000 acknowledges this disconnect by switching its own DTR
       output to off.

    To prevent all RS232 ports from eventually entering the nonallocatable
    state, and therefore making it impossible to log in, set
    Disconnect_On_Disconnect to True when using this kind of communications
    equipment.

    To instruct the R1000 to send a disconnect signal to a port that
    receives a disconnect signal from a remote port, execute the command:

      Set_Disconnect_On_Disconnect (Line    => n,
                                    Enabled => True);

    where n is the desired port number.

 *  Logoff on disconnect: When a user disconnects from a port before
    logging off from an Environment session, that session continues to run
    on the R1000 unless the port is set to log off on disconnect.

    To set logoff on disconnect for a specific port, execute the command:

      Set_Logoff_On_Disconnect (Line    => n,
                                Enabled => True);

    where n is the desired port number.

 *  Disconnect on logoff: When a user logs off from an Environment session,
    the port remains connected unless it is set to disconnect on logoff.
    This setting is especially useful for Telnet ports and is usually
    included in the machine-initialization Terminal_Configuration file.

    To set disconnect on logoff for a specific port, execute the command:

      Set_Disconnect_On_Logoff (Line    => n,
                                Enabled => True);

    where n is the desired port number.

 *  Disconnect on failed login: When a user repeatedly fails to log into an
    Environment session, perhaps by entering incorrect passwords or
    usernames, the connection between the user's terminal and the R1000
    is maintained--unless Disconnect_On_Failed_Login is set to True.

    To set a port to disconnect after repeated failed logins, execute the
    command:

      Set_Disconnect_On_Failed_Login (Line    => n,
                                      Enabled => True);

    where n is the desired port number.

 *  Log failed logins: When a user repeatedly fails to log into an
    Environment session, the attempt can be recorded in the system error
    log.

    To keep a log of failed logins, execute the command:

      Set_Log_Failed_Logins (Line    => n,
                             Enabled => True);

    where n is the desired port number.


 Configuring RS232 Ports

 RS232 hardware settings on the R1000's serial port and the connected
 device's serial port must match. Sometimes these settings are dictated
 exclusively by the terminal device. The following subsections describe
 these settings and how to change them through package Terminal
 commands--note, however, that these settings are normally configured
 through the Terminal_Configuration file.


 Data-Transmission Rate

 The data-transmission rate is the speed at which data is sent from and
 received by a port.

 To set the input or the output data-transmission rate for an RS232 port,
 use one (or both) of the following commands:

   Set_Input_Rate (Line  => n,
                   To_Be => i);

   Set_Output_Rate (Line  => n,
                    To_Be => i);

 where n is the port number and i is a valid input or output rate as listed
 in the reference entry.

 Both input and output rates are usually the same value.


 Number of Data Bits

 Each transmitted character is represented by a specified number of data
 bits. The number of bits in a character depends on the character set that
 the terminal uses. Normally this is seven or eight bits.

 To set the number of data bits per character for a specified RS232 port,
 execute the following command:

   Set_Character_Size (Line  => n,
                       To_Be => i);

 where n is the port number and i is the desired character size (an integer
 5 through 8).


 Number of Stop Bits

 Stop bits are transmitted after each character to serve as a frame for
 establishing data synchronization. The R1000 can receive data with any
 number of stop bits, but some terminal devices require a specific setting
 of one or two stop bits.

 To set the number of stop bits transmitted by a specific RS232 port,
 execute the following command:

   Set_Stop_Bits (Line  => n,
                  To_Be => i);
                                                                           

 where n is the port number and i is the number of desired stop bits (1 or
 2).


 Parity Checking

 You can specify no parity, odd parity, or even parity for characters
 received and transmitted by an RS232 port. If an odd or even parity is
 selected, then each transmitted character contains a parity bit that
 maintains either an odd or even number of 1 bits in the character. For
 example, if the character represented by 0100101 is to be transmitted
 using even parity, a 1 is added in the eighth bit to make 10100101, which
 contains an even number of 1 bits. If odd parity were used, the eighth bit
 would be 0 to make 00100101, which contains an odd number of 1 bits.

 Parity is used to detect errors affecting an odd number of bits. (This is
 true regardless of whether even or odd parity is specified). If an even
 number of bits is affected, the error will not be detected. For example,
 if 01001011 is transmitted (even parity) but 01111011 is received, the
 error will not be detected, because the character still contains an even
 number of 1 bits. In modern serial communications, parity checking is
 commonly omitted.

 To set the parity for a specified RS232 port, execute the following
 command:

   Set_Parity (Line  => n,
               To_Be => parity);

 where n is the port number and parity is the desired parity setting (None,
 Odd, or Even).


 Flow Control

 Flow control is the regulation of data flow. Some terminal devices require
 flow control to prevent transmission overruns. There are two general types
 of flow control:

 *  Hardware flow control: Hardware flow control consists of signals that
    are monitored by firmware in port-controller circuit boards. The ports
    on the R1000 can be configured to use RTS, CTS, and DTR signals for flow
    control.

    To enable hardware flow control (CTS) for transmitted data, you need to
    make a physical switch setting on the port controller.

    To enable hardware flow control for received data, execute the
    Set_Receive_Flow_Control command as described in the reference entry.

 *  Software flow control: Software flow control is executed by software
    running on the R1000 or the workstation. If software flow control is
    selected, then the flow of data is stopped when the device sends the
    XOFF byte or character. The flow is resumed when the XON byte or
    character is sent.

    To enable software flow control for data transmitted from an R1000
    port, execute the Set_Flow_Control command.

    To enable software flow control for data received by an R1000 port,
    execute the Set_Receive_Flow_Control command. See the reference entry
    for descriptions of the required parameters for these two commands.


 @node !Commands.Terminal.Character_Bits_Range

 subtype Character_Bits_Range is
         System_Utilities.Character_Bits_Range;

 DESCRIPTION

 Specifies the number of data bits per character.

 This command defines a subtype that is a set of integers in the range 5
 through 8.


 REFERENCES

 type System_Utilities.Character_Bits_Range



 @node !Commands.Terminal.Current

 function Current
          (S : Machine.Session_Id := Default.Session) return Port
                                renames System_Utilities.Terminal;

 DESCRIPTION

 Returns the port number through which the specified session is logged in.

 This function renames function Terminal in package System_Utilities.


 PARAMETERS

 S : Machine.Session_Id := Default.Session;

 Specifies the session. The S parameter defaults to the current session (the
 session in which the function is executed).


 return Port;

 Returns the number of the port through which a specified session is
 connected. The default is the port number of the current session.


 REFERENCES

 function System_Utilities.Terminal



 @node !Commands.Terminal.Parity_Kind

 subtype Parity_Kind is System_Utilities.Parity_Kind;

 DESCRIPTION

 Specifies the type of parity bit that is received with each character:
 none, even, or odd.


 REFERENCES

 type System_Utilities.Parity_Kind



 @node !Commands.Terminal.Port

 subtype Port is Natural range 0 .. 4 * 16 * 16;

 DESCRIPTION

 Specifies the range of port numbers.



 @node !Commands.Terminal.Set_Character_Size

 procedure Set_Character_Size
               (Line  : Port                 := Terminal.Current;
                To_Be : Character_Bits_Range :=
                                System_Utilities.Character_Size);

 DESCRIPTION

 Sets the number of data bits per character.

 This setting affects both transmitted and received data.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 To_Be : Character_Bits_Range := System_Utilities.Character_Size;

 Specifies the new character size. The default eight bits.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.

 This procedure is valid only for RS232 communications.


 EXAMPLES

 The command:

   Terminal.Set_Character_Size (Line  => 16,
                                To_Be => 8);

 sets the character size for port 16 to eight bits. (This is the proper
 setting when configuring the R1000 for use with the M68020/Bare CDF.)


 REFERENCES

 procedure Set_Parity
 procedure Set_Stop_Bits
 function System_Utilities.Character_Size



 @node !Commands.Terminal.Set_Detach_On_Disconnect

 procedure Set_Detach_On_Disconnect
           (Line    : Port    := Terminal.Current;
            Enabled : Boolean :=
                         System_Utilities.Detach_On_Disconnect);

 DESCRIPTION

 This procedure is not currently supported by the Environment.



 @node !Commands.Terminal.Set_Disconnect_On_Disconnect

 procedure Set_Disconnect_On_Disconnect
           (Line    : Port    := Terminal.Current;
            Enabled : Boolean :=
                      System_Utilities.Disconnect_On_Disconnect);

 DESCRIPTION

 Enables or disables the Disconnect_On_Disconnect option for a particular
 port.

 This option is disabled automatically by the Environment on new systems,
 when a disk-incompatible release of the Environment is installed, or
 whenever the Environment state stored on disk is lost.

 If this option is enabled for an RS232 port, the R1000 responds to an
 incoming disconnect signal received on the port by initiating an outgoing
 disconnect signal on that port.

 For an RS232 port, an incoming disconnect signal occurs when the R1000
 senses the data carrier detect (DCD) turn from on to off. An outgoing
 disconnect signal occurs when the R1000 toggles data terminal ready (DTR)
 from on to off for 3 seconds and then back to on again.

 This command takes effect immediately.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 Enabled : Boolean := System_Utilities.Disconnect_On_Disconnect;

 Specifies the setting of the Disconnect_On_Disconnect option. The default
 is the current setting.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job
 have operator capability.

 This command applies only to RS232 ports.


 REFERENCES

 function System_Utilities.Disconnect_On_Disconnect



 @node !Commands.Terminal.Set_Disconnect_On_Failed_Login

 procedure Set_Disconnect_On_Failed_Login
           (Line    : Port    := Terminal.Current;
            Enabled : Boolean :=
                      System_Utilities.Disconnect_On_Failed_Login);

 DESCRIPTION

 Enables or disables the Disconnect_On_Failed_Login option for a particular
 port.

 This option is disabled on a new system, when a disk-incompatible release
 of the Environment is installed, or whenever the Environment state stored
 on disk is lost.

 If this option is enabled for a port, the R1000 initiates an outgoing
 disconnect signal on the port when a user repeatedly fails to log in on
 that port--for example, by entering an incorrect password or unrecognized
 username.

 For an RS232 port, an outgoing disconnect signal occurs when the R1000
 toggles data terminal ready (DTR) from on to off for 3 seconds and then
 back to on again.

 This command takes effect immediately.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 Enabled : Boolean := System_Utilities.Disconnect_On_Failed_Login;

 Specifies the setting of the Disconnect_On_Failed_Login option. The default
 is the current setting.


 RESTRICTIONS

 Execution of this procedure requires that the executing job have operator
 capability.


 REFERENCES

 function System_Utilities.Disconnect_On_Failed_Login



 @node !Commands.Terminal.Set_Disconnect_On_Logoff

 procedure Set_Disconnect_On_Logoff
      (Line    : Port    := Terminal.Current;
       Enabled : Boolean := System_Utilities.Disconnect_On_Logoff);

 DESCRIPTION

 Enables or disables the Disconnect_On_Logoff option for a particular port.

 This option is disabled on a new system, when a disk-incompatible release
 of the Environment is installed, or whenever the Environment state stored
 on disk is lost.

 If this option is enabled for a port, the R1000 initiates an outgoing
 disconnect on the port whenever a user logs off a session running on the
 port. This procedure is especially useful for Telnet ports and is usually
 included in a machine-intitialization procedure so that a user is
 automatically disconnected from a Telnet port when logging off.

 For an RS232 port, an outgoing disconnect signal occurs when the R1000
 toggles data terminal ready (DTR) from on to off for 3 seconds and then
 back to on again.

 This command takes effect immediately.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 Enabled : Boolean := System_Utilities.Disconnect_On_Logoff;

 Specifies the new setting of this option. The default is the current
 setting.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job
 have operator capability.


 REFERENCES

 function System_Utilities.Disconnect_On_Logoff



 @node !Commands.Terminal.Set_Flow_Control

 procedure Set_Flow_Control
           (Line  : Port   := Terminal.Current;
            To_Be : String := System_Utilities.Flow_Control);

 DESCRIPTION

 Enables software flow control for data transmitted by the R1000 on the
 specified line (see Set_Receive_Flow_Control for regulating received data).

 A device such as a terminal or a printer attached to an R1000 port can
 control the flow of data transmitted to it from the R1000 in two ways:

 *  Hardware flow control: The flow of data is stopped when the device
    turns off the Clear To Send (CTS) modem control signal. The flow is
    restarted when the CTS signal is turned on.

 *  Software flow control: The flow of data is stopped when the device
    sends the XOFF byte or character. The flow is restarted when the XON
    byte or character is sent.

 This procedure enables or disables only software flow control. Hardware
 flow control is enabled or disabled by a hardware configuration switch in
 the R1000 port controller. There is no software interface to enable or
 disable hardware flow control.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 To_Be : String := System_Utilities.Flow_Control;

 Specifies whether to set software flow control to "None" or "Xon_Xoff". The
 default is "None".


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job
 have operator capability.

 This procedure is valid only for RS232 communications.


 EXAMPLES

 The command:

   Terminal.Set_Flow_Control (Line  => 16,
                              To_Be => "None");

 disables software flow control. This is the proper setting when configuring
 the R1000 for use with the M68020/Bare CDF.

 The command:

   Terminal.Set_Flow_Control (Line  => 16,
                              To_Be => "Xon_Xoff");

 enables software flow control.


 REFERENCES

 procedure Set_Xon_Xoff_Bytes
 function System_Utilities.Flow_Control



 @node !Commands.Terminal.Set_Input_Rate

 procedure Set_Input_Rate
           (Line  : Port   := Terminal.Current;
            To_Be : String := System_Utilities.Input_Rate);

 DESCRIPTION

 Sets the data rate for data received by the R1000 on the specified line.

 Valid incoming data rates include:

   DISABLE       BAUD_50       BAUD_75       BAUD_110
   BAUD_134_5    BAUD_150      BAUD_200      BAUD_300
   BAUD_600      BAUD_1200     BAUD_1800     BAUD_2400
   BAUD_4800     BAUD_9600     BAUD_19200    EXT_REC_CLK

 EXT_REC_CLK is the only allowed value for Telnet ports. In general, this
 value indicates that the input rate of the data is determined by an
 external clock (and is not under local control). For a Telnet port, this
 means that the data-transmission rate is not configurable. In this case it
 is "set" by either the transmission rate of the Telnet port (10 Mbits per
 second) or the transmission rate at the remote end of the transmission
 (whichever of these two values is less).


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 To_Be : String := System_Utilities.Input_Rate;

 Specifies the new input rate, which must be one of those specified above.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job
 have operator capability.

 This procedure is valid only for RS232 communications.


 EXAMPLES

 The command:

   Terminal.Set_Input_Rate (Line  => 16,
                            To_Be => "Baud_9600");

 sets the rate of data sent to the R1000 using port 16 to 9,600 bits per
 second. This is the proper setting when configuring the R1000 for use with
 the M68020/Bare CDF.


 REFERENCES

 procedure Set_Output_Rate
 function System_Utilities.Input_Rate
       

 @node !Commands.Terminal.Set_Log_Failed_Logins

 procedure Set_Log_Failed_Logins
         (Line    : Port    := Terminal.Current;
          Enabled : Boolean := System_Utilities.Log_Failed_Logins);

 DESCRIPTION

 Enables or disables the Log_Failed_Logins option for a particular port.

 If this option is enabled for a port, the R1000 writes an entry to the
 system error log when a user repeatedly fails to log in on that port. This
 procedure is useful for security purposes-for instance, when trying to
 determine if someone has tried unsuccessfully to log in by guessing a
 password.

 By default, this option is disabled.


 PARAMETERS

 Line : Port := Terminal.Current;

  Specifies the line to be affected. The default is the current line.



 Specifies the new setting of this option. The default is the current
 setting.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job
 have operator capability.


 REFERENCES

 function System_Utilities.Log_Failed_Logins



 @node !Commands.Terminal.Set_Login_Disabled

 procedure Set_Login_Disabled
           (Line     : Port    := Terminal.Current;
            Disabled : Boolean := System_Utilities.Login_Disabled);

 DESCRIPTION

 Enables or disables the Login_Disabled option for the specified port.

 By default, this option is disabled--that is, the port can be enabled for 
 login.

 If this option is enabled for a port, the port cannot be enabled for login, 
 even if the Operator.Enable_Terminal procedure is used.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 Disabled : Boolean := System_Utilities.Login_Disabled;

 Specifies the new setting of this option. The default is the current setting.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.


 REFERENCES

 procedure Operator.Disable_Terminal
 procedure Operator.Enable_Terminal
 function System_Utilities.Enabled
 function System_Utilities.Login_Disabled



 @node !Commands.Terminal.Set_Logoff_On_Disconnect

 procedure Set_Logoff_On_Disconnect
      (Line    : Port    := Terminal.Current;
       Enabled : Boolean := System_Utilities.Logoff_On_Disconnect);

 DESCRIPTION

 Enables or disables the Logoff_On_Disconnect option for a specified port.

 This option is disabled on new systems, when a disk-incompatible release of the
 Environment is installed, or whenever the Environment state stored on disk is
 lost.

 If this option is enabled for a port, and the R1000 detects a disconnection of
 that port, it logs off the associated session. The user is not required to log
 out of a session before disconnecting from the port. Uncommitted buffers are
 saved before the user's session is terminated. If an Environment program is
 reading from the port when a disconnect occurs, a disconnect status code is sent
 to the program.

 The R1000 detects an RS232 port disconnect by a drop in the data carrier detect
 (DCD) signal; a Telnet port disconnect is detected by the termination of the
 Telnet session.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 Enabled : Boolean := System_Utilities.Logoff_On_Disconnect;

 Specifies the new setting of this option. The default is the current setting.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.


 REFERENCES

 function System_Utilities.Logoff_On_Disconnect



 @node !Commands.Terminal.Set_Output_Rate

 procedure Set_Output_Rate
           (Line  : Port   := Terminal.Current;
            To_Be : String := System_Utilities.Output_Rate);

 DESCRIPTION

 Sets the data rate for data transmitted by the R1000 on the specified line.

 Valid output data rates include:

   DISABLE       BAUD_50       BAUD_75       BAUD_110
   BAUD_134_5    BAUD_150      BAUD_200      BAUD_300
   BAUD_600      BAUD_1200     BAUD_1800     BAUD_2400
   BAUD_4800     BAUD_9600     BAUD_19200    EXT_REC_CLK

 EXT_REC_CLK is the only allowed value for Telnet ports. In general, this value
 indicates that the output rate of the data is determined by an external clock
 (and is not under local control). For a Telnet port, this means that the
 data-transmission rate is not configurable. In this case it is "set" by either the
 transmission rate of the Telnet port (10 Mbits per second) or the transmission
 rate at the remote end of the transmission (whichever of these two values is
 less).


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 To_Be : String := System_Utilities.Output_Rate;

 Specifies the new output rate, which must be one of those specified above.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.

 This procedure is valid only for RS232 communications.


 REFERENCES

 procedure Set_Input_Rate
 function System_Utilities.Output_Rate



 @node !Commands.Terminal.Set_Parity

 procedure Set_Parity
           (Line  : Port        := Terminal.Current;
            To_Be : Parity_Kind := System_Utilities.Parity);

 DESCRIPTION

 Sets the parity for the specified port to None, Even, or Odd.

 This setting affects both transmitted and received data.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 To_Be : Parity_Kind := System_Utilities.Parity;

 Specifies the parity setting: None, Even, or Odd. None is the default.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.

 This procedure is valid only for RS232 communications.


 EXAMPLES

 The command:

   Terminal.Set_Parity (Line => 16, To_Be => System_Utilities.None);

 specifies that you do not want parity checking enabled for port 16. This is the
 proper setting when configuring the R1000 for use with the M68020/Bare CDF.


 REFERENCES

 procedure Set_Character_Size
 procedure Set_Stop_Bits
 function System_Utilities.Parity



 @node !Commands.Terminal.Set_Receive_Flow_Control

 procedure Set_Receive_Flow_Control
         (Line  : Port   := Terminal.Current;
          To_Be : String := System_Utilities.Receive_Flow_Control);

 DESCRIPTION

 Enables or disables flow control of data received by the R1000 (see Set_Flow_Con-
 trol for transmitted data).

 Certain devices use flow control to prevent data overruns. Some devices support
 hardware flow control (CTS receiving, RTS or DTR transmitting) and some devices
 support software flow control (through XON and XOFF transmissions).


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 To_Be : String := System_Utilities.Receive_Flow_Control;

 Specifies that flow control for the specified port should be set to None, XON-
 _XOFF, RTS, or DTR. The default is None.

 Four types of receive flow control are available:

 *  None: Indicates that there is no software or hardware flow control for the
    line.

 *  XON_XOFF: Indicates that software flow control is enabled for the line. This
    value indicates that the device should stop transmitting when it receives an
    XOFF from the Rational system and can resume transmission when it receives an
    XON.

 *  RTS: Indicates that hardware flow control based on the RTS modem control
    signal is enabled for the line. This value indicates that the device should
    stop transmitting when the Rational system switches the RTS modem control
    signal to off and can resume transmission when the signal is switched to on.

 *  DTR: Indicates that hardware flow control based on the DTR modem control
    signal is enabled for the line. This value indicates that the device should
    stop transmitting when the Rational system switches the DTR modem control
    signal to off and can resume transmission when the signal is switched to on.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.

 This procedure is valid only for RS232 communications.


 EXAMPLES

 The command:

   Terminal.Set_Receive_Flow_Control (Line => 16, To_Be => "None");

 disables software flow control. This is the proper setting when configuring the
 R1000 for use with the M68020/Bare CDF.


 REFERENCES

 procedure Set_Flow_Control
 procedure Set_Receive_Xon_Xoff_Bytes
 procedure Set_Receive_Xon_Xoff_Characters
 function System_Utilities.Receive_Flow_Control



 @node !Commands.Terminal.Set_Receive_Xon_Xoff_Bytes

 procedure Set_Receive_Xon_Xoff_Bytes
           (Line     : Port               := Terminal.Current;
            Xon_Xoff : System.Byte_String :=
                         System_Utilities.Receive_ Xon_Xoff_Bytes);

 DESCRIPTION

 Sets the byte codes that represent the XON and XOFF flow-control bytes used by
 software flow control to regulate data received on the specified port.

 Using bytes instead of characters for flow control allows the complete seven-bit
 character set (ASCII) to be reserved for other uses.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 Xon_Xoff : System.Byte_String := System_Utilities.Receive_Xon_Xoff_Bytes;

 Specifies the new flow-control bytes. This parameter takes a string consisting of
 the byte representing XON, followed by the byte representing XOFF.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.

 This procedure is valid only for RS232 communications.


 REFERENCES

 procedure Set_Receive_Flow_Control
 function System_Utilities.Receive_Xon_Xoff_Bytes



 @node !Commands.Terminal.Set_Receive_Xon_Xoff_Characters

 procedure Set_Receive_Xon_Xoff_Characters
                  (Line     : Port   := Terminal.Current;
                   Xon_Xoff : String :=
                   System_Utilities.Receive_Xon_Xoff_Characters);

 DESCRIPTION

 Sets the character codes that represent the XON and XOFF flow-control characters
 used by software flow control to regulate data received on the specified port.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 Xon_Xoff : String := System_Utilities.Receive_Xon_Xoff_Characters;

 Specifies the new flow-control characters. This parameter takes a string
 consisting of the character representing XON, followed by the character
 representing XOFF. The default character for XON is ASCII DC1; the default
 character for XOFF is ASCII DC3.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.

 This procedure is valid only for RS232 communications.


 REFERENCES

 procedure Set_Receive_Flow_Control
 function System_Utilities.Receive_Xon_Xoff_Characters



 @node !Commands.Terminal.Set_Stop_Bits

 procedure Set_Stop_Bits
           (Line  : Port            := Terminal.Current;
            To_Be : Stop_Bits_Range := System_Utilities.Stop_Bits);

 DESCRIPTION

 Sets the number of stop bits for the specified port.

 The integer range for Stop_Bits_Range is 1 through 2.

 The stop-bit setting affects transmitted data only. The R1000 can always receive
 data with any number of stop bits.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 To_Be : Stop_Bits_Range := System_Utilities.Stop_Bits;

 Specifies the number of stop bits to be transmitted, either 1 or 2. The default is
 1.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.

 This procedure is valid only for RS232 communications.


 EXAMPLES

 The command:

   Terminal.Set_Stop_Bits (Line => 16, To_Be => 2);

 configures the R1000 to transmit two stop bits. This is the proper setting when
 configuring the R1000 for use with the M68020/Bare CDF.


 REFERENCES

 procedure Set_Character_Size
 procedure Set_Parity
 function System_Utilities.Stop_Bits



 @node !Commands.Terminal.Set_Terminal_Type

 procedure Set_Terminal_Type
           (Line  : Port   := Terminal.Current;
            To_Be : String := System_Utilities.Terminal_Type);

 DESCRIPTION

 Sets the output driver types for the current port or for the port of a remote
 terminal device.

 This information is used by terminal-handling software (for example, the 
 Environment's editor) in generating terminal output data.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 To_Be : String := System_Utilities.Terminal_Type;

 Specifies the new output driver type. This parameter is case-insensitive.

 The output driver types supported by the Environment are:

 *  XRTERM

 *  Rational

 *  VT100

 *  Facit


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.


 REFERENCES

 function System_Utilities.Terminal_Type



 @node !Commands.Terminal.Set_Xon_Xoff_Bytes

 procedure Set_Xon_Xoff_Bytes
           (Line     : Port               := Terminal.Current;
            Xon_Xoff : System.Byte_String :=
                             System_Utilities.Xon_Xoff_Bytes);

 DESCRIPTION

 Sets the byte codes that represent the XON and XOFF flow-control bytes used by
 software flow control to regulate data transmitted from the specified port.

 Using bytes instead of characters for flow control allows the complete seven-bit
 character set (ASCII) to be reserved for other uses.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 Xon_Xoff : System.Byte_String := System_Utilities.Xon_Xoff_Bytes;

 Specifies the new flow-control bytes. This parameter takes a string consisting of
 the byte representing XON, followed by the byte representing XOFF.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.

 This procedure is valid only for RS232 communications.


 REFERENCES

 procedure Set_Receive_Xon_Xoff_Bytes
 procedure Set_Xon_Xoff_Characters
 function System_Utilities.Xon_Xoff_Bytes



 @node !Commands.Terminal.Set_Xon_Xoff_Characters

 procedure Set_Xon_Xoff_Characters
       (Line     : Port   := Terminal.Current;
        Xon_Xoff : String := System_Utilities.Xon_Xoff_Characters);

 DESCRIPTION

 Sets the character codes that represent the XON and XOFF flow-control characters
 used by software flow control to regulate data transmitted from the specified
 port.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the line to be affected. The default is the current line.


 Xon_Xoff : String := System.Utilities.Xon_Xoff_Characters;

 Specifies the new flow-control characters. This parameter takes a string
 consisting of the character representing XON, followed by the character
 representing XOFF. The default character for XON is ASCII DC1; the default
 character for XOFF is ASCII DC3.


 RESTRICTIONS

 Execution of this procedure requires that the user or the executing job have
 operator capability.

 This procedure is valid only for RS232 communications.


 REFERENCES

 procedure Set_Receive_Xon_Xoff_Characters
 procedure Set_Xon_Xoff_Bytes
 function System_Utilities.Xon_Xoff_Characters



 @node !Commands.Terminal.Settings

 procedure Settings (Line : Port := Terminal.Current);

 DESCRIPTION

 Displays a summary of the current settings for the specified port.

 By default, this procedure returns the settings for the current port.


 PARAMETERS

 Line : Port := Terminal.Current;

 Specifies the port number.


 EXAMPLES

 The command:

   Terminal.Settings (16);

 displays information such as the following:

   Terminal Settings for Port 16
   -----------------------------
   Terminal Type                  = RATIONAL
   Input Baud Rate                = BAUD_9600
   Output Baud Rate               = BAUD_9600
   Parity                         = NONE
   Stop_Bits                      = 2
   Char_Size                      = CHAR_8
   Flow Control for Transmit Data = NONE
   Flow Control for Receive Data  = NONE
   Login_Disabled                 = FALSE
   Log_Failed_Logins              = FALSE
   Disconnect_On_Failed_Login     = FALSE
   Disconnect_On_Logoff           = FALSE
   Logoff_On_Disconnect           = FALSE
   Disconnect_On_Disconnect       = FALSE

 Note that if the value of Flow Control for Transmit Data were XON_XOFF instead of
 NONE, then two more entries would appear, one for XON and one for XOFF, as shown
 in the next example.

 The command:

   Terminal.Settings (1);

 displays information such as the following:

   Terminal Settings for Port 1
   ----------------------------
   Terminal Type                  = RATIONAL
   Input Baud Rate                = BAUD_9600
   Output Baud Rate               = BAUD_9600
   Parity                         = NONE
   Stop_Bits                      = 2
   Char_Size                      = CHAR_8
   Flow Control for Transmit Data = XON_XOFF
   Xon                            = DC1
   Xoff                           = DC3
   Flow Control for Receive Data  = NONE
   Login_Disabled                 = FALSE
   Log_Failed_Logins              = FALSE
   Disconnect_On_Failed_Login     = FALSE
   Disconnect_On_Logoff           = FALSE
   Logoff_On_Disconnect           = FALSE
   Disconnect_On_Disconnect       = FALSE

 Notice that the settings displayed for port 1 (the operator-console port) have
 two additional fields, one for XON and one for XOFF.


 REFERENCES

 renamed function Current



 @node !Commands.Terminal.Stop_Bits_Range

 subtype Stop_Bits_Range is System_Utilities.Stop_Bits_Range;

 DESCRIPTION

 Specifies the range of stop bits available for a port.

 The integer range is 1 through 2.


 REFERENCES

 subtype System_Utilities.Stop_Bits_Range