|
DataMuseum.dkPresents historical artifacts from the history of: Rational R1000/400 Tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about Rational R1000/400 Tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: S T
Length: 520671 (0x7f1df)
Types: TextFile
Names: »SMU_HELP«
└─⟦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⟧
@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