|
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: 483569 (0x760f1)
Types: TextFile
Names: »SJM_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.Job
Package Job provides commands for controlling jobs associated with user
sessions. The commands in this package can be used to manage job priority
(foreground or background) and job connections to sessions (attached or
detached). Thus, commands in this package change the class and kind of
user-initiated jobs.
As with most commands in the world !Commands, commands from package Job
are intended for interactive use, although they can be used
programmatically within Ada procedures. For more information about jobs,
see also:
* The Key Concepts of this book for information about changing the
behavior of a job, such as how it responds to errors
* Package Program for operations for programmatic job control, such as
spawning new jobs from existing jobs
* Package Remote for operations for executing jobs across R1000s on the
same network
* The System Management Utilities (SMU) book, package Scheduler, for
information about managing the way the Environment allocates resources
to jobs
RESOURCES IN PACKAGE JOB
The commands in package Job fall into several functional groups. Types and
constants are not included in this list.
Putting a job in the background: Disconnect, Interrupt
Bringing a job into the foreground: Connect
Temporarily stopping a job: Disable
Restarting a stopped job: Enable
Terminating a job: Kill
Displaying a message at the end of a job: Set_Termination_Message
KEY CONCEPTS FOR PACKAGE JOB
A job consists of one or more commands that are executed together. For
example, executing multiple commands in a command window constitutes a
single job.
A job is initiated when commands are executed through a key combination or
a command window. Jobs also can be initiated programmatically from other
jobs using commands in package Program (see package Program in this book).
When a job is created, the Environment assigns it a job identification
number (job number). The Environment assigns job numbers uniquely for each
session. The range is 0 through 255.
For further information about job characteristics and job behavior, see
the Key Concepts of this book. The remainder of this package introduction
contains information about using commands in this package to control job
priority and to control the connection between jobs and sessions.
USING COMMANDS IN PACKAGE JOB
Using commands in package Job, you can interactively manage the priority
(percent of processor time) assigned to user-initiated jobs. You can
also manipulate the job connection to your session.
You can use commands in package Job to manage jobs that were started under
any of the sessions associated with your username. However, to manipulate
a job that belongs to another user, you must have operator capability. See
the System Management Utilities (SMU) book, package Operator, for
information about operator capability.
The following subsections contain information about:
* Placing a job in the background
* Temporarily stopping a job
* Terminating a job
* Obtaining information about jobs
Placing a Job in the Background
Normally, user-initiated jobs are run in the foreground as attached jobs
(or connected jobs). Because foreground jobs are typically highly
interactive and require fast response, they are allocated the majority of
system resources. An attached job maintains control of your session,
preventing you from entering other commands until the job finishes.
However, you can cause user-initiated jobs to execute in the background,
making them detached jobs (or disconnected jobs). Background jobs are
allocated the remaining resources after foreground jobs are handled.
Detaching a job and placing it in the background allows you to enter other
commands while the job continues executing.
Four commands control whether user-initiated jobs execute as background
jobs or foreground jobs:
* Interrupt
* Disconnect
* !Commands.Command.Spawn
* Connect
The Interrupt procedure is generally bound to a key combination
([Control][G] under the standard key bindings). This procedure enables
you to detach from the current job while the job is running.
The Disconnect procedure performs the same operation as the Interrupt
procedure, except that it should be used programmatically within Ada
procedures. For example, calling the Disconnect procedure as the first
statement in a program causes that program to always run in the
background. You can also use the Disconnect procedure to specify that a
program begin in the foreground and then run in the background after
certain operations have been performed.
The !Commands.Command.Spawn procedure allows you to execute the contents
of a command window in the background from the start. Thus, it essentially
performs the same operation as promoting the job in the command window
with !Commands.Common.Promote and then using the Interrupt procedure.
The Connect procedure can be used to reconnect to a disconnected job.
Reconnecting to a job makes the session unavailable for other operations
and causes the job to run in the foreground.
Temporarily Stopping a Job
Package Job provides two commands for temporarily stopping and restarting
userinitiated jobs:
* Disable
* Enable
The Disable procedure can be used to temporarily stop a job from
executing. A disabled job is not terminated, but it is prevented from
executing by the Environment. A disabled job has been rendered
ineligible for processor time.
The Enable procedure can be used to restart a disabled job. Enabling a job
allows the job to resume executing at the discretion of the scheduler.
Terminating a Job
To permanently stop a job from executing, use the Kill procedure. The Kill
procedure causes the job to be terminated.
When you kill a job, all files declared as Current_Output, Current_Input,
or Current_Error, or files on the current-output, current-input, or
current-error stacks, are closed (see package Log for more information
about these stacks). All other files are abandoned, and temporary files are
deleted.
Obtaining Information about Jobs
To obtain information about the jobs currently active on the system, you
can use the What.Users or What.Jobs procedure.
The What.Users procedure generates a static list of active jobs and
information about those jobs, including:
* User and session under which the job was started
* Job number
* Job state (Run, Idle, Wait, Disabled, or Queued)
* Elapsed time since the job began
* Name of the job
By default, this list is sent to an Environment output window.
The What.Jobs procedure generates a dynamic listing of jobs active on the
system. The window produced by this procedure is continually monitored by
the system and updated periodically (as determined by the Interval
parameter). In addition to the information displayed by the What.Users
procedure, for each active job the What.Jobs procedure lists:
* Total amount of CPU time the job has used since it began executing
* Percentage of CPU time over the last interval (as determined by the
Interval parameter) that was consumed by the job
* Number of pages of memory the job is currently using
* Number of times the job has had to wait for the disk since it began
Note that you can control your jobs directly through the What.Jobs
display, using commands from package !Commands.Common (generally bound to
keys). In particular, you can disable, enable, or kill jobs that belong to
your username. You can also connect to a previously disconnected job. Note
that the What.Jobs display is updated at specified intervals until it is
released or abandoned. See package What for more information about the
What.Jobs display.
To obtain even more information about active jobs, you can use the
!Commands.System_Maintenance'Spec_View.Units.Show_Jobs or the
!Commands.System_Maintenance'Spec_View.Units.Show_Job_Names procedure.
@node !Commands.Job.Connect
procedure Connect (The_Job : Id := 0);
DESCRIPTION
Connects the current session to the specified job.
This procedure connects (attaches) the current session to a previously
disconnected (detached) job. Connecting the session to a job causes the
job to run in the foreground. As a result, connecting the session to a
job effectively suspends input from the keyboard until the job
completes. However, connected jobs can read keyboard input with
facilities in package Window_Io (see the Data and Device Input/Output
(DIO) book). Connected jobs also can bring windows onto the screen.
To interactively disconnect a session from a job, use the Interrupt
procedure. To programmatically set a job to disconnect from the session at
a specific point, use the Disconnect procedure.
PARAMETERS
The_Job : Id := 0;
Specifies the number of the job to be connected. The job must be associated
with the current session. The default, 0, connects you to the most
recently interrupted job for the current session.
EXAMPLES
Assume that a user called MAT has two jobs associated with his session
S_1, as shown in the following What.Users display:
User Status on June 30, 1991 at 04:22:52 PM
User Line Job S Time Job Name
======== ==== ==== ==== ========= ==========================
MAT 21 RUN 53:04.96 session'(S_1)
232 IDLE 00:02.45 !USERS.MAT % COMPILATION.MAKE
218 IDLE 02:37:01 !USERS.MAT % WHAT.LOCKS
The following command reconnects the terminal on which MAT is working to
job 232 in the current session:
Job.Connect (The_Job => 232);
REFERENCES
procedure Disconnect
procedure Interrupt
@node !Commands.Job.Disable
procedure Disable (The_Job : Id;
The_Session : String := "");
DESCRIPTION
Temporarily stops execution of the specified job.
This procedure temporarily stops the specified job. The job is not
terminated but is prevented from executing by the Environment. The job
identifier 0 can be used to disable all jobs for the specified session. To
disable jobs associated with sessions other than your current session, you
must supply the pathname of the session associated with the job (for
example, !Users.Mat.S_2).
To restart a disabled job, use the Enable procedure.
To terminate a job, use the Kill procedure.
PARAMETERS
The_Job : Id;
Specifies the job number for the job to be disabled. A value of 0 stops all
jobs for the specified session, provided that session belongs to the
current user; the value 0 cannot be used to stop all jobs for a session
that belongs to another user.
The_Session : String := "";
Specifies the session with which the job is associated. Special names,
wildcards, and context characters can be used if they resolve to a single
object. The name supplied to this parameter is resolved with respect to
the current library. The name must resolve to a session object--for
example, !Users.Robinson.S_1. The default value, the null string, specifies
the current session.
RESTRICTIONS
To disable jobs that belong to another user, you must have read access to
that user's home world or be operating in privileged mode (belong to the
access-control group Privileged and have enabled privileges).
ERRORS
The name specified in the Session parameter is resolved with respect to the
current library. If a simple name is provided and you are not in the
library that contains the session object, an error such as the following
is produced:
"s_1" is not an accessible session
EXAMPLES
Assume that a user named MAT has two jobs associated with his current
session, S_1, as shown in the following What.Users display:
User Status on June 30, 1991 at 04:22:52 PM
User Line Job S Time Job Name
======== ==== === ==== ========= ==========================
MAT 21 RUN 53:04.96 session'(S_1)
232 IDLE 00:02.45 !USERS.MAT % COMPILATION.MAKE
218 IDLE 02:37:01 !USERS.MAT % WHAT.LOCKS
The following command temporarily stops job 232 in the current session:
Job.Disable (The_Job => 232, The_Session => "");
REFERENCES
procedure Enable
procedure Kill
@node !Commands.Job.Disconnect
procedure Disconnect (The_Job : Id := 0);
DESCRIPTION
Disconnects the current session from the specified job.
This procedure disconnects (detaches) the current session from the
specified job, causing that job to run in the background. Control of the
keyboard is returned to the user.
Note that the position of the cursor is cached at the beginning of a job.
Thus, a job that requires knowledge of cursor position can be interrupted,
leaving the user free to perform other commands. The same applies for
resolution of any special names.
This procedure is the programmatic equivalent to the Interrupt procedure;
it should be used within an Ada procedure or from a command window. If you
want to bind a key so that you can interactively disconnect from the
current job, use the Interrupt procedure.
To reconnect a session to a disconnected job, use the Connect procedure.
PARAMETERS
The_Job : Id := 0;
Specifies the job number for a job associated with the current session. The
default, 0, disconnects from the current job.
RESTRICTIONS
This procedure is not intended to be bound to a key. Use the Interrupt
procedure instead.
EXAMPLES
Example 1
The Disconnect procedure can be used to force any program to run in the
background, even if it started to run in the foreground. For example, a
program of the following form always runs in the background, even if it is
executed from a command window:
procedure Main is
begin
Job.Disconnect;
...
end Main;
This program performs basically the same as if a program had been executed
from a command window and then was interrupted by the Interrupt procedure.
Example 2
The Disconnect procedure also can be used to force a program to run in the
background after running in the foreground. For example, a program of the
following form begins in the foreground and then runs in the background
after gathering statistical information to be processed:
procedure Main is
begin
... -- gather statistics
Job.Disconnect;
... -- process information
end Main;
REFERENCES
procedure Connect
procedure Interrupt
@node !Commands.Job.Enable
procedure Enable (The_Job : Id;
The_Session : String := "");
DESCRIPTION
Restarts the specified disabled job.
This procedure restarts execution of the specified job. The job identifier 0
can be used to enable all jobs for the specified session. To enable jobs
associated with sessions other than your current session, you must supply
the pathname of the session associated with the job (for example,
!Users.Mat.S_2).
To temporarily stop a job, use the Disable procedure.
PARAMETERS
The_Job : Id;
Specifies the job number for the job to be enabled. A value of 0 stops all
jobs for the specified session, provided that session belongs to the
current user; the value 0 cannot be used to enable all jobs for a session
that belongs to another user.
The_Session : String := "";
Specifies the session with which the job is associated. Special names,
wildcards, and context characters can be used if they resolve to a single
object. The name supplied to this parameter is resolved with respect to
the current library. The name must resolve to a session object--for
example, !Users.Robinson.S_1. The default value, the null string, specifies
the current session.
RESTRICTIONS
To enable jobs that belong to another user, you must have read access to
that user's home world or be operating in privileged mode (belong to the
accesscontrol group Privileged and have enabled privileges).
EXAMPLES
Assume that user MAT has two jobs associated with his current session,
S_1, as shown in the following What.Users display:
User Status on June 30, 1991 at 04:22:52 PM
User Line Job S Time Job Name
====== ==== === ==== ========= ==============================
MAT 21 RUN 53:04.96 session'(S_1)
232 IDLE 00:02.45 !USERS.MAT % COMPILATION.MAKE
213 IDLE 02:37:01 !USERS.MAT WHAT.LOCKS
The following command restarts job 232 associated with MAT's current
session:
Job.Enable (The_Job => 232, The_Session => "");
REFERENCES
procedure Disable
@node !Commands.Job.Id
subtype Id is Machine.Job_Id;
DESCRIPTION
Defines a subtype that identifies jobs.
This subtype defines the integers used to identify jobs. These
identification numbers are assigned by the Environment to each job when
the job begins. The range is 0 through 255.
To determine the ID for a particular job, use What.Users or What.Jobs to
list the jobs currently active on the system.
@node !Commands.Job.Interrupt
procedure Interrupt;
DESCRIPTION
Disconnects the current session from the current job.
This procedure disconnects the current session from the current job,
causing that job to run in the background. Control of the keyboard is
returned to the user.
Note that the position of the cursor is cached at the beginning of a job.
Thus, a job that requires knowledge of cursor position can be interrupted,
leaving the user free to perform other commands. The same applies to the
resolution of any special names.
This procedure is the interactive equivalent to the Disconnect procedure;
it can be bound to a key so that you can interactively disconnect from the
current job. To programmatically disconnect from a specified job, use the
Disconnect procedure.
To reconnect to a disconnected job, use the Connect procedure.
RESTRICTIONS
This procedure should be bound to a key. Use the Disconnect procedure from
programs or command windows.
REFERENCES
procedure Connect
procedure Disconnect
@node !Commands.Job.Kill
procedure Kill (The_Job : Id;
The_Session : String := "");
DESCRIPTION
Terminates the specified job.
This procedure terminates execution of the specified job. All files declared
as Current_Output, Current_Input, or Current_Error, or files on the
current-output, current-input, or current-error stacks, are closed (see
package Log for more information about these stacks). All other files are
abandoned, and temporary files are deleted.
To temporarily stop execution of a job, use the Disable procedure.
PARAMETERS
The_Job : Id;
Specifies the job number of the job to be killed.
Unlike other commands in this package, the Kill command does not accept
the value 0 to specify all jobs in the current user's session.
The_Session : String := "";
Specifies the session with which the job is associated. Special names,
wildcards, and context characters can be used if they resolve to a single
object. The name supplied to this parameter is resolved with respect to
the current library. The name must resolve to a session object--for
example, !Users.Robinson.S_1. The default value, the null string, specifies
the current session.
RESTRICTIONS
To kill a job that belongs to another user, you must have read access to
that user's home world or be operating in privileged mode (belong to the
access-control group Privileged and have enabled privileges).
To kill certain jobs (such as core-editor jobs), you may need operator
capability. For information about operator capability, see package
Operator in the System Management Utilities (SMU) book.
EXAMPLES
Assume that a user named MAT has two jobs associated with his current
session, S_1, as shown in the following What.Users display:
User Status on June 30, 1991 at 04:22:52 PM
User Line Job S Time Job Name
======== ==== === ==== ========= ==============================
MAT 21 RUN 53:04.96 session'(S_1)
232 IDLE 00:02.45 !USERS.MAT % COMPILATION.MAKE
218 IDLE 02:37:01 !USERS.MAT % WHAT.JOBS
The following command kills job 218 in the current session:
Job.Kill (The_Job => 218, The_Session => "");
REFERENCES
procedure Disable
package Log
@node !Commands.Job.Set_Termination_Message
procedure Set_Termination_Message (S : String := "");
DESCRIPTION
Defines the message that is to be displayed when the job terminates.
This message is sent to Standard_Error, which is the Environment message
window.
PARAMETERS
S : String := "";
Specifies the message to be displayed. The default is no termination
message.
EXAMPLES
The following command defines a termination message:
Job.Set_Termination_Message (S => "Terminated with no errors");
When placed inside a program called Check_Sum and executed by user RJB,
the command produces the following termination message in the message
window:
!USERS.RJB % Check_Sum terminated: Terminated with no errors
@node !Commands.Log
Package Log provides procedures for manipulating the logs that are
generated by many Environment-defined commands. The procedures in this
package can be used to write logs to text files where they can be saved for
future reference. They can also be used to copy and filter existing log
files. User-written commands can use the Environment's log facilities by
writing output with any of the Put_Line procedures defined in this package.
Note that the procedures in package Log are intended only for manipulating
log output. For information about controlling other types of job output,
see Chapter 2, "Job Characteristics and Behavior."
RESOURCES IN PACKAGE LOG
The commands in package Log fall into several functional groups. Types and
constants are not included in this list.
Setting the log file: Set_Error, Set_Log, Set_Output
Copying and filtering existing log files: Copy, Filter, Filter_Errors,
Summarize
Managing Current_Input files: Pop_Input, Reset_Input, Set_Input
Managing Current_Error files: Pop_Error, Reset_Error, Set_Error
Managing Current_Output files: Pop_Output, Reset_Log,
Reset_Output, Set_Log, Set_Output
Writing messages into log files: Put_Condition, Put_Errors,
Put_Job_Messages, Put_Line,
Put_Line_Generic,
Put_System_Messages
Forcing buffered output into log files: Flush
Saving log files: Save
Identifying a message kind's prefix: Image
KEY CONCEPTS FOR PACKAGE LOG
Many commands report progress and error information in log messages. When
you execute a command, the Environment collects all of the log messages
from that command into a single log, which it then writes to a log file.
For example, the following log was generated by the Compilation.Promote
procedure:
91/06/07 14:31:26 ::: [Compilation.Promote ("<S>", ALL_PARTS, CODED,
91/06/07 14:31:27 ... "<WORLDS>", FALSE, PERSEVERE);].
91/06/07 14:31:27 ::: !USERS.JAF.PLAYGROUND.FACTORIAL'SPEC is already
91/06/07 14:31:27 ... INSTALLED.
91/06/07 14:31:27 ::: !USERS.JAF.PLAYGROUND.FACTORIAL'BODY is already
91/06/07 14:31:28 ... INSTALLED.
91/06/07 14:31:28 ::: !USERS.JAF.PLAYGROUND.FACTORIAL'SPEC is already
91/06/07 14:31:28 ... CODED.
91/06/07 14:31:33 --- Messages generated while promoting !USERS.JAF.
91/06/07 14:31:33 ... PLAYGROUND.FACTORIAL'BODY to CODED.
91/06/07 14:31:34 --- 33 instructions for subprog FACTORIAL.
91/06/07 14:31:34 --- 83 instructions for segment 4427009.
91/06/07 14:31:34 +++ !USERS.JAF.PLAYGROUND.FACTORIAL'BODY has been
91/06/07 14:31:34 ... CODED.
91/06/07 14:31:34 ::: 2 units were already INSTALLED.
91/06/07 14:31:34 ::: 1 unit was already CODED.
91/06/07 14:31:34 +++ 1 unit was CODED.
91/06/07 14:31:34 ::: [End of Compilation.Promote Command].
Figure 1 Log Messages Produced by the Compilation.Promote Command
Log messages differ from other types of job output in the type of
information they contain and in how they are generated:
* Log messages generally provide progress, error, notes, and other
information about the execution of a command. In contrast, job reports
provide information specifically requested by the user, such as a list
of jobs currently active on the system.
* Log messages are subject to the default characteristics you set in
session and job response profiles. Specifically, you can set:
- The kinds of messages that are to be included in the log
- The log file to which the log is to be written
- The prefixes to precede each line in the log
- The width (number of columns) allowed for each line in the log
Other types of output are controlled completely by the command
generating the output.
The remainder of this "Key Concepts" section discusses the various
characteristics of log messages and the commands in this package that
affect those characteristics. For information about other types of job
output, see Chapter 2, "Job Characteristics and Behavior."
Message Kinds
Commands may produce a number of different kinds of log messages, where
each kind of message conveys a characteristic kind of information and is
preceded by a characteristic set of symbols. Environment-defined commands
write nine kinds of messages. Three additional message kinds are provided
for user-defined purposes. All twelve message kinds are described in Table
1. For further information about message kinds, see type Profile.Msg_Kind
in this book.
Table 1 Log Message Kinds
-----------------------------------------------------
| | | |
|Kind |Symbol|Description |
| | | |
-----------------------------------------------------
| | | |
|At_Msg |@@@ |Has no predefined meaning. At |
| | |messages are not used by the |
| | |Environment but can be used by |
| | |users to insert messages into |
| | |the log files for user-defined |
| | |purposes. |
-----------------------------------------------------
| | | |
|Auxiliary_Msg|::: |Indicates a general message. |
| | |Auxiliary messages are pro- |
| | |vided by the Environment as |
| | |commentary on the execution of |
| | |commands. |
-----------------------------------------------------
| | | |
|Debug_Msg |??? |Indicates a debugging message. |
| | |Debug messages (also called |
| | |diagnostic messages) are |
| | |provided by the Environment as |
| | |an aid in debugging commands. |
-----------------------------------------------------
| | | |
|Dollar_Msg |$$$ |Has no predefined meaning. |
| | |Dollar messages are not used by |
| | |the Environment but can be used |
| | |by users to insert messages into|
| | |the log files for user-defined |
| | |purposes. |
-----------------------------------------------------
| | | |
|Error_Msg |*** |Indicates a serious error. Error|
| | |messages indicate that the |
| | |operation has found some |
| | |condition that prevents it from |
| | |completing successfully. This |
| | |condition usually causes the |
| | |error reaction to be taken by |
| | |the command. An error message |
| | |may be accompanied by a negative|
| | |message. |
-----------------------------------------------------
| | | |
|Exception_Msg|%%% |Indicates that an exception was |
| | |raised during the execution of |
| | |the command. Exception messages |
| | |indicate that the operation |
| | |has found some condition that |
| | |prevents it from continuing. |
| | |This condition usually causes |
| | |the error reaction to be taken |
| | |by the command. An exception |
| | |message may be accompanied by |
| | |a negative message. |
-----------------------------------------------------
| | | |
|Negative_Msg |++* |Indicates negative progress. |
| | |Negative messages are provided |
| | |by the Environment when |
| | |operations do not complete suc- |
| | |cessfully. A negative message is|
| | |usually accompanied by an error |
| | |or exception message indicating |
| | |the condition that prevented |
| | |the operation from completing |
| | |successfully. |
-----------------------------------------------------
| | | |
|Note_Msg |--- |A general message. Note messages|
| | |are provided by the Environment |
| | |as commentary on the execution |
| | |of commands. |
-----------------------------------------------------
| | | |
|Position_Msg |>>> |Indicates the position in some |
| | |object where an event, ex- |
| | |plained by another message, has |
| | |occurred. Position messages |
| | |are provided by the Environment |
| | |as an aid in locating errors and|
| | |other events in large objects. |
-----------------------------------------------------
| | | |
|Positive_Msg |+++ |Indicates positive progress. |
| | |Positive messages are provided |
| | |by the Environment when |
| | |operations complete |
| | |successfully. |
-----------------------------------------------------
| | | |
|Sharp_Msg |### |Has no predefined meaning. Sharp|
| | |messages are not used by the |
| | |Environment but can be used by |
| | |users to insert messages into |
| | |the log files for user-defined |
| | |purposes. |
-----------------------------------------------------
| | | |
|Warning_Msg |!!! |Warns of some minor error. |
| | |Warning messages indicate that |
| | |the operation has found some |
| | |condition that is not quite |
| | |correct but is not serious |
| | |enough to prevent the operation |
| | |from continuing. |
-----------------------------------------------------
Log Filters
When you execute a command, you can cause the command to filter the
messages so that only certain kinds of messages are written into the log
file. For example, you may not be interested in auxiliary or note messages
but want to see all error and negative messages.
You can set the log filter through one of several mechanisms:
* To set the default log filter for all commands executed under a
particular session, you can set the Profile.Log_Kind_Msgs session
switches for that session. Setting these switches sets the session
response profile for the current session (see "Default Log
Characteristics," page nn).
* To set the default log filter for multiple commands in a single job, you
can call one of the following procedures from within the job (for
example, from the same command window as other commands):
- Log.Set_Log
- Profile.Include
- Profile.Set_Filter
These procedures set the log-filter component of the job response profile
of the current job. The Set_Log procedure also sets the log-file
component. For further information, see "Default Log Characteristics,"
page nn.
* To set the log filter for a single command, use the Response parameter
of that command (see Parameter-Value Conventions in the Reference
Summary (RS) book).
You can also have the Environment filter existing log files while copying
them, so that only certain kinds of messages are included in the new file.
Filtering an existing log file is especially useful when you want to
compare the file to another file or a template. For further information
about filtering existing log files, see "Copying and Filtering Existing Log
Files," page nn. For information about comparing log files and using
templates, see the Library Management (LM) book, package File_Utilities.
Log Files
Logs are ultimately written into one of three destinations:
* Standard_Error (the message window)
* Standard_Output (an Environment output window)
* A text file
Logs can be sent directly to Standard_Output or Standard_Error, or they
can be sent to any of the three destinations through one of the following
redirectable files:
* Current_Output, which, by default, redirects output to Standard_Output
* Current_Error, which, by default, redirects output to Standard_Error
Although Current_Output and Current_Error are referred to as "files," they
are really pointers to one of the three destinations listed above. For
example, if the log file is set to be Current_Output (the system default),
you can then redirects the log by changing the file pointed to by
Current_Output, as shown in Figure 2.
STEP 1 STEP 2
YOU SET THE YOU REDIRECT
LOG FILE TO BE: CURRENT_OUTPUT OR
CURRENT_ERROR TO:
|- Standard_Output
|
|- Standard_Error
Log messages -> |
|- Current_Output -> |- Text file
| |
|- Current_Error -> |- Standard_Output
|
|- Standard_Error
|
|- Current_Output ->
|
|- Current_Error ->
Figure 2 Directing Log Messages to a Destination
You can change the log file through one of several mechanisms:
* To set the default log file for all commands executed under a particular
session, you can set the Profile.Log_File session switch for that
session. Setting this switch sets the log-file component of the session
response profile for the current session (see "Default Log
Characteristics," below).
* To set the default log file for multiple commands in a single job, you
can call one of the following procedures from within the job (for
example, from the same command window as other commands):
- Log.Set_Output
- Log.Set_Log
- Log.Set_Error
- !Tools.Profile.Set_Log_File
These procedures set the log-file component of the job response profile
of the current job. Procedures from package Log also set Current_Output
or Current_Error. Additionally, the Set_Log procedure sets the
log-filter for the current job. For further information, see "Setting
the Default Log File for a Job," page nn.
* To set the log file for a single command, you can use the Response
parameter of that command (see Parameter-Value Conventions in the
Reference Summary (RS) book).
For further information about directing log files and other types of job
output, see Chapter 2, "Job Characteristics and Behavior." Chapter 2 also
contains information about redirecting Current_Output or Current_Error
without changing the log file.
Default Log Characteristics
Log characteristics for Environment commands are determined by the job
response profile for the job in which the command is executing. The job
response profile gets it values from the session response profile for the
current session, which gets its values from the system default profile.
Most Enviroment commands have a Response parameter through which you can
override the log characteristics set by the job response profile; however,
even commands that do not have a Response parameter are subject to the
response profile for the current job.
The following subsections describe the default log characteristics used by
Environment commands and how they are set.
For further information about response characteristics and profiles, see
Chapter 2, "Job Characteristics and Behavior," or package Profile in this
book. For information about using the Response parameter to set the log
characteristics for a single command, see Parameter-Value Conventions in
the Reference Summary (RS) book.
System Default Log Characteristics
The system default profile defines the log characteristics that are
delivered as part of the standard Environment. Environment-defined commands
use these log characteristics unless you explicitly have set other log
characteristics for the current session, current job, or the command
itself (using the Response parameter of the command).
In particular, the system default log characteristics cause commands to:
* Write log output to Current_Output (as indicated by the value
Use_Output)
* Include all log messages except debug messages (denoted by the prefix
???) in the log file
* Precede each line of the log with the date, time, and symbol indicating
the message kind
* Allow a width of 77 columns for each line in the log
These system default characteristics are shown in Figure 1 at the
beginning of this package introduction.
Default Log Characteristics for a Session
The default log characteristics for a session are defined in the session
response profile for that session. The log characteristics in a session
response profile override those in the system default profile.
Environment-defined commands use these log characteristics unless you
explicitly set other characteristics for the current job or the command
itself.
The initial values of the session response profile for your default
session, S_1, are copied from the system default profile. Subsequent
sessions copy their response-profile values from the session response
profile for session S_1.
You can set the component values of a session response profile through
session switches with the prefix "Profile." Specifically, the following
session switches determine the log characteristics in the session
response profile:
Log_At_Sign_Msgs Log_Auxiliary_Msgs
Log_Diagnostic_Msgs Log_Dollar_Msgs
Log_Error_Msgs Log_Exception_Msgs
Log_File Log_Line_Width
Log_Negative_Msgs Log_Note_Msgs
Log_Prefix_1 Log_Prefix_2
Log_Prefix_3 Log_Position_Msgs
Log_Positive_Msgs Log_Sharp_Msgs
Log_Warning_Msgs
Session response profiles persist across logins, lasting until you change
any of the relevant session-switch values.
For further information about these switches, including the values
accepted by each, see Session Switches in this book or the online help for
each switch (obtained by selecting the desired switch and executing the
!Commands.Common.Explain command, which is generally bound to a key or
key combination).
For information about editing these switches directly, see Session
Switches in this book. For information about changing these switch values
programmatically, see package Profile, also in this book.
Default Log Characteristics for a Job
The default log characteristics for all the commands in a job are defined
in the job response profile for that job. The log characteristics in the
job response profile for the current job override those in both the system
default and session response profiles. Environment-defined commands use the
log characteristics in the job response profile for the current job
unless you specify other characteristics through the command's Response
parameter. Environment-defined commands that do not have a Response
parameter always use the log characteristics set in the job response
profile for the current job.
The initial values of a job response profile are copied from the session
response profile for the current session; however, you can set other log
characteristics in the job response profile for the current job. Setting
the default log characteristics for a job allows you to:
* Override one or more log characteristics from the session response
profile for the duration of the current job
* Set the log file to be a specific text file rather than an
Environment-defined "file" (such as Current_Output)
* Change the log characteristics for several commands in the same job
through a single operation
To set the job response profile for the current job, you can call any of
the procedures listed in Table 2 from the same command window as (and
preceding the commands in) the job you want to affect.
Table 2 Commands for Setting the Default Log Characteristics for a Job
--------------------------------------------------------
| | |
|Characteristic|Commands for Setting This Characteristic |
| | |
--------------------------------------------------------
| | |
|Log file |Log.Set_Log, Log.Set_Output, |
| |Log.Set_Error, Profile.Set_Log_File |
--------------------------------------------------------
| | |
|Log filter |Log.Set_Log, Profile.Set_Filter |
| | |
--------------------------------------------------------
| | |
|Log prefixes |Profile.Set_Prefixes |
| | |
--------------------------------------------------------
| | |
|Log width |Profile.Set_Width |
| | |
--------------------------------------------------------
These procedures can also be called from within your programs to set
specific log characteristics that will always be used when that command
executes. Setting specific log characteristics is especially useful for
servers that may be started by different users but that should always
log information using the same format and filter.
For further information about setting the log file, see "Setting the
Default Log File for a Job," page nn. For further information about
setting other log characteristics in the job response profile for the
current job, see the introduction to package Profile in this book.
USING COMMANDS IN PACKAGE LOG
The following subsections contain information about using commands in
package Log interactively to:
* Set the default log file for the current job
* Copy and filter existing log files
They also contain information about calling procedures in package Log from
your applications to:
* Manage stacks of current output, error, and input files
* Write messages to the log file
Setting the Default Log File for a Job
You can set the default log file for all the commands in a single job by
calling one of three procedures from package Log:
* Set_Error
* Set_Output
* Set_Log
Each of these procedures performs two operations:
* Sets the log file for the current job to be one of two redirectable
"files":
- Set_Output and Set_Log set the log file to be Current_Output.
- Set_Error sets the log file to be Current_Error.
* Redirects Current_Output or Current_Error to be the specified file,
pushing the file onto a stack of Current_Output or Current_Error
files (see "Managing Current Output, Error, and Input Files," page
nn).
Procedures in package Log differ from the Profile.Set_Log_File procedure,
which sets only the log file, and procedures from package !Io.Io, which set
only Current_Output or Current_Error.
By setting both the log file and the Current_Output (or Current_Error) file,
procedures in package Log ensure that any other type of job output sent
to Current_Output is redirected along with the log file. Procedures in
package Log are especially useful when:
* You are executing a command such as Library.Resolve that produces both
log messages and a job report or display that is not part of the log
and you want to redirect both types of output.
* You are executing several commands in a single command window and want
to redirect the logs for all the commands.
* You are executing a command that does not have a Response parameter and
you want to redirect the log.
Note that if you want to set the log file for a single command, you can use
the Response parameter of that command (see Parameter-Value Conventions in
the Reference Summary (RS) book).
Copying and Filtering Existing Log Files
Sometimes you may want to keep a series of logs from similar operations so
that you can compare progress and error information. You may want to
compare these logs to each other or construct a template against which to
compare all the logs. In either case, ensuring that the logs include the
same set of message kinds makes the comparisons easier.
Specifying that the Environment use the same filter when creating the logs
is one way to ensure that the logs contain the same set of messages.
Alternatively, you can have the Environment write the full set of log
messages into a text file and then copy the log into another file,
instructing the Environment to filter the messages while copying. Writing
the complete log into a file allows you to create several additional files,
using different filters.
You can use the following commands from package Log to copy text files that
contain log messages and filter the messages in the process:
* Copy
* Filter
* Filter_Errors
* Summarize
The filtered copy can be directed to another text file or to Current_Output.
Note that if the original log does not contain a particular kind of
message, the new log will not contain that kind of message, even if that
message kind is included in the specified filter.
The Copy, Filter, Filter_Errors, and Summarize procedures differ only in
how you specify the log filter to be used. The following subsections
discuss how to:
* Copy a predefined set of message kinds
* Copy an arbitrary set of message kinds
Copying a Predefined Set of Message Kinds
The Copy command allows you to use an existing filter when copying a log
file. By default, the Copy command uses the log-filter specified in the job
response profile for the current job (by default, the filter specified
through the Profile.Log_Kind_Msgs session switches for the current
session). However, you can specify any value of type Profile.Log_Filter,
including those constants defined in package Profile. These constants are
described in Table 3, beginning with the filter that includes the fewest
kinds of messages.
For example, assume that you have a file called Test_6_3_91, which contains
the full set of log messages from the execution of an application you are
developing.
Table 3 Predefined Filters
--------------------------------------------------------
| | |
|Filter |Description |
--------------------------------------------------------
| | |
|Profile.Quiet |Specifies that no messages are to be |
| |included in the log file. |
--------------------------------------------------------
| | |
|Profile.Summary|Specifies that only positive (+++) and |
| |negative (++*) messages summarizing |
| |command progress are to be included in |
| |the log file. |
--------------------------------------------------------
| | |
|Profile.Errors |Specifies that only messages indicating |
| |various degrees of errors are to be |
| |included in the log file. Specifically, |
| |this filter includes negative (++*), |
| |warning (!!!), error (***), and |
| |exception (%%%) messages. |
--------------------------------------------------------
| | |
|Profile.Terse |Specifies that the minimal set of |
| |messages that includes progress, error, |
| |and user-defined messages be included |
| |in the log file. Specifically, this |
| |filter includes at (@@@), dollar ($$$), |
| |error (***), exception (%%%), negative |
| |(++*), position (>>>), positive (+++), |
| |sharp (###), and warning (!!!) |
| |messages. This filter does not include |
| |auciliary (:::), debug (???), or note |
| |(---) messages. |
--------------------------------------------------------
| | |
|Profile.Full |Specifies that all messages except |
| |debug messages (denoted by ???) are to |
| |be included in the log file. |
--------------------------------------------------------
Suppose that you want to copy only any negative, warning, error, or
exception messages from that file into a new file called Test_6_3_91_Errors.
To do so, you could execute the following command:
Log.Copy (Log_File => "Test_6_3_91_Full",
Destination => "Test_6_3_91_Errors",
Filter => Profile.Errors);
Copying an Arbitrary Set of Message Kinds
The Filter, Filter_Errors, and Summarize procedures perform the same
operation as the Copy procedure; however, they allow you to specify the
filter as a set of Boolean values, one for each message kind. They are
especially useful if none of the predefined filters contain the set of
message kinds you want to include in the new log file.
For example, assume that you want to copy any negative, warning, error,
exception, or position messages from a log file called called
Test_6_3_91_Full into a new file called Test_6_3_91_Errors. The
Profile.Errors filter includes the first four of these message kinds, but it
does not include position messages indicating where the error may have
occurred. For this reason, you cannot use the Copy command discussed
above. Instead, you could use the following command, which allows you to
specify any set of message kinds:
Log.Filter (Log_File => "Test_6_3_91_Full",
Destination => "Test_6_3_91_Errors",
Auxiliaries => False,
Diagnostics => False,
Notes => False,
Positives => False,
Negatives => True,
Positions => True,
Warnings => True,
Errors => True,
Exceptions => True,
Sharps => False,
Dollars => False,
Ats => False);
The Filter, Filter_Errors, and Summarize procedures differ only in their
default values. By default:
* The Filter procedure includes all message kinds.
* The Filter_Errors procedure includes auxiliary (:::), debug (???),
negative (++*), warning (!!!), and error (***) messages.
* The Summarize procedure includes auxiliary (:::), debug (???), positive
(+++), and negative (++*) messages.
Managing Current Output, Error, and Input Files
As described in "Log Files," page nn, you can set the log file to be one of
two redirectable files:
* Current_Output, which, by default, redirects output to Standard_Output
(an Environment I/O window)
* Current_Error, which, by default, redirects output to Standard_Error
(the message window)
Similarly, you can read input from a redirectable file:
* Current_Input, which, by default, obtains input from Standard_Input (an
Environment I/O window)
Although Current_Output, Current_Error, and Current_Input are referred to
as "files," they are actually pointers to a specific file. Implementing these
files as pointers allows you to redirect input and output easily. It also
allows the Environment to offer a stack mechanism for input, output, and
error files. These stacks are maintained for a particular job and can be
managed programmatically from within the job using procedures from package
Log or package !Io.Io.
Commands from package Log that control stacks of output, error, and input
files are listed in Table 4. The column under which the procedure is listed
indicates the stack affected by that procedure; the row indicates the
operation the procedure performs on the stack.
Table 4 Commands from Package Log for Input, Error, and Output Stacks
----------------------------------------------------------
| | | | |
|Operation |Current_Output|Current_Error|Current_Input|
| | | | |
----------------------------------------------------------
| | | | |
|Push a file |Set_Output, |Set_Error |Set_Input |
| |Set_Log | | |
----------------------------------------------------------
| | | | |
|Pop a file |Pop_Output |Pop_Error |Pop_Input |
| | | | |
----------------------------------------------------------
| | | | |
|Reset the stack|Reset_Output, |Reset_Error |Reset_Input |
| |Reset_Log | | |
| | | | |
----------------------------------------------------------
The following subsections discuss the implications of setting, popping,
and resetting files.
Pushing Files onto the Stacks
Pushing a file onto the top of the stack sets that file to be the "current"
file to be used. For example, the following command sets Messages_1_91 to
be the Current_Output file, causing all output sent to Current_Output to
be written in that file:
Log.Set_Output (To_Be => "Messages_1_91");
When the job completes, Messages_1_91 and any other files on the stack are
closed and Current_Output is reset to the system default, Standard_Output.
Popping Files from the Stacks
Popping a file removes it from the stack, making the previous file the new
top of the stack and the "current" file.
Popping a file from the stack does not close the file. You can continue
writing to the file by setting it to be the current file again, using the
corresponding Set procedure. In this case, the new output is appended to
the original output. Note, however, that if you do not set the file back
on the stack or explicitly close the file, the contents may be lost when
the job completes.
For example, assume that there are three files on the stack of output files:
Output_1 on top, followed by Output_2 and Output_3. The following
command pops Output_1 off the stack:
Log.Pop_Output;
The resulting stack contains only two files: Output_2 and Output_3. Output
sent to Current_Output is now written to Output_2. Note that Output_1 is
still open and will not be closed automatically at the end of the job. If
you do not explicitly close Output_1 before the end of the job, the
contents of the file may be lost.
Resetting the Stacks
Resetting a stack removes the current file from the top of the stack,
making the previous file the new top of the stack and the "current" file.
Unlike when you pop a file, when you reset the stack, the removed file is
closed, ensuring that the contents are saved. If you attempt to write to
this file after it has been closed--for example, by setting it as the
current file again--the original contents of the file will be overwritten.
An Example of Stack Manipulation
The following procedure starts a server that logs off sessions that have
been idle for a specified amount of time. Notice that it calls the
Log.Set_Output procedure to set Current_Output to be a specified file and to
set the log file to be Current_Output. It then calls Io.Set_Error to set
Current_Error to also be Current_Output. This combination ensures that all
output that can be redirected is sent to a single destination--in this
case a text file called !Machine.Error_Logs.Logoff_Idle_Users_Server_Log.
with Io;
with Library;
with Log;
with Pipe;
with Debug_Tools;
procedure Logoff_Server
(Maximum_Idle_Time_In_Minutes : in Natural := 60;
Polling_Interval_In_Minutes : in Natural := 5) is
begin
Log.Set_Output
("!MACHINE.ERROR_LOGS.LOGOFF_IDLE_USERS_SERVER_LOG");
Io.Set_Error (Io.Current_Output);
-- Above procedures set log file to be Current_Output,
-- redirect Current_Output to text file,
-- and redirect Current_Error to Current_Output.
-- This combination ensures that all redirectable output goes
-- to the specified file.
Operator.Enable_Privileges (Enable => True);
if not Operator.Privileged_Mode then
Log.Put_Line
(Message => "Could not enable privileges. " &
"The Idle Users Logoff server was not
activated",
Kind => Profile.Error_Msg,
Response => Profile.Verbose);
Log.Save (Response => Profile.Verbose);
-- Flushes all output to log and saves log.
Io.Reset_Output;
Io.Reset_Error;
-- Closes output and error files and removes the files
-- from the stack, making the previous file the new top
-- of stack before returning to calling job.
end if;
--
-- Parts of the application are omitted from this example.
--
exception
when Terminate_Server =>
Log.Save (Response => Profile.Verbose);
Pipe.Close (Pipe => Pipe_To_Server);
Library.Destroy
(Existing => Idle_Users.Context & "." &
Name_Of_Pipe_To_Server,
Threshold => 1,
Limit => "<DIRECTORIES>",
Response => "<NIL>");
Io.Reset_Output;
Io.Reset_Error;
when others =>
Log.Put_Line
(Message => "Encountered an unexpected exception " &
"in the Idle_Users.Logoff_Server on " &
Time_Image (For_Time => Calendar.Clock) &
" (Exception => " &
Debug_Tools.Get_Exception_Name
(Fully_Qualify => True,
Machine_Info => True) & ")",
Kind => Profile.Exception_Msg,
Kind => Profile.Exception_Msg,
Response => Profile.Verbose);
Log.Save (Response => Profile.Verbose);
Pipe.Close (Pipe => Pipe_To_Server);
Library.Destroy
(Existing => Idle_Users.Context & "." &
Name_Of_Pipe_To_Server,
Threshold => 1,
Limit => "<DIRECTORIES>",
Response => "<NIL>");
Io.Reset_Output;
Io.Reset_Error;
end Logoff_Server;
Writing Messages into Log Files
You can use the Environment's log-file facilities for your applications by
calling procedures from package Log that write additional information into
the log files. These procedures fall into two groups--procedures that
write:
* Additional Environment-generated messages, such as status and error
information
* User-defined messages
These two groups of procedures are discussed in the following subsections.
Writing Additional Environment Messages
Package Log provides four procedures that write information that is
generated by the Environment but not automatically included in the logs:
* Put_Condition writes information of type Simple_Status.Condition.
* Put_Errors writes information of type Error_Messages.Error.
* Put_Job_Messages writes the contents of the system message log for the
specified job.
* Put_System_Messages write the contents of the system message log for
the current job.
The Put_System_Messages and Put_Job_Messages procedures are useful if you
want additional information about the progress of a specific job.
The Put_Errors and Put_Condition procedures are useful in combination with
certain Environment commands, such as the Program.Create_Job procedure,
that return values of the types indicated above.
For example, the following program creates a separate job under which to
start each program named in a file (File_1) and then reports the status of
each job creation using the Put_Condition procedure:
with Io, Program, Simple_Status;
procedure Start_Servers is
File_1 : Io.File_Type;
Job : Program.Job_Id;
Status : Simple_Status.Condition;
begin
Io.Open (File_1, Io.Infile, "Programs_To_Start");
while not Io.End_Of_File (File_1) loop
Program.Create_Job
(S => Io.Get_Line (File_1),
Job => Job, Status => Status);
if Program.Started_Successfully (Status) then
Io.Put_Line ("Started Job " &
Program.Job_Id'Image (Job));
else
Log.Put_Condition (Status);
end if;
end loop;
Io.Close (File_1);
end Start_Servers;
Writing User-Defined Messages
Package Profile provides a family of Put_Line procedures that allow
additional messages, beyond those produced by the Environment, to be
placed in the log file. In addition to allowing you to specify the message
text, these procedures allow you to assign a message kind (of type
Profile.Msg_Kind) to the message.
You can specify any message kind; however, it is recommended that you
assign message kinds in a manner consistent with the Environment's use of
message kinds (see "Message Kinds," page nn). Several message kinds also
are reserved for user-defined purposes:
* At messages (Profile.At_Msg) are denoted by @@@.
* Dollar messages (Profile.Dollar_Msg) are denoted by $$$.
* Sharp messages (Profile.Sharp_Msg) are denoted by ###.
Be aware that when a message is written into the log file, only that kind
of message is included in the log filter specified through the Response
parameter of the Put_Line procedure. Thus, if your messages are dollar
messages, you should ensure that the log filter includes dollar messages
by setting the Response parameter accordingly.
The various Put_Line procedures differ in how you specify the message to
be written. In general, you have two options:
* You can specify the exact message to be written.
* You can specify that the message dynamically reference up to two
objects.
These methods are discussed below.
Specifying the Exact Message to Be Written
For most purposes, you can use a Put_Line procedure that writes the string
exactly as you have indicated. For example, most Environment commands call
this Put_Line procedure to write a log message reporting the final status
of the command.
Assume that Operation_Name is a variable of type String that contains the
name of the procedure being executed, such as:
Operation_Name : String := "Compilation.Promote";
The following command writes a completion message, including the name of
the operation that has completed, into the log file:
Log.Put_Line (Message => "[" & Operation_Name &
" has completed -- No errors detected]",
Kind => Profile.Auxiliary_Msg,
Response => "<PROFILE>");
The resulting log message appears in Figure 3.
91/08/20 15:59:50 ::: [Compilation.Promote has completed -- No errors
91/08/20 15:59:50 ... detected]
Figure 3 Sample Log Message Resulting from Put_Line
This message is written into the log file specified in the Response
parameter of the Put_Line procedure. Using the log file specified in the job
response profile for the current job (indicated by the special value
"<PROFILE>") ensures that all the log messages for a single job are
written into the same log file.
Note that the message is also subject to the log filter, prefixes, and width
specified in the Response parameter of the Put_Line procedure.
Dynamically Referencing Objects in Messages
Other Put_Line procedures, including the Put_Line_Generic procedure, allow
you to dynamically reference up to two Environment objects. The procedures
compute the names of the specified objects and insert those names into the
message text. You can also embed symbols in the message text to specify
how the names are to be computed and where they are to be inserted. For
more information, see the reference entries for procedures Put_Line and
Put_Line_Generic.
@node !Commands.Log.Copy
procedure Copy
(Log_File : Name := "<IMAGE>";
Destination : Name := "";
Filter : Profile.Log_Filter := Profile.Filter);
DESCRIPTION
Copies the specified log file into a new file, using the specified log filter.
This procedure both copies the log from one file into another and filters
the log messages in the process. Only those messages whose kinds are
included in the specified filter are included in the new log file. By
default, the procedure uses the filter that is specified in the job response
profile for the current job.
The new log filter is sent to the location specified in the Destination
parameter. By default, the new log file is sent to Current_Output, which
is, by default, an Environment output window.
To copy a log and filter its contents in the process, you can also use the
Filter, Filter_Errors, and Summarize procedures. Whereas the Copy
procedure allows you to specify an existing filter, these procedures allow
you to specify a Boolean value for each message kind, indicating whether
messages of that kind are to be included in the new log file.
PARAMETERS
Log_File : Name := "<IMAGE>";
Specifies the log file to be copied. The default is the log file in the
current image.
Destination : Name := "";
Specifies the destination for the new log file. The default (the null
string) sends the log file to Current_Output, which is, by default, an
Environment output window.
Filter : Profile.Log_Filter := Profile.Filter;
Specifies the filter to use when copying the log file. The filter can define
any subset of messages in the log. Only those messages whose kind is
included in the filter are copied into the new log file. This parameter
accepts any value of type Profile.Log_Filter, including those constants
defined in package Profile:
Errors Specifies that only negative (++*), warning (!!!),
error (***), and exception (%%%) messages are to be
included in the log file.
Full Specifies that all messages except debug messages
(denoted by ???) are to be included in the log file.
Quiet Specifies that no messages are to be included in the
log file.
Summary Specifies that only positive (+++) and negative (++*)
messages are to be included in the log file.
Terse Specifies that the following kinds of messages are to
be included in the log file: at (@@@), dollar ($$$),
error (***), exception (%%%), negative (++*),
position (>>>), positive (+++), sharp (###), and
warning (!!!).
REFERENCES
procedure Filter
procedure Filter_Errors
procedure Summarize
package Profile
constant Profile.Errors
constant Profile.Full
constant Profile.Quiet
constant Profile.Summary
constant Profile.Terse
@node !Commands.Log.Filter
procedure Filter (Log_File : Name := "<IMAGE>"
Destination : Name := "";
Auxiliaries : Boolean := True;
Diagnostics : Boolean := True;
Notes : Boolean := True;
Positives : Boolean := True;
Negatives : Boolean := True;
Positions : Boolean := True;
Warnings : Boolean := True;
Errors : Boolean := True;
Exceptions : Boolean := True;
Sharps : Boolean := True;
Dollars : Boolean := True;
Ats : Boolean := True);
DESCRIPTION
Filters the specified log file based on the specified parameters and then
writes the result into the specified destination.
This procedure both copies the log from one file into another and filters
the log messages in the process. Only those message kinds for which the
value is True are included in the new log file. By default, all messages
are included in the new log file.
The new log filter is written into the location specified in the Destination
parameter. By default, the new log file is sent to Current_Output, which
is, by default, an Environment output window.
This procedure is renamed by the Filter_Errors and Summarize procedures.
To copy a log and filter its contents in the process, you can also use the
Copy procedure. Whereas the Filter procedure allows you to specify a
Boolean value for each message kind, the Copy procedure allows you to
specify an existing filter.
PARAMETERS
Log_File : Name := "<IMAGE>";
Specifies the log file to be copied and filtered. The default is the log file
in the current image.
Destination : Name := "";
Specifies the destination for the new log file. The default (the null
string) sends the log file to Current_Output, which is, by default, an
Environment output window.
Auxiliaries : Boolean := True;
Specifies whether to write auxiliary messages (denoted by :::) into the
destination file. The default, True, is to write them.
Diagnostics : Boolean := True;
Specifies whether to write diagnostic or debug messages (denoted by ???)
into the destination file. The default, True, is to write them.
Notes : Boolean := True;
Specifies whether to write note messages (denoted by ---) into the
destination file. The default, True, is to write them.
Positives : Boolean := True;
Specifies whether to write positive messages (denoted by +++) into the
destination file. The default, True, is to write them.
Negatives : Boolean := True;
Specifies whether to write negative messages (denoted by ++*) into the
destination file. The default, True, is to write them.
Positions : Boolean := True;
Specifies whether to write position messages (denoted by >>>) into the
destination file. The default, True, is to write them.
Warnings : Boolean := True;
Specifies whether to write warning messages (denoted by !!!) into the
destination file. The default, True, is to write them.
Errors : Boolean := True;
Specifies whether to write error messages (denoted by ***) into the
destination file. The default, True, is to write them.
Exceptions : Boolean := True;
Specifies whether to write exception messages (denoted by %%%) into the
destination file. The default, True, is to write them.
Sharps : Boolean := True;
Specifies whether to write sharp messages (denoted by ###) into the
destination file. The default, True, is to write them.
Dollars : Boolean := True;
Specifies whether to write dollar messages (denoted by $$$) into the
destination file. The default, True, is to write them.
Ats : Boolean := True;
Specifies whether to write at messages (denoted by @@@) into the
destination file. The default, True, is to write them.
REFERENCES
procedure Copy
procedure Filter_Errors
procedure Summarize
type Profile.Msg_Kind
@node !Commands.Log.Filter_Errors
procedure Filter_Errors (Log_File : Name := "<IMAGE>"
Destination : Name := "";
Auxiliaries : Boolean := True;
Diagnostics : Boolean := True;
Notes : Boolean := False;
Positives : Boolean := False;
Negatives : Boolean := True;
Positions : Boolean := False;
Warnings : Boolean := True;
Errors : Boolean := True;
Exceptions : Boolean := False;
Sharps : Boolean := False;
Dollars : Boolean := False;
Ats : Boolean := False)
renames Filter;
DESCRIPTION
Filters the specified log file based on the specified parameters and then
writes the result into the specified destination.
This procedure both copies the log from one file into another and filters
the log messages in the process. Only those message kinds for which the
value is True are included in the new log file. By default, only auxiliary
(:::), diagnostic (???), negative (++*), warning (!!!), and error (***)
messages are included in the new log file.
The new log filter is written into the location specified in the Destination
parameter. By default, the new log file is sent to Current_Output, which
is, by default, an Environment output window.
This procedure renames the Filter procedure. The Summarize procedure also
renames the Filter procedure, using different default parameter values.
To copy a log and filter its contents in the process, you can also use the
Copy procedure. Whereas the Filter_Errors procedure allows you to
specify a Boolean value for each message kind, the Copy procedure allows
you to specify an existing filter.
PARAMETERS
Log_File : Name := "<IMAGE>";
Specifies the log file to be copied and filtered. The default is the log file
in the current image.
Destination : Name := "";
Specifies the destination for the new log file. The default (the null
string) sends the log file to Current_Output, which is, by default, an
Environment output window.
Auxiliaries : Boolean := True;
Specifies whether to write auxiliary messages (denoted by :::) into the
destination file. The default, True, is to write them.
Diagnostics : Boolean := True;
Specifies whether to write diagnostic or debug messages (denoted by ???)
into the destination file. The default, True, is to write them.
Notes : Boolean := False;
Specifies whether to write note messages (denoted by ---) into the
destination file. The default, False, is not to write them.
Positives : Boolean := False;
Specifies whether to write positive messages (denoted by +++) into the
destination file. The default, False, is not to write them.
Negatives : Boolean := True;
Specifies whether to write negative messages (denoted by ++*) into the
destination file. The default, True, is to write them.
Positions : Boolean := False;
Specifies whether to write position messages (denoted by >>>) into the
destination file. The default, False, is not to write them.
Warnings : Boolean := True;
Specifies whether to write warning messages (denoted by !!!) into the
destination file. The default, True, is to write them.
Errors : Boolean := True;
Specifies whether to write error messages (denoted by ***) into the
destination file. The default, True, is to write them.
Exceptions : Boolean := False;
Specifies whether to write exception messages (denoted by %%%) into the
destination file. The default, False, is not to write them.
Sharps : Boolean := False;
Specifies whether to write sharp messages (denoted by ###) into the
destination file. The default, False, is not to write them.
Dollars : Boolean := False;
Specifies whether to write dollar messages (denoted by $$$) into the
destination file. The default, False, is not to write them.
Ats : Boolean := False;
Specifies whether to write at messages (denoted by @@@) into the
destination file. The default, False, is not to write them.
REFERENCES
procedure Copy
procedure Filter
procedure Summarize
type Profile.Msg_Kind
@node !Commands.Log.Flush
procedure Flush
(Response : Profile.Response_Profile := Profile.Get);
DESCRIPTION
Forces any buffered output into the log file.
This procedure forces all output from the buffer into the log file. This
procedure is useful when synchronizing interactive activities to make
certain that all buffered output has been displayed.
Note that this procedure need only be used when writing output to a text
file. Note also that, if the output file is currently displayed, you may
have to refresh the image of that file to see the flushed output.
To force all buffered output into the log file and save the file without
closing it, use the Save procedure.
PARAMETERS
Response : Profile.Response_Profile := Profile.Get;
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
REFERENCES
procedure Save
function Profile.Get
@node !Commands.Log.Image
function Image (Kind : Profile.Msg_Kind) return String;
DESCRIPTION
Returns the three-character prefix associated with the specified kind of log
message.
Environment commands produce various kinds of messages as they execute.
The various kinds of messages are represented by the enumerations of type
Profile.Msg_Kind. Each kind of message also can be referenced using the
three-character string prefix associated with it. The Image function
essentially "translates" enumerations of type Profile.Msg_Kind into the
corresponding string.
PARAMETERS
Kind : Profile.Msg_Kind;
Specifies the kind of log message.
return String;
Returns the three-character string prefix associated with the specified kind
of log message.
EXAMPLES
Assume that you want to know the three-character string prefix associated
with debugging messages. To find out, you can use the following command:
Io.Echo (Log.Image (Profile.Debug_Msg));
As a result, the desired prefix is displayed in the message window:
???
REFERENCES
package Profile
type Profile.Msg_Kind
@node !Commands.Log.Name
subtype Name is String;
DESCRIPTION
Defines a name for a log file.
Strings of this type can use all of the special names, wildcards, context
prefixes, and attributes that are defined for naming objects in the
Environment. Strings of this type, however, must be unambiguous; each can
resolve only to a single object. See Parameter-Value Conventions in the
Reference Summary (RS) book for more information about naming objects.
REFERENCES
Reference Summary (RS), Parameter-Value Conventions
@node !Commands.Log.Pop_Error
procedure Pop_Error renames Io.Pop_Error;
DESCRIPTION
Pops the current-error file off the stack of error files.
This procedure pops the current value of Current_Error off the stack of
error files. The current-error file is not closed and will not be closed
automatically at the end of the job (only files still on the stack are
closed at the end of the job). Thus, the current-error file can be used
again with another Set_Error procedure.
The top of the stack and Current_Error are reset to be the previous file on
the stack.
To close the current-error file and pop it off the stack, use the
Reset_Error procedure.
To push a file onto the stack of error files, use the Set_Error procedure or
the Io.Set_Error procedure. Note that the Log.Set_Error and Io.Set_Error
procedures are not identical. See Set_Error for details.
For more information about the stack mechanism for managing I/O files, see
the introduction to this package.
REFERENCES
procedure Reset_Error
procedure Set_Error
Text Input/Output (TIO), procedure Io.Pop_Error
@node !Commands.Log.Pop_Input
procedure Pop_Input renames Io.Pop_Input;
DESCRIPTION
Pops the current-input file off the stack of input files.
This procedure pops the current value of Current_Input off the stack of
input files. The current-input file is not closed and will not be closed
automatically at the end of the job (only files still on the stack are
closed at the end of the job). Thus, the current-input file can be used
again with another Set_Input procedure.
The top of the stack and Current_Input are reset to be the previous file on
the stack.
To close the current-input file and pop it off the stack, use the
Reset_Input procedure.
To push a file onto the stack of input files, use the Set_Input procedure.
For more information about the stack mechanism for managing I/O files, see
the introduction to this package.
REFERENCES
procedure Reset_Input
procedure Set_Input
Text Input/Output (TIO), procedure Io.Pop_Input
@node !Commands.Log.Pop_Output
procedure Pop_Output renames Io.Pop_Output;
DESCRIPTION
Pops the current-output file off the stack of output files.
This procedure pops the current value of Current_Output off the stack of
output files. The current-output file is not closed and will not be closed
automatically at the end of the job (only files still on the stack are
closed at the end of the job). Thus, the current-output file can be used
again with another Set_Output procedure.
The top of the stack and Current_Output are reset to be the previous file
on the stack.
To close the current output file and pop it off the stack, use the
Reset_Output procedure.
To push a file onto the stack of error files, use the Set_Output procedure
or the Io.Set_Output procedure. Note that the Log.Set_Output and
Io.Set_Output procedures are not identical. See Set_Output for details.
For more information about the stack mechanism for managing I/O files, see
the introduction to this package.
REFERENCES
procedure Reset_Output
procedure Set_Output
Text Input/Output (TIO), procedure Io.Pop_Output
Text Input/Output (TIO), procedure Io.Set_Output
@node !Commands.Log.Put_Condition
procedure Put_Condition
(Status : Simple_Status.Condition;
Response : Profile.Response_Profile := Profile.Get);
DESCRIPTION
Converts the value of the Status parameter to a textual representation
and writes it into the log file.
Many commands in the Environment return a value of type
!Tools.Simple_Status.Condition as an indication of whether the operation
succeeded or failed. This procedure enables the user to write the results
returned by a Status parameter into the log file for the current job.
PARAMETERS
Status : Simple_Status.Condition;
Specifies the status value that is to be written into the log file.
Response : Profile.Response_Profile := Profile.Get;
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
REFERENCES
function Profile.Get
Programming Tools (PT), package Simple_Status
@node !Commands.Log.Put_Errors
procedure Put_Errors
(Errors : Error_Messages.Errors;
Response : Profile.Response_Profile := Profile.Get);
DESCRIPTION
Enters the specified error messages into the log file.
PARAMETERS
Errors : Error_Messages.Errors;
Specifies the error messages to be entered into the log file.
Response : Profile.Response_Profile := Profile.Get;
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
REFERENCES
package Profile
function Profile.Get
@node !Commands.Log.Put_Job_Messages
procedure Put_Job_Messages
(For_Job : Machine.Job_Id;
Response : Profile.Response_Profile := Profile.Get);
DESCRIPTION
Formats and writes the contents of the system message log for the specified
job into the log file for the current job.
To write the contents of the system message log for the current job into
the log file, use the Put_System_Messages procedure.
PARAMETERS
For_Job : Machine.Job_Id;
Specifies the job number for the job whose messages are to be displayed.
Response : Profile.Response_Profile := Profile.Get;
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
REFERENCES
procedure Put_System_Messages
function Profile.Get
@node !Commands.Log.Put_Line
procedure Put_Line
(Message : String;
Kind : Profile.Msg_Kind := Profile.Note_Msg;
Response : Profile.Response_Profile := Profile.Get);
DESCRIPTION
Writes the specified message into the log file for the current job.
This procedure allows additional messages (beyond those written by the
Environment) to be placed in the log file. These additional messages can
indicate progress within a sequence of commands or status information
about the job.
By default, the specified message is entered into the log as a general note
message (denoted by the "---" prefix). You can use the Kind parameter to
specify a different kind of message. Note that messages specified by the
Put_Line procedure are subject to the filter specified as part of the
Response parameter. Consequently, if you define the message to be a warning
message and the Response parameter causes warning messages to be filtered
out of the log, then the message specified by this procedure is also
filtered out.
If the specified message is to be written into the log, it is formatted
using the log prefixes and line width specified as part of the Response
parameter.
PARAMETERS
Message : String;
Specifies the message to be placed in the log file.
Kind : Profile.Msg_Kind := Profile.Note_Msg;
Specifies the kind of message to be placed into the log file. The default is
a general note message (denoted by the "---" prefix). For a list of the
values accepted by this parameter, see type Profile.Msg_Kind.
Response : Profile.Response_Profile := Profile.Get;
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
REFERENCES
procedure Put_Line
generic procedure Put_Line_Generic
type Profile.Msg_Kind
@node !Commands.Log.Put_Line
procedure Put_Line
(Object1 : Directory.Object;
Message : String := "";
Object2 : Directory.Object := Directory.Nil;
Kind : Profile.Msg_Kind := Profile.Note_Msg;
Response : Profile.Response_Profile := Profile.Get);
procedure Put_Line
(Object1 : Directory.Version;
Message : String := "";
Object2 : Directory.Version := Directory.Nil;
Kind : Profile.Msg_Kind := Profile.Note_Msg;
Response : Profile.Response_Profile := Profile.Get);
procedure Put_Line
(Object1 : Diana.Tree;
Message : String := "";
Object2 : Diana.Tree := Diana.Empty;
Kind : Profile.Msg_Kind := Profile.Note_Msg;
Response : Profile.Response_Profile := Profile.Get);
DESCRIPTION
Writes the specified message into the log file; the message can reference up
to two Environment objects.
By default, the specified message is written into the log as a general note
message (denoted by the "---" prefix). You can use the Kind parameter to
specify a different kind of message. Note that messages specified by the
Put_Line procedure are subject to the filter specified as part of the
Response parameter. Consequently, if you define the message to be a warning
message and the Response parameter causes warning messages to be filtered
out of the log, then the message specified by this procedure is also
filtered out.
If the message is accepted into the log, the names of the specified objects
are computed and inserted into the message text. You can embed the
following symbols in the message text to specify how the names are to be
computed and where they are to be inserted:
* To request names computed by the Directory.Naming.Unique_Full_Name
function, use <1> and <2> to indicate where to insert the names for
Object1 and Object2, respectively.
* To request names computed by the Directory.Naming.Get_Simple_Name func-
tion, use <<1>> and <<2>> to indicate where to insert the names for
Object1 and Object2, respectively.
If either Object1 or Object2 resolves to nil, its corresponding symbol in
the message text is replaced by the null string. If none of the symbols
listed above appear in the message text, then the object names are
computed using the Directory.Naming.Unique_Full_Name function, and the
names for Object1 and Object2 appear at the beginning and end of the
message, respectively.
These three Put_Line procedures provide a more convenient and efficient
alternative to the first Put_Line procedure in this package. The first
Put_Line procedure has no special parameters for object names, so that
object names can be specified only as literal text in the message string.
This means that object names must be computed in advance as part of your
application, whether or not the message ever needs to be produced. In
contrast, the three Put_Line procedures documented here compute the object
names for you (so your application does not have to compute them).
Furthermore, the object names are computed only when the message is
actually required.
PARAMETERS
Object1 : Directory.Object;
Object1 : Directory.Version;
Object1 : Diana.Tree;
Specifies the first object whose name is to appear in the message.
Message : String := "";
Specifies the text of the message to be entered into the log. The text can
contain the special symbols <1>, <2>, <<1>>, or <<2>> to position the
names of the first and second objects within the message and to determine
the method of computing these names.
Object2 : Directory.Object := Directory.Nil;
Object2 : Directory.Version := Directory.Nil;
Object2 : Diana.Tree := Diana.Empty;
Specifies the second object whose name is to appear in the message.
Kind : Profile.Msg_Kind := Profile.Note_Msg;
Specifies the kind of message to be placed into the log file. The default is
a general note message (denoted by the "---" prefix). For a list of the
values accepted by this parameter, see the Profile.Msg_Kind type.
Response : Profile.Response_Profile := Profile.Get;
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
REFERENCES
procedure Put_Line
generic procedure Put_Line_Generic
type Profile.Msg_Kind
@node !Commands.Log.Put_Line_Generic
generic
type Object_Type is private;
with function Full (Object : Object_Type) return String;
with function Simple (Object : Object_Type) return String;
with function Is_Nil (Object : Object_Type) return Boolean;
with function Nil return Object_Type;
procedure Put_Line_Generic
(Object1 : Object_Type;
Message : String := "";
Object2 : Object_Type := Nil;
Kind : Profile.Msg_Kind := Profile.Note_Msg;
Response : Profile.Response_Profile := Profile.Get);
DESCRIPTION
Writes the specified message into the log file; the message can reference up
to two objects of the specified Object_Type.
By default, the specified message is written into the log as a general note
message (denoted by the "---" prefix). You can use the Kind parameter to
specify a different kind of message. Note that messages specified by the
Put_Line_Generic procedure are subject to the filter specified in the
Response parameter. Consequently, if you define the message to be a warning
message and the current response parameter causes warning messages to be
filtered out of the log, then the message specified by this procedure is
also filtered out.
If the message is accepted into the log, the names of the specified objects
are computed and inserted into the message text. You can embed the
following symbols in the message text to specify how the names are to be
computed and where they are to be inserted:
* To request names computed by the Full function, use <1> and <2> to
indicate where to insert the names for Object1 and Object2,
respectively.
* To request names computed by the Simple function, use <<1>> and <<2>>
to indicate where to insert the names for Object1 and Object2,
respectively.
If the Is_Nil function returns True for either Object1 or Object2, the
corresponding symbol in the message text is replaced by the null string
and neither the Full function nor the Simple function is called.
If the Is_Nil function returns False but no symbols appear in the message
text to indicate the form or location of the object names, the names for
Object1 and Object2 are computed using the Full function; these names
appear at the beginning and end of the message, respectively.
PARAMETERS
Object1 : Object_Type;
Specifies the first object whose name is to appear in the message.
Message : String := "";
Specifies the text of the message to be entered into the log. The text can
contain the special symbols <1>, <2>, <<1>>, or <<2>> to position the
names of the first and second objects within the message and to determine
the method of computing these names.
Object2 : Object_Type := Nil;
Specifies the second object whose name is to appear in the message.
Kind : Profile.Msg_Kind := Profile.Note_Msg;
Specifies the kind of message to be placed into the log file. The default is
a general note message (denoted by the "---" prefix). For a list of the
values accepted by this parameter, see the Profile.Msg_Kind type.
Response : Profile.Response_Profile := Profile.Get;
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
REFERENCES
generic formal function Put_Line_Generic.Full
generic formal function Put_Line_Generic.Is_Nil
generic formal function Put_Line_Generic.Nil
generic formal type Put_Line_Generic.Object_Type
generic formal function Put_Line_Generic.Simple
@node !Commands.Log.Put_Line_Generic.Full
function Full (Object : Object_Type) return String;
DESCRIPTION
Returns the fully qualified pathname of the specified object.
This function is used by generic procedure Put_Line_Generic to obtain
the fully qualified pathname of the object named in the Object1 or
Object2 parameters. The name returned by this function is inserted into
the message at the location indicated by the <1> or <2> symbols for the
names for Object1 and Object2, respectively.
If the Is_Nil function returns True for either Object1 or Object2, the
corresponding symbol in the message text is replaced by the null string
and the Full function is not called.
If the Is_Nil function returns False but no symbols appear in the message
text to indicate the form or location of the object names, the names for
Object1 and Object 2 are computed by the Full function; these names
appear at the beginning and end of the message, respectively.
PARAMETERS
Object : Object_Type
Specifies the object for which to return the fully qualified pathname.
return String;
Returns the fully qualified pathname of the object.
REFERENCES
generic procedure Put_Line_Generic
generic formal function Put_Line_Generic.Simple
@node !Commands.Log.Put_Line_Generic.Is_Nil
function Is_Nil (Object : Object_Type) return Boolean;
DESCRIPTION
Returns a Boolean value indicating whether or not the specified value is
the null string.
This function is used by generic procedure Put_Line_Generic to determine
whether the value for the Object1 or Object2 parameter is null:
* If this function returns True for either Object1 or Object2, the
corresponding symbol in the message text is replaced by the null string
and neither the Full function nor the Simple function is called.
* If this function returns False for either Object1 or Object2, the
corresponding symbol in the message text is replaced by the full or
simple name of the object (that is, the name returned by the Full
function or the Simple function, as indicated by the replaced
symbol).
However, if no symbols appear in the message text to indicate the form
or location of the object names, the names for Object1 and Object2
are computed using the Full function; these names appear at the
beginning and end of the message, respectively.
For further information about inserting object names into the message, see
generic procedure Put_Line_Generic.
PARAMETERS
Object : Object_Type
Specifies the value to be checked for the null string.
return Boolean;
Returns True if the value of the parameter is the null string; otherwise,
this function returns False.
REFERENCES
generic procedure Put_Line_Generic
generic formal function Put_Line_Generic.Nil
@node !Commands.Log.Put_Line_Generic.Nil
function Nil return Object_Type;
DESCRIPTION
Returns a value of type Object_Type that corresponds to the null string.
This function is used by generic procedure Put_Line_Generic as the default
value for the Object2 parameter. The Nil function returns a value of type
Object_Type that is equivalent to the null string. When this function
appears as the value of a parameter of type Object_Type, the Is_Nil
function returns True for that parameter.
PARAMETERS
return Object_Type;
Returns a value of type Object_Type that corresponds to the null string.
REFERENCES
generic formal function Is_Nil
generic procedure Put_Line_Generic
@node !Commands.Log.Put_Line_Generic.Object_Type
type Object_Type is Private;
DESCRIPTION
Defines a type of object.
Parameter values of this type are used by generic procedure
Put_Line_Generic to supply object names to be inserted into the message.
@node !Commands.Log.Put_Line_Generic.Simple
function Simple (Object : Object_Type) return String;
DESCRIPTION
Returns the simple name of the specified object.
This function is used by generic procedure Put_Line_Generic to obtain the
simple name of the object named in the Object1 or Object2 parameters. The
simple name of an object is the rightmost name component. The name
returned by this function is inserted into the message at the location
indicated by the <<1>> or <<2>> symbols (for the names for Object1 and
Object2, respectively).
If the Is_Nil function returns True for either Object1 or Object2, the
corresponding symbol in the message text is replaced by the null string
and the Simple function is not called.
If the Is_Nil function returns False but no symbols appear in the message
text to indicate the form or location of the object names, the names for
Object1 and Object2 are computed using the Full function; these names
appear at the beginning and end of the message, respectively.
PARAMETERS
Object : Object_Type
Specifies the object for which to return the simple name.
return String;
Returns the fully qualified pathname of the object.
REFERENCES
generic formal function Full
generic procedure Put_Line_Generic
@node !Commands.Log.Put_System_Messages
procedure Put_System_Messages
(Response : Profile.Response_Profile := Profile.Get);
DESCRIPTION
Formats and writes the contents of the system message log for the current
job into the log file for the current job.
To write the contents of the system message log for a specified job into
the log file, use the Put_Job_Messages procedure.
PARAMETERS
Response : Profile.Response_Profile := Profile.Get;
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
REFERENCES
procedure Put_Job_Messages
function Profile.Get
@node !Commands.Log.Reset_Error
procedure Reset_Error renames Io.Reset_Error;
DESCRIPTION
Closes the current-error file and pops it off the stack of error files.
This procedure pops the current value of Current_Error off the stack of
error files. The current-error file is also closed; thus, it cannot be used
again with another Set_Error procedure.
The top of the stack and Current_Error are reset to be the previous error
file on the stack.
To pop the current-error file off the stack without closing it, use the
Pop_Error procedure.
To push a file onto the stack of error files, use the Set_Error procedure or
the Io.Set_Error procedure. Note that the Log.Set_Error and Io.Set_Error
procedures are not identical. See the Set_Error procedure for details.
For further information about the stack mechanism for managing I/O files,
see the introduction to this package.
REFERENCES
procedure Pop_Error
procedure Set_Error
Text Input/Output (TIO), procedure Io.Reset_Error
@node !Commands.Log.Reset_Input
procedure Reset_Input renames Io.Reset_Input;
DESCRIPTION
Closes the current-input file and pops it off the stack of input files.
This procedure pops the current value of Current_Input off the stack of
input files. The current-input file is also closed; thus, it cannot be used
again with another Set_Input procedure.
The top of the stack and Current_Input are reset to be the previous input
file on the stack.
To pop the current-input file off the stack without closing it, use the
Pop_Input procedure.
To push a file onto the stack of input files, use the Set_Input procedure.
For further information about the stack mechanism for managing I/O files,
see the introduction to this package.
REFERENCES
procedure Pop_Input
procedure Set_Input
Text Input/Output (TIO), procedure Io.Reset_Input
@node !Commands.Log.Reset_Log
procedure Reset_Log
(Filter : Profile.Log_Filter := Profile.Filter);
DESCRIPTION
Closes the current-output file, pops it off the stack of output files, and
sets the log filter to the specified value.
Note: This procedure is the same as the Reset_Output procedure, except
that this procedure also sets the log filter.
This procedure pops the current value of Current_Output off the stack of
output files. The current-output file is also closed; thus, it cannot be
used again with another Set_Output procedure.
The top of the stack and Current_Output are reset to be the previous
output file on the stack.
This procedure also sets the log-filter component of the job response
profile to be the specified filter. The default is the filter specified in the
job response profile for the current job.
To set the current-output file and the filter, use the Set_Log procedure.
For further information about the stack mechanism used to manage I/O files,
see the introduction to this package. For further information about
profiles and profile components, see package Profile.
PARAMETERS
Filter : Profile.Log_Filter := Profile.Filter;
Specifies the value to which to set the filter component of the job response
profile. The default is the filter specified in the job response profile for
the current job.
REFERENCES
procedure Reset_Output
procedure Set_Log
package Profile
@node !Commands.Log.Reset_Output
procedure Reset_Output renames Io.Reset_Output;
DESCRIPTION
Closes the current-output file and pops it off the stack of output files.
Note: This procedure is the same as the Reset_Log procedure, except that
the Reset_Log procedure also sets the log-filter component in the job
response profile for the current job.
This procedure pops the current value of Current_Output off the stack of
output files. The current-output file is also closed; thus, it cannot be
used again with another Set_Output procedure.
The top of the stack and Current_Output are reset to be the previous
output file on the stack.
To pop the current-output file off the stack without closing it, use the
Pop_Output procedure.
To push a file onto the stack of output files, use the Set_Output procedure
or the Io.Set_Output procedure. Note that the Log.Set_Output and
Io.Set_Output procedures are not identical. See the Set_Output procedure
for details.
For further information about the stack mechanism for managing I/O files,
see the introduction to this package.
REFERENCES
procedure Pop_Output
procedure Set_Output
Text Input/Output (TIO), procedure Io.Reset_Output
Text Input/Output (TIO), procedure Io.Set_Output
@node !Commands.Log.Save
procedure Save
(Response: Profile.Response_Profile := Profile.Get);
DESCRIPTION
Forces any buffered output into the log file and then makes the current
contents of the log file permanent.
A log file does not become permanent until it is saved or closed. This
procedure first flushes all buffered output into the file and then commits
the log file without closing it.
This procedure should not be used to save log files written to
Standard_Output (an Environment output window).
PARAMETERS
Response : Profile.Response_Profile := Profile.Get;
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
REFERENCES
procedure Flush
function Profile.Get
@node !Commands.Log.Set_Error
procedure Set_Error (To_Be : Name := ">>FILE NAME<<");
DESCRIPTION
Sets the current-error file to be the specified file and pushes that file onto
the stack of error files. This procedure sets the value of Current_Error to
be the specified file. Any previous values of error files are pushed onto
the stack of error files. This is the same stack of error files that is
managed by commands in package Io.
This procedure also sets the log-file component of the job response profile
for the current job to Use_Error so that output will be sent to
Current_Error, as determined by this procedure. Thus, this procedure
differs from Io.Set_Error, which sets Current_Error but does not change
the log-file component of the job response profile.
To pop the current-error file off the stack, use the Pop_Error or
Reset_Error procedure.
For further information about the stack mechanism for managing I/O files,
see the introduction to this package.
PARAMETERS
To_Be : Name := ">>FILE NAME<<";
Specifies the file to which Current_Error is to be set. The default
parameter placeholder ">>FILE NAME<<" must be replaced or an error will
result.
REFERENCES
procedure Pop_Error
procedure Reset_Error
Text Input/Output (TIO), procedure Io.Set_Error
@node !Commands.Log.Set_Input
procedure Set_Input (To_Be : Name := "<REGION>")
renames Io.Set_Input;
DESCRIPTION
Sets the current-input file to be the specified file and pushes that file onto
the stack of input files.
This procedure sets the value of Current_Input to be the specified file. Any
previous values of input files are pushed onto the stack of input files.
This is the same stack of input files that is managed by commands in
package Io.
To pop the current-error file off the stack, use the Pop_Input or
Reset_Input procedure.
For further information about the stack mechanism for managing I/O files,
see the introduction to this package.
PARAMETERS
To_Be : Name := "<REGION>";
Specifies the file to which Current_Input is to be set. The default is the
object in the currently selected region.
REFERENCES
procedure Pop_Input
procedure Reset_Input
Text Input/Output (TIO), procedure Io.Set_Input
@node !Commands.Log.Set_Log
procedure Set_Log (To_Be : Name := ">>FILE NAME<<";
Filter : Profile.Log_Filter := Profile.Filter);
DESCRIPTION
Sets the current-output file to the specified file, pushes that file onto the
stack of output files, and sets the filter to the specified value.
Note: This procedure is the same as the Set_Output procedure, except that
this procedure also sets the log filter.
This procedure sets the value of Current_Output to be the specified file.
This value and any previous values of output files are pushed onto the
stack of output files. This is the same stack of output files that is
managed by the Set_Output procedure and commands in package Io.
This procedure also sets the log-filter component of the job response
profile to be the specified filter. The default is the filter specified in the
job response profile for the current job.
Finally, this procedure sets the log-file component of the job response
profile for the current job to Use_Output so that output will be sent to
Current_Output, as determined by this procedure. Thus, this procedure
differs from Io.Set_Output, which sets Current_Output but does not change
the log-file or log-filter components of the job response profile.
To pop the current-output file off the stack and set the filter component of
the job response profile, use the Reset_Log procedure.
For further information about the stack mechanism used to manage I/O files,
see the introduction to this package. For further information about
profiles and profile components, see package Profile.
PARAMETERS
To_Be : Name := ">>FILE NAME<<";
Specifies the file to which Current_Output is to be set. The default
parameter placeholder ">>FILE NAME<<" must be replaced or an error will
result.
Filter : Profile.Log_Filter := Profile.Filter;
Specifies the value to which to set the filter component of the job response
profile. The default is the filter specified in the job response profile for
the current job.
REFERENCES
procedure Reset_Log
procedure Set_Output
package Profile
@node !Commands.Log.Set_Output
procedure Set_Output (To_Be : Name := ">>FILE NAME<<");
DESCRIPTION
Sets the current-output file to be the specified file and pushes that file
onto the stack of output files.
Note: This procedure is the same as the Set_Log procedure, except that the
Set_Log procedure also sets the log-filter component in the job response
profile for the current job.
This procedure sets the value of Current_Output to be the specified file.
Any previous values of output files are pushed onto the stack of output
files. This is the same stack of output files that is managed by the Set_Log
procedure and commands in package Io.
This procedure also sets the log-file component of the job response profile
for the current job to Use_Output so that output will be sent to
Current_Output, as determined by this procedure. Thus, this procedure
differs from Io.Set_Output, which sets Current_Output but does not change
the log-file component of the job response profile.
To pop the current-output file off the stack, use the Pop_Output or
Reset_Output procedure.
For further information about the stack mechanism for managing I/O files,
see the introduction to this package.
PARAMETERS
To_Be : Name := ">>FILE NAME<<";
Specifies the file to which Current_Output is to be set. The default
parameter placeholder ">>FILE NAME<<" must be replaced or an error will
result.
REFERENCES
procedure Pop_Output
procedure Reset_Output
Text Input/Output (TIO), procedure Io.Set_Output
@node !Commands.Log.Summarize
procedure Summarize
(Log_File : Name := "<IMAGE>";
Destination : Name := "";
Auxiliaries : Boolean := True;
Diagnostics : Boolean := True;
Notes : Boolean := False;
Positives : Boolean := True;
Negatives : Boolean := True;
Positions : Boolean := False;
Warnings : Boolean := False;
Errors : Boolean := False;
Exceptions : Boolean := False;
Sharps : Boolean := False;
Dollars : Boolean := False;
Ats : Boolean := False) renames Filter;
DESCRIPTION
Filters the specified log file based on the specified parameters and then
writes the result into the specified destination.
This procedure both copies the log from one file into another and filters
the log messages in the process. Only those message kinds for which the
value is True are included in the new log file. By default, only auxiliary
(:::), diagnostic (???), positive (+++), and negative (++*) messages are
included in the new log file.
The new log file is written into the location specified in the Destination
parameter. By default, the new log file is sent to Current_Output, which
is, by default, an Environment output window.
This procedure renames the Filter procedure. The Filter_Errors procedure
also renames the Filter procedure, using different default parameter
values. To copy a log and filter its contents in the process, you can also
use the Copy procedure. Whereas the Summarize procedure allows you to
specify a Boolean value for each message kind, the Copy procedure allows
you to specify an existing filter.
PARAMETERS
Log_File : Name := "<IMAGE>";
Specifies the log file to be copied and filtered. The default is the log file
in the current image.
Destination : Name := "";
Specifies the destination for the new log file. The default (the null
string) sends the log file to Current_Output, which is, by default, an
Environment output window.
Auxiliaries : Boolean := True;
Specifies whether to write auxiliary messages (denoted by :::) into the
destination file. The default, True, is to write them.
Diagnostics : Boolean := True;
Specifies whether to write diagnostic or debug messages (denoted by ???)
into the destination file. The default, True, is to write them.
Notes : Boolean := False;
Specifies whether to write note messages (denoted by ---) into the
destination file. The default, False, is not to write them.
Positives : Boolean := True;
Specifies whether to write positive messages (denoted by +++) into the
destination file. The default, True, is to write them.
Negatives : Boolean := True;
Specifies whether to write negative messages (denoted by ++*) into the
destination file. The default, True, is to write them.
Positions : Boolean := False;
Specifies whether to write position messages (denoted by >>>) into the
destination file. The default, False, is not to write them.
Warnings : Boolean := False;
Specifies whether to write warning messages (denoted by !!!) into the
destination file. The default, False, is not to write them.
Errors : Boolean := False;
Specifies whether to write error messages (denoted by ***) into the
destination file. The default, False, is not to write them.
Exceptions : Boolean := False;
Specifies whether to write exception messages (denoted by %%%) into the
destination file. The default, False, is not to write them.
Sharps : Boolean := False;
Specifies whether to write sharp messages (denoted by ###) into the
destination file. The default, False, is not to write them.
Dollars : Boolean := False;
Specifies whether to write dollar messages (denoted by $$$) into the
destination file. The default, False, is not to write them.
Ats : Boolean := False;
Specifies whether to write at messages (denoted by @@@) into the
destination file. The default, False, is not to write them.
REFERENCES
procedure Copy
procedure Filter
procedure Filter_Errors
type Profile.Msg_Kind
@node !Tools.Profile
Package Profile contains procedures and functions for programmatically
manipulating job response profiles, session response profiles, and the
system default profile. These profiles can be used by both
Environment-defined and user-defined commands to determine how to
respond to errors, how to generate error logs, and which activity,
remote-passwords file, and remote-sessions file to use. Using
facilities from this package, you can set, modify, and query for
information about profiles.
For further information about controlling job behavior, including how to
specify the response characteristics to be used by a particular command
and how to interactively set values in session and job response profiles,
see Chapter 2, "Job Characteristics and Behavior."
RESOURCES IN PACKAGE PROFILE
The commands in package Profile fall into several functional groups. This
list includes procedures and functions.
Setting a session response profile:
Include_In_Default Set_Default
Set_Default_Activity Set_Default_Filter
Set_Default_Log_File Set_Default_Prefixes
Set_Default_Reaction Set_Default_Remote_Passwords
Set_Default_Remote_Sessions Set_Default_Response
Set_Default_Width
Setting a job response profile:
Include Set
Set_Activity Set_Filter
Set_Log_File Set_Prefixes
Set_Reaction Set_Remote_Passwords
Set_Remote_Sessions Set_Response
Set_Width
Obtaining values from job and session response profiles:
Activity Default_Activity
Default_Remote_Passwords Default_Remote_Sessions
Filter Get
Get_Default Includes
Log_File Persevere
Propagate Reaction
Remote_Passwords Remote_Sessions
Width
Representing and obtaining the system default profile:
Default_Filter Default_Log_File
Default_Prefixes Default_Profile
Default_Reaction Default_Width
Converting between profile representations:
Convert Image
Value
Building profiles for use in parameters:
Ignore Nil
Raise_Exception Response
Verbose Warn
This package also contains predefined filters (constants) for use in
parameters:
Errors Full
Quiet Summary
Terse
INTRODUCTION TO PROFILES
Commands obtain certain information required for execution from their
response characteristics. In particular, a command's response
characteristics tell it:
* How to respond to errors
* Where to generate the logs that summarize command behavior
* How to filter and format the messages that are recorded in these logs
* Where to find the activity to use (when executing commands that compile
and/or load programs written in subsystems)
* Where to find the remote-passwords file and remote-sessions file to use
when executing commands on remote systems
When a command executes, it can be instructed to take its response
characteristics from a prepackaged set of characteristics called a
response profile.
Commands can be "hard-coded" to take their response characteristics from a
particular profile so that they always use the same characteristics. For
example, servers often include instructions to write all log messages into
a particular file.
Commands also can obtain their response characteristics from a Response
parameter. Response parameters allow the user executing the command to
specify the particular set of response characteristics or to specify a
profile from which to take the response characteristics. This enables each
user to tailor the command's behavior to his or her needs.
This section contains information about:
* Response profile components
* Environment-defined response profiles
* User-defined response profiles
The remainder of this package introduction contains information about:
* Response profiles and Environment commands
* Response profiles and user-defined commands
* Setting the job response profile for the current job
* Setting the session response profile for the current session
* Obtaining profiles and profile components
* Building and using your own profiles
* Converting between profile representations
For information about using the Response parameter to specify response
characteristics to Environment-defined commands, see Parameter-Value
Conventions in the Reference Summary (RS) book.
Response-Profile Components
Response profiles are stored by the Environment as an aggregate of
component values. These component values represent each of the response
characteristics that can be set for commands (see Table 1).
Table 1 Response-Profile Components
------------------------------------------------
| | |
|Component| Description |
| | |
------------------------------------------------
| | |
|Error |Specifies (1) whether the job should |
|reaction |persevere or quit and (2) whether or |
| |not the job should propagate errors. |
| |Error reactions are enumerations of |
| |type Error_Reaction. |
------------------------------------------------
| | |
|Log |Specifies the kinds of messages that |
|filter |will be reported in or filtered from a|
| |job's output log. Message kinds are |
| |enumerations of type Msg_Kind. |
------------------------------------------------
| | |
|Log |Specifies whether messages are pre- |
|prefixes |fixed with the time, date, and/or kind|
| |of message. Log prefixes are enumera- |
| |tions of type Log_Prefix. |
------------------------------------------------
| | |
|Log |Specifies the width of the log |
|width |display--that is, the maximum number |
| |of characters in a message line. This |
| |value is a positive integer. |
-------- ---------------------------------------
| | |
|Log file |Specifies whether the log output is |
| |displayed in an output window or in |
| |the message window, or whether it can |
| |be directed to a file. The locations |
| |to which logs can be directed are |
| |enumerations of type Log_Output_File. |
------------------------------------------------
| | |
|Activity |Specifies the name of the activity to |
| |be used when programs written in |
| |subsystems are executed. For |
| |information about activities, see the |
| |Project Management (PM) book. |
------------------------------------------------
| | |
|Remote |Specifies the name of the |
|passwords|remote-passwords file, used in |
| |networking operations. For information|
| |about remote-passwords files, see |
| |package Remote_Passwords in this book.|
------------------------------------------------
| | |
|Remote |Specifies the name of the |
|sessions |remote-sessions file, used in |
| |networking operations. See type |
| |Remote_Sessions_Type in this package. |
------------------------------------------------
Environment-Defined Response Profiles
Basic Response Profiles
The Environment provides three basic response profiles from which a command
can take its response characteristics:
* The system default profile, which is provided by the Environment for
general use.
* The session response profile, which is available to any command
executing in a given session. Every session has a session response
profile associated with it, whether or not you explicitly set one. The
components of the session response profile are reflected in session
switches with the prefix "Profile."
* The job response profile, which is available to any command executing in
the current job. A job response profile is associated with every job,
whether or not you explicitly set one.
The component values of each of these response profiles initially are set
by the Environment. Specifically:
* The values of the system default profile are copied into the session
response profile for your default session, S_1.
* The values of the session response profile for S_1 are copied into the
session response profiles for subsequent sessions.
* The values of the session response profile for any session are copied
into the job response profile for jobs run under that session.
This cascading initialization is depicted in Figure 1.
---------------
| |
| SYSTEM |
| DEFAULT |
| PROFILE |
| |
| --------------- ---------------
| | | | |
| | SESSION | | SESSION |
\ -------| RESPONSE | | RESPONSE |
\ | PROFILE | -------> | PROFILES |
\ | FOR S_1 | | FOR OTHER |
\ | | | SESSIONS |
\ | --------------- | ---------------
\ | | | | | |
\ -------| JOB | -------| JOB |
\ | RESPONSE | | RESPONSE |
\ | PROFILE(S) | | PROFILE(S) |
\ | | | |
\ | | | |
\ | | | |
V | | | |
--------------- ---------------
Figure 1 The Three Basic Response Profiles
By default, Environment commands use the response characteristics specified
in the job response profile for the job in which the command is executing.
Because the job response profile gets its initial values from the session
response profile for the current session, Environment commands are subject
to the default characteristics you set in the session response profile.
Thus:
* Setting session switches with the prefix "Profile" allows you to
establish default behavior for commands executed under that session.
* Setting the job response profile (by calling commands from packages
Activity, Log, or Profile as part of the job) allows you to override
session default behavior for the duration of the job. This is
especially useful when you want to change the behavior of several
commands that are part of the same job.
You can specify the special values listed in Table 2 to any command that
accepts the string representation of a profile. In particular, you can
specify these values to the Response parameter of Environment and
user-defined commands to cause the commands to take their response
characteristics from one of the basic profiles. You also can specify these
values to commands in this package that set, obtain values from, and
convert profiles.
Table 2 Special Values for Specifying Basic Profiles
-----------------------------------------------------
| | |
|Special Value| Description |
| | |
-----------------------------------------------------
| | |
|"<PROFILE>" |Specifies the job response profile for |
| |the current job. Keep in mind that a |
| |job is any set of commands that are |
| |executed together. For example, |
| |executing multiple commands in a single|
| |command window constitutes a single |
| |job. |
-----------------------------------------------------
| | |
|"<SESSION>" |Specifies the session response profile |
| |for the current session. |
| | |
-----------------------------------------------------
| | |
|"<DEFAULT>" |Specifies the system default profile. |
| | |
| | |
-----------------------------------------------------
Special-Purpose Profiles
In addition to the three basic response profiles, the Environment provides
a number of special-purpose profiles from which commands can take their
response characteristics. The component values of these profiles are preset
to:
* Specify the kinds of log messages commands using the job response
profile can send to the log file
* Specify how commands using the job response profile will respond to
errors
You can specify the special values listed in Table 3 to any command that
accepts the string representation of a profile. In particular, you can
specify these values to the Response parameter of Environment and
user-defined commands to cause the commands to take their response
characteristics from one of the basic profiles. You also can specify these
values to commands in this package that set, obtain values from, and
convert profiles.
Table 3 Special Values for Special-Purpose Response Profiles
-----------------------------------------------
| | |
|Special Value | Response Characteristics |
-----------------------------------------------
| | |
|"<ERRORS>" |Logs only negative, error, and |
| |exception messages (++*, ***, |
| |%%%); perseveres at errors, |
| |without raising an exception; |
| |otherwise, same as job response |
| |profile. |
-----------------------------------------------
| | |
|"<IGNORE>" |Logs no messages; perseveres at |
| |errors, without raising an |
| |exception; otherwise, same as |
| |job response profile. |
-----------------------------------------------
| | |
|"<NIL>" |Logs no messages; quits at the |
| |first error, without raising an |
| |exception; uses no activity, |
| |remote-passwords, or remote- |
| |sessions file; ignores job and |
| |session response profiles. |
-----------------------------------------------
| | |
|"<PROGRESS>" |Logs only positive, negative, |
| |error, and exception messages |
| |(+++, ++*, ***, %%%); perseveres|
| |at errors, without raising an |
| |exception; otherwise, same as |
| |job response profile. |
-----------------------------------------------
| | |
|"<QUIET>" |Same as "<IGNORE>". |
-----------------------------------------------
| | |
|"<RAISE- |Raises an exception at the first|
| _EXCEPTION>"|error and quits immediately; |
| |otherwise, same as job response |
| |profile. (For package Archive |
| |commands, you should use the |
| |string "Raise_Error, <PROFILE>" |
| |instead to permit graceful |
| |termination after exception is |
| |raised.) |
-----------------------------------------------
| | |
|"<VERBOSE>" |Logs all messages except debug |
| |messages (???); otherwise, same |
| |as job response profile. |
-----------------------------------------------
| | |
|"<WARN>" |Logs only negative, warning, |
| |error, and exception messages |
| |(++*, !!!, ***, %%%); perseveres|
| |at errors, without raising an |
| |exception; otherwise, same as |
| |job response profile. |
-----------------------------------------------
Note that apart from message filtering and error reaction, these profiles
provide the same response characteristics as the current job response
profile. That is, you can think of the special values in Table 3 as being
variants of the "<PROFILE>" special value.
User-Defined Profiles
Occasionally, you may want your application to use a specific set of
response characteristics instead of taking its response characteristics
from the Environment-defined defaults.
For example, assume that you are creating a server that logs off idle
sessions after a preset amount of time. Also assume that you want this
server to use the response characteristics in the Environment's system
default profile for all characteristics except the log file. In
particular, you want the server to write the log to a text file with
the name of the server and the current date. In this case, you can
build a profile within your application and use that profile
throughout.
For information about how to do this, see "Building Your Own Profiles,"
page nn.
RESPONSE PROFILES AND ENVIRONMENT COMMANDS
By default, the response characteristics for Environment commands are
determined by the job response profile for the job in which the command is
executing. Because the job response profile gets its initial values from
the session response profile for the current session, Environment
commands are subject to the default response characteristics you set in
the session response profile.
Most Environment commands have a Response parameter through which you can
override the response characteristics set in the job response profile.
(Environment-defined commands that do not have a Response parameter always
use the response characteristics specified in the job response profile.)
For commands whose Response parameter accepts a string value, you can use
a special value such as "<PROFILE>", "<WARN>", or "<ERRORS>" to cause the
command to take its response characteristics from any Environment-defined
response profile. These special values are described in Tables 2 and 3,
page nn.
The Response parameters of some Environment commands accept values of type
Profile.Response_Profile rather than string values. In this case, you can
use one of several functions in this package to specify the profile from
which the command is to take its response characteristics. These functions
are described in "Obtaining a Complete Profile," page nn.
For further information about using the Response parameter of Environment-
defined commands, see Parameter-Value Conventions in the Reference Summary
(RS) book.
RESPONSE PROFILES AND USER-DEFINED COMMANDS
If you are creating a site-specific tool that will run on the R1000, you
may want it to behave like Environment commands. That is, you may want
your command to use different response characteristics based on the user
executing it. You can accomplish this by having your command use the basic
response profiles maintained by the Environment.
There are several guidelines for using response profiles in your commands:
* If you define your command to have a Response parameter:
- Define command behavior so that it uses the response characteristics
specified through this parameter. For example, when errors are
encountered, check the error reaction specified through the Response
parameter and ensure that your command behaves accordingly.
- Make sure that your command is not sensitive to the characteristics
defined in the job response profile for the calling job or any
"hard-coded" response characteristics.
* If your command calls any procedures or functions, make sure they use
appropriate response characteristics. In general, they should use the
same response characteristics as your command; however, you may want
them to use other response characteristics when:
- You want your command to heavily filter messages generated by subpro-
grams it calls so that users see only messages directly from your
command and errors from calls to other subprograms.
- You want subprograms called by your command to raise an exception if
they encounter errors so that you have more control over the error
and exception handling of those subprograms.
Note that you may not be able to change the response characteristics of
all the subprograms you call, especially if you call user-defined
commands that have "hard-coded" response characteristics.
* Do not permanently affect anything outside your command. If you modify
the job or session response profile from within your command, reset the
profile to the original value before your command completes.
Following these guidelines, there are basically two methods for using
response profiles in your commands. Both of these methods suggest that you
give your command a Response parameter. They differ, however, in that:
* Method I entails setting the job response profile to the value specified
through the Response parameter of your command and then resetting it
before returning to the calling job.
* Method II entails passing the value specified through the Response
parameter of your command to any other commands it calls, without
changing the job response profile.
These two methods are described in more detail in the following
subsections. Each method is followed by an example using the method in a
simple program. The example for method II is followed by sections that
provide more detailed information about the procedures and functions in
package Profile that you can use to set and obtain values from profiles.
Method I
One method for making your commands take their response characteristics
from a response profile is to set the job response profile for the current
job, use this profile to determine the response characteristics of your
command and any subprograms it calls, and then reset the job response
profile at the end of your command.
There are two advantages to changing the job response profile:
* Most Environment-defined commands with a Response parameter use the job
response profile by default. Thus, you do not have to change the value
specified to the Response parameter of subprograms called by your
command.
* Environment-defined commands that do not have a Response parameter
always use the job response profile. Changing the job response profile is
the only way to change the response characteristics for these commands.
Remember that the job response profile exists for the duration of the
entire job, not just a single command. For this reason, when using this
method, you must save the job response profile at the time your command was
called and reset it before returning to the calling job. Otherwise,
commands in the current job called after yours will be subject to the job
response profile you have set.
Instructions for Method I
The following instructions describe how to use method I in your
procedures. They are followed by a simple example.
1. Give your command a Response parameter that accepts a string value. The
recommended default value is "<PROFILE>", which copies the response
characteristics from the job response profile for the current job:
procedure Build_Training_Users
(First_User_Number : in Positive := 1;
Last_User_Number : in Positive;
Username_Prefix : in String := "Advanced";
Response : in String := "<PROFILE>") is
2. Save the job response profile for the calling job so that you can reset
it at the end of your command:
Old_Job_Profile : Profile.Response_Profile := Profile.Get;
3. Convert the value of the Response parameter to a variable of type
Profile.Response_Profile:
Current_Job_Profile : Profile.Response_Profile :=
Profile.Value (Response);
You may need this value if you call subprograms, such Profile.Set, that
accept values of type Profile.Response_Profile.
4. Set the job response profile to be the one specified in the Response
parameter of your command:
Profile.Set (Profile => Current_Job_Profile);
5. Make sure any subprograms called by your command use appropriate
response characteristics:
a. Usually you will want subprograms you call to use the same response
characteristics as your command. Because you have set the job
response profile to include the characteristics specified to your
command, subprograms called by your command should use the job
response profile, as indicated by the value "<PROFILE>" or
Profile.Get:
Log.Put_Line (Message => "Command has completed",
Kind => Profile.Auxiliary_Msg,
Response => Profile.Get);
Operator.Create_User (User => User_Name,
Password => User_Name,
Volume => 0,
Response => "<PROFILE>");
b. In certain situations, you may want subprograms you call to use
other response characteristics. For example, you may want them to
raise an exception if they encounter errors so that you have more
control over the error and exception handling of those subprograms.
Note that Environment-defined commands that do not have a Response
parameter automatically use the response characteristics in the job
response profile for the current job.
6. When appropriate, base command behavior on the values in the job
response profile. For example, you may have something like the following
in your command so that when your command encounters errors, it bases
its behavior on the error-reaction component of the job response
profile:
if Profile.Reaction (Profile.Get) = Profile.Raise_Error then
Log.Flush;
raise Propagate;
else
Log.Flush;
raise Quit;
end if;
7. Reset the job response profile at the end of your command:
Profile.Set (Profile => Original_Job_Profile);
Remember that your command may exit from a number of places, depending
on whether or not it encounters errors. Make sure that you reset the
job response profile at all of these places.
Example Using Method I
The following procedure is used by some Rational technical representatives
to create multiple users for Rational training. The comments indicate how
facilities from package Profile are used according to the method outlined
above.
with Debug_Tools;
with Directory_Tools;
with Log;
with Operator;
with Profile;
with String_Utilities;
-- Step 1: Give your procedure a Response parameter that accepts a
-- string value, with the default value <PROFILE>.
procedure Build_Training_Users_Too
(First_User_Number : in Positive := 1;
Last_User_Number : in Positive;
Username_Prefix : in String := "Advanced";
Response : in String := "<PROFILE>") is
package Naming renames Directory_Tools.Naming;
package Object renames Directory_Tools.Object;
-- Step 2: Save the current job response profile.
Old_Job_Profile : Profile.Response_Profile := Profile.Get;
-- Step 3: Change the string value in the Response parameter
-- to a variable of type Profile.Response_Profile.
Current_Job_Profile : Profile.Response_Profile :=
Profile.Value (Response);
Errors_Detected : Boolean := False;
Quit : exception;
Propagate : exception;
----------------------------------------
procedure Output_Error_Message (User_Name : in String) is
begin
Log.Put_Line
(Message => "Unable to create user """ & User_Name & """",
Kind => Profile.Error_Msg,
Response => Profile.Get);
end Output_Error_Message;
----------------------------------------
procedure Output_Closing_Message_For_Errors is
begin
Log.Put_Line
(Message => "[end of Build_Training_Users--error(s) detected]",
Kind => Profile.Auxiliary_Msg,
Response => Profile.Get);
end Output_Closing_Message_For_Errors;
----------------------------------------
function Current_Library (Of_Object : String) return String is
All_Objects : Object.Iterator :=
Naming.Resolution (Name => Of_Object,
Context => Naming.Default_Context,
Objects_Only => True);
An_Object : Object.Handle;
begin
An_Object := Object.Value (All_Objects);
return Naming.Unique_Full_Name (The_Object => An_Object);
end Current_Library;
----------------------------------------
begin
-- Step 4: Set the job response profile to be the value
-- specified in the Response parameter of your procedure.
Profile.Set (Profile => Current_Job_Profile);
-- Step 5: Make sure subprograms called by your procedure
-- use the appropriate response characteristics. Generally, you
-- should cause them to use the job response profile, by specifying
-- the value <PROFILE> or Profile.Get to their Response parameters.
Log.Put_Line (Message =>
"[Build_Training_Users (First_User_Number => " &
String_Utilities.Number_To_String
(First_User_Number) & ", Last_User_Number => " &
String_Utilities.Number_To_String
(Last_User_Number) &
", Username_Prefix => """ & Username_Prefix &
""", Response => """ & Response & """);]",
Kind => Profile.Auxiliary_Msg,
Response => Profile.Get);
declare
Context : constant String :=
String_Utilities.Capitalize (Current_Library ("$"));
Course : constant String :=
String_Utilities.Capitalize
(Naming.Simple_Name (Naming.Prefix (Context)));
Master_Full_Pathname : constant String :=
String_Utilities.Capitalize ("!Users." & Course & "_Master");
begin
-- Enable privileges (required to create users).
Operator.Enable_Privileges (Enable => True);
if Operator.Privileged_Mode /= True then
Log.Put_Line (Message => "You must have operator capability" &
" to create training users",
Kind => Profile.Error_Msg,
Response => Profile.Get);
Output_Closing_Message_For_Errors;
--
-- Step 7: Reset the job response profile at every place
-- from which your procedure may return to the calling job,
-- including premature returns when errors are encountered.
--
Profile.Set (Profile => Old_Job_Profile);
return;
end if;
if First_User_Number > Last_User_Number then
Log.Put_Line (Message =>
"The First_User_Number must be 'less than'" &
" or 'equal to' the Last_User_Number",
Kind => Profile.Error_Msg,
Response => Profile.Get);
Output_Closing_Message_For_Errors;
--
-- Step 7: Reset the job response profile at every place
-- from which your procedure may return to the calling job,
-- including premature returns when errors are encountered.
--
Profile.Set (Profile => Old_Job_Profile);
return;
end if;
for User_Count in First_User_Number .. Last_User_Number loop
declare
User_Number : constant String :=
String_Utilities.Number_To_String (User_Count);
User_Name : constant String :=
Username_Prefix & "_" & User_Number;
Users_Full_Pathname : constant String :=
String_Utilities.Capitalize ("!Users." & User_Name);
begin
-- Step 5: Make sure subprograms called by your
-- procedure use the appropriate response characteristics.
-- Below you want the Operator.Create_User procedure to
-- raise an exception when errors are encountered so that
-- your command can track the error and generate a message
-- indicating exactly which call(s) to Create_User
-- resulted in error(s).
Operator.Create_User
(User => User_Name,
Password => User_Name,
Volume => 0,
Response => "Raise_Error, <PROFILE>");
exception
when others =>
Errors_Detected := True;
--
-- Step 6: Define the behavior of your procedure
-- based on the values in the job response profile.
--
case (Profile.Reaction (Profile.Get)) is
when Profile.Quit =>
Output_Error_Message (User_Name);
Output_Closing_Message_For_Errors;
raise Quit;
when Profile.Propagate =>
Output_Error_Message (User_Name);
Output_Closing_Message_For_Errors;
raise Propagate;
when Profile.Persevere =>
Output_Error_Message (User_Name);
when Profile.Raise_Error =>
Output_Error_Message (User_Name);
end case;
end;
end loop;
if (Errors_Detected) then
Output_Closing_Message_For_Errors;
else
Log.Put_Line
("[end of Build_Training_Users--no errors detected]",
Kind => Profile.Auxiliary_Msg,
Response => Profile.Get);
end if;
-- Step 7: Reset the job response profile before returning to
-- the calling job.
Profile.Set (Profile => Old_Job_Profile);
end;
exception
--
-- Step 7: Reset the job response profile at every place
-- from which your procedure may exit, including when exceptions
-- are encountered.
--
when Propagate =>
Profile.Set (Profile => Old_Job_Profile);
raise;
when Quit =>
Profile.Set (Profile => Old_Job_Profile);
null;
when others =>
Log.Put_Line (Message =>
"Encountered an unexpected " & "exception: " &
Debug_Tools.Get_Exception_Name,
Kind => Profile.Exception_Msg,
Response => Profile.Get);
Output_Closing_Message_For_Errors;
Profile.Set (Profile => Old_Job_Profile);
if Profile.Propagate (Response => Profile.Get) then
raise;
end if;
end Build_Training_Users_Too;
Method II
Another method for making your commands take their response
characteristics from a response profile is to base the behavior of your
command on the value specified through its Response parameter and pass this
value to any other subprograms called by your command.
The main advantage of this method is that you do not change the job
response profile for the current job. Thus, you don't have to save the job
response profile for the calling job and reset it at the end of your
command to avoid affecting other commands in the current job.
However, there are two disadvantages to using this method:
* If your command calls Environment subprograms that have a Response
parameter, you need to pass the response characteristics specified to
the Response parameter of your command to each of these subprograms.
* If your command calls Environment subprograms that do not have a
Response parameter, those subprograms will not inherit these response
characteristics. Environment subprograms that do not have Response
parameters will continue to use the job response profile, which has not
been changed since your command began.
Instructions for Method II
The following instructions describe how to use method II in your
procedures. They are followed by an example that uses method II in the
same program shown above under method I.
1. Give your command a Response parameter that accepts a string value. The
recommended default value is "<PROFILE>", which copies the response
characteristics from the job response profile for the current job:
procedure Build_Training_Users
(First_User_Number : in Positive := 1;
Last_User_Number : in Positive;
Username_Prefix : in String := "Advanced";
Response : in String := "<PROFILE>") is
2. Convert the value of the Response parameter to a variable of type
Profile.Response_Profile:
Response_Value : Profile.Response_Profile :=
Profile.Value (Response);
You will need this value if you call subprograms, such as Log.Put_Line,
that have a Response parameter that accepts only values of type
Profile.Response_Profile.
3. Make sure any subprograms called by your command use appropriate
response characteristics:
a. Usually you will want subprograms you call to use the same response
characteristics as your command. In this case, you should pass the
value specified to the Response parameter of your command to these
subprograms, using the value Response or Response_Value:
Operator.Create_User (User => User_Name,
Password => User_Name,
Volume => 0,
Response => Response);
Log.Put_Line (Message => "Command has completed",
Kind => Profile.Auxiliary_Msg,
Response => Response_Value);
b. In certain situations, you may want subprograms you call to use
other response characteristics. For example, you may want them to
raise an exception if they encounter errors so that you have more
control over the error and exception handling of those subprograms.
Note that Environment-defined commands that do not have a Response
parameter automatically use the response characteristics in the job
response profile for the current job and therefore cannot be instructed
to use other response characteristics. Similarly, your command may
call user-defined subprograms for which the response characteristics
cannot be changed.
4. When appropriate, base command behavior on the values in the Response
parameter of your subprogram. For example, you may have something like
the following in your subprogram so that when it encounters errors, it
bases its behavior on the error-reaction component of the Response
parameter:
if Profile.Reaction (Response_Value) = Profile.Raise_Error
then
Log.Flush;
raise Propagate;
else
raise Quit;
end if;
Example Using Method II
The following procedure, used by some Rational technical representatives
to create multiple users for Rational training, is the same as the one
shown in the example for method I. The comments indicate how facilities
from package Profile are used in this version according to method II
outlined above.
with Debug_Tools;
with Directory_Tools;
with Log;
with Operator;
with Profile;
with String_Utilities;
-- Step 1: Give your procedure a Response parameter that accepts a
-- string value, with the default value <PROFILE>.
procedure Build_Training_Users_Too
(First_User_Number : in Positive := 1;
Last_User_Number : in Positive;
Username_Prefix : in String := "Advanced";
Response : in String := "<PROFILE>") is
package Naming renames Directory_Tools.Naming;
package Object renames Directory_Tools.Object;
-- Step 2: Change the string value in the Response parameter to
-- a variable of type Profile.Response_Profile.
Response_Value : Profile.Response_Profile := Profile.Value (Response);
Errors_Detected : Boolean := False;
Quit : exception;
Propagate : exception;
----------------------------------------
procedure Output_Error_Message (User_Name : in String) is
begin
Log.Put_Line
(Message => "Unable to create user """ & User_Name & """",
Kind => Profile.Error_Msg,
Response => Response_Value);
end Output_Error_Message;
----------------------------------------
procedure Output_Closing_Message_For_Errors is
begin
Log.Put_Line
(Message => "[end of Build_Training_Users--error(s) detected]",
Kind => Profile.Auxiliary_Msg,
Response => Response_Value);
end Output_Closing_Message_For_Errors;
----------------------------------------
function Current_Library (Of_Object : String) return String is
All_Objects : Object.Iterator :=
Naming.Resolution (Name => Of_Object,
Context => Naming.Default_Context,
Objects_Only => True);
An_Object : Object.Handle;
begin
An_Object := Object.Value (All_Objects);
return Naming.Unique_Full_Name (The_Object => An_Object);
end Current_Library;
----------------------------------------
begin
-- Step 3: Make sure subprograms called by your procedure
-- use the appropriate response characteristics. Generally, you
-- should cause them to use the response characteristics specified
-- to the Response parameter of this procedure. Recall that
-- Response is the string form and that Response_Value is the
-- internal (type Profile.Response_Profile) form.
Log.Put_Line (Message =>
"[Build_Training_Users (First_User_Number => " &
String_Utilities.Number_To_String
(First_User_Number) & ", Last_User_Number => " &
String_Utilities.Number_To_String
(Last_User_Number) &
", Username_Prefix => """ & Username_Prefix &
""", Response => """ & Response & """);]",
Kind => Profile.Auxiliary_Msg,
Response => Response_Value);
declare
Context : constant String :=
String_Utilities.Capitalize (Current_Library ("$"));
Course : constant String :=
String_Utilities.Capitalize
(Naming.Simple_Name (Naming.Prefix (Context)));
Master_Full_Pathname : constant String :=
String_Utilities.Capitalize ("!Users." & Course & "_Master");
begin
-- Enable privileges (required to create users).
Operator.Enable_Privileges (Enable => True);
if Operator.Privileged_Mode /= True then
Log.Put_Line (Message => "You must have operator capability" &
" to create training users",
Kind => Profile.Error_Msg,
Response => Response_Value);
Output_Closing_Message_For_Errors;
return;
end if;
if First_User_Number > Last_User_Number then
Log.Put_Line (Message =>
"The First_User_Number must be 'less than'" &
" or 'equal to' the Last_User_Number",
Kind => Profile.Error_Msg,
Response => Response_Value);
Output_Closing_Message_For_Errors;
return;
end if;
for User_Count in First_User_Number .. Last_User_Number loop
declare
User_Number : constant String :=
String_Utilities.Number_To_String (User_Count);
User_Name : constant String :=
Username_Prefix & "_" & User_Number;
Users_Full_Pathname : constant String :=
String_Utilities.Capitalize ("!Users." & User_Name);
begin
-- Step 3: Make sure subprograms called by your procedure
-- use the appropriate response characteristics. Below you
-- want the Operator.Create_User procedure to raise an
-- exception when errors are encountered so that your
-- procedure can track the error and generate a message
-- indicating exactly which call(s) to Create_User
-- resulted in error(s).
Operator.Create_User
(User => User_Name,
Password => User_Name,
Volume => 0,
Response => "Raise_Error, Response");
exception
when others =>
Errors_Detected := True;
--
-- Step 4: Define the behavior of your procedure
-- based on the values specified in its Response
-- parameter.
--
case (Profile.Reaction (Response_Value)) is
when Profile.Quit =>
Output_Error_Message (User_Name);
Output_Closing_Message_For_Errors;
raise Quit;
when Profile.Propagate =>
Output_Error_Message (User_Name);
Output_Closing_Message_For_Errors;
raise Propagate;
when Profile.Persevere =>
Output_Error_Message (User_Name);
when Profile.Raise_Error =>
Output_Error_Message (User_Name);
end case;
end;
end loop;
if (Errors_Detected) then
Output_Closing_Message_For_Errors;
else
Log.Put_Line
("[end of Build_Training_Users--no errors detected]",
Kind => Profile.Auxiliary_Msg,
Response => Response_Value);
end if;
end;
exception
when Propagate =>
raise;
when Quit =>
null;
when others =>
Log.Put_Line (Message =>
"Encountered an unexpected " & "exception: " &
Debug_Tools.Get_Exception_Name,
Kind => Profile.Exception_Msg,
Response => Response_Value);
Output_Closing_Message_For_Errors;
--
-- Step 4: Define the behavior of this procedure based on the
-- the value specified in its Response parameter.
--
if Profile.Propagate (Response => Response_Value) then
raise;
end if;
end Build_Training_Users_Too;
SETTING A JOB RESPONSE PROFILE
You can use procedures from package Profile to set components of a job
response profile programmatically within applications you are creating or
interactively from command windows. When you use procedures from package
Profile to set a job response profile, the procedure automatically sets the
job response profile for the current job. This value is discarded when the
job completes execution.
Note that only commands that take their response characteristics from the
job response profile (generally indicated by "<PROFILE>" in the Response
parameter of the command) are affected by these settings.
The following subsections describe the commands from package Profile that
are available for:
* Setting a complete job response profile
- Through string values that represent profiles or their components
- Through the internal representations of profiles or their components
* Setting individual components of a job response profile
Setting a Complete Profile through a String Value
To set all the components of a job response profile through a string value,
you can use the Set procedure. The Set procedure accepts string values
similar to those accepted by the Response parameter of Environment
commands. This string can:
* Specify a predefined profile
* Specify an arbitary set of components
Specifying a Predefined Profile
The Set command accepts special values such as "<SESSION>", "<DEFAULT>",
and "<ERRORS>" to cause the job response profile to copy its components
from an Environment-defined response profile. These special values are
described in "Environment-Defined Response Profiles," page nn.
Specifying an Arbitrary Set of Components
Sometimes you want to set the job response profile to include a set of
components for which there is no Environment-defined profile. In this case,
you can specify a series of option specifications to the Set command,
indicating a value for each component. You can also combine option
specifications with a special value to tailor the components from a
predefined profile. Each option specification overrides an individual
component in the profile.
For example, assume that you want the output for a particular job to be
255 characters wide to allow long messages to fit onto single lines.
Assume further that this is the only change you want to make to the
characteristics initially inherited from the session response profile for
the current session. The following command sets the job response profile
for the current job accordingly (note that individual option specifications
and the special value are separated by commas):
Profile.Set (Profile => "Width=>255, <SESSION>",
Status => Profile_Set_Status);
Note when using options specifications that if you do not include a value
for a particular component, that component assumes a null value. This may
cause unwanted (or at least unexpected) command behavior. For this
reason, it is often a good idea to combine options specifications with a
special value, such as "<SESSION>".
Whereas the previous example sets all the components, the following
command provides the job response profile with only one component--namely,
that of output width. Because no other components are specified, the job
response profile assumes the null value for all other components. Thus,
commands that use the response characteristics in this profile generate
no messages, have no instructions for responding to errors, and have no
activity to use (should they need one):
Profile.Set (Profile => "Width=>255",
Status => Profile_Set_Status);
Notice that when using the Set command, you must supply a value of type
!Tools.Simple_Status.Condition to the Status parameter. This value is used
by the Environment to return information if errors are encountered during
execution. You can use the Log.Put_Condition procedure to write this status
to the log file (see package Log in this book).
For further information about specifying a complete set of response
characteristics through a string value, see the information about the
Response parameter in Parameter-Value Conventions in the Reference Summary
(RS) book.
Setting a Complete Profile through the Internal Representation
When you are manipulating profiles programmatically, it is often easier to
set the job response profile for the current job through the internal
representation. Using the internal representation is especially useful
when you want to copy the complete profile or some of its components from
existing profiles.
In particular, commands in package Profile allow you to:
* Specify a predefined profile
* Specify an arbitary set of components
Specifying a Predefined Profile
Package Profile provides a Set procedure that accepts values of type
Response_Profile, which is the internal representation of a complete
profile.
Using the Set procedure, you can set the job response profile to be a
profile you have defined in your application or one of the three basic
Environment-defined profiles. You can specify Environment-defined
profiles to the Set procedure by using the following functions:
* Default_Profile returns the system default profile.
* Get_Default returns the session response profile for the current
session.
* Get returns the job response profile for the current job.
For example, the following procedure sets the job response profile for the
current job to the system default profile:
Profile.Set (Profile => Profile.Default_Profile);
Specifying an Arbitrary Set of Components
To set the job response profile through an arbitrary set of components, you
can use the Set_Response procedure. The Set_Response procedure is
especially useful when you want to take profile components from more than
one source.
For example, suppose you want the job response profile for the current job
to:
* Include the Propagate error reaction, which causes commands to stop
executing at the first error and raise an exception
* Include a line width of 255 columns
* Obtain the values for all other components from the session response
profile for the current session
The following procedure sets the job response profile accordingly:
Profile.Set_Response
(Reaction => Profile.Propagate,
Filter => Profile.Filter (Profile.Get_Default),
Prefixes => Profile.Prefixes (Profile.Get_Default),
Width => 255,
Activity => Profile.Activity (Profile.Get_Default),
Log_File => Profile.Log_File (Profile.Get_Default));
Note that the Set_Response procedure does not have parameters through
which you can specify the remote-passwords and remote-sessions files to be
used. Instead, the profile built by this procedure assumes a null value
for each of these files. If you need to set a remote-passwords or
remote-sessions file for a job, you can either use a different procedure to
set the job response profile or use the Set_Remote_Passwords or
Set_Remote_Sessions procedures after this procedure.
For further information about providing parameter values to the
Set_Response procedure, see "Obtaining Profiles and Profile Components,"
page nn, or the reference entries for types Activity_Type, Error_Reaction,
Log_File, Log_Filter, and Log_Prefixes.
Setting Individual Components
Package Profile provides a variety of procedures you can use to set
individual components of the job response profile for the current job:
Include Set_Activity
Set_Filter Set_Log_File
Set_Prefixes Set_Reaction
Set_Remote_Passwords Set_Remote_Sessions
Set_Width
The Include procedure sets the value for a single message kind in the
log-filter component of the job response profile. The other procedures set
the component indicated in the procedure's name. These procedures affect
only the component indicated; they do not affect any other components in
the profile.
For information about using these commands, including information about
the values accepted by each, see the reference entries in this package.
SETTING A SESSION RESPONSE PROFILE
The session response profile for a particular session defines the default
response characteristics to be used by commands executing in that session.
More specifically, the session response profile for a session is used to
initialize each job response profile associated with a job running under
that session. Since most commands use the response characteristics
defined in the job response profile for the current job, the session
response profile serves to provide the default response characteristics for
most commands.
The component values of a session response profile are represented by a
group of session switches with the prefix "Profile." Thus, to set your
session response profile interactively, edit the appropriate session
switches. For further information, see Chapter 2, "Job Characteristics
and Behavior," or Session Switches in this book.
To set a session response profile from within applications you are
creating, you can call commands from this package. When you use commands
from package Profile to set a session response profile, the command
automatically sets the profile for the current session. This value is
reflected in the switch file for that session and is saved and available
for use in subsequent logins. Most profile components take effect
immediately; however, the remote-passwords and remote-sessions files take
effect only at login.
Note that only commands that take their response characteristics from a
job response profile that has not been changed since the job began or
that take their response characteristics directly from the session
response profile (generally indicated by "<SESSION>" in the Response
parameter of the command) are affected by these settings.
The following subsections describe the commands from package Profile for:
* Setting a complete session response profile
* Setting individual components of a session response profile
Setting a Complete Session Response Profile
Package Profile provides three procedures for setting all the components of
a session response profile in a single step:
* The Set_Default procedure accepts string values similar to those
accepted by the Response parameter of many Environment commands.
* Two procedures accept the internal representations of profiles or their
components:
- A Set_Default procedure accepts values of type Response_Profile,
which is the internal representation of a complete profile.
- The Set_Default_Response procedure accepts a set of values, each
representing an individual component.
As noted, these procedures differ only in the way you specify the new
profile. Each procedure is similar to the corresponding Set or Set_Response
command used for setting a job response profile. For more information about
the values accepted by these procedures, see "Setting a Job Response
Profile," page nn.
Setting Individual Components of a Session Response Profile
Package Profile provides a variety of procedures you can use to set
individual components of the session response profile for the current
session:
Include_In_Default Set_Default_Activity
Set_Default_Filter Set_Default_Log_File
Set_Default_Prefixes Set_Default_Reaction
Set_Default_Remote_Passwords Set_Default_Remote_Sessions
Set_Default_Width
These procedures are similar to the commands used for setting individual
components of a job response profile. For more information about using
these commands and the values they accept, see the reference entries in
this package.
OBTAINING PROFILES AND PROFILE COMPONENTS
Package Profile provides a variety of functions that return a complete
profile or a particular component of a profile. You can use these functions
in your applications to query the job and session response profiles and
determine behavior accordingly. You also can use these functions to
supply values to the procedures that set profiles and profile components.
The following subsections contain information about:
* Obtaining a complete response profile
* Obtaining a single component of a response profile
* Querying about particular components of a profile
Obtaining a Complete Profile
Package Profile provides several functions that return a complete response
profile:
* Get returns either the string or the internal representation of the job
response profile for the current job.
* Get_Default returns either the string or the internal representation of
the session response profile for the current session.
* Default_Profile returns the internal representation of the system
default profile.
* Response and its renames (Ignore, Nil, Raise_Exception, Response,
Verbose, and Warn) build a profile from the component values you
specify and return the internal representation of that profile (see
"Building Your Own Profiles," page nn).
Notice that there are two forms each of the Get and Get_Default functions.
One form of the function returns a string value suitable for writing to a
file or passing to another command that requires the string representation
of a profile. For example, if you wanted to write the session response
profile for your current session to the message window, you could execute
the following command:
Io.Echo (Profile.Get_Default);
The other form of the Get and Get_Default functions returns a value of
type Response_Profile suitable for providing to most of the procedures
and functions in this package. Functions that return the internal
representation of a profile are especially useful for specifying a profile
to functions that return individual profile components (described in the
following subsection).
Obtaining Individual Components of a Profile
Package Profile provides a set of functions that return the component
indicated in the name of the function:
Activity Default_Activity
Default_Remote_Passwords Default_Remote_Sessions
Filter Log_File
Prefixes Reaction
Remote_Passwords Remote_Sessions
Width
Functions that have names beginning with the word "Default" return the
indicated component of the session response profile for the current
session. All other functions return the indicated component of the
specified profile (by default, the job response profile for the current job).
These functions are especially useful:
* To determine particular aspects of behavior within your application,
such as error reaction, based on the job or session response profile
of the executing user
* As parameter values for:
- Procedures such as Set_Response that set profiles through a series of
components
- Other functions such as Response that build profiles from a series of
components.
For example, when your application encounters an error, you may want it to
determine behavior based on the error-reaction characteristic specified
in the job response profile for the current job. Assume that, at the very
least, you want it to generate a different closing message depending on
whether errors were encountered and raise an exception if the job
response profile specifies that it should. In this case, you could include a
series of if statements such as the following:
if <errors were detected> then
if Profile.Reaction (Profile.Get) = Profile.Raise_Error then
Log.Flush (Response => Profile.Get);
Profile.Set (Response => Old_Job_Profile);
raise Propagate;
end if;
else
Log.Put_Line (Message => "[Operation has completed " &
"-- no errors detected]",
Kind => Profile.Auxiliary_Msg,
Response => Profile.Get);
end if;
Log.Flush (Response => Profile.Get);
Profile.Set (Response => Old_Job_Profile);
raise Quit;
Querying about Particular Components of a Profile
Package Profile also provides procedures that query about particular
components of a response profile:
* Propagate returns True if commands that use the specified profile raise
an exception when errors are encountered--that is, if the
error-reaction component of the specified profile is Propagate or
Raise_Error.
* Persevere returns True if commands that use the specified profile
continue executing when errors are encountered--that is, if the
error-reaction component of the specified profile is Persevere or
Raise_Error.
* Includes returns True if the log-filter component of the specified profile
contains the specified message kind.
BUILDING YOUR OWN PROFILES
In addition to the three basic profiles, the Environment allows you to
build your own profiles for use in your applications. You can define your
profiles through either the string or the internal representation.
Through a String Value
You can build your own profiles using string values similar to those
accepted by the Response parameter of Environment-defined commands. For
example, at the beginning of your application, you can define your own
profile, Local_Profile, as shown below:
Local_Profile : String :=
("PROPAGATE, ***, ++*, %%%, !!!," &
"Width=>80, Use_Error, Prefixes=>Symbols," &
"Activity=>!Machine.Release.Current.Activity," &
"Remote_Passwords => <NIL>, Remote_Sessions => <NIL>");
Within your application, you can then set this profile to be the job
response profile (as in method I on page nn), or you could pass this
profile to subprograms you call (as in method II on page nn).
Note that if you do not include a value for a particular component, that
component assumes a null value. This may cause unwanted (or at least
unexpected) command behavior.
For further information about the string representation of profiles, see
the discussion of the Response parameter in Parameter-Value Conventions
in the Reference Summary (RS) book.
Through the Internal Representation
You can use the Response function to build your own profiles using the
internal representation of profile components. The Response function builds
a profile from the series of component values you specify and then returns
the internal representation of that profile.
By default, the Response function builds a profile that has the same
components as the job response profile for the current job; however, you
can specify other component values. You also can use the following
functions, which rename the Response function with different default
values:
* Ignore
* Nil
* Raise_Exception
* Verbose
* Warn
The Response function and its renames are especially useful when you want
to combine profile components from several other profiles into a new profile.
For example, suppose you want a profile that copies all of its components
from the job response profile for the current job except the error reaction
and the line width. Instead, the profile is to include the Propagate error
reaction and a line width of 255 columns. The following procedure builds
the profile accordingly and assigns it to a variable of type
Response_Profile:
Local_Profile : Profile.Response_Profile := Response
(Reaction => Profile.Propagate,
Filter => Profile.Filter (Profile.Get),
Prefixes => Profile.Prefixes (Profile.Get),
Width => 255,
Activity => Profile.Activity (Profile.Get));
Within your application, you then can set this profile to be the job
response profile (as in method I on page nn), or you could pass this
profile to subprograms you call (as in method II on page nn).
Note: You cannot set a remote-passwords or a remote-sessions file through
these functions. To set remote-passwords and remote-sessions files, you can
use the Set_Remote_Passwords and Set_Remote_Sessions procedures.
CONVERTING BETWEEN PROFILE REPRESENTATIONS
Several commands in package Profile have two forms: one that manipulates
the profile through the string representation and one that manipulates the
profile through the internal representation. For example, the Get function,
which returns the job response profile for the current job, returns either
a string value or a value of type Response_Profile, depending on how it is
used.
However, many other commands do not have two forms. When using these com-
mands, you may need to convert between the string and internal
representations of a profile. To do so, you can use one of three commands:
* Image returns the string representation of the specified profile.
* Convert returns the internal representation of the specified profile.
* Value is the functional form of the Convert procedure.
For example, assume that you need the string representation of the system
default profile. Package Profile provides only the Default_Profile function,
which returns a value of type Response_Profile. To convert this value to a
string value and write it to the message window, you could execute the
following command:
Io.Echo (Profile.Image (Profile.Default_Profile));
In contrast, assume that you want to create your own profile and assign it
to a variable of type Response_Profile that can be easily referenced
programmatically. You could define your own profile, Current_Profile, as
shown below:
Current_Profile : Profile.Response_Profile := Profile.Value
("Width=>70, ~:::," &
"Activity=>!Machine.Release.Current.Activity," &
"<DEFAULT>");
@node !Tools.Profile.Activity
function Activity (Response : Response_Profile := Profile.Get)
return Activity_Type;
DESCRIPTION
Returns the value of the activity component of the specified profile.
The activity component specifies the activity file to be used for mapping
between subsystems and specific releases of those subsystems. For further
information about activities, see the Project Management (PM) book.
To obtain the value of the activity component in the session response
profile, use the Default_Activity function.
PARAMETERS
Response : Response_Profile := Profile.Get;
Specifies the profile from which to return the activity component. The
default is the job response profile for the current job.
return Activity_Type;
Returns the value of the activity component.
REFERENCES
subtype Activity_Type
function Default_Activity
procedure Set_Activity
procedure Set_Default_Activity
Project Management (PM)
@node !Tools.Profile.Activity_Type
subtype Activity_Type is Directory.Object;
DESCRIPTION
Defines a representation for an activity.
This subtype defines the value for the activity component of a response
profile. It is a subtype of type !Implementation.Directory.Object, which is
an implementation detail of the Environment library system. For further
information, see your Rational technical representative.
An activity defines mappings between subsystems and specific releases of
those subsystems. For further information about activities, see the
Project Management (PM) book.
REFERENCES
Project Management (PM)
@node !Tools.Profile.Cached_Selected_Text
function Cached_Selected_Text return String;
DESCRIPTION
Returns a string representing the selected text as cached at job
initialization.
Certain information is cached at job initialization. For example, the
resolutions of the special names are cached. This function can be used to
obtain the resolution of the selected text. The cursor need not be in the
selection.
PARAMETERS
return String;
Returns a string representing the selected text.
REFERENCES
procedure Get_Cached_Resolution
@node !Tools.Profile.Convert
procedure Convert (Image : String;
Response : out Response_Profile;
Status : in out Simple_Status.Condition);
DESCRIPTION
Converts from the string representation of a profile to the internal
representation.
The functional version of this operation is called Value. To convert from
the internal representation of a profile to the string representation, use
the Image procedure.
For further information about the representation of profiles, see the
introduction to this package.
PARAMETERS
Image : String;
Specifies the string representation of a profile.
Response : out Response_Profile;
Specifies the internal representation of the profile specified by the Image
parameter.
Status : in out Simple_Status.Condition;
Returns the status indicating that the procedure has executed correctly
or, if there is an error, a message indicating the type of error. To
convert the status to a string representation and enter it into the log
file, use the Log.Put_Condition procedure.
REFERENCES
procedure Image
function Value
procedure Log.Put_Condition
Programming Tools (PT), package Simple_Status
@node !Tools.Profile.Default_Activity
function Default_Activity return Activity_Type;
DESCRIPTION
Returns the value of the activity component of the session response profile
for the current session.
An activity defines mappings between subsystems and specific releases of
those subsystems. For further information about activities, see the
Project Management (PM) book.
To obtain the value of the activity component of the job response profile,
use the Activity function.
PARAMETERS
return Activity_Type;
Returns the value of the activity component.
REFERENCES
subtype Activity_Type
function Activity
procedure Set_Default_Activity
Project Management (PM)
@node !Tools.Profile.Default_Filter
Default_Filter : constant Log_Filter := Full;
DESCRIPTION
Defines a constant that represents the log-filter component of the system
default profile.
The system default filter is Full. The Full filter specifies that the
following message types should be put in the log file: auxiliary (:::),
note (---), positive (+++), position (>>>), negative (++*), warning (!!!),
error (***), exception (%%%), sharp (###), at (@@@), and dollar ($$$).
This filter does not include debug messages (???). (For further information
on types of messages, see the Msg_Kind type.)
This filter is used to initialize the log-filter component of the session
response profile for each user's default session (S_1).
REFERENCES
function Default_Profile
type Msg_Kind
@node !Tools.Profile.Default_Log_File
Default_Log_File : constant Log_Output_File := Use_Output;
DESCRIPTION
Defines a constant that represents the log-file component of the system
default profile.
The system default log file is Use_Output, which directs log output to
Current_Output. By default, Current_Output is an Environment output
window. This log file is used if a different log file is not specified in the
session or job response profile.
This file is used to initialize the log-file component of the session
response profile for each user's default session (S_1).
REFERENCES
function Default_Profile
type Log_Output_File
@node !Tools.Profile.Default_Prefixes
Default_Prefixes : constant Log_Prefixes
:= (Yr_Mn_Dy, Hr_Mn_Sc, Symbols);
DESCRIPTION
Defines a constant that represents the prefixes component of the system
default profile.
The prefixes component specifies the set of prefixes to be used when messages
are inserted into the log file. The system default prefixes are Yr_Mn_Dy,
Hr_Mn_Sec, and Symbols. This set of prefixes is used if a different set
is not specified in the session or job response profile.
For further information, see the Log_Prefix and Log_Prefixes types.
REFERENCES
function Default_Profile
type Log_Prefix
type Log_Prefixes
@node !Tools.Profile.Default_Profile
function Default_Profile return Response_Profile;
DESCRIPTION
Returns the internal representation of the system default profile.
This is the profile that is used by the Environment to initialize the
session response profile for each user`s default session (S_1).
The system default profile is the aggregate of all of the default constants
defined in this package. The components for the system default profile are:
* Error reaction: The command should persevere.
* Log filter: Auxiliary (:::), note (---), positive (+++), position (>>>),
negative (++*), warning (!!!), error (***), exception (%%%), sharp
(###), at (@@@), and dollar ($$$) messages should be included in the
log file.
* Log prefixes: Each log message is to be preceded by the Yr_Mn_Dy,
Hr_Mn_Sc, and Symbols prefixes (the Symbols prefix indicates the type of
message put in the log).
* Line width: The width of log messages before they are wrapped is 77
characters. Messages that have been wrapped are prefixed with the
ellipsis (...) symbol.
* Log file: The log file should be sent to Current_Output, which is, by
default, an Environment output window.
* Activity: Specifies that none should be used.
* Remote-passwords file: Specifies that none should be used.
* Remote-sessions file: Specifies that none should be used.
PARAMETERS
return response_profile;
Returns the internal representation of the system default profile.
REFERENCES
constant Default_Filter
constant Default_Log_File
constant Default_Prefixes
constant Default_Reaction
constant Default_Width
type Error_Reaction
type Log_Output_File
type Log_Prefix
type Log_Prefixes
type Msg_Kind
@node !Tools.Profile.Default_Reaction
Default_Reaction : constant Error_Reaction := Persevere;
DESCRIPTION
Defines a constant that represents the error-reaction component of the
system default profile.
The system default error reaction is Persevere, which causes commands to
continue executing without raising an exception when errors are
encountered. This error reaction is used to initialize the error-reaction
component of the session response profile for each user's default session
(S_1).
For further information, see type Error_Reaction.
REFERENCES
type Error_Reaction
@node !Tools.Profile.Default_Remote_Passwords
function Default_Remote_Passwords return Remote_Passwords_Type;
DESCRIPTION
Returns the value of the remote-passwords-file component of the session
response profile for the current session.
A remote-passwords file is a text file that specifies the usernames and
passwords to be used when accessing remote machines. For further
information, see package Remote_Passwords in this book.
To obtain the value of the remote-passwords-file component of the job
response profile, use the Remote_Passwords function.
PARAMETERS
return Remote_Passwords_Type;
Returns the value of the remote-passwords-file component.
REFERENCES
function Remote_Passwords
type Remote_Passwords_Type
procedure Set_Default_Remote_Passwords
package Remote_Passwords
@node !Tools.Profile.Default_Remote_Sessions
function Default_Remote_Sessions return Remote_Sessions_Type;
DESCRIPTION
Returns the value of the remote-sessions-file component of the session
response profile for the current session.
A remote-sessions file is a text file that specifies which session (or
account) should be used when logging into a remote machine.
To obtain the value of the remote-sessions-file component of the job
response profile, use the Remote_Sessions function.
PARAMETERS
return Remote_Sessions_Type;
Returns the value of the remote-sessions-file component.
REFERENCES
function Remote_Sessions
type Remote_Sessions_Type
procedure Set_Default_Remote_Sessions
@node !Tools.Profile.Default_Width
Default_Width : constant Natural := 77;
DESCRIPTION
Defines a constant that represents the line-width component of the system
default profile.
The line-width component specifies the maximum length of lines in the log
file. If a log message is longer than the width defined in the profile, the
log message is continued on the next line. Messages that have been
continued are prefixed with the ellipsis (...) symbol.
The system default width is 77 columns. This width is used to initialize
the line-width component of the session response profile for each user's
default session (S_1).
REFERENCES
function Default_Profile
@node !Tools.Profile.Error
Error : exception;
DESCRIPTION
Defines the exception raised when an error condition occurs in a command
and the error reaction is defined to be Raise_Error.
@node !Tools.Profile.Errors
Errors : constant Log_Filter := Log_Filter'(Negative_Msg ..
Exception_Msg => True, others => False);
DESCRIPTION
Defines a log filter that allows only the following kinds of messages to be
included in the log file: negative (++*), warning (!!!), error (***), and
exception (%%%).
This constant can be used in the Filter parameter of procedures, such as
the Set_Response procedure, to specify that only these four types of
messages should appear in the log file.
REFERENCES
constant Full
type Log_Filter
type Msg_Kind
constant Quiet
constant Summary
constant Terse
@node !Tools.Profile.Error_Reaction
type Error_Reaction is (Quit, Propagate, Persevere, Raise_Error);
DESCRIPTION
Defines the four different reactions to an error that a command can have.
Commands respond, based on the specified error reaction, with respect to
two dimensions:
* Perseverance: The first dimension determines whether the job stops at
the first error or continues processing. Even when set to stop at the
first error, when log messages are to be generated, the job continues
processing long enough to print an error message.
* Exception propagation: The second dimension determines whether the job
is to propagate an exception to its caller when it terminates a run in
which errors have occurred. If processing has persevered, the Error
exception is raised; otherwise, an exception related to the error
that caused processing to stop is raised.
This type defines four error reactions based on these two dimensions.
ENUMERATIONS
Persevere
Specifies that the job continue executing as best it can after errors
are discovered. No exception is raised. Note that even if the job is to
stop at the first error or if the job is not to raise exceptions, error
messages may have been accumulated for the job; these messages can be
displayed using the Log.Put_System_Messages procedure.
Propagate
Specifies that the command terminate at its first error. An exception is
raised. If no other exception is defined for the command, the Error
exception is raised. Note that even if the job is to stop at the first
error or if the job is not to raise exceptions, error messages may have
been accumulated for the job; these messages can be displayed using the
Log.Put_System_Messages procedure.
Quit
Specifies that the command terminate at its first error. No exception is
raised.
Raise_Error
Specifies that the command continue executing as best it can after errors
are discovered. At some point, an exception is raised. If no other
exception is defined for the command, the Error exception is raised. Note
that even if the job is to stop at the first error or if the job is not to
raise exceptions, error messages may have been accumulated for the job;
these messages can be displayed using the Log.Put_System_Messages
procedure.
@node !Tools.Profile.Filter
function Filter (Response : Response_Profile := Profile.Get)
return Log_Filter;
DESCRIPTION
Returns the value of the log-filter component of the specified profile.
The log-filter component represents a collection of Boolean values, one for
each message kind. Messages of any kind whose value is True are included
in the log file.
To determine whether a particular message kind is included in the filter of
a specified profile, you also can use the Includes function.
To set the log-filter component in the job and session response profiles,
use the Set_Filter and Set_Default_Filter procedures, respectively.
PARAMETERS
Response : Response_Profile := Profile.Get;
Specifies the profile from which the filter component is desired. The default
is the job response profile for the current job.
return Log_Filter;
Returns the value of the filter component.
REFERENCES
procedure Include
procedure Include_In_Default
function Includes
type Log_Filter
subtype Msg_Kind
procedure Set_Default_Filter
procedure Set_Filter
@node !Tools.Profile.Full
Full : constant Log_Filter := Log_Filter'(Debug_Msg => False,
others => True);
DESCRIPTION
Defines a log filter that allows all messages except debug messages (denoted
by ???) to be included in the log file.
This constant can be used in the Filter parameter of procedures, such as
the Set_Response procedure, to specify that all messages except
debugging messages should appear in the log file.
REFERENCES
constant Errors
type Log_Filter
type Msg_Kind
constant Quiet
constant Summary
constant Terse
@node !Tools.Profile.Get
function Get return Response_Profile;
function Get return String;
DESCRIPTION
Returns the job response profile for the current job.
This function returns the current job response profile. It can be used as a
parameter to commands in the Environment to supply the current job
response profile to those commands.
The initial values of the job response profile are obtained from the
session response profile. Thus, if the user has not explicitly set values
in the job response profile, this function returns the same values as those
contained in the session response profile.
PARAMETERS
return Response_Profile;
Returns the internal representation of the job response profile.
return String;
Returns the string representation of the job response profile.
REFERENCES
procedure Set
@node !Tools.Profile.Get_Cached_Resolution
procedure Get_Cached_Resolution
(Name : String;
The_Declaration : out Directory.Declaration;
The_Object : out Directory.Object;
The_Version : out Directory.Version;
Status : out Directory.Naming.Name_Status);
DESCRIPTION
Retrieves the resolution of the specified special name as cached at job
initialization.
Certain information is cached at job initialization. For example, the
resolutions of the special names "<IMAGE>", "<CURSOR>", "<REGION>", and
"<SELECTION>" are cached so that they are resolved consistently throughout
the job. This procedure can be used to obtain the resolution of one of
these special names.
PARAMETERS
Name : String;
Specifies the special name for which the cached resolution is desired.
Special names include: "<IMAGE>", "<CURSOR>", "<REGION>", and
"<SELECTION>".
The_Declaration : out Directory.Declaration;
Returns the directory declaration.
The_Object : out Directory.Object;
Returns the directory object.
The_Version : out Directory.Version;
Returns the directory version.
Status : out Directory.Naming.Name_Status;
Returns the name status.
REFERENCES
function Cached_Selected_Text
@node !Tools.Profile.Get_Default
function Get_Default return Response_Profile;
function Get_Default return String;
DESCRIPTION
Returns the session response profile for the current session.
This function returns the current session response profile. It can be used
as a parameter to commands in the Environment to supply the current
session response profile to those commands.
The initial values of the session response profile for each user's default
session (S_1) are obtained from the system default profile. (Subsequent
sessions initially assume the values of the default session.) Thus, if the
user has not explicitly set values in the session response profile, this
function returns the same values as those contained in the system default
profile.
PARAMETERS
return Response_Profile;
Returns the internal representation of the session response profile.
return String;
Returns the string representation of the session response profile.
REFERENCES
procedure Set_Default
@node !Tools.Profile.Ignore
function Ignore (Reaction : Error_Reaction := Profile.Persevere;
Filter : Log_Filter := Profile.Quiet;
Prefixes : Log_Prefixes := Profile.Prefixes;
Width : Natural := Profile.Width;
Activity : Activity_Type := Profile.Activity;
Log_File : Log_Output_File := Profile.Log_File)
return Response_Profile renames Response;
DESCRIPTION
Returns the profile built from the specified components.
This function builds a profile from the specified components and returns
that profile. The profile returned by this function can be tailored to
include any reaction, filter, prefixes, width, activity, and/or log file.
By default, the profile includes the Persevere error reaction and the Quiet
filter. The Persevere error reaction causes commands to continue executing
without raising an exception when errors are encountered. The Quiet filter
causes no log messages to be generated. For all other components, the
default is the value in the job response profile for the current job.
This function can be used in other commands to use, or to set as the
default, a profile containing the specified components.
This function renames the Response function.
PARAMETERS
Reaction : Error_Reaction := Profile.Persevere;
Specifies the error-reaction component for the profile. The default is the
Persevere error reaction, which causes commands to continue executing
without raising an exception when errors are encountered.
Filter : Log_Filter := Profile.Quiet;
Specifies the log-filter component for the profile. The default is the Quiet
filter, which allows no messages to be inserted into the log file.
Prefixes : Log_Prefixes := Profile.Prefixes;
Specifies the log-prefixes component for the profile. The default is the
prefixes in the job response profile for the current job.
Width : Natural := Profile.Width;
Specifies the line-width component for the profile. The default is the width
in the job response profile for the current job.
Activity : Activity_Type := Profile.Activity;
Specifies the activity component for the profile. The default is the
activity in the job response profile for the current job.
Log_File : Log_Output_File := Profile.Log_File;
Specifies the log-file component for the profile. The default is the log file
in the job response profile for the current job.
return Response_Profile;
Returns the internal representation of the profile.
REFERENCES
function Nil
function Raise_Exception
function Response
function Verbose
function Warn
@node !Tools.Profile.Image
function Image (Profile : Response_Profile :=
Standard.Profile.Get) return String;
DESCRIPTION
Returns the string representation of the specified profile.
To obtain the internal representation of a profile, use the Convert
procedure or the Value function.
For more information about the representation of profiles, see the
introduction to this package.
PARAMETERS
Profile : Response_Profile := Standard.Profile.Get;
Specifies the response profile for which to return the string
representation. The default is the job response profile for the current
job.
return String;
Returns the string representation of the specified profile.
REFERENCES
procedure Convert
function Value
@node !Tools.Profile.Include
procedure Include (Kind : Msg_Kind;
Value : Boolean := True);
DESCRIPTION
Sets the log-filter component in the job response profile for the current
job to include (or not include) the specified kind of message; whether or
not the kind of message is to be included is determined by the Value
parameter.
To determine whether a particular kind of message is already included in a
specified profile, use the Includes function.
To set the value for a message kind in the session response profile, use
the Include_In_Default procedure.
PARAMETERS
Kind : Msg_Kind;
Specifies the kind of message to include or not to include in the filter.
Value : Boolean := True;
Specifies whether the specified kind of message should be included. The
default, True, includes the message.
REFERENCES
function Filter
procedure Include_In_Default
function Includes
type Msg_Kind
procedure Set_Filter
@node !Tools.Profile.Includes
function Includes (Kind : Msg_Kind;
Response : Response_Profile := Profile.Get)
return Boolean;
DESCRIPTION
Returns a Boolean value indicating whether the specified kind of message is
included in the log-file component of the specified profile.
This function returns the value of the specified message kind from the
filter for the specified profile. Messages of any kind whose value is True
are included in log files generated with the profile.
To obtain the values of all the message kinds in the log-filter component
for a specified profile, use the Filter function.
To set the value for a message kind in the job and session response
profiles, use the Include and Include_In_Default procedures, respectively.
PARAMETERS
Kind : Msg_Kind;
Specifies the kind of message for which to return the value.
Response : Response_Profile := Profile.Get;
Specifies the profile from which to return the message-kind value. The
default is the job response profile for the current job.
return Boolean;
Returns True if the specified message kind is included in the log files
generated with the specified profile; otherwise, the function returns False.
REFERENCES
function Filter
procedure Include
procedure Include_In_Default
subtype Msg_Kind
procedure Set_Default_Filter
procedure Set_Filter
@node !Tools.Profile.Include_In_Default
procedure Include_In_Default (Kind : Msg_Kind;
Value : Boolean := True);
DESCRIPTION
Changes the log-filter component of the session response profile for the
current session to include (or not include) the specified kind of message;
whether or not the kind of message is to be included is determined by the
Value parameter.
To determine whether a particular kind of message is included in the
log-filter component of a specified profile, use the Includes function.
To set the value for a message kind in the job response profile, use the
Include procedure.
PARAMETERS
Kind : Msg_Kind;
Specifies the kind of message to include or not to include in the log
filter.
Value : Boolean := True;
Specifies whether the specified kind of message should be included. The
default, True, includes the message.
REFERENCES
function Filter
procedure Include
function Includes
subtype Msg_Kind
procedure Set_Default_Filter
@node !Tools.Profile.Log_File
function Log_File (Response : Response_Profile := Profile.Get)
return Log_Output_File;
DESCRIPTION
Returns the value of the log-file component of the specified profile.
The log-file component specifies where log output is to be sent. Log output
can be sent to any specified text file or to any of the four destinations
defined by the Log_Output_File type.
To set the log-file component in the job response profile, use the
Set_Log_File procedure.
To set the log-file component in the session response profile, use the
Set_Default_Log_File procedure.
PARAMETERS
Response : Response.Profile := Profile.Get;
Defines the profile for which the log-file component is desired. The default
is the job response profile for the current job.
return Log_Output_File;
Returns the value of the log-file component.
REFERENCES
type Log_Output_File
procedure Set_Default_Log_File
procedure Set_Log_File
@node !Tools.Profile.Log_Filter
type Log_Filter is array (Msg_Kind) of Boolean;
DESCRIPTION
Defines the log filters.
This type defines the filters that are used to generate and filter the log
files. A filter contains a Boolean value for each kind of message that can
be generated. Message kinds with the value True are included in any log
files generated with the profile. Message kinds with the value False are
filtered out of the log file (not included).
REFERENCES
type Msg_Kind
@node !Tools.Profile.Log_Output_File
Type Log_Output_File is (Use_Output, Use_Error,
Use_Standard_Output,
Use_Standard_Error);
DESCRIPTION
Defines four different places to which log output can be directed.
See the Key Concepts of this book and package Log for more information
about directing log output.
ENUMERATIONS
Use_Error
Specifies that log output should be sent to Current_Error. By default,
Current_Error directs output to Standard_Error; however, Current_Error can
be redirected to another location using the Log.Set_Error procedure or the
Io.Set_Error procedure.
Use_Output
Specifies that log output should be sent to Current_Output. By default,
Current_Output directs output to Standard_Output; however,
Current_Output can be redirected to another location using the
Log.Set_Output or Io.Set_Output procedure.
Use_Standard_Error
Specifies that log output should be sent to Standard_Error, which is the
Environment message window. Standard_Error cannot be redirected.
Use_Standard_Output
Specifies that log output should be sent to Standard_Output, which is an
Environment output window. Standard_Output cannot be redirected.
@node !Tools.Profile.Log_Prefix
type Log_Prefix is (Nil, Time, Hr_Mn_Sc, Hr_Mn, Date, Mn_Dy_Yr,
Dy_Mon_Yr, Yr_Mn_Dy, Symbols);
DESCRIPTION
Defines the kinds of prefixes that can appear before messages in the log
file.
ENUMERATIONS
Date
Specifies a verbose format for the date: the spelled-out month, the day of
the month, and the year, such as June 30, 1991.
Dy_Mon_Yr
Specifies an abbreviated format for the date: the day of the month, an
abbreviation of the month, and the year, such as 30-JUN-91.
Hr_Mn
Specifies a military format for time: hours and minutes, such as 21:08.
Hr_Mn_Sc
Specifies a military format for time: hours, minutes, and seconds, such as
19:54:04.
Mn_Dy_Yr
Specifies a short format for the date: the numeric month, the day of the
month, and the year, such as 06/30/91.
Nil
Specifies an empty prefix. If any of the three prefixes are not used, the
enumeration should be set to this prefix.
Symbols
Specifies the symbols associated with the kind of message. These symbols
denote the kind of message being added to the log file, such as *** or !!!.
See the Msg_Kind type for the set of all message kinds and their
symbols.
Time
Specifies the normal A.M./P.M. format for time: hours, minutes, and
seconds, such as 11:34:32 AM or 8:19:09 PM.
Yr_Mn_Dy
Specifies a short format for the date: the year, the numeric month, and the
day of the month, such as 91/06/30.
REFERENCES
type Log_Prefixes
type Msg_Kind
@node !Tools.Profile.Log_Prefixes
type Log_Prefixes is array (1 .. 3) of Log_Prefix;
DESCRIPTION
Defines the set of prefixes that can appear before messages in the log file.
This type defines the set of three message prefixes. These prefixes are
inserted in order at the beginning of each log message. Up to three
prefixes are allowed. Less than three prefixes can be used by setting the
extra prefix or prefixes to the Nil enumeration.
See the Log_Prefix type for a list of the log prefixes available.
REFERENCES
type Log_Prefix
type Msg_Kind
@node !Tools.Profile.Msg_Kind
type Msg_Kind is (Auxiliary_Msg, Debug_Msg, Note_Msg,
Positive_Msg, Position_Msg, Negative_Msg,
Warning_Msg, Error_Msg, Exception_Msg,
Sharp_Msg, At_Msg, Dollar_Msg);
DESCRIPTION
Defines the kinds of messages that can be inserted in the log file.
Each kind of message is associated with a three-character symbol. These
symbols are noted in the enumerations and can be included in the log file
by specifying the Symbols prefix.
ENUMERATIONS
At_Msg
Specifies a message that has no predefined meaning. This kind of message is
not used by the Environment but can be used by users to insert messages
into the log files for user-defined purposes. This message is denoted by
@@@.
Auxiliary_Msg
Specifies a general message. This kind of message is provided by the
Environment as commentary on the execution of commands. This message is
denoted by :::.
Debug_Msg
Specifies a debugging message. This kind of message is provided by the
Environment as an aid in debugging commands. This message is denoted by
???.
Dollar_Msg
Specifies a message that has no predefined meaning. This kind of message is
not used by the Environment but can be used by users to insert messages
into the log files for user-defined purposes. This message is denoted by
$$$.
Error_Msg
Specifies a message indicating a serious error. This kind of message
indicates that the operation has found some condition that prevents the
operation from completing successfully. This causes the error reaction
to be taken by the command. A message of this kind may be accompanied by a
negative message. This message is denoted by ***.
Exception_Msg
Specifies a message indicating that an exception was raised during the
execution of the command. This kind of message indicates that the
operation has found some condition that prevents the operation from
continuing. This causes the error reaction to be taken by the command. A
message of this kind may be accompanied by a negative message. This
message is denoted by %%%.
Negative_Msg
Specifies a message indicating negative progress. This kind of message is
provided by the Environment when operations do not complete successfully.
This causes the error reaction to be taken by the command. This message is
denoted by ++*.
Note_Msg
Specifies a general message. This kind of message is provided by the
Environment as commentary on the execution of commands. This message is
denoted by ---.
Position_Msg
Specifies a message indicating the position in some object where an event,
explained by another message, has occurred. This kind of message is
provided by the Environment as an aid in locating errors and other events
in large objects. This message is denoted by >>>.
Positive_Msg
Specifies a message indicating positive progress. This kind of message is
provided by the Environment when operations complete successfully. This
message is denoted by +++.
Sharp_Msg
Specifies a message that has no predefined meaning. This kind of message is
not used by the Environment but can be used by users to insert messages
into the log files for user-defined purposes. This message is denoted by
###.
Warning_Msg
Specifies a message that warns of some minor error. This kind of message
indicates that the operation has found some condition that is not quite
correct but is not serious enough to prevent the operation from
continuing. This message is denoted by !!!.
REFERENCES
type Log_Prefix
type Log_Prefixes
@node !Tools.Profile.Name
subtype Name is String;
DESCRIPTION
Defines a name.
This type accepts the complete set of special names, wildcards, context
characters, and attributes that are defined for naming objects in the
Environment. The name, however, must be unambiguous; it can resolve only
to a single object. For additional information about naming objects in
the Environment, see Parameter-Value Conventions in the Reference Summary
(RS) book.
REFERENCES
Reference Summary (RS), Parameter-Value Conventions
@node !Tools.Profile.Nil
function Nil
(Reaction : Error_Reaction := Profile.Quit;
Filter : Log_Filter := Profile.Quiet;
Prefixes : Log_Prefixes := Profile.No_Prefixes;
Width : Natural := Profile.Default_Width;
Activity : Activity_Type := Profile.Default_Activity;
Log_File : Log_Output_File := Profile.Default_Log_File)
return Response_Profile renames Response;
DESCRIPTION
Returns the profile built from the specified components.
This function builds a profile from the specified components and returns
that profile. The profile returned by this function can be tailored to
include any reaction, filter, prefixes, width, activity, and/or log file.
By default, the profile returned by this function includes the following
components:
* The Quit error reaction, which specifies that the job terminate upon the
first error without raising an exception
* The Quiet filter, which specifies that no log messages be generated
* The No_Prefixes prefix, which specifies that no log-message prefixes be
generated
* The system default line width of 77
* The activity component specified in the session response profile
* The log-file component specified in the system default profile
This function can be used in other commands to use, or to set as the
default, a profile containing the specified components.
This function renames the Response function.
PARAMETERS
Reaction : Error_Reaction := Profile.Quit;
Specifies the error-reaction component for the profile. The default is the
Quit error reaction, which causes the job to stop at the first error
without raising an exception.
Filter : Log_Filter := Profile.Quiet;
Specifies the log-filter component for the profile. The default is the Quiet
filter, which allows no messages to be added to the log file.
Prefixes : Log_Prefixes := Profile.No_Prefixes;
Specifies the log-prefixes component for the profile. The default is that no
prefixes be used.
Width : Natural := Profile.Default_Width;
Specifies the line-width component for the profile. The default is 77
columns (the value of the Default_Width constant).
Activity : Activity_Type := Profile.Default_Activity;
Specifies the activity component for the profile. The default is the
activity in the session response profile for the current session.
Log_File : Log_Output_File := Profile.Default_Log_File;
Specifies the log-file component for the profile. The default log file is
Current_Output, which is, by default, an Environment output window.
return Response_Profile;
Returns the internal representation of the profile.
REFERENCES
function Default_Profile
function Ignore
function Raise_Exception
function Response
function Verbose
function Warn
@node !Tools.Profile.No_Prefixes
No_Prefixes : constant Log_Prefixes := (Nil, Nil, Nil);
DESCRIPTION
Defines a constant that specifies that no prefixes appear before log
messages.
REFERENCES
type Log_Prefix
type Log_Prefixes
@node !Tools.Profile.Persevere
function Persevere (Response : Response_Profile := Profile.Get)
return Boolean;
DESCRIPTION
Returns a Boolean value indicating whether commands that use the specified
profile continue executing when errors are encountered--that is, whether
the error-reaction component of the profile is set either to the Persevere
enumeration or to the Raise_Error enumeration.
PARAMETERS
Response : Response_Profile := Profile.Get;
Specifies the profile for which the error-reaction component is to be
checked. The default is the job response profile for the current job.
return Boolean;
Returns True if the error-reaction component of the specified profile is set
to the Persevere enumeration or the Raise_Error enumeration; otherwise,
this function returns False.
REFERENCES
type Error_Reaction
function Propagate
procedure Set_Default_Reaction
procedure Set_Reaction
@node !Tools.Profile.Prefixes
function Prefixes (Response : Response_Profile := Profile.Get)
return Log_Prefixes;
DESCRIPTION
Returns the value of the log-prefixes component of the specified profile.
The log-prefixes component determines the log prefixes that are included
when log messages are generated.
To set the log-prefixes component in the job response profile, use the
Set_Prefixes procedure.
To set the log-prefixes component in the session response profile, use the
Set_Default_Prefixes procedure.
PARAMETERS
Response : Response_Profile := Profile.Get;
Specifies the profile for which the log-prefixes component is desired. The
default is the job response profile for the current job.
return Log_Prefixes;
Returns the value of the log-prefixes component.
REFERENCES
procedure Set_Default_Prefixes
procedure Set_Prefixes
@node !Tools.Profile.Propagate
function Propagate (Response : Response_Profile := Profile.Get)
return Boolean;
DESCRIPTION
Returns a Boolean value indicating whether commands that use the profile
raise an exception when errors are encountered--that is, whether the
error-reaction component of the profile is set to either the Propagate
enumeration or the Raise_Error enumeration.
PARAMETERS
Response : Response_Profile := Profile.Get;
Specifies the profile for which the error-reaction component is to be
checked. The default is the job response profile for the current job.
return Boolean;
Returns True if the error-reaction component of the profile is set to the
Propagate enumeration or the Raise_Error enumeration; otherwise, this
function returns False.
REFERENCES
type Error_Reaction
function Persevere
procedure Set_Default_Reaction
procedure Set_Reaction
@node !Tools.Profile.Quiet
Quiet : constant Log_Filter := Log_Filter'(others => False);
DESCRIPTION
Defines a log filter that allows no messages to be included in the log file.
This constant can be used in the Filter parameter of procedures, such as
the Set_Response procedure, to specify that no messages should appear in
the log file.
REFERENCES
constant Errors
constant Full
type Log_Filter
type Msg_Kind
constant Summary
constant Terse
@node !Tools.Profile.Raise_Exception
function Raise_Exception
(Reaction : Error_Reaction := Profile.Propagate;
Filter : Log_Filter := Profile.Filter;
Prefixes : Log_Prefixes := Profile.Prefixes;
Width : Natural := Profile.Width;
Activity : Activity_Type := Profile.Activity;
Log_File : Log_Output_File := Profile.Log_File)
return Response_Profile renames Response;
DESCRIPTION
Returns the profile built from the specified components.
This function builds a profile from the specified components and returns
that profile. The profile returned by this function can be tailored with
any reaction, filter, prefixes, width, activity, and/or log file. By default,
the profile includes the Propagate error reaction, which causes commands
to stop executing at the first error and raise an exception. For all other
components, the default is the value in the job response profile for the
current job.
This function can be used in other commands to use, or to set as the
default, a profile containing the specified components.
This function renames the Response function.
PARAMETERS
Reaction : Error_Reaction := Profile.Propagate;
Specifies the error-reaction component for the profile. The default is the
Propagate reaction, which causes commands to stop executing at the first
error and to raise an exception.
Filter : Log_Filter := Profile.Filter;
Specifies the log-filter component for the profile. The default is the filter
in the job response profile for the current job.
Prefixes : Log_Prefixes := Profile.Prefixes;
Specifies the log-prefixes component for the profile. The default is the
prefixes in the job response profile for the current job.
Width : Natural := Profile.Width;
Specifies the line-width component for the profile. The default is the width
in the job response profile for the current job.
Activity : Activity_Type := Profile.Activity;
Specifies the activity component for the profile. The default is the
activity in the job response profile for the current job.
Log_File : Log_Output_File := Profile.Log_File;
Specifies the log-file component for the profile. The default is the log file
in the job response profile for the current job.
return Response_Profile;
Returns the internal representation of the profile.
REFERENCES
function Ignore
function Nil
function Response
function Verbose
function Warn
@node !Tools.Profile.Reaction
function Reaction (Response : Response_Profile := Profile.Get)
return Error_Reaction;
DESCRIPTION
Returns the value of the error-reaction component of the specified profile.
The error-reaction component of a profile determines what action commands
are to take if an error occurs during execution. The four types of error
reactions are defined by the Error_Reaction type.
To set the error-reaction components of the job and session response
profiles, use the Set_Reaction and Set_Default_Reaction procedures,
respectively.
PARAMETERS
Response : Response_Profile := Profile.Get;
Specifies the profile from which to return the error-reaction component. The
default is the job response profile for the current job.
return Error_Reaction;
Returns the value of the error-reaction component.
REFERENCES
type Error_Reaction
function Persevere
function Propagate
procedure Set_Default_Reaction
procedure Set_Reaction
@node !Tools.Profile.Remote_Passwords
function Remote_Passwords
(Response : Response_Profile := Profile.Get)
return Remote_Passwords_Type;
DESCRIPTION
Returns the value of the remote-passwords-file component of the specified
profile.
A remote-passwords file is a text file that specifies the usernames and
passwords to be used when accessing remote machines. For further
information, see package Remote_Passwords in this book.
To obtain the value of the remote-passwords-file component of the session
response profile, use the Default_Remote_Passwords function.
PARAMETERS
Response : Response_Profile := Profile.Get;
Specifies the profile from which to return the remote-passwords-file
component. The default is the job response profile for the current job.
return Remote_Passwords_Type;
Returns the value of the remote-passwords-file component.
REFERENCES
function Default_Remote_Passwords
type Remote_Passwords_Type
procedure Set_Remote_Passwords
package Remote_Passwords
@node !Tools.Profile.Remote_Passwords_Type
subtype Remote_Passwords_Type is Directory.Object;
DESCRIPTION
Defines the subtype that represents a remote-passwords file.
This subtype defines the value for the remote-passwords-file component of a
response profile. It is of type !Implementation.Directory.Object, which is
an implementation detail of the Environment library system. For further
information, see your Rational technical representative.
A remote-passwords file is a text file that specifies the usernames and
passwords to be used when accessing remote machines. For further
information, see package Remote_Passwords in this book.
REFERENCES
package Remote_Passwords
@node !Tools.Profile.Remote_Sessions
function Remote_Sessions
(Response : Response_Profile := Profile.Get)
return Remote_Sessions_Type;
DESCRIPTION
Returns the value of the remote-sessions-file component of the specified
profile.
A remote-sessions file is a text file that specifies which session (or
account) should be used when logging into a remote machine.
To obtain the value of the remote-sessions-file component of the session
response profile, use the Default_Remote_Sessions function.
PARAMETERS
Response : Response_Profile := Profile.Get;
Specifies the profile from which to return the remote-sessions-file
component. The default is the job response profile for the current job.
return Remote_Sessions_Type;
Returns the value of the remote-sessions-file component.
REFERENCES
function Default_Remote_Sessions
type Remote_Sessions_Type
procedure Set_Default_Remote_Sessions
procedure Set_Remote_Sessions
@node !Tools.Profile.Remote_Sessions_Type
subtype Remote_Sessions_Type is Directory.Object;
DESCRIPTION
Defines the subtype that represents a remote-sessions file.
This subtype defines the value for the remote-sessions-file component of a
response profile. It is of type !Implementation.Directory.Object, which
is an implementation detail of the Environment library system. For
further information, see your Rational technical representative.
A remote-sessions file is a text file that specifies which session (or
account) should be used when logging into a remote machine.
@node !Tools.Profile.Response
function Response
(Reaction : Error_Reaction := Profile.Reaction;
Filter : Log_Filter := Profile.Filter;
Prefixes : Log_Prefixes := Profile.Prefixes;
Width : Natural := Profile.Width;
Activity : Activity_Type := Profile.Activity;
Log_File : Log_Output_File := Profile.Log_File)
return Response_Profile;
DESCRIPTION
Returns the profile built from the specified components.
This function builds a profile from the specified components and returns
that profile. The profile returned by this function can be tailored with
any reaction, filter, prefixes, width, activity, and/or log file. By default,
the profile includes the components in the job response profile for the
current job.
This function can be used in other commands to use, or to set as the
default, a profile containing the specified components.
PARAMETERS
Reaction : Error_Reaction := Profile.Reaction;
Specifies the error-reaction component for the response profile. The default
is the reaction in the job response profile for the current job.
Filter : Log_Filter := Profile.Filter;
Specifies the log-filter component for the profile. The default is the filter
in the job response profile for the current job.
Prefixes : Log_Prefixes := Profile.Prefixes;
Specifies the log-prefixes component for the profile. The default is the
prefixes in the job response profile for the current job.
Width : Natural := Profile.Width;
Specifies the line-width component for the profile. The default is the width
in the job response profile for the current job.
Activity : Activity_Type := Profile.Activity;
Specifies the activity component for the profile. The default is the
activity in the job response profile for the current job.
Log_File : Log_Output_File := Profile.Log_File;
Specifies the log-file component for the profile. The default is log file in
the job response profile for the current job.
return Response_Profile;
Returns the internal representation of the profile.
REFERENCES
function Ignore
function Nil
function Raise_Exception
function Verbose
function Warn
@node !Tools.Profile.Response_Profile
type Response_Profile is private;
DESCRIPTION
Defines a response profile.
This type defines the set of values that is collectively called a response
profile. These values determine eight components of job behavior: error
reaction, a log filter, a set of log-message prefixes, a log width, a log
output file, a remote-passwords file, a remote-sessions file, and an
activity. All of these are described further in the introduction to this
package.
@node !Tools.Profile.Set
procedure Set (Profile : Response_Profile);
procedure Set (Profile : String;
Status : in out Simple_Status.Condition);
DESCRIPTION
Sets the job response profile for the remainder of the current job to be
the specified profile.
At job initialization, the values of the job response profile are obtained
from the session response profile. This procedure can be used to change the
job response profile to be the specified profile.
You can specify a profile using the string representation or using any of
the following functions, which return the internal representation of a
profile: Ignore, Nil, Raise_Error, Response, Set, Verbose, and Warn.
Changes made to the job response profile in the middle of a job apply to
the remainder of the job. They do not affect parts of the job that have
already executed.
You can also set the job response profile using the Set_Response procedure.
PARAMETERS
Profile : Response_Profile;
Specifies the internal representation of the profile.
Profile : String;
Specifies the string representation of the profile.
Status : in out Simple_Status.Condition;
Returns the status indicating that the procedure has executed correctly
or, if there is an error, a message indicating the type of error. To
convert the status to a string representation and enter it into the log
file, use the Log.Put_Condition procedure.
REFERENCES
procedure Set_Response
procedure Log.Put_Condition
Programming Tools (PT), package Simple_Status
@node !Tools.Profile.Set_Activity
procedure Set_Activity (Activity : Activity_Type);
DESCRIPTION
Sets the activity component in the job response profile for the current
job.
The activity component specifies the activity file to be used for mapping
between subsystems and specific releases of those subsystems. For further
information about activities, see the Project Management (PM) book.
This procedure is for programmatic use only. To set the activity file to be
used by a particular command, use the Response parameter of that command.
To set the default activity file for a session, use the
!Commands.Activity.Set_Default procedure, or edit the Profile.Activity
session switch directly.
PARAMETERS
Activity : Activity_Type;
Specifies the value to which the activity component is to be set. This
value must be of type Activity_Type; that is, it must be a file handle.
REFERENCES
function Activity
type Activity_Type
function Set_Default_Activity
Project Management (PM)
@node !Tools.Profile.Set_Default
procedure Set_Default (Profile : Response_Profile);
procedure Set_Default (Profile : String;
Status : in out Simple_Status.Condition);
DESCRIPTION
Sets the session response profile for the current session.
When your default session is created, the values of the session response
profile are obtained from the system default profile. Subsequent sessions
initially assume the values of your default session. This procedure can
then be used to change the session response profile for your current
session to be a specified profile. Note that the values of the session
response profile are also set in the session switches that have the
processor name "Profile."
You can specify a profile to this procedure using the string representation
or using any of the following functions, which return the internal
representation of a profile: Ignore, Nil, Raise_Error, Response, Set,
Verbose, and Warn.
You can also change the session response profile by editing the appropriate
session switches or using the Set_Default_Response procedure.
PARAMETERS
Profile : Response_Profile;
Specifies the internal representation of a profile.
Profile : String;
Specifies the string representation of a profile.
Status : in out Simple_Status.Condition;
Returns the status indicating that the procedure has executed correctly
or, if there is an error, a message indicating the type of error. To
convert the status to a string representation and enter it into the log
file, use the Log.Put_Condition procedure.
REFERENCES
function Ignore
function Nil
function Raise_Exception
function Response
procedure Set_Default_Response
function Verbose
function Warn
procedure Log.Put_Condition
Programming Tools (PT), package Simple_Status
@node !Tools.Profile.Set_Default_Activity
procedure Set_Default_Activity (Activity : Activity_Type);
DESCRIPTION
Sets the activity component in the session response profile for the current
session.
The activity component specifies the activity file to be used for mapping
between subsystems and specific releases of those subsystems. For further
information about activities, see the Project Management (PM) book.
This procedure is for programmatic use only. To set the default activity
file for a session, use the !Commands.Activity.Set_Default procedure, or
edit the Profile.Activity session switch directly.
PARAMETERS
Activity : Activity_Type;
Specifies the activity to which the activity component is to be set. This
value must be of subtype Activity_Type.
REFERENCES
type Activity_Type
function Default_Activity
procedure Set_Activity
Project Management (PM)
@node !Tools.Profile.Set_Default_Filter
procedure Set_Default_Filter (Auxiliaries : Boolean := True;
Diagnostics : Boolean := True;
Notes : Boolean := True;
Positives : Boolean := True;
Negatives : Boolean := True;
Positions : Boolean := True;
Warnings : Boolean := True;
Errors : Boolean := True;
Exceptions : Boolean := True;
Sharps : Boolean := True;
Dollars : Boolean := True;
Ats : Boolean := True);
DESCRIPTION
Sets the filter component to include the specified kinds of messages; the
filter component is set in the session response profile for the current
session.
The log-filter component is a collection of Boolean values, one for each
message kind. This procedure sets the value for each message kind to be
the specified value. Message kinds whose value is True are included in the
log file.
PARAMETERS
Auxiliaries : Boolean := True;
Specifies whether to include auxiliary messages (denoted by :::) in the log
file. The default, True, is to include auxiliary messages.
Diagnostics : Boolean := True;
Specifies whether to include diagnostic (debug) messages (denoted by ???)
in the log file. The default, True, is to include diagnostic messages.
Notes : Boolean := True;
Specifies whether to include note messages (denoted by ---) in the log file.
The default, True, is to include note messages.
Positives : Boolean := True;
Specifies whether to include positive messages (denoted by +++) in the log
file. The default, True, is to include positive messages.
Negatives : Boolean := True;
Specifies whether to include negative messages (denoted by ++*) in the log
file. The default, True, is to include negative messages.
Positions : Boolean := True;
Specifies whether to include position messages (denoted by >>>) in the log
file. The default, True, is to include position messages.
Warnings : Boolean := True;
Specifies whether to include warning messages (denoted by !!!) in the log
file. The default, True, is to include warning messages.
Errors : Boolean := True;
Specifies whether to include error messages (denoted by ***) in the log
file. The default, True, is to include error messages.
Exceptions : Boolean := True;
Specifies whether to include exception messages (denoted by %%%) in the log
file. The default, True, is to include exception messages.
Sharps : Boolean := True;
Specifies whether to include messages denoted with the sharp sign (###) in
the log file. The default is to include sharp messages.
Dollars : Boolean := True;
Specifies whether to include messages denoted with the dollar sign ($$$) in
the log file. The default is to include dollar messages.
Ats : Boolean := True;
Specifies whether to include messages denoted with the at sign (@@@) in the
log file. The default is to include at messages.
REFERENCES
function Filter
procedure Include_In_Default
function Includes
type Msg_Kind
procedure Set_Default_Filter
@node !Tools.Profile.Set_Default_Filter
procedure Set_Default_Filter (Filter : Log_Filter);
DESCRIPTION
Sets the filter component to be the specified filter; the filter component is
set in the session response profile for the current session.
The log-filter component represents a collection of Boolean values, one for
each message kind. This procedure sets the collection of values to be the
collection in the named filter. Message kinds whose value is True are
included in the log file.
PARAMETERS
Filter : Log_Filter;
Specifies the filter to which the filter component is to be set. This
parameter accepts any predefined filter, including the constants in this
package that define filters. These constants are described below:
Errors Specifies that only negative (++*), warning (!!!),
error (***), and exception (%%%) messages are to be
included in the log file.
Full Specifies that all messages except debug messages
(denoted by ???) are to be included in the log file.
Quiet Specifies that no messages are to be included in the
log file.
Summary Specifies that only positive (+++) and negative (++*)
messages are to be included in the log file.
Terse Specifies that the following kinds of messages are to
be included in the log file: at (@@@), dollar ($$$),
error (***), exception (%%%), negative (++*),
position (>>>), positive (+++), sharp (###), and
warning (!!!).
REFERENCES
function Filter
procedure Include_In_Default
function Includes
type Msg_Kind
procedure Set_Default_Filter
@node !Tools.Profile.Set_Default_Log_File
procedure Set_Default_Log_File (Log_File : Log_Output_File);
DESCRIPTION
Sets the log-file component in the session response profile for the current
session.
The log-file component specifies where log output is to be sent. Log output
can be sent to any of the four destinations defined by the Log_Output_File
type.
To set the log-file component in the job response profile, use the
Set_Log_File procedure.
To obtain the log-file component of a specified profile, use the Log_File
function.
For further information about directing log output, see the Key Concepts
of this book.
PARAMETERS
Log_File : Log_Output_File;
Specifies the log file to which the log-file component is to be set. This
parameter accepts the four destinations defined by the Log_Output_File
type:
Use_Error Specifies that log output should be sent to
Current_Error. By default, Current_Error directs
output to Standard_Error; however, Current_Error can
be redirected to another location.
Use_Output Specifies that log output should be sent to
Current_Output. By default, Current_Output directs
output to Standard_Output; however, Current_Output
can be redirected to another location.
Use_Standard_Error Specifies that log output should be sent to
Standard_Error, which is the Environment message
window. Standard_Error cannot be redirected.
Use_Standard_Output Specifies that log output should be sent to
Standard_Output, which is an Environment output
window. Standard_Output cannot be redirected.
EXAMPLES
The system default profile specifies that log output is to be sent to an
Environment output window. Environment output windows are major windows
and often replace other major windows when they are created.
Suppose you want to change the log-output file so that log output is sent
to the message window so that major windows are not replaced when log
output is generated. The following command sets the log-file component of
the session response profile for the current session to be Use_Error:
Profile.Set_Default_Log_File (Log_File => Profile.Use_Error);
Use_Error specifies that log output should be sent to Current_Error, which
is, by default, the message window. Use_Error appears as the new value for
the Profile.Log_File switch in the switch file for your current session.
REFERENCES
function Log_File
type Log_Output_File
procedure Set_Log_File
@node !Tools.Profile.Set_Default_Prefixes
procedure Set_Default_Prefixes (Prefixes : Log_Prefixes);
procedure Set_Default_Prefixes
(Prefix1, Prefix2, Prefix3 : Log_Prefix := Nil);
DESCRIPTION
Sets the log-prefixes component to be the specified set of prefixes; the
prefixes component is set in the session response profile for the current
session.
The log-prefixes component determines the log prefixes that are included
when log messages are generated.
To set the log-prefixes component in the job response profile, use the
Set_Prefixes procedure.
To obtain the log-prefixes component for a particular profile, use the
Prefixes function.
PARAMETERS
Prefixes : Log_Prefixes;
Specifies the set of three prefixes to which the log-prefixes component is to
be set.
Prefix1 : Log_Prefix := Nil;
Specifies the prefix to which the first log-prefix value is to be set.
Prefix2 : Log_Prefix := Nil;
Specifies the prefix to which the second log-prefix value is to be set.
Prefix3 : Log_Prefix := Nil;
Specifies the prefix to which the third log-prefix value is to be set.
REFERENCES
type Log_Prefix
type Log_Prefixes
function Prefixes
procedure Set_Prefixes
@node !Tools.Profile.Set_Default_Reaction
procedure Set_Default_Reaction (Reaction : Error_Reaction);
DESCRIPTION
Sets the error-reaction component of the session response profile for the
current session.
The error-reaction component of a profile determines what action to take if
an error occurs during execution of a command.
To set the error-reaction component of a job response profile, use the
Set_Reaction procedure.
To obtain the value of the error-reaction component of a specified profile,
use the Reaction function.
PARAMETERS
Reaction : Error_Reaction;
Specifies the error reaction to which the error-reaction component is to be
set. The four types of error reactions are defined by the Error_Reaction
type:
Persevere Specifies that the command continue executing as best
it can after errors are discovered. No exception is
raised.
Propagate Specifies that the command terminate at its first
error. An exception is raised.
Quit Specifies that the command terminate at its first
error. No exception is raised.
Raise_Error Specifies that the command continue executing as best
it can after errors are discovered. At some point,
an exception is raised.
REFERENCES
type Error_Reaction
function Persevere
function Propagate
function Reaction
procedure Set_Reaction
@node !Tools.Profile.Set_Default_Remote_Passwords
procedure Set_Default_Remote_Passwords
(Passwords : Remote_Passwords_Type);
DESCRIPTION
Sets the remote-passwords-file component in the session response profile for
the current session.
A remote-passwords file is a text file that specifies the usernames and
passwords to be used when accessing remote machines. For further
information, see package Remote_Passwords in this book.
This procedure is for programmatic use only. To set the default
remote-passwords file for a session, use the Remote_Passwords.Set_Default
procedure, or edit the Profile.Remote_Passwords session switch directly.
PARAMETERS
Passwords : Remote_Passwords_Type;
Specifies the value to which the remote-passwords-file component is to be
set. This value must be of subtype Remote_Passwords_Type.
REFERENCES
function Default_Remote_Passwords
type Remote_Passwords_Type
procedure Set_Remote_Passwords
package Remote_Passwords
@node !Tools.Profile.Set_Default_Remote_Sessions
procedure Set_Default_Remote_Sessions
(Sessions : Remote_Sessions_Type);
DESCRIPTION
Sets the remote-sessions-file component in the session response profile for
the current session.
A remote-sessions file is a text file that specifies which session (or
account) should be used when logging into a remote machine.
This procedure is for programmatic use only. To set the default
remote-sessions file for a session, edit the Profile.Remote_Sessions session
switch directly.
PARAMETERS
Sessions : Remote_Sessions_Type;
Specifies the value to which the remote-sessions-file component is to be
set. This value must be of subtype Remote_Sessions_Type.
REFERENCES
function Default_Remote_Sessions
type Remote_Sessions_Type
procedure Set_Remote_Sessions
@node !Tools.Profile.Set_Default_Response
procedure Set_Default_Response
(Reaction : Error_Reaction :=
Profile.Reaction (Profile.Get_Default);
Filter : Log_Filter :=
Profile.Filter (Profile.Get_Default);
Prefixes : Log_Prefixes :=
Profile.Prefixes (Profile.Get_Default);
Width : Natural :=
Profile.Width (Profile.Get_Default);
Activity : Activity_Type :=
Profile.Activity (Profile.Get_Default);
Log_File : Log_Output_File :=
Profile.Log_File (Profile.Get_Default));
DESCRIPTION
Sets the session response profile for the current session to have the
specified reaction, filter, prefixes, width, activity, and log-file
components.
When your default session is created, the values of the session response
profile are obtained from the system default profile. Subsequent sessions
initially assume the values of your default session. This procedure can be
used to change the session response profile for your current session to be
the specified profile. Note that these values are also set in the session
switches that have the processor name "Profile."
The default parameters specify the values of the current session response
profile, which have the effect of not changing the session default profile.
However, any of the parameters can be changed to affect only some of the
values.
You can also change the session response profile by editing the appropriate
session switches or using the Set_Default procedure.
PARAMETERS
Reaction : Error_Reaction := Profile.Reaction (Profile.Get_Default);
Specifies the error reaction to which the error-reaction component is to be
set. The default does not change the value of the error-reaction
component.
Filter : Log_Filter := Profile.Filter (Profile.Get_Default);
Specifies the filter to which the filter component is to be set. The default
does not change the value of the filter component.
Prefixes : Log_Prefixes := Profile.Prefixes (Profile.Get_Default);
Specifies the set of log prefixes to which the prefixes component is to be
set. The default does not change the value of the prefixes component.
Width : Natural := Profile.Width (Profile.Get_Default);
Specifies the width to which the line-width component is to be set. The
default does not change the value of the width component.
Activity : Activity_Type := Profile.Activity (Profile.Get_Default);
Specifies the activity to which the activity component is to be set. The
default does not change the value of the activity component.
Log_File : Log_Output_File := Profile.Log_File (Profile.Get_Default);
Specifies the log output file to which the log-file component is to be set.
The default does not change the value of the log-file component.
REFERENCES
procedure Set_Default
@node !Tools.Profile.Set_Default_Width
procedure Set_Default_Width (Width : Natural);
DESCRIPTION
Sets the line-width component in the session response profile for the
current session.
The line-width component specifies the maximum length of lines in the log
file. If a log message is longer than the width defined in the profile, the
log message is continued on the next line.
To set the line-width component in a job response profile, use the
Set_Width procedure.
To obtain the value of the line-width component of a particular profile,
use the Width function.
PARAMETERS
Width : Natural;
Specifies the width to which the line-width component is to be set. The
maximum width is 1,023 columns.
REFERENCES
procedure Set_Width
function Width
@node !Tools.Profile.Set_Filter
procedure Set_Filter (Auxiliaries : Boolean := True;
Diagnostics : Boolean := True;
Notes : Boolean := True;
Positives : Boolean := True;
Negatives : Boolean := True;
Positions : Boolean := True;
Warnings : Boolean := True;
Errors : Boolean := True;
Exceptions : Boolean := True;
Sharps : Boolean := True;
Dollars : Boolean := True;
Ats : Boolean := True);
DESCRIPTION
Sets the filter component to include the specified kinds of messages; the
filter component is set in the job response profile for the current job.
The log-filter component represents a collection of Boolean values, one for
each message kind. This procedure sets the value for each message kind to
be that specified. Message kinds whose value is True are included in the
log file.
PARAMETERS
Auxiliaries : Boolean := True;
Specifies whether to include auxiliary messages (denoted by :::) in the log
file. The default, True, is to include auxiliary messages.
Diagnostics : Boolean := True;
Specifies whether to include diagnostic (debug) messages (denoted by ???)
in the log file. The default, True, is to include diagnostic messages.
Notes : Boolean := True;
Specifies whether to include note messages (denoted by ---) in the log file.
The default, True, is to include note messages.
Positives : Boolean := True;
Specifies whether to include positive messages (denoted by +++) in the log
file. The default, True, is to include positive messages.
Negatives : Boolean := True;
Specifies whether to include negative messages (denoted by ++*) in the log
file. The default, True, is to include negative messages.
Positions : Boolean := True;
Specifies whether to include position messages (denoted by >>>) in the log
file. The default, True, is to include position messages.
Warnings : Boolean := True;
Specifies whether to include warning messages (denoted by !!!) in the log
file. The default, True, is to include warning messages.
Errors : Boolean := True;
Specifies whether to include error messages (denoted by ***) in the log
file. The default, True, is to include error messages.
Exceptions : Boolean := True;
Specifies whether to include exception messages (denoted by %%%) in the log
file. The default, True, is to include exception messages.
Sharps : Boolean := True;
Specifies whether to include messages denoted with the sharp sign (###) in
the log file. The default is to include sharp messages.
Dollars : Boolean := True;
Specifies whether to include messages denoted with the dollar sign ($$$) in
the log file. The default is to include dollar messages.
Ats : Boolean := True;
Specifies whether to include messages denoted with the at sign (@@@) in the
log file. The default is to include at messages.
REFERENCES
function Filter
procedure Include
function Includes
type Msg_Kind
procedure Set_Filter
@node !Tools.Profile.Set_Filter
procedure Set_Filter (Filter : Log_Filter);
DESCRIPTION
Sets the filter component to be the specified filter; the filter component is
set in the job response profile for the current job.
The log-filter component represents a collection of Boolean values, one for
each message kind. This procedure sets the collection of values to be the
collection in the named filter. Message kinds whose value is True are
included in the log file.
PARAMETERS
Filter : Log_Filter;
Specifies the filter to which the filter component is to be set. This
parameter accepts any predefined filter, including the constants in this
package that define filters. These constants are described below:
Errors Specifies that only negative (++*), warning (!!!),
error (***), and exception (%%%) messages are to be
included in the log file.
Full Specifies that all messages except debug messages
(denoted by ???) are to be included in the log file.
Quiet Specifies that no messages are to be included in the
log file.
Summary Specifies that only positive (+++) and negative (++*)
messages are to be included in the log file.
Terse Specifies that the following kinds of messages are to
be included in the log file: at (@@@), dollar ($$$),
error (***), exception (%%%), negative (++*),
position (>>>), positive (+++), sharp (###), and
warning (!!!).
REFERENCES
function Filter
proceudure Include
type Msg_Kind
procedure Set_Filter
@node !Tools.Profile.Set_Log_File
procedure Set_Log_File (Log_File : Log_Output_File);
DESCRIPTION
Sets the log-file component in the job response profile for the current job.
The log-file component specifies where log output is to be sent. Log output
can be sent to any of the four destinations defined by the Log_Output_File
type.
To set the log-file component in the session response profile, use the
Set_Default_Log_File procedure.
To obtain the log-file component of a specified profile, use the Log_File
function.
For further information about directing log output, see the Key Concepts
of this book.
PARAMETERS
Log_File : Log_Output_File;
Specifies the log file to which the log-file component is to be set. This
parameter accepts the four destinations defined by type Log_Output_File:
Use_Error Specifies that log output should be sent to
Current_Error. By default, Current_Error
directs output to Standard_Error; however,
Current_Error can be redirected to another
location.
Use_Output Specifies that log output should be sent to
Current_Output. By default, Current_Output
directs output to Standard_Output; however,
Current_Output can be redirected to another
location.
Use_Standard_Error Specifies that log output should be sent to
Standard_Error, which is the Environment
message window. Standard_Error cannot be
redirected.
Use_Standard_Output Specifies that log output should be sent to
Standard_Output, which is an Environment
output window. Standard_Output cannot be
redirected.
EXAMPLES
According to the system default profile, log output is sent to an
Environment output window. Environment output windows are major windows
and often replace other major windows when they are created.
Suppose for a particular job that you want to change the log output file to
send log output to the message window so that major windows are not
replaced when log output is generated. The following command sets the
log-file component of the job response profile for the current job to be
Use_Error:
Profile.Set_Log_File (Log_File => Profile.Use_Error);
Use_Error specifies that log output should be sent to Current_Error, which
is, by default, the message window. This log file is used for the remainder
of the job.
REFERENCES
function Log_File
type Log_Output_File
procedure Set_Default_Log_File
@node !Tools.Profile.Set_Prefixes
procedure Set_Prefixes (Prefixes : Log_Prefixes);
procedure Set_Prefixes
(Prefix1, Prefix2, Prefix3 : Log_Prefix := Nil);
DESCRIPTION
Sets the log-prefixes component to be the specified set of prefixes; the
prefixes component is set in the job response profile for the current job.
The log-prefixes component determines the log prefixes that are included
when log messages are generated.
To set the log-prefixes component in the session response profile, use the
Set_Default_Prefixes procedure.
To obtain the log-prefixes component for a particular profile, use the
Prefixes function.
PARAMETERS
Prefixes : Log_Prefixes;
Specifies the set of three prefixes to which the log-prefixes component is to
be set.
Prefix1 : Log_Prefix := Nil;
Specifies the prefix to which the first log-prefix value is to be set.
Prefix2 : Log_Prefix := Nil;
Specifies the prefix to which the second log-prefix value is to be set.
Prefix3 : Log_Prefix := Nil;
Specifies the prefix to which the third log-prefix value is to be set.
REFERENCES
type Log_Prefix
type Log_Prefixes
function Prefixes
procedure Set_Default_Prefixes
@node !Tools.Profile.Set_Reaction
procedure Set_Reaction (Reaction : Error_Reaction);
DESCRIPTION
Sets the error-reaction component of the job response profile for the
current job.
The error-reaction component of a profile determines what action to take if
an error occurs during execution of a command.
To set the error-reaction component of a session response profile, use the
Set_Default_Reaction procedure.
To obtain the value of the error-reaction component of a specified profile,
use the Reaction function.
PARAMETERS
Reaction : Error_Reaction;
Specifies the error-reaction to which to set the error-reaction component
of the session response profile. The four types of error reactions are
defined by the Error_Reaction type:
Persevere Specifies that the command continue executing as best
it can after errors are discovered. No exception is
raised.
Propagate Specifies that the command terminate at its first
error. An exception is raised. If no other exception
is defined for the command, the Error exception is
raised.
Quit Specifies that the command terminate at its first
error. No exception is raised.
Raise_Error Specifies that the command continue executing as best
it can after errors are discovered. At some point,
an exception is raised. If no other exception is
defined for the command, the Error exception is
raised.
REFERENCES
type Error_Reaction
function Persevere
function Propagate
function Reaction
procedure Set_Default_Reaction
@node !Tools.Profile.Set_Remote_Passwords
procedure Set_Remote_Passwords
(Passwords : Remote_Passwords_Type);
DESCRIPTION
Sets the remote-passwords-file component in the job response profile for the
current job.
A remote-passwords file is a text file that specifies the usernames and
passwords to be used when accessing remote machines. For further
information, see package Remote_Passwords in this book.
This procedure is for programmatic use only. To set the default
remote-passwords file to be used by a particular command, use the Response
parameter of that command. To set the default remote-passwords file for a
session, use the Remote_Passwords.Set_Default procedure, or edit the
Profile.Remote_Passwords session switch directly.
PARAMETERS
Passwords : Remote_Passwords_Type;
Specifies the value to which the remote-passwords-file component is to be
set. This value must be of subtype Remote_Passwords_Type.
REFERENCES
function Remote_Passwords
type Remote_Passwords_Type
procedure Set_Default Remote_Passwords
package Remote_Passwords
@node !Tools.Profile.Set_Remote_Sessions
procedure Set_Remote_Sessions (Sessions : Remote_Sessions_Type);
DESCRIPTION
Sets the remote-sessions-file component in the job response profile for the
current job.
A remote-sessions file is a text file that specifies which session (or
account) should be used when logging into a remote machine.
This procedure is for programmatic use only. To set the default
remote-sessions file to be used by a particular command, use the Response
parameter of that command. To set the default remote-sessions file for a
session, edit the Profile.Remote_Sessions session switch.
PARAMETERS
Sessions : Remote_Sessions_Type;
Specifies the value to which the remote-sessions-file component is to be
set. This value must be of subtype Remote_Sessions_Type.
REFERENCES
function Remote_Sessions
type Remote_Sessions_Type
procedure Set_Default_Remote_Sessions
@node !Tools.Profile.Set_Response
procedure Set_Response
(Reaction : Error_Reaction := Profile.Reaction;
Filter : Log_Filter := Profile.Filter;
Prefixes : Log_Prefixes := Profile.Prefixes;
Width : Natural := Profile.Width;
Activity : Activity_Type := Profile.Activity;
Log_File : Log_Output_File := Profile.Log_File);
DESCRIPTION
Sets the job response profile for the remainder of the current job to have
the specified reaction, filter, prefixes, width, activity, and log-file
values.
At job initialization, the values of the job response profile are obtained
from the session response profile. This procedure can be used to change the
job response profile. The default parameters specify the current values of
the job response profile, which have the effect of not changing the job
response profile. However, any of the parameters can be changed to affect
only some of the values.
Changes made to the job response profile in the middle of a job apply to
the remainder of the job. They do not affect parts of the job that have
already executed.
You can also set the job response profile using the Set procedure.
PARAMETERS
Reaction : Error_Reaction := Profile.Reaction;
Specifies the error reaction to which the error-reaction component is to be
set. The default does not change the value of the error-reaction
component.
Filter : Log_Filter := Profile.Filter;
Specifies the filter to which the filter component is to be set. The default
does not change the value of the filter component.
Prefixes : Log_Prefixes := Profile.Prefixes;
Specifies the set of log prefixes to which the prefixes component is to be
set. The default does not change the value of the prefixes component.
Width : Natural := Profile.Width;
Specifies the width to which the line-width component is to be set. The
default does not change the value of the width component.
Activity : Activity_Type := Profile.Activity;
Specifies the activity to which the activity component is to be set. The
default does not change the value of the activity component.
Log_File : Log_Output_File := Profile.Log_File;
Specifies the log output file to which the log-file component is to be set.
The default does not change the value of the log-file component.
REFERENCES
procedure Set
@node !Tools.Profile.Set_Width
procedure Set_Width (Width : Natural);
DESCRIPTION
Sets the line-width component in the job response profile for the current
job.
The line-width component specifies the maximum length of lines in the log
file. If a log message is longer than the width defined in the profile, the
log message is continued on the next line. Messages that have been
continued are prefixed with the ellipsis (...) symbol.
To set the line-width component in the session response profile, use the
Set_Default_Width procedure.
To obtain the value of the line-width component in a specified profile, use
the Width function.
PARAMETERS
Width : Natural;
Specifies the width to which the line-width component is to be set. The
maximum width is 1,023 columns.
REFERENCES
procedure Set_Default_Width
function Width
@node !Tools.Profile.Summary
Summary : constant Log_Filter := Log_Filter'(Positive_Msg |
Negative_Msg => True, others => False);
DESCRIPTION
Defines a log filter that allows only positive (+++) and negative (++*)
messages to be included in the log file.
This constant can be used in the Filter parameter of procedures, such as
the Set_Response procedure, to specify that only these two kinds of
messages should appear in log file.
REFERENCES
constant Errors
constant Full
type Log_Filter
type Msg_Kind
constant Quiet
constant Terse
@node !Tools.Profile.Terse
Terse : constant Log_Filter := Log_Filter'(False, False, False,
others => True);
DESCRIPTION
Defines a log filter that allows only terse messages to be included in the
log file.
Terse messages include the following kinds: at (@@@), dollar ($$$), error
(***), exception (%%%), negative (++*), position (>>>), positive (+++),
sharp (###), and warning (!!!).
This constant can be used in the Filter parameter of procedures, such as
the Set_Response procedure, to specify that only this terse set of
messages should appear in the log file.
REFERENCES
constant Full
constant Errors
type Log_Filter
type Msg_Kind
constant Quiet
constant Summary
@node !Tools.Profile.Value
function Value (Image : String := Profile.Get)
return Response_Profile;
DESCRIPTION
Returns the internal representation of the specified profile.
Given a string representation of a response profile, this function returns
the internal representation of that profile.
The procedural form of this command is Convert. To obtain the string
representation of a profile, use the Image function.
For further information about the representation of profiles, see the
introduction to this package.
PARAMETERS
Image : String := Profile.Get;
Specifies the string representation of the profile for which to return the
internal representation. The default is the job response profile for the
current job.
return Response_Profile;
Returns the internal representation of the response profile.
REFERENCES
procedure Convert
function Image
@node !Tools.Profile.Verbose
function Verbose
(Reaction : Error_Reaction := Profile.Reaction;
Filter : Log_Filter := Profile.Full;
Prefixes : Log_Prefixes := Profile.Prefixes;
Width : Natural := Profile.Width;
Activity : Activity_Type := Profile.Activity;
Log_File : Log_Output_File := Profile.Log_File)
return Response_Profile renames Response;
DESCRIPTION
Returns the profile built from the specified components.
This function builds a profile from the specified components and returns
that profile. The profile returned by this function can be tailored with
any reaction, filter, prefixes, width, activity, and/or log file. By default,
the profile includes the Full log filter, which specifies that all messages
except debug messages (denoted by ???) be included in the log file. For all
other components, the default is the value in the job response profile for
the current job.
This function can be used in other commands to use, or to set as the
default, a profile containing the specified components.
This function renames the Response function.
PARAMETERS
Reaction : Error_Reaction := Profile.Reaction;
Specifies the error-reaction component for the profile. The default is the
error reaction in the job response profile for the current job.
Filter : Log_Filter := Profile.Full;
Specifies the log-filter component for the response profile. The default is
the Full filter, which includes all messages except debug messages (denoted
by ???).
Prefixes : Log_Prefixes := Profile.Prefixes;
Specifies the log-prefixes component for the profile. The default is the
prefixes in the job response profile for the current job.
Width : Natural := Profile.Width;
Specifies the line-width component for the profile. The default is the width
in the job response profile for the current job.
Activity : Activity_Type := Profile.Activity;
Specifies the activity component for the profile. The default is the
activity in the job response profile for the current job.
Log_File : Log_Output_File := Profile.Log_File;
Specifies the log-file component for the profile. The default is the log file
specified in the job response profile for the current job.
return Response_Profile;
Returns the internal representation of the profile.
REFERENCES
function Ignore
function Nil
function Raise_Exception
function Response
function Warn
@node !Tools.Profile.Warn
function Warn (Reaction : Error_Reaction := Profile.Persevere;
Filter : Log_Filter := Profile.Full;
Prefixes : Log_Prefixes := Profile.Prefixes;
Width : Natural := Profile.Width;
Activity : Activity_Type := Profile.Activity;
Log_File : Log_Output_File := Profile.Log_File)
return Response_Profile renames Response;
DESCRIPTION
Returns the profile built from the specified components.
This function builds a profile from the specified components and returns
that profile. The profile returned by this function can be tailored with
any reaction, filter, prefixes, width, activity, and/or log file.
By default, the profile includes the Persevere error reaction and the Full
log filter. The Persevere error reaction specifies that commands continue to
execute without raising an exception when errors are encountered. The Full
filter specifies that all messages except debug messages (denoted by ???) be
included in the log file. For all other components, the profile uses the
components in the job response profile for the current job.
This function can be used in other commands to use, or to set as the
default, a profile containing the specified components.
This function renames the Response function.
PARAMETERS
Reaction : Error_Reaction := Profile.Persevere;
Specifies the error-reaction component for the profile. The default is the
Persevere reaction.
Filter : Log_Filter := Profile.Full;
Specifies the log-filter component for the profile. The default is the Full
filter, which includes all messages except debug messages.
Prefixes : Log_Prefixes := Profile.Prefixes;
Specifies the log-prefixes component for the profile. The default is the
prefixes in the job response profile for the current job.
Width : Natural := Profile.Width;
Specifies the line-width component for the profile. The default is the width
in the job response profile for the current job.
Activity : Activity_Type := Profile.Activity;
Specifies the activity component for the profile. The default is the
activity in the job response profile for the current job.
Log_File : Log_Output_File := Profile.Log_File;
Specifies the log-file component for the profile. The default is the log file
in the job response profile for the current job.
return Response_Profile;
Returns the internal representation of the profile.
REFERENCES
function Ignore
function Nil
function Raise_Exception
function Response
function Verbose
@node !Tools.Profile.Width
function Width (Response : Response_Profile := Profile.Get)
return Natural;
DESCRIPTION
Returns the value of the line-width component in the specified profile.
The line-width component specifies the maximum length of lines in the log
file. If a log message is longer than the width defined in the profile, the
log message is continued on the next line. Messages that have been
continued are prefixed with the ellipsis (...) symbol.
To set the line-width component in the job and session response profiles,
use the Set_Width and Set_Default_Width procedures, respectively.
PARAMETERS
Response : Response_Profile := Profile.Get;
Specifies the profile from which to return the line width. The default is
the job response profile for the current job.
return Natural;
Returns the value of the line-width component.
@node !Commands.Program
Package Program provides procedures that can be called in user-developed
programs. In particular, commands in this package can be called by
programs such as servers that run independent of a particular session.
Commands in this package can be included in a program to change the
identity of the job, control interaction with other jobs, and initiate
other jobs from the current job.
For commands that execute jobs across R1000s that are connected by a
network, see package Remote, also in this book.
RESOURCES IN PACKAGE PROGRAM
The commands in package Program fall into several functional groups. Types
and constants are not included in this list.
Changing the access-control identity of a job: Change_Identity
Starting a new job: Create_Job, Run_Job
Running commands as part of the current job: Run
Determining whether a job has started correctly: Started_Successfully
Instructing one job to wait for another: Wait_For
Obtaining the current load view: Current
KEY CONCEPTS FOR PACKAGE PROGRAM
Package Program provides procedures that can be called in a user-developed
program to cause it to programmatically change certain features of the job
under which it is executing. You can call these procedures in a program to
control the access-control identity of the job and its interaction with
other jobs. You can also use the procedures to start new jobs from within
an existing job.
The following subsections contain further information about:
* Running a set of procedures as part of the current job
* Starting new jobs programmatically
* Instructing one job to wait for another
* Changing the access-control identity of a job
Running a Set of Procedures as Part of the Current Job
Package Program contains the Run procedure for running a set of procedures
as part of the current job.
The Run procedure can be called in a program to cause another program to
compile, link, and execute the Ada statements specified. This procedure
is useful for building programs that dynamically run different sets of
operations.
The Ada statements specified to the Run procedure must be in the form of a
string. The Ada statements can be any series of statements that can be
placed between a begin/end pair. (The begin/end pair is implicit.)
Note that the Ada statements must run to completion before this procedure
completes; they are not run as a separate job. For information about
starting a new job from an existing job, see "Starting New Jobs
Programmatically," below.
Starting New Jobs Programmatically
Package Program contains two procedures for starting new jobs
programmatically:
* Create_Job
* Run_Job
These two procedures accept a series of Ada statements in the form of a
string and then create a new job under which to execute those statements.
The Ada statements can be any series of statements that can be placed
within a begin/end pair.
The only difference between the procedures is that Create_Job returns the
job number and a status indicating whether or not the job has started
successfully; Run_Job does not return job number or status information.
The following subsections describe various characteristics of the job
created by the Create_Job or Run_Job procedures, including:
* The access-control identity of the job
* The username and session under which the new job is to run
* The devices used by the new job for Standard_Input, Standard_Output,
and Standard_Error
Access-Control Identity of the New Job
By default, the new job inherits the access-control identity of the job
that initiated it. That is, the new job belongs to the same access-control
groups as the initiating job. If the initiating job has changed its
access-control identity since it began, the new job inherits the
access-control identity in effect at the time the new job is started.
You can use the User and Password options to assign a nondefault
access-control identity for the new job. You can also specify a username
such as Network_Public through the User option.
User and Session of the New Job
The user and session associated with the new job affect how the job
interacts with input, output, and error windows. In particular, the job
uses the standard I/O and error windows for the associated session,
provided that the session is still active and the default values are used
for the input, output, and error files.
By default, the new job is associated with the user and session of the
initiating job. If the job is started during machine initialization, it
assumes the identity *SYSTEM. *SYSTEM jobs are not associated with a user
session. For this reason, *SYSTEM jobs may not have access to standard
Environment windows.
You can specify a nondefault user and session through the User and Session
options. You can specify the names of individual users or names such as
Network_Public. The session for jobs running under Network_Public is
!Machine.Network_Public_Session.
Note that the associated session does not determine the activity or
session switches used by the job. A new job always inherits the activity
and session switches of the initiating job.
Standard Input, Output, and Error Files for the New Job
Normally, jobs running in the Environment use editor windows for the
Standard_Input, Standard_Output, and Standard_Error files. Specifically,
Standard_Input and Standard_Output are I/O windows and Standard_Error is
the message window. These files cannot be changed once jobs have begun.
However, when you are running jobs that are independent of your session,
you cannot ensure that these editor windows will exist. If an application
tries to use one of these windows and the window does not exist, the job
will terminate and all messages will be lost. This is a problem especially
if you have started a job under a username such as Network_Public for
which there is never an active session.
To prevent this problem, the Create_Job and Run_Job procedures create a
new environment in which to run the new job. In this new environment,
Standard_Input, Standard_Output, and Standard_Error can be designated to
be text files. Specifically, when you use Create_Job or Run_Job to start a
new job, you can indicate the files that are to be used as Standard_Input,
Standard_Output, and Standard_Error for that job, using the Input,
Output, and Error options, respectively. Specifying text files through
these options ensures that the job will always be able to access
Standard_Input, Standard_Output, and Standard_Error.
If you do not specify the Input, Output, and Error options, the normal
editor windows are used, provided that the user's session is still
active. That is, the new job assumes Standard_Output and Standard_Input to
be an Environment I/O window and Standard_Error to be the message window.
Note that after the job has started, the Standard_Input, Standard_Output,
and Standard_Error files cannot be changed. To redirect input, output, or
error messages for the new job, you must redirect Current_Input,
Current_Output, and Current_Error. (By default, Current_Input,
Current_Output, and Current_Error direct output to Standard_Input,
Standard_Output, and Standard_Error, respectively.) For a complete
discussion about Environment input, output, and error files, see the Key
Concepts of this book.
Instructing One Job to Wait for Another
Sometimes when you have several interdependent jobs running
simultaneously, one job must finish before another continues.
To cause one job to wait for another, you can use the Wait_For procedure.
The Wait_For procedure causes the job calling the procedure to wait for a
particular job (specified by job number) to terminate before continuing to
execute.
Changing the Access-Control Identity of a Job
When a job begins, it assumes the job identity of the user or job that
initiated it. The job identity is the username and session to which the
job belongs. The job identity determines:
* The session switches that are to be used by the job
* The editor windows that are to be used by the job
* The access-control identity of the job
The access-control identity of a job is the access-control groups to which
the job belongs. Depending on what the job is to access, it may need to
change its access-control identity so that it belongs to a different set
of groups.
To cause a program to assume a particular access-control identity, you can
include a call to the Change_Identity procedure in that program. The
Change_Identity procedure changes the access-control identity of the job
to be the identity of the specified user. A password for the specified user
must be supplied and be correct unless the calling job belongs to the
access-control group Privileged and has enabled privileges.
Note that the Change_Identity procedure changes only the access-control
identity. The job identity (the username and session with which the job is
associated) is not changed.
The access-control identity can be changed back to the original identity
of the job by calling the Change_Identity procedure with the
Restore_Identity option.
For more information about access control, see the Library Management (LM)
book, package Access_List.
@node !Commands.Program.Change_Identity
procedure Change_Identity (To_User : String := "";
Password : String := "";
Options : String := "";
Status : in out Condition);
DESCRIPTION
Changes the access-control identity of the job and changes other
characteristics of the job as specified by the Options parameter.
This procedure changes the access-control identity of the job that
calls it to be the identity of the specified user. The access-control
identity is the set of access-control groups to which the job belongs.
By default, jobs belong to the same access-control groups as the
initiating job or user.
A password for the specified user must be supplied and correct unless the
calling job belongs to the access-control group Privileged and has enabled
privileges (using either the Operator.Enable_Privileges procedure or this
procedure with the Privileged option set to True).
Note that only the access-control identity is changed. The job identity
(the username and session with which the job is associated) is not
changed.
The access-control identity can be changed back to the original job
identity by calling this procedure with the Restore_Identity option.
For a description of access-control concepts, see the Library Management
(LM) book, package Access_List.
PARAMETERS
To_User : String := "";
Specifies the user to whom to change the access-control identity. The job
will belong to the same access-control groups as the user specified in
this parameter. If the default value of the null string is supplied, the
username is not changed.
Password : String := "";
Specifies the password for the user specified in the To_User parameter. A
password must be supplied unless the username is not being changed or
the calling job is a member of access-control group Privileged and has
enabled privileges.
Options : String := "";
Specifies additional changes to be made to the characteristics of the
calling job. If the To_User parameter is null, the Options parameter is
still processed. The legal options are:
* Privileged
Enables privileged mode for the calling job. The user specified in the
To_User parameter, or the current user if none is specified, must be a
member of the access-control group Privileged.
* Privileged => Boolean
Enables or disables privileged mode based on the value supplied. To
enable privileged mode, the user specified in the To_User parameter, or
the current user if none is specified, must be a member of the
access-control group Privileged. Disabling privileges has no effect
if the calling job is not running under privileged mode.
* Restore_Identity
Changes the access-control identity of the calling job back to the
original job identity. A password is not required to do this.
Status : in out Condition;
Returns an indication of the success or failure of the attempt to change
the identity of the calling job. The value of this parameter must be of
subtype Condition. If !Tools.Simple_Status.Error (Status) returns False,
the operation is successful. If it is not successful, the
Log.Put_Condition procedure or the Simple_Status.Display_Message
function can be used to obtain the cause of the error. See subytpe
Condition for further information.
REFERENCES
subtype Condition
procedure Log.Put_Condition
Library Management (LM), package Access_List
Programming Tools (PT), function Simple_Status.Display_Message
Programming Tools (PT), function Simple_Status.Error
System Management Utilities (SMU), procedure Operator.Enable_Privileges
@node !Commands.Program.Condition
subtype Condition is Simple_Status.Condition;
DESCRIPTION
Defines a status condition that can be used to return error information
from subprogram calls.
A condition consists of a condition name and a message. The condition name
indicates the type of error (if any), the severity of the error, and
whether the operation completed successfully. The message provides
additional information about the error.
Typically, a condition is returned from an operation such as a call of the
Create_Job or the Change_Identity procedure. The condition returned can
be interrogated with the Started_Successfully function or the
!Tools.Simple_Status.Error function.
If there are errors, the Log.Put_Condition procedure can be used to report
the condition name and message in the log file. Alternatively, you can use
the !Tools.Simple_Status.Display_Message function to obtain a complete
formatted message as a string.
REFERENCES
procedure Change_Identity
procedure Create_Job
function Started_Successfully
procedure Log.Put_Condition
Programming Tools (PT), function Simple_Status.Display_Message
Programming Tools (PT), function Simple_Status.Error
@node !Commands.Program.Create_Job
procedure Create_Job
(S : String := "<SELECTION>";
Job : out Job_Id;
Status : in out Condition;
Debug : Boolean := False;
Context : String := "$";
After : Duration := 0.0;
Options : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
Creates a job to execute the statements specified by the S parameter.
Note: This procedure is identical to the Run_Job procedure except that the
Run_Job procedure does not return the job number or a status indicating
whether the new job has started successfully.
This procedure compiles, links, and executes the Ada statements in the S
parameter. The Ada statements can be any series of statements that can
be placed between a begin/end pair. (The begin/end pair is implicit.)
The statements are executed in the context named in the Context
parameter. This context is used to determine Ada visibility and name
resolution. The default is the current library.
This procedure also creates a new job under which to execute the
statements. The job number for this new job is returned in the Job
parameter. The call to Create_Job returns once this job has been
started.
An indication of the success or failure of the attempt to start the new
job is returned in the Status parameter. This condition can be
interrogated by the Started_Successfully function. For further
information about the new job's identity, user, session, and standard
input, output, and error files, see the introduction to this package.
To force the new job to wait before executing, specify the number of
seconds the job is to wait in the After parameter.
To start the new job under the debugger, specify the value True for the
Debug parameter.
PARAMETERS
S : String := "<SELECTION>";
Specifies the Ada statements to be compiled, linked, and executed. The Ada
statements can be any series of statements that can be placed between a
begin/end pair. (The begin/end pair is implicit.) If the default value,
"<SELECTION>", is used, the procedure designated by the selection is
executed. The selection must be in an Ada unit or a library:
* If the selection is in an Ada unit, the procedure to be executed must
be visible (that is, it must be a library unit or it must be visible in
a package specification). If an entire procedure is selected in an Ada
unit, it is the procedure executed. Otherwise, the procedure that
contains the selection is executed.
* If the selection is in a library, the procedure that is selected is
executed.
Job : out Job_Id;
Returns the number of the job started by this procedure. If the job is not
started successfully, the value returned is undefined.
Status : in out Condition;
Returns an indication of the success or failure of the attempt to create
the job. To determine whether a job has started successfully, you can use
the Started_Successfully function. If the job has not started
successfully, the Log.Put_Condition procedure can be used to report the
error in a log message.
Debug : Boolean := False;
Specifies whether the job should be started under the debugger. By default,
the job is not started under the debugger.
Context : String := "$";
Specifies the context in which the Ada statements are compiled. This
context is used to determine Ada visibility and to resolve names of
library objects referenced by the statements. The string provided can be
any legal library name. The default value is the current library.
After : Duration := 0.0;
Specifies the number of seconds the job should wait before beginning to
execute the statements. The default causes the job to start immediately.
Options : String := "";
Specifies the options to be used for running the job. Options can be used
to specify the new job's identity, Standard_Input file, Standard_Output
file, and Standard_Error file. For more information about using these
options to control the characteristics of the new job, see the
introduction to this package. The legal options are:
* Input=filename
Specifies that this file be used for the new job's Standard_Input file.
Note that the name of this file is resolved using the context of the job
calling Create_Job, not the context supplied by the Context parameter.
If an input file is not specified, the standard Environment editor
window (an I/O window) is used for Standard_Input.
* Output=filename
Specifies that this file be used for the new job's Standard_Output file.
Note that the name of this file is resolved using the context of the job
calling Create_Job, not the context supplied by the Context parameter.
If an output file is not specified, the standard Environment editor
window (an I/O window) is used for Standard_Output.
* Error=filename
Specifies that this file be used for the new job's Standard_Error file.
Note that the name of this file is resolved using the context of the job
calling Create_Job, not the context supplied by the Context parameter.
If an error file is not specified, the standard Environment editor window
(the message window) is used for Standard_Error.
* User=username
Specifies that the new job be run with the identity of this user. The
new job belongs to the same access-control groups as this user and
uses this user's session. A Password option also must be supplied
unless the initiating job belongs to the access-control group
Privileged and has enabled privileges. If a User option is not
specified, the new job inherits the identity of the initiating job, and
the Session and Password options are ignored.
* Password=password value
Specifies that this password be used for the user named in the User
option. If the User option is not supplied, this option is ignored. If
the initiating job belongs to access-control group Privileged and has
enabled privileges, the password need not be supplied.
* Session=session name
Specifies that this session be used for the newly created job. The job
uses the terminal and windows associated with this session, provided
they are still active and the Input, Output, and Error options are not
specified. Note that the new job always uses the activities and session
switches inherited from the initiating job, never the new job's
session.
This session must belong to the user specified in the User option and
already exist. If the User option is not supplied, this option is
ignored and the new job inherits the session of the initiating job. If
the User option is present, but no Session option is supplied, the
default session of the specified user (S_1) is used.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job. Note that the response specified by this parameter is used
by the job calling Create_Job; it is not used by the job that is started
as a result of Create_Job.
RESTRICTIONS
The Create_Job, Run, and Run_Job procedures should not be called
concurrently from a single job--that is, within a job only one task should
be executing a call to any of these procedures at any given time. If calls
are made concurrently from a single job, unpredictable errors may result.
ERRORS
Errors can occur when the Ada statement is syntactically or semantically
incorrect, when code-generation errors exist, or when improper activities
are provided. The executed Ada statements also can produce errors.
Errors other than those occurring in the execution of the Ada statements
in the S parameter are reported as part of the current job, based on the
response specified in the Response parameter.
EXAMPLES
The following program creates a separate job under which to start each
program named in a file (F) and then reports the status of each job
creation:
with Io, Program, Simple_Status;
procedure Start_Servers is
F : Io.File_Type;
Job : Program.Job_Id;
Status : Simple_Status.Condition;
begin
Io.Open (F, Io.Infile, "Programs_To_Start");
while not Io.End_Of_File (F) loop
Program.Create_Job
(S => Io.Get_Line (F), Job => Job, Status => Status);
if Program.Started_Successfully (Status) then
Io.Put_Line ("Started Job " &
Program.Job_Id'Image (Job));
else
Log.Put_Condition (Status);
end if;
end loop;
Io.Close (F);
end Start_Servers;
REFERENCES
procedure Run
procedure Run_Job
function Started_Successfully
procedure Log.Put_Condition
@node !Commands.Program.Current
function Current (Subsystem : String := ">>SUBSYSTEM NAME<<";
Unit : String := ">>PROCEDURE NAME<<";
Parameters : String := "";
Activity : String := "<ACTIVITY>")
return String;
DESCRIPTION
Returns a string containing a procedure call to the specified unit.
The procedure call includes the name of the subsystem and the spec or load
view containing the unit.
First, this function determines the current spec and load views for the
subsystem named in the Subsystem parameter. The current views are
determined using the activity specified in the Activity parameter. If the
activity does not contain an entry for the specified subsystem, an error
will result.
This function then checks for the specified unit in the current load view
and its imports. If the specified unit exists in the current load view, the
string returned by this function includes the name of the current load
view. If the specified unit exists in the current load view's imports, the
string includes the name of the imported view. If the unit cannot be
located in either the current load view or its imports, the string
includes the name of the current spec view. (This happens, for example, if
the load-view entry in the activity references a code view.)
The string returned by this function can be passed as the S parameter to
the Create_Job, Run, and Run_Job procedures. Thus, this function can be
used for constructing general-purpose routines that do not need to be
modified each time a new release of the application is made.
See the Project Management (PM) book for further information about
activities and subsystems.
PARAMETERS
Subsystem : String := ">>SUBSYSTEM NAME<<";
Specifies the subsystem for which to determine the current spec and load
views. This subsystem must be named in the activity specified by the
Activity parameter. Special names, wildcards, and context characters can
be used, provided they resolve to a single subsystem. The default
parameter placeholder, ">>SUBSYSTEM NAME<<", must be replaced or an error
will result.
Unit : String := ">>PROCEDURE NAME<<";
Specifies the name of a procedure. This procedure must exist in the current
spec or load view for the specified subsystem or the view's imports.
Special names, wildcards, and context characters can be used, provided
they resolve to a single procedure. The default parameter placeholder,
">>PROCEDURE NAME<<", must be replaced or an error will result.
Parameters : String := "";
Specifies the parameters to be supplied to the procedure named in the Unit
parameter. Note that parentheses, commas, quotes, and so forth must be
supplied.
Activity : String := "<ACTIVITY>";
Specifies the activity to be used to determine the current spec and load
views for the specified subsystem. Special names, wildcards, and context
characters can be used, provided they resolve to a single activity file. By
default, the activity specified in the job response profile for the
current job is used.
return String;
Returns a string containing a procedure call that is suitable for the
Create_Job, Run, and Run_Job procedures.
ERRORS
The !Io.Io_Exceptions.Name_Error exception will be raised if the Unit
specified cannot be located in the current spec or load view for the named
subsystem or in the imports for either view.
EXAMPLES
Assume that the current activity for the calling job contains an entry for
subsystem !Project_Tools that names Rev1_0_0 as the current load view.
Assume Rev1_0_0 contains a procedure in the Units directory with the
following specification:
procedure Gather_Metrics (Units : String;
Verbose : Boolean);
To obtain the pathname for the current version of Gather_Metrics, use the
following function:
Program.Current (Subsystem => "!Project_Tools",
Unit => "Gather_Metics",
Parameters => "(""!Project_Library"", True)",
Activity => "<ACTIVITY>");
The resulting procedure call, shown below, could be used in a call to
Run_Job in the login procedure for the project administrator to collect
project metrics each time he or she logs in:
"!PROJECT_TOOLS.REV1_0_0.UNITS".Gather_Metrics ("!Project_Library", True);
REFERENCES
procedure Create_Job
procedure Run
procedure Run_Job
Project Management (PM)
@node !Commands.Program.Job_Id
subtype Job_Id is Machine.Job_Id;
DESCRIPTION
Defines the job number for a job.
When a job is created, the Environment assigns it a unique job number in
the range 0 through 255. This job number is used by many commands to
indicate the job on which to operate.
REFERENCES
procedure Create_Job
procedure Wait_For
@node !Commands.Program.Run
procedure Run (S : String := "<SELECTION>";
Context : String := "$";
Response : String := "<PROFILE>");
DESCRIPTION
Runs the statements specified by the S parameter as part of the current
job.
This procedure compiles, links, and executes the Ada statements in the S
parameter. The Ada statements can be any series of statements that can
be placed between a begin/end pair. (The begin/end pair is implicit.) If
the default value of the S parameter is used, the procedure designated by
the selection is executed. The selection must be in an Ada unit or a
library.
The statements are executed in the context named in the Context parameter.
This context is used to determine Ada visibility and name resolution. The
default is the current library.
The Ada statements must run to completion before this procedure completes;
they are not run as a separate job.
If an exception propagates out of the statements executed by this
procedure, a message indicating the exception is written into the log file
for the current job. The exception does not propagate to the caller.
To create a new job and run the specified statements under that job, use
the Create_Job or Run_Job procedure.
PARAMETERS
S : String := "<SELECTION>";
Specifies the Ada statements to be compiled, linked, and executed. The Ada
statements can be any series of statements that can be placed between a
begin/end pair. The begin/end pair is implicit. If the default value,
"<SELECTION>", is used, the procedure designated by the selection is
executed. The selection must be in an Ada unit or a library:
* If the selection is in an Ada unit, the procedure to be executed must
be visible (that is, it must be a library unit or it must be visible in
a package specification). If an entire procedure is selected in an Ada
unit, it is the procedure executed. Otherwise, the procedure that
contains the selection is executed.
* If the selection is in a library, the procedure that is selected is
executed.
Context : String := "$";
Specifies the context in which the Ada statements are compiled. This
context is used to determine Ada visibility and to resolve names of
library objects referenced by the statements. The string provided can be
any legal library name. The default value is the current library.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
RESTRICTIONS
The Run, Create_Job, and Run_Job procedures should not be called
concurrently from a single job--that is, within a job only one task should
be executing a call to any of these procedures at any given time. If calls
are made concurrently from a single job, unpredictable errors may result.
ERRORS
Errors can occur when the Ada statement is syntactically or semantically
incorrect, when code-generation errors exist, or when improper activities
are provided. The executed Ada statements also can produce errors.
EXAMPLES
The following program is an example of a login procedure that contains a
request for another procedure to be executed:
with Program;
procedure Login is
begin
...
Program.Run ("""!Projects.Project_A"".Initialize;");
...
end Login;
In this login procedure, the Run procedure requests that an initialization
routine be run. The initialization routine exists in a specific library
(!Projects.Project_A). Using this syntax allows the initialization routine
to be changed regularly without requiring that the Login procedure be
demoted and repromoted each time the initialization routine is changed.
REFERENCES
procedure Create_Job
procedure Run_Job
@node !Commands.Program.Run_Job
procedure Run_Job (S : String := "<SELECTION>";
Debug : Boolean := False;
Context : String := "$";
After : Duration := 0.0;
Options : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
Creates a job to execute the statements specified by the S parameter.
Note: This procedure is identical to the Create_Job procedure except that
the Create_Job procedure returns the job number or a status indicating
whether the new job has started successfully.
This procedure compiles, links, and executes the Ada statements in the S
parameter. The Ada statements can be any series of statements that can
be placed between a begin/end pair. (The begin/end pair is implicit.)
The statements are executed in the context named in the Context
parameter. This context is used to determine Ada visibility and name
resolution. The default is the current library.
This procedure also creates a new job under which to execute the
statements. The call to Run_Job returns once this job has been started.
For information about the new job's identity, user, session, and standard
input, output, and error files, see the introduction to this package.
To force the new job to wait before executing, specify the number of
seconds the job is to wait in the After parameter.
To start the new job under the debugger, specify the value True for the
Debug parameter.
PARAMETERS
S : String := "<SELECTION>";
Specifies the Ada statements to be compiled, linked, and executed. The Ada
statements can be any series of statements that can be placed between a
begin/end pair. (The begin/end pair is implicit.) If the default value,
"<SELECTION>", is used, the procedure designated by the selection is
executed. The selection must be in an Ada unit or a library:
* If the selection is in an Ada unit, the procedure to be executed must
be visible (that is, it must be a library unit or it must be visible in
a package specification). If an entire procedure is selected in an Ada
unit, it is the procedure executed. Otherwise, the procedure that
contains the selection is executed.
* If the selection is in a library, the procedure that is selected is
executed.
Debug : Boolean := False;
Specifies whether the job should be started under the debugger. By default,
the job is not started under the debugger.
Context : String := "$";
Specifies the context in which the Ada statements are compiled. This
context is used to determine Ada visibility and to resolve names of
library objects referenced by the statements. The string provided can be
any legal library name. The default value is the current library.
After : Duration := 0.0;
Specifies the number of seconds the job should wait before beginning to
execute the statements. The default causes the job to start immediately.
Options : String := "";
Specifies the options to be used for running the job. Options can be used
to specify the new job's identity, Standard_Input file, Standard_Output
file, and Standard_Error file. For more information about using these
options to control the characteristics of the new job, see the
introduction to this package. The legal options are:
* Input=filename
Specifies that this file be used for the new job's Standard_Input file.
Note that the name of this file is resolved using the context of the job
calling Create_Job, not the context supplied by the Context parameter.
If an input file is not specified, the standard Environment editor
window (an I/O window) is used for Standard_Input.
* Output=filename
Specifies that this file be used for the new job's Standard_Output file.
Note that the name of this file is resolved using the context of the job
calling Create_Job, not the context supplied by the Context parameter.
If an output file is not specified, the standard Environment editor
window (an I/O window) is used for Standard_Output.
* Error=filename
Specifies that this file be used for the new job's Standard_Error file.
Note that the name of this file is resolved using the context of the job
calling Create_Job, not the context supplied by the Context parameter.
If an error file is not specified, the standard Environment editor window
(the message window) is used for Standard_Error.
* User=username
Specifies that the new job be run with the identity of this user. The
new job belongs to the same access-control groups as this user and uses
this user's session. A Password option also must be supplied unless
the initiating job belongs to the access-control group Privileged and
has enabled privileges. If a User option is not specified, the new job
inherits the identity of the initiating job, and the Session and
Password options are ignored.
* Password=password value
Specifies that this password be used for the user named in the User
option. If the User option is not supplied, this option is ignored. If
the initiating job belongs to access-control group Privileged and has
enabled privileges, the password need not be supplied.
* Session=session name
Specifies that this session be used for the newly created job. The job
uses the terminal and windows associated with this session, provided
they are still active and the Input, Output, and Error options are not
specified. Note that the new job always uses the activities and session
switches inherited from the initiating job, never the new job's
session.
This session must belong to the user specified in the User option and
already exist. If the User option is not supplied, this option is
ignored and the new job inherits the session of the initiating job. If
the User option is present but no Session option is supplied, the
default session of the specified user (S_1) is used.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job. Note that the response specified by this parameter is used
by the job calling Run_Job; it is not used by the job that is started as a
result of Run_Job.
RESTRICTIONS
The Create_Job, Run, and Run_Job procedures should not be called
concurrently from a single job--that is, within a job only one task should
be executing a call to any of these procedures at any given time. If calls
are made concurrently from a single job, unpredictable errors may result.
ERRORS
Errors can occur when the Ada statement is syntactically or semantically
incorrect, when code-generation errors exist, or when improper activities
are provided. The executed Ada statements also can produce errors.
Errors other than those occurring in the execution of the Ada statements
in the S parameter are reported as part of the current job, based on the
response specified in the Response parameter.
EXAMPLES
The following program creates a separate job under which to start each
program named in a file (F):
with Io, Program, Simple_Status;
procedure Start_Servers is
F : Io.File_Type;
Job : Program.Job_Id;
Status : Simple_Status.Condition;
begin
Io.Open (F, Io.Infile, "Programs_To_Start");
while not Io.End_Of_File (F) loop
Program.Run_Job
(S => Io.Get_Line (F));
end loop;
Io.Close (F);
end Start_Servers;
REFERENCES
procedure Create_Job
procedure Run
@node !Commands.Program.Started_Successfully
function Started_Successfully (Status : Condition)
return Boolean;
DESCRIPTION
Returns a Boolean value indicating whether an attempt to create a job has
been successful.
This procedure can be used to determine whether the Create_Job procedure
has been successful. If the attempt is not successful, the cause of the
error can be interrogated using function
!Tools.Simple_Status.Display_Message. Alternatively, you can use the
Log.Put_Condition procedure, which reports the cause of the error in a log
message.
PARAMETERS
Status : Condition;
Specifies the status returned from the attempt to create a job. This
parameter must be replaced by a value of subtype Condition or an error
will result.
return Boolean;
Returns True if the job to which the condition pertains is started
successfully; otherwise, this function returns False.
REFERENCES
procedure Create_Job
procedure Log.Put_Condition
Programming Tools (PT), procedure Simple_Status.Display_Message
@node !Commands.Program.Wait_For
procedure Wait_For (Job : Job_Id);
DESCRIPTION
Causes the current job to wait until the specified job has terminated
before continuing to execute.
This procedure can be used when several interdependent jobs are running
simultaneously to indicate that the current job is to wait for the
specified job to terminate before continuing. It is especially useful
when the current job requires information about the status of another
job before continuing.
Note that, in some cases, the call does not return immediately but returns
some time after the job completes.
New jobs can be initiated from within an existing job using the Create_Job
or Run_Job procedure.
PARAMETERS
Job : Job_Id;
Specifies the job number of the job for which the current job is to wait.
REFERENCES
procedure Create_Job
procedure Run_Job
@node !Commands.Remote
Package Remote gives the user the ability to execute programs on other
R1000s on the same network and to display the image of an object from
another R1000 (on the same network) in a local I/O window. Specifically,
package Remote contains the following two procedures:
* Run: Executes the specified Ada statements or program on a remote R1000.
Errors are reported on the local R1000.
* Show: Displays the image of an object from a remote R1000 on the local
R1000.
The access-control identity of the remote jobs is determined by the
remote-passwords file named in the Response parameter. If the Response
parameter does not name a remote-passwords file, or if the remote-passwords
file does not contain an entry for the specified remote R1000, then the
remote job assumes the identity of the archive server, Network_Public.
@node !Commands.Remote.Run
procedure Run (Machine : String := ">>MACHINE_NAME<<";
Command : String := "<IMAGE>";
File_Context : String := "$";
Run_Context : String := "<DEFAULT>";
Options : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
Runs a command on another R1000.
This procedure formats, compiles, links, and executes the Ada statements
named in the Command parameter. The Ada statements can be any series of
statements that can be placed between a begin/end pair. (The begin/end
pair is implicit.) If the Ada statements in the Command parameter name an
existing Ada unit, that unit must exist on the remote R1000.
The File_Context parameter specifies the library on the remote R1000 in
which to look for any Ada units called by the Command parameter. After the
statements in the Command parameter begin executing, the library named in
the Run_Context parameter is considered the current library. Any filenames
referenced by the statements in the Command parameter are resolved with
respect to this library. Note that this procedure first determines the run
context and then determines the file context, based on the run context.
Thus, if the file context uses relative pathnames or context characters,
they are resolved against the library named in the Run_Context
parameter.
Note that the value specified in the Response parameter is evaluated twice,
once on the local machine and again on the remote machine. Specifically,
the string is first evaluated to determine command behavior on the local
machine. Any special values (such as <PROFILE>) are resolved locally. The
string in the Response parameter is then passed to the remote machine.
If special values are used, they are resolved a second time--this time on
the remote machine--to determine the response characteristics for the
remote portion of command execution.
When using special values in the Response parameter, be aware that this
command does not create a session on the remote machine. For this
reason, any response characteristic for which there is no value in the
system default profile (such as an activity file) will assume the null
string on the remote machine. To avoid problems, explicitly specify those
characteristics in the Response parameter, as shown below:
Remote.Run
(Machine => "machine_1",
Command => "<IMAGE>",
File_Context => "$",
Run_Context => "<DEFAULT>",
Options => "",
Response => "Activity =>
!Machine.Release.Current.Activity, <PROFILE>");
If the profile named in the Response parameter specifies a remote-passwords
file, and if that file has an entry for the specified remote R1000, then this
procedure uses the identity (the username and password) associated with
that machine in the remote-passwords file. If not, this procedure uses the
identity of the archive server.
PARAMETERS
Machine : String := ">>MACHINE_NAME<<";
Specifies the name of the remote R1000 on which to run the command. The de-
fault parameter placeholder, ">>MACHINE_NAME<<", must be replaced or an
error will result.
Command : String := "<IMAGE>";
Specifies the set of Ada statements to be run on the remote R1000. The set
of statements can be any that can be placed in a begin/end pair. (The
begin/end pair is implicit.) The special names "<IMAGE>" (the default) and
"<SELECTION>" are accepted. No other naming expressions are accepted; the
string must be executable Ada statements. Any Ada units called by these
statements must exist in the library named in the File_Context parameter
or its links.
File_Context : String := "$";
Specifies the context for resolving the Ada names specified in the Command
parameter. Wildcards and context characters can be used if they resolve
to a unique library.
Note that if a relative pathname is specified, it is resolved with respect
to the context established by the Run_Context parameter. Thus, the
default, the current library, is the library specified in the Run_Context
parameter.
Run_Context : String := "<DEFAULT>";
Specifies the location in the library hierarchy of the remote R1000 in
which the command is to run. This library is the name-resolution context
on the remote R1000. If the Command parameter references any other library
objects, those names are resolved with respect to the run context. Objects
in the library specified to be the run context can be called using only
their simple names; all others must be qualified.
The default special name, "<DEFAULT>", specifies the context on the remote
R1000 with the same name as the current context on the local R1000. If
that name-resolution context does not exist on the remote R1000, the root
world (!) is used. Wildcards and context characters can be used if they
resolve to a unique library.
Options : String := "";
No options currently are implemented for this command. This parameter is
reserved for future development.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
RESTRICTIONS
To execute a command on the remote R1000, the Run procedure must have read
access to that command.
ERRORS
Errors are reported on the local R1000.
EXAMPLES
Example 1
Assume that you have a procedure called Generate_Status on a remote R1000
called M2. The fully qualified pathname is
!Local.Local_Utilities.Generate_Status. The Generate_Status procedure
gathers the contents of each user's status file, joins the entries into a
single file, and creates a file (using !Io.Io.Create) called Status_ date
containing these entries. Daily status files are to be placed in
!Local.Status.
The following command performs this operation from an R1000 other than M2:
Remote.Run (Machine => "M2",
Command => "Generate_Status",
File_Context => "^.Local_Utilities",
Run_Context => "!Local.Status",
Options => "",
Response => "<PROFILE>");
The output log is displayed on the local R1000.
Example 2
Assume that you are prototyping part of a program in a command window and
that you want to test how these code segments will execute on a remote
R1000. You want the context on the remote R1000 to be the context with the
same name as the local context.
To execute the statements in the command window on a remote R1000 called
M3, first place the cursor in the command window containing the statements.
From this command window, execute the !Commands.Common.Create_Command
procedure to open a subordinate command window. In this subordinate
command window, enter the following command:
Remote.Run (Machine => "M3",
Command => "<IMAGE>",
File_Context => "$",
Run_Context => "<DEFAULT>",
Options => "",
Response => "<PROFILE>");
Errors will be reported on the local R1000.
REFERENCES
procedure Program.Run
@node !Commands.Remote.Show
procedure Show (Machine : String := ">>MACHINE_NAME<<";
Object_Name : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
Displays the contents of a library object that is on another R1000.
This procedure displays the image of an object from another R1000 on the
same network. The display is sent to Current_Output, which is, by default,
an Environment output window.
If the profile specified in the Response parameter specifies a
remote-passwords file, and if that file has an entry for the remote R1000,
this procedure uses the identity (the username and password) associated
with that R1000 in the remote-passwords file. If not, this procedure uses
the identity of the archive server.
PARAMETERS
Machine : String := ">>MACHINE_NAME<<";
Specifies the name of the remote R1000. The default parameter placeholder,
">>MACHINE_NAME<<", must be replaced or an error will result.
Object_Name : String := "<CURSOR>";
Specifies the name of the object to be displayed. Special names, wildcards,
and context characters can be used, provided they resolve to a single
object. The default is the object on the remote R1000 that has the same
fully qualified pathname as the local object designated by the cursor.
The name supplied to this parameter is resolved with respect to the
library on the remote R1000 that has the same name as the current library
on the local R1000. If that library does not exist on the remote R1000,
then the root world (!) is used.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
RESTRICTIONS
To display an object on the remote R1000, the Show procedure must have
read access to that object.
ERRORS
Errors are reported on the local R1000.
EXAMPLES
Suppose that you are working on a project that spans multiple R1000s and
that you want to view a package (!Projects.Common_Utilities.Reports) that
exists on a remote R1000 (M4) so that you can verify compatibility with a
package you are currently developing. You can execute the following
command to display package Reports:
Remote.Show (Machine => "M4",
Object_Name => "!Projects.Common_Utilities.Reports",
Response => "<PROFILE>");
The command produces the following display in an Environment output window
on the local R1000:
91/05/01 18:14:00 ::: [Remote.Show, Machine => "M4", Object_Name =>
91/05/01 18:14:01 ... "!Projects.Common_Utilities.Reports",
91/05/01 18:14:02 ... Response => "<PROFILE>"].
91/05/01 18:14:02 --- showing M4 !PROJECTS.COMMON_UTILITIES.REPORT
with Group;
with Person;
package Reports is
-- This defines the set of reports available and provides the
-- necessary processing to display the reports.
type Options is (Name_Only, Name_And_Address, All_Info);
procedure Put (The_Group : in Group.Collection;
With_Options : in Reports.Options :=
Reports.All_Info;
With_Report_Header : in String := "");
procedure Put (The_Person : in Person.Object;
With_Options : in Reports.Options :=
Reports.All_Info);
end Reports;
91/05/01 18:14:05 ::: [end of Remote.Show operation].
@node !Commands.Remote_Passwords
Package Remote_Passwords provides commands for manipulating remote-pass-
words files. Remote-passwords files are accessed by commands that perform
operations across a network, including commands that are part of the
standard Rational Environment (such as those in !Commands.Ftp) and
commands from other Rational products (such as the Rational Compilation
Integrator).
By default, the commands in this package modify the remote-passwords file
for the current session. Thus, these commands provide a convenient
alternative to locating the file in the library hierarchy and editing it
directly. Furthermore, these commands provide a way to encrypt the
passwords listed in the file.
As with most commands in the world !Commands, the commands in this package
are intended for interactive use, but they can be used programmatically.
RESOURCES IN PACKAGE REMOTE_PASSWORDS
Adding entries to a remote-passwords file: Add
Editing entries in a remote-passwords file: Change, Update
Creating a remote-passwords file: Create
Deleting entries from a remote-passwords file: Delete
Displaying the encrypted form of a password: Show_Encryption
Managing the default remote-passwords file: Get_Default, Set_Default
KEY CONCEPTS FOR PACKAGE REMOTE_PASSWORDS
For security purposes, computer operations often require a username and
password. Usernames and passwords required for remote operations can be
stored and encrypted in remote-passwords files. Thus, using
remote-passwords files enables the user to perform remote operations
without the necessity of supplying usernames and passwords directly to
the networking command.
Many facilities check for a remote-passwords file when performing
networking operations. Specifically, commands in packages !Commands.Ftp and
!Commands.Remote and the !Commands.Archive.Copy procedure check for a
remote-passwords file. Remote-passwords files are also used by many of
Rational's other products, including the Rational Publishing Interface
(RPI), the Rational Teamwork Interface (RTI), the Target Build Utility
(TBU), the Rational Compilation Integrator (RCI), and Rational's family of
Cross-Development Facility (CDF) products. For specific information about
how each of these products gains access to remote-passwords files, see that
product's manuals.
This package introduction contains information about:
* Determining when to use a remote-passwords file
* Using a remote-passwords file: the basic scenario
* Manipulating remote-passwords files, including:
- Creating a remote-passwords file
- Editing remote-passwords files
- Encrypting passwords
* Setting the default remote-passwords file
* Overriding the default remote-passwords file
* Using remote-passwords files from *SYSTEM jobs
Determining When to Use a Remote-Passwords File
Many networking operations allow you to specify a remote username and
password in command parameters, in library switches, in session
switches, or in a remote-passwords file. Remote-passwords files are
recommended for storing and providing networking information if:
* You want to encrypt passwords.
* You routinely access several other machines, each of which requires a
different username or password.
* You use commands that implicitly perform networking operations, and you
want to specify the remote username under which to perform the
operations. For example, the Archive.Copy procedure and commands in
package Remote perform remote operations but do not explicitly request
a remote username or password. Thus, if you do not have a default
remote-passwords file, these commands use the identity (and
access-control groups) of the archive server, Network_Public.
Using a Remote-Passwords File: The Basic Scenario
Usually there are several machines that you access frequently using
networking operations. Although you can have any number of
remote-passwords files, you generally have one that contains the machine
names, usernames, and passwords you use most frequently.
For example, assume that you have accounts on five machines (called
Machine_1 through Machine_5) that are connected to the same network:
* For Machine_1 and Machine_2, your username is YUser. The security on
these machines is relatively high, so you choose to encrypt your
passwords for these machines.
* For Machine_3 and Machine_4, your username is also YUser; however, the
security on these machines is low, so you choose the same unencrypted
password--namely, My_Password!.
* For Machine_5, your username is YUsername. The security on this machine
is such that you do not want your password in a file but prefer to enter
it from your keyboard when necessary.
To use the remote-passwords facility, you create a text file with a name
such as !Users.Your_Username.Secret_Stuff that includes the following
entries:
Machine_1 YUser <DES:BD27F7CF136E24B6>
Machine_2 YUser <DES:49E379F4EAD9B339>
Machine_5 YUsername <PROMPT>
Others YUser My_Password!
To make this remote-passwords file the default for all networking
operations from your current session, you can use the
Remote_Passwords.Set_Default command, which sets the
Profile.Remote_Passwords switch in your session switch file to point to this
file:
Remote_Passwords.Set_Default
(Existing_File => "!Users.Your_Username.Secret_Stuff",
For_Session => "",
Response => "<PROFILE>");
Note that you must log out and log back in for the default
remote-passwords file to take effect.
After your remote-passwords file has been created and entered into the
Profile.Remote_Passwords switch, you can edit it by using commands in
this package or by locating it in the library hierarchy and editing it
directly.
For example, suppose you want to gain access to a new machine called Ma-
chine_6. On this machine your username is YourUsername. Because you may be
changing your password frequently, you want to be prompted for the
password when one is needed. To add the entry to your remote-passwords
file, you can execute the following command:
Remote_Passwords.Add (New_Hostname => "Machine_6",
New_Username => "YourUsername",
New_Password => """<PROMPT>""",
Encryption => Remote_Passwords.None,
For_Session => "",
Response => "<PROFILE>");
Notice that to enter the value "<PROMPT>" into the remote-passwords file
using this command, you must enclose the value in a total of three sets of
double quotation marks. The two extra sets of quotation marks are
necessary to ensure that the value is interpreted as a string to be
inserted into the remote-passwords file rather than as an indication to
prompt you for the value to be entered in the file.
Manipulating Remote-Passwords Files
A remote-passwords file is a text file that contains one or more entries of
the following form:
machine_name username password
where machine_name is the network name of a machine to which the user has
access, username is a valid username on the specified machine, and password
is the required password for the specified username.
The word "Others" can be used in the machine_name column to mean all other
machines to which a user has access. Including an entry for "Others" is
useful when you have identical usernames and passwords on two or more
machines and do not want to specify each of them individually. If used,
"Others" should be on the last line in the file.
The username can be:
* A literal string, which is a string of any length not containing
blanks. This string can, but need not, be enclosed by quotation marks.
* The special value <PROMPT>, which causes the user to be prompted for
the username during an operation that accesses the remote host. The
word <PROMPT> must be in uppercase and enclosed by angle brackets (<>).
The form of the password can be:
* A literal string. Entries for literal passwords are case-sensitive, so
the entry slithy_toves differs from Slithy_Toves.
* The special value <PROMPT>, which causes the user to be prompted for
the password during an operation that accesses the remote host. The
word <PROMPT> must be in uppercase and must be enclosed by angle
brackets (<>).
* An encrypted password, which appears as a hexadecimal string enclosed
in angle brackets. See "Encrypting Passwords," below, for more
information.
* The null string (""), which indicates that no password is required. (In
this case, the password can be omitted altogether.)
Creating Remote-Passwords Files
Remote-passwords files are text files. Thus, to create a new, empty
remote-passwords file, you can use the !Commands.Text.Create procedure.
If you want to create a remote-passwords file by copying an existing file,
you can use the Create procedure from this package. The Create procedure
copies the contents of the specified source file into a new remote-passwords
file. Using the Create procedure, you can also specify the method of
encryption to be used for passwords in the new file. The new
remote-passwords file is created in the current context.
After you have created a remote-passwords file, you can set it to be the
default for all networking operations in a particular session. See
"Setting the Default Remote-Passwords file," page nn, for more
information.
Editing Remote-Passwords Files
There are two ways to edit remote-passwords files:
* You can edit a remote-passwords file, without having to locate it in the
library hierarchy and open it for editing, using commands (Add, Change,
Delete) in this package. See the entries for the Add, Change, and
Delete procedures for more information.
* You can edit a remote-passwords file directly using basic text-editing
operations. See the Editing Specific Types (EST) book, Text Images, for
information about editing text files.
Encrypting Passwords
Using commands in this package, you can encrypt passwords in a
remote-passwords file. Specifically, the Add and Change procedures have an
Encryption_Method parameter that allows you to specify the form of
encryption to be used. Three methods of encryption are available:
* Des: Specifies that the password value be encrypted using a Data
Encryption Standard (DES) algorithm. Entries encrypted using this
method appear in the remote-passwords file in angle brackets and have
the prefix DES. For example:
<DES:018853AB3F000CC4FEB7D5F91C2772FD>
* Hex: Specifies that the password value be encryped in hexadecimal
notation. Entries encrypted using this method appear in the
remote-passwords file in angle brackets and have the prefix HEX. For
example:
<HEX:6D795F70617373776F7264>
* None: Specifies that no encryption be used. Unencrypted passwords appear
in the remote-passwords file in clear text. For example:
My_Password
If you decide to edit the remote-passwords file directly, you can use the
Show_Encryption command to generate the encrypted value and then
region-copy it into the file.
Note that the encryption key for a password entry is the password
associated with the username under which the entry was created. For
example, if your password for the local machine is Splot, then Splot is
the key used to encrypt (and decrypt) entries in your remote-passwords
file. Thus, if you change your password (using the
!Commands.Operator.Change_Password procedure), you must use the Update
procedure to reencrypt the entries in your remote-passwords file. You also
need to update your remote-passwords file if you copy it onto a machine for
which you have a different password.
Setting the Default Remote-Passwords File
The default remote-passwords file for your session is the file named in the
Profile.Remote_Passwords session switch. This value also serves as the
remote-passwords component of the session response profile for that
session (see package Profile).
To set the value of this switch, you can use one of the following methods:
* Execute the Remote_Passwords.Set_Default command, specifying the name
of your remote-passwords file and the session for which it is to be the
default. The command will take effect the first time you set a default
remote-passwords file; otherwise, the new default will take effect the
next time you log in.
* Edit your session switch file directly:
1. Execute the Switches.Edit_Session_Attributes procedure to open the
switch file for your current session for editing.
2. Select the Profile.Remote_Passwords switch.
3. Execute the !Commands.Common.Edit procedure. This procedure opens a
command window containing the following prompt:
Change ("current switch value")
4. Enter the name of your remote-passwords file and promote the command
window.
5. Promote the session switch file to commit the change. The change will
take effect the next time you log in.
You can also programmatically set the default remote-passwords file for
your current session using the Profile.Set_Default_Remote_Passwords
command.
Overriding the Default Remote-Passwords File
By default, the remote-passwords file specified in your session switch file
is used for all networking operations. However, you can specify another
remote-passwords file in either of two other ways:
* You can set the remote-passwords file for the current job using the
Profile.Set_Remote_Passwords command.
* You can set the remote-passwords file for a particular command in the
Response parameter of that command.
For example, the following command uses the username and password
associated with machine M2 in a remote-passwords file called Secret_Stuff:
Remote.Run
(Machine => "M2",
Command => "Daily_Report",
File_Context => "$",
Run_Context => "<DEFAULT>",
Options => "",
Response => "Remote_Passwords=>Secret_Stuff,<PROFILE>");
Some commands also allow you to specify remote username and password
information in command parameters, library switches, or session
switches. The commands that check these locations do so in the following
order:
* The command's username and password parameters
* The library switches for the current world or view (Ftp.Username and
Ftp.Password switches)
* The session switches for the current session (Session_Ftp.Username and
Session_Ftp.Password switches)
* The remote-passwords file of the profile specified in the Response
parameter of the command. If the command does not have a Response
parameter, the command uses the remote-passwords file specified in the
job response profile for the current job.
Using Remote-Passwords Files from *SYSTEM Jobs
You can use remote-passwords files from *SYSTEM jobs, such as jobs started
during machine initialization.
To use remote-passwords files from *SYSTEM jobs, such as those started by
machine initialization, you should be aware that *SYSTEM jobs are not
associated with a user session or session response profile. Instead, they
use a system-defined response profile, which does not include a
remote-passwords file. For this reason, if you want a *SYSTEM job to use a
remote-passwords file, you must either:
* Explicitly set the remote-passwords file in the job response profile for
the job (using !Tools.Profile.Set_Remote_Passwords), or
* Specify the remote-passwords file in the Response parameter of the
command(s) that perform networking operations.
If the remote-passwords file used by a *SYSTEM job contains encrypted pass-
words, the job will use the password for user Operator as the key to
decrypt the remote-passwords file. For this reason, encrypted entries must
be added to the remote-passwords file by user Operator. If the Operator
password is changed, the remote-passwords file must be updated (using the
Update procedure in this package). The remote-passwords file also must be
updated if it is copied onto a machine for which user Operator has a
different password.
@node !Commands.Remote_Passwords.Add
procedure Add
(New_Hostname : String := ">>REMOTE HOST<<";
New_Username : String := ">>REMOTE USER<<";
New_Password : String := "<PROMPT>";
Encryption : Encryption_Method := Remote_Passwords.Des;
For_Session : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
Adds an entry to the remote-passwords file for the specified session.
This procedure adds an entry with the specified hostname (machine name),
username, and password to the remote-passwords file for the specified
session. If an entry for the specified hostname already exists, an error
message is generated and the remote-passwords file is left unchanged. If
changes are made, this procedure commits those changes.
To change the username and password associated with an existing hostname,
use the Change procedure.
PARAMETERS
New_Hostname : String := ">>REMOTE HOST<<";
Specifies the name of a host machine to be entered into the
remote-passwords file. The default parameter placeholder, ">>REMOTE
HOST<<", must be replaced or an error will result.
New_Username : String := ">>REMOTE USER<<";
Specifies the username to be entered into the remote-passwords file. This
username must exist on the specified host machine. The default parameter
placeholder, ">>REMOTE USER<<", must be replaced or an error will
result.
New_Password : String := "<PROMPT>";
Specifies the password to be entered into the remote-passwords file. The
default, "<PROMPT>", causes the command to prompt the user for the
password that is to be entered in the remote-passwords file. To specify
that the value "<PROMPT>" be inserted into the remote-passwords file, you
must enclose the value in a total of three sets of double quotation marks:
"""<PROMPT>""".
Encryption : Encryption_Method := Remote_Passwords.Des;
Specifies the form of encryption to be applied to the password. The
following values are accepted:
Des The default. Specifies that the password value be
encrypted using a Data Encryption Standard (DES)
algorithm.
Hex Specifies that the password value be encryped in
hexadecimal notation.
None Specifies that no encryption be used.
For_Session : String := "";
Specifies the session for which the remote-passwords file is to be changed.
The null string (the default) signifies the current session for the current
user.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
RESTRICTIONS
To add an entry to a remote-passwords file, you must have write access to
the file.
EXAMPLES
Example 1
The following command adds an entry in the remote-passwords file for the
current session naming machine M3, username Reyes, and the password
Opensesame:
Remote_Passwords.Add (New_Hostname => "M3",
New_Username => "Reyes",
New_Password => "Opensesame",
Encryption => Remote_Passwords.Des,
For_Session => "",
Response => "<PROFILE>");
The resulting entry, shown below, includes the password as encrypted using
a DES algorithm:
M3 Reyes <DES:3AF67FA316AE1BE6016414A22E67A98F>
Example 2
Suppose that when accessing remote host machines not explicitly named in
the remote-passwords file, you want commands to prompt you for a username
and password. The following command creates an appropriate entry in the
remote-passwords file for the current session:
Remote_Passwords.Add (New_Hostname => "Others",
New_Username => "<PROMPT>",
New_Password => """<PROMPT>""",
Encryption => Remote_Passwords.None,
For_Session => "",
Response => "<PROFILE>");
Notice that in the New_Password parameter the value <PROMPT> requires
three sets of double quotation marks: one set to indicate a string
parameter value and two additional sets to indicate quotation marks
within the parameter value. The resulting entry appears as shown below:
Others <PROMPT> <PROMPT>
REFERENCES
procedure Change
procedure Create
@node !Commands.Remote_Passwords.Change
procedure Change
(Existing_Hostname : String := ">>REMOTE HOST<<";
New_Username : String := ">>REMOTE USER<<";
New_Password : String := "<PROMPT>";
Encryption : Encryption_Method := Remote_Passwords.Des;
For_Session : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
Changes an existing entry in the remote-passwords file for the specified
session.
This procedure edits the entry for the specified host machine to include
the specified username and password. If an entry for the specified host
machine does not exist already, it is added. This procedure then commits
the changed remote-passwords file.
To create an entry for a new host machine, use the Add procedure.
PARAMETERS
Existing_Hostname : String := ">>REMOTE HOST<<";
Specifies the name of a host machine in the remote-passwords file. The
default parameter placeholder, ">>REMOTE HOST<<", must be replaced or an
error will result.
New_Username : String := ">>REMOTE USER<<";
Specifies the username to be entered into the remote-passwords file. This
username must exist on the specified remote host. The default parameter
placeholder, ">>REMOTE USER<<", must be replaced or an error will result.
New_Password : String := "<PROMPT>";
Specifies the password to be entered into the remote-passwords file. The
default, "<PROMPT>", causes the command to prompt the user for the
password that is to be entered in the remote-passwords file. To specify
that the value "<PROMPT>" be inserted into the remote-passwords file, you
must enclose the value in two sets of double quotation marks,
""<PROMPT>"".
Encryption : Encryption_Method := Remote_Passwords.Des;
Specifies the form of encryption to be applied to the password. The
following values are accepted:
Des The default. Specifies that the password value be
encrypted using a Data Encryption Standard (DES)
algorithm.
Hex Specifies that the password value be encryped in
hexadecimal notation.
None Specifies that no encryption be used.
For_Session : String := "";
Specifies the session for which the remote-passwords file is to be changed.
The null string (the default) signifies the current session for the current
user.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
RESTRICTIONS
To edit a remote-passwords file, you must have write access to that file.
EXAMPLES
Assume that a user named Mike Burgan has a remote-passwords file that
includes the entries shown below:
Machine_1 MBurgan <DES:BD27F7CF136E24B6>
Machine_2 MCB Opensesame
Machine_5 MCBurgan <PROMPT>
Others MCB My_Password!
Suppose that security is tightened on Machine_2, so he has changed his
password to Abracadabra. He can edit his remote-passwords file and encrypt
the new password using the following procedure:
Remote_Passwords.Change
(Existing_Hostname => "Machine_2",
New_Username => "MCB",
New_Password => "Abracadabra",
Encryption => Remote_Passwords.Des,
For_Session => "",
Response => "<PROFILE>");
The resulting remote-passwords file appears below:
Machine_1 MBurgan <DES:BD27F7CF136E24B6>
Machine_2 MCB <DES:03AA568F271D15BA63B766FAD326F1ED>
Machine_5 MCBurgan <PROMPT>
Others MCB My_Password!
Note that the Change procedure can be used from any location in the
library hierarchy. It does not need to be used from a remote-passwords
file.
REFERENCES
procedure Add
procedure Create
@node !Commands.Remote_Passwords.Create
procedure Create
(New_File : String := ">>REMOTE PASSWORDS FILE<<";
Source_File : String := "";
Source_Password : String := "<PROMPT>";
Encryption : Encryption_Method := Remote_Passwords.Des;
Response : String := "<PROFILE>");
DESCRIPTION
Creates a new remote-passwords file.
This procedure creates a new remote-passwords file, using the specified
source file to initialize the contents of the file.
The passwords in the source file are decrypted using the password specified
in the Source_Password parameter. They are then entered into the new
remote-passwords file using the encryption method specified in the
Encryption parameter. Any source entries that cannot be decrypted by the
source password are not copied into the new file.
PARAMETERS
New_File : String := ">>REMOTE PASSWORDS FILE<<";
Specifies the name of the new remote-passwords file. The default parameter
placeholder, ">>REMOTE PASSWORDS FILE<<", must be replaced or an error
will result.
Source_File : String := "";
Specifies the name of the source file from which to copy the
remote-passwords entries. The default, the null string, specifies that the
new remote-passwords file is to be empty.
Source_Password : String := "<PROMPT>";
Specifies the password to be used as the key for decrypting the passwords
in the source file. This password must match the password used when the
entries in the source file were originally created and encrypted. Any
entries that cannot be decrypted are not copied into the new remote-passwords
file. The default, "<PROMPT>", prompts the user to enter the source password.
Encryption : Encryption_Method := Remote_Passwords.Des;
Specifies the form of encryption to be used for entering the passwords in
the new remote-passwords file. The following values are accepted:
Des The default. Specifies that the password value be
encrypted using a Data Encryption Standard (DES)
algorithm.
Hex Specifies that the password value be encryped in
hexadecimal notation.
None Specifies that no encryption be used.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
RESTRICTIONS
Only those entries in the source file that can be decrypted using the
specified source password will be copied into the new remote-passwords file.
EXAMPLES
The following command creates a new remote-passwords file called
Secret_Passwords and copies the entries from a remote-passwords file
called Original_Passwords into the new file. The passwords in
Original_Passwords were encrypted by a user whose password at the time of
encryption was Marsbar.
Remote_Passwords.Create (New_File => "Secret_Passwords",
Source_File => "Original_Passwords",
Source_Password => "Marsbar",
Encryption => Remote_Passwords.Des,
Response => "<PROFILE>");
The new entries are encrypted according to a DES algorithm.
REFERENCES
procedure Add
subtype Encryption_Method
@node !Commands.Remote_Passwords.Delete
procedure Delete (Existing_Hostname : String := ">>REMOTE HOST<<";
For_Session : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
Removes the specified entry from the remote-passwords file for the specified
session.
This procedure deletes the entry for the specified host machine from the
remote-passwords file for the specified session. If an entry for the
specified host machine does not exist, a warning message is generated.
PARAMETERS
Existing_Hostname : String := ">>REMOTE HOST<<";
Specifies the name of a host machine in the remote-passwords file. The
default parameter placeholder, ">>REMOTE HOST<<", must be replaced or an
error will result.
For_Session : String := "";
Specifies the session for which the remote-passwords file is to be changed.
The null string (the default) signifies the current session for the current
user.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
RESTRICTIONS
To delete entries from a remote-passwords file, you must have write access
to that file.
EXAMPLES
Assume that the default remote-passwords file for your current session
contains the following entries:
Machine_1 MBurgan <DES:BD27F7CF136E24B6>
Machine_2 MCB Opensesame
Machine_5 MCBurgan <PROMPT>
Others MCB My_Password!
The following command deletes the entry for Machine_5:
Remote_Passwords.Delete (Existing_Hostname => "Machine_5",
For_Session => "",
Response => "<PROFILE>");
REFERENCES
procedure Add
procedure Change
@node !Commands.Remote_Passwords.Encryption_Method
type Encryption_Method is (None, Hex, Des);
DESCRIPTION
Defines the forms of encryption that can be applied to the passwords
entered into a remote-passwords file.
Values of this type can be specified in the Encryption parameter of
commands in this package.
ENUMERATIONS
Des
Specifies that the password value be encrypted using a Data Encryption
Standard (DES) algorithm. Entries encrypted using this method appear in
the remote-passwords file in angle brackets and have the prefix DES. For
example:
<DES:018853AB3F000CC4FEB7D5F91C2772FD>
Hex
Specifies that the password value be encryped in hexadecimal notation.
Entries encrypted using this method appear in the remote-passwords file in
angle brackets and have the prefix HEX. For example:
<HEX:6D795F70617373776F7264>
None
Specifies that no encryption be used. Unencrypted passwords appear in the
remote-passwords file in clear text. For example:
My_Password
@node !Commands.Remote_Passwords.Get_Default
function Get_Default (For_Session : String := "";
Response : String := "<WARN>")
return String;
DESCRIPTION
Returns the name of the remote-passwords file for the specified session.
This procedure returns the fully qualified pathname of the remote-passwords
file specified in the Profile.Remote_Passwords session switch for the
specified session.
To obtain the default remote-passwords file for the current session for
programmatic use, see the Profile.Default_Remote_Passwords function.
PARAMETERS
For_Session : String := "";
Specifies the session for which the remote-passwords file is to be changed.
The null string (the default) signifies the current session for the current
user.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default value indicates that the command
is to log only negative, error, warning, and exception messages, to
persevere at errors without raising an exception, and to use the job
response profile for the current job for all other response
characteristics.
return String;
Returns the fully qualified pathname of the remote-passwords file. If errors
are encountered during the processing of this function, the null string is
returned.
EXAMPLES
Suppose that you want to view the default remote-passwords file for your
current session, but you cannot remember the name of the file. The
following command opens a window containing the default remote-passwords
file for your current session:
Definition (Remote_Passwords.Get_Default);
REFERENCES
procedure Set_Default
function Profile.Default_Remote_Passwords
@node !Commands.Remote_Passwords.Set_Default
procedure Set_Default (Existing_File : String := "<IMAGE>";
For_Session : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
Sets the default remote-passwords file for the specified session.
The command will take effect immediately the first time you set a default
remote-passwords file; otherwise, the new default will take effect the
next time you log in.
This procedure sets the specified remote-passwords file to be the default
remote-passwords file for the specified session. The name of this file is
stored in the Profile.Remote_Passwords switch of the session switch file
associated with the specified session. When no switch file exists, it is
created before the value is stored.
Note that the value of the Profile.Remote_Passwords session switch also
serves as the remote-passwords-file component of the session response
profile for the current session. Thus, to programmatically set the
default remote-passwords file for the current session, you can use the
Profile.Set_Default_Remote_Passwords procedure.
To obtain the fully qualified pathname of the remote-passwords file for a
particular session, use the Get_Default function.
PARAMETERS
Existing_File : String := "<IMAGE>";
Specifies the name of the remote-passwords file. The default is the current
image or the current selection, if one exists. Special names, wildcards,
and context characters can be used if they resolve to a single name.
For_Session : String := "";
Specifies the session for which the remote-passwords file is to be changed.
The null string (the default) signifies the current session for the current
user.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
EXAMPLES
When executed from the library containing a remote-passwords file called
Secret_Passwords, the following command sets that file to be the default
for the current session:
Remote_Passwords.Set_Default
(Existing_File => "Secret_Passwords",
For_Session => "",
Response => "<PROFILE>");
REFERENCES
function Get_Default
@node !Commands.Remote_Passwords.Show_Encryption
procedure Show_Encryption
(Of_Password : String := "<PROMPT>";
Encryption : Encryption_Method := Remote_Passwords.Des);
DESCRIPTION
Displays the encrypted form of the specified password.
This procedure displays the encrypted form of the specified password using
the specified encryption method. This procedure is useful if you are
editing a remote-passwords file directly and want to encrypt passwords.
The value displayed is identical to what would be entered in the
remote-passwords file if the same password and encryption method were
used in the Add or Change procedure.
The job report is sent to Current_Error, which is, by default, the message
window.
PARAMETERS
Of_Password : String := "<PROMPT>";
Specifies the password for which the encrypted form is desired. The
default, "<PROMPT>", prompts the user to enter the password to be
encrypted.
Encryption : Encryption_Method := Remote_Passwords.Des;
Specifies the form of encryption to be used for entering the passwords in
the new remote-passwords file. The following values are accepted:
Des The default. Specifies that the password value be
encrypted using a Data Encryption Standard (DES)
algorithm.
Hex Specifies that the password value be encryped in
hexadecimal notation.
None Specifies that no encryption be used.
EXAMPLES
The following command displays the password Opensesame encrypted according
to a DES algorithm:
Remote_Passwords.Show_Encryption
(Of_Password => "Opensesame",
Encryption => Remote_Passwords.Des);
The resulting display, shown below, is sent to the message window:
<DES:3AF67FA316AE1BE6016414A22E67A98F>
REFERENCES
procedure Add
procedure Change
type Encryption_Method
@node !Commands.Remote_Passwords.Update
procedure Update (Old_Password : String := "<PROMPT>";
For_Session : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
Updates the encryption of passwords in the remote-passwords file so that
the new encryption key is the password associated with the current user
and machine.
The encryption key for an encrypted password entry is the password for the
user who created the entry. Note that this is the password in effect at
the time the entry was created. If a user changes his or her password
(using the !Commands.Operator.Change_Password procedure), any encrypted
passwords must be updated using this procedure or errors will result when
networking operations try to use passwords encrypted under the old
password encryption key.
This procedure first decrypts the passwords in the remote-passwords file
using the password specified in the Old_Password parameter. It then
reencrypts the passwords using the current user's password for the local
machine.
PARAMETERS
Old_Password : String := "<PROMPT>";
Specifies the old password under which the remote-password entries were en-
crypted. The default, "<PROMPT>", prompts the user to enter the old
password.
For_Session : String := "";
Specifies the session for which the remote-passwords file is to be changed.
The null string (the default) signifies the current session for the current
user.
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. For the values
accepted by this parameter, see Parameter-Value Conventions in the
Reference Summary (RS) book. The default is the job response profile for
the current job.
EXAMPLES
Suppose that you have changed your password from Opensesame to
Abracadabra. To update any encrypted entries in your default
remote-passwords file so that they use Abracadabra as the encryption key,
you can use the following command:
Remote_Passwords.Update (Old_Password => "Opensesame",
For_Session => "",
Response => "<PROFILE>");
If you do not update your remote-passwords file, any operations that try to
use passwords encrypted under the old key (Opensesame) will fail.
@node !Commands.Search_List
Package Search_List provides commands for manipulating searchlists.
Searchlists are the Environment's mechanism for resolving Ada command
names that are used in command windows. Through commands in this package,
users can create, edit, view, and reset searchlists.
As with most commands in the world !Commands, these commands are intended
for interactive use, although they can be used programmatically.
RESOURCES IN PACKAGE SEARCH_LIST
The commands in package Search_List fall into several functional groups.
Types and constants are not included in this list.
Creating searchlists: Set_Up
Viewing searchlists: Display, Show_List
Editing searchlist components: Add, Delete, Replace
Resetting searchlists: Reset_To_System_Default
Storing searchlists as text files: Revert, Save
Resolving searchlist components: Display_Libraries, Show_Item
KEY CONCEPTS FOR PACKAGE SEARCH_LIST
When a command is executed, it must be located before it can be run. The
Environment locates commands using a searchlist.
A searchlist is an ordered list of libraries that is associated with a user
session. One searchlist is associated with each user session. When you enter
a command through a command window, the Environment searches through each of
the libraries named in your searchlist until the command being entered is
found. Units that are found through the searchlist are used in constructing
an implicit with clause that provides visibility for the command window.
Note that searchlists differ from links, which are used to resolve the
simple names in with clauses of Ada units. Links are not used to resolve
names in command windows unless they are explicitly included in your
searchlist (see "Searchlist Components," page nn, for more information).
The remainder of this introduction discusses:
* Searchlist components
* The system default searchlist
* A sample scenario
* Resolution of command names without a searchlist
* Resolution of object names relative to a searchlist
* Use of commands from package Search_List for:
- Creating searchlists
- Viewing searchlists
- Editing searchlists
- Resetting searchlists to the system default
- Saving and reusing multiple searchlists
- Determining how command names are being resolved
- Gaining access to searchlists
Searchlist Components
Each of the entries in the searchlist is referred to as a component of
that searchlist. Searchlist components are ordered; that is, each
searchlist component is associated with a position number.
A searchlist component must be a naming expression that resolves to one or
more library names. Searchlist components can use naming expressions such
as wildcard characters, context characters, and attributes. Naming
expressions in searchlists are resolved to library names when the
searchlist is used. Thus, context-sensitive naming expressions may
resolve to different libraries, depending on the context in which a
command is being executed. Three naming expressions are used frequently
in searchlists:
* The dollar symbol ($) can be used to mean the library enclosing the
current context, where the current context is the context from which
the searchlist is being used.
* The grave symbol (`) can be used after a library name to specify that
the links for that library also be searched when resolving command names.
The links for a library specify particular Ada units in other libraries
that are visible within that library. Note that links are normally used
to resolve simple names in with clauses of Ada units. When names are
resolved in command windows, links are checked only as a result of being
named in the searchlist, using the grave.
* The 'Spec_View and 'View attributes can be used after a subsystem name
to specify that the current spec view and load view, respectively, be
searched when to resolve command names. The current spec and load views
are determined using the default activity file for the current session.
Using these attributes prevents your having to update your searchlist
each time a new release is made.
Only fully qualified pathnames (beginning with !) or naming expressions
that resolve to fully qualified pathnames (such as $) can be used in
searchlists. Names requiring searchlist resolution cannot be added to the
searchlist. For more information about naming expressions, see
Parameter-Value Conventions in the Reference Summary (RS) book.
Note: If a searchlist contains any invalid component, the entire
searchlist is considered invalid by the Environment. If a user's
searchlist is invalid, commands entered by that user are resolved
relative to the system default searchlist. If the system default
searchlist is invalid, commands are resolved relative to the Environment's
hard-coded default searchlist (the initial system default searchlist for
all systems).
System Default Searchlist
The Environment provides a system default searchlist (located in
!Machine.Search_Lists.Default). If a searchlist has not been created for
a particular session, command names entered during that session are
resolved using the default searchlist. The default searchlist is also used
to initalize the contents of newly created searchlists.
The initial default searchlist (supplied by Rational) contains these
components:
$`
!COMMANDS
!LOCAL
!COMMANDS.ABBREVIATIONS`
!MACHINE.RELEASE.CURRENT.COMMANDS`
!IO
!TOOLS
!TOOLS.NETWORKING
System managers can edit this default searchlist to include site-specific
libraries. System managers also can extend the visibility provided by the
default searchlist by adding links in world
!Machine.Release.Current.Commands to site-specific tools.
Note that the $ resolves to the current library; thus, the library to
which it resolves depends on the context from which a command is entered.
Sample Scenario
Assume that a user named Burgan has created his own debug command in a
personal Commands directory. Assume further that his group also has
project-specific commands in !Projects.Project_Name.Commands, and his site
has local commands in !Local.Commands.
Under the default searchlist, Burgan can execute a command in one of these
libraries only if he is in the library that contains that command (via
the $ searchlist component). However, Burgan would like to be able to use
these commands from any command window. To make these commands globally
accessible, Burgan adds a component in his searchlist for each library.
Burgan's searchlist is shown below. Notice that he has chosen to insert
the components for personal, project-specific, and local Commands
directories after the Environment library called Commands.
$`
!COMMANDS
!USERS.BURGAN.COMMANDS`
!PROJECTS.PROJECT_NAME.COMMANDS`
!LOCAL.COMMANDS`
!LOCAL
!COMMANDS.ABBREVIATIONS`
!MACHINE.RELEASE.CURRENT.COMMANDS`
!IO
!TOOLS
!TOOLS.NETWORKING
Suppose that Burgan executes the Debug.Break command from a subdirectory
called !Users.Burgan.Projects. When he executes the command, the
Environment checks the following locations for an Ada package called Debug,
stopping at the first resolution:
* The current library, !Users.Burgan.Projects and its links library
* !Commands
The Environment stops at !Commands because package Debug is defined in
!Commands. The Environment does not check any other components for units
called Debug. Thus, any personal, project-specific, or local debug facility
is not found. If Burgan wants his personal commands to be used first, he
can change the order of components in his searchlist so that
!Users.Burgan.Commands appears above !Commands.
Notice that the components for Burgan's personal, project, and local
Commands libraries are followed by the grave symbol (`). The grave causes
the Environment to also search the set of links for each of those
libraries when resolving command names. Using the grave allows Burgan to
gain access to new tools (even those in other libraries) without modifying
his searchlist. To gain access to a new tool, Burgan can simply add a link
to that tool in the set of links for !Users.Burgan.Commands.
Note that to facilitate the use of the grave in searchlists, the libraries
followed by the grave should have links for visibility only. They should
not have links that are used by the tools in that library to resolve names
in with clauses.
Resolving Command Names without a Searchlist
Sometimes you need to execute a command that cannot be resolved relative
to your searchlist. Rather than edit your searchlist, you can provide the
name of the library as a string in quotation marks in front of the command
name. For example, assume that you have a procedure called
Initialize_Help_Files in !Documentation.Help.Tools. To execute
Initialize_Help_Files, you can execute the following command:
"!Documentation.Help.Tools".Initialize_Help_Files
Resolving Object Names Relative to the Searchlist
By default, pathnames of objects, particularly those called by commands,
are resolved relative to the current library. However, sometimes you may
want pathnames to be resolved relative to your searchlist. In
particular, you may want to reference the Ada specification of an
Environment command as an object, but you do not know the fully qualified
pathname of the object.
To force pathnames to be resolved with respect to your searchlist, you can
use the backslash symbol (\). In particular, \name looks for an Ada unit
with the specified name in each of the libraries listed in the current
searchlist.
For example, assume that the current window contains your home world and
that you want to view the Ada specification for the Environment command
package Library. You can do this from the current context using the
following command:
Definition ("\Library");
Because the system default searchlist includes the world !Commands, the
above command opens a window containing !Commands.Library.
See Parameter-Value Conventions in the Reference Summary (RS) book for
more information about the backslash character.
USING COMMANDS FROM PACKAGE SEARCH_LIST
Using commands from this package, you can:
* Create, view, and edit searchlists
* Reset searchlists to the system default
* Save searchlists to text files for later use
* Determine how command names are being resolved relative to the
searchlist
* Gain access to searchlists
The following subsections discuss these operations and the commands
available for each.
Creating Searchlists
You need to create a searchlist only if you want to change its components.
If no searchlist has been created for a session, operations in that
session resolve command names using the system default searchlist (see
"System Default Searchlist," page nn).
To create a new searchlist for a particular session, you can use the
Set_Up procedure. This procedure allows you to specify the components
that are to be included in the searchlist. All searchlists are created in
the !Machine.Search_Lists world and are named using the convention
username_session_name. For example, the searchlist for user Reyes's
session S_1 is named Reyes_S_1.
Note that if you execute the Add, Replace, or Delete command before you
explicitly create a searchlist, those commands will automatically create
a searchlist for your current session (with the same components as the
system default searchlist) before performing the desired operation.
Viewing Searchlists
Package Search_List provides two commands for viewing searchlists:
* Display
* Show_List
If you simply want to see a list of the components in your searchlist, you
can use the Display procedure. The Display procedure generates a textual
representation of your searchlist and sends this display, by default, to
an Environment output window. Because the display is a textual
representation and not an actual searchlist, you cannot edit your
searchlist directly from this window.
To open your searchlist for editing, use the Show_List procedure. The
Show_List procedure displays your searchlist in a window. From this window
you can edit your searchlist using commands from this package and from
package !Commands.Common (see "Editing Searchlists," below).
Editing Searchlists
This package provides three commands for modifying searchlist components:
* Add
* Delete
* Replace
These commands can be used from any location in the library hierarchy;
they do not need to be used from a window containing a searchlist.
Searchlists also can be opened for editing (using the Show_List procedure)
and modified using commands from package !Commands.Common, which generally
are bound to keys (see "Commands from Package Common for Editing Search-
lists," page nn). When used in a searchlist, some commands in package
Common call commands in this package. In particular, the
Common.Object.Insert, Common.Object.Delete, and Common.Edit commands
call the Add, Delete, and Replace commands, respectively.
Changes to searchlists are implicitly committed and take effect
immediately.
Resetting Searchlists to the System Default
If you are having trouble resolving Environment command names, you may
want to reset your searchlist to match the system default searchlist. You
can do this using the Reset_To_System_Default procedure. This procedure
deletes all the entries in your searchlist and replaces them with the
components in the system default searchlist. See "System Default
Searchlist," page nn, for more information.
Saving and Reusing Multiple Searchlists
You can use different searchlists for different projects. For example,
when you are working on debug tools, you may want your searchlist to
resolve debug commands with respect to the library containing your debug
facilities. However, when you are working on other projects, you want
debug commands to resolve with respect to the Environment's debug
facilities in !Commands.
Generally, if you use several different searchlists on a regular basis,
you probably want to create different sessions for each project. Creating
different sessions allows you to tailor your searchlist and other
characteristics such as key bindings, login procedures, error reaction,
and log files for specific projects (see the Key Concepts of this book for
more details).
If you want to invoke different searchlists in the same session, you can
use the following procedures to keep and reuse searchlists:
* The Save procedure writes the contents of the searchlist for the
specified session into a text file.
* The Revert procedure replaces the searchlist for the specified session
with the contents of the specified text file.
Note, however, that the Revert procedure overwrites your existing
searchlist. Thus, your existing searchlist will be lost (unless you first
write it into a file using the Save procedure).
Determining How a Command Name Is Being Resolved
Sometimes a particular command name does not resolve or does not resolve
as expected. When this happens, you can use the following three commands
to help determine the source of the problem:
* Display_Libraries
* Show_Item
* What.Search_List_Resolution
The Display_Libraries procedure displays a list of the libraries to which
your searchlist resolves. This procedure is especially useful when your
searchlist contains naming expressions that resolve differently
depending on the context in which your searchlist is being used.
If you want to view the library named by one of your searchlist
components, you can use the Show_Item procedure. This procedure opens a
window containing the library named by the specified searchlist component.
If a command name does not resolve, you can view the libraries to check
for similar command names.
If a command name does not resolve as you expect it to, you can use the
What.Search_List_Resolution procedure to determine the fully qualified
pathname to which the name is being resolved and the searchlist component
being used to resolve the name. Often problems with command-name
resolution are caused by the ordering of the searchlist components.
Gaining Access to Searchlists
Searchlists are explicitly associated with a particular user and session.
To reflect this association, a user's searchlists are accessed through
that user's home world (even though all searchlists are actually contained
in !Machine.Search_Lists). Thus, to modify the searchlist for a specified
user, you must have read access to that user's home world.
Note that if another user has a read lock on your searchlist while you
change the the access rights for your home world, that lock does not
prohibit the user from continuing to edit your searchlist. It only
prevents future operations from modifying your searchlist.
COMMANDS FROM PACKAGE COMMON FOR EDITING SEARCHLISTS
The commands from package !Commands.Common in Table 1 are supported for
editing searchlists. Commands from package Common typically are used
through the key combinations to which they are bound. For further
information about these commands, see the Editing Specific Types (EST)
book, package Common.
Table 1 Commands from Package Common for Editing Searchlists
---------------------------------------------------------------------
| | |
|Key Bound To ... |Accomplishes ... |
---------------------------------------------------------------------
| | |
|Common.Abandon |Ends the editing of the searchlist. The window |
| |is removed from the screen and from the window |
| |directory. Since all operations on searchlists |
| |implicitly commit any changes, this procedure |
| |does not abandon any of those changes. When |
| |used from a searchlist, this procedure has the |
| |same effect as the Release procedure. |
---------------------------------------------------------------------
| | |
|Common.Commit |Has no effect. All operations on searchlists |
| |implicitly commit any changes. |
---------------------------------------------------------------------
| | |
|Common.Create_Command|Creates a command window for the current |
| |window, if one does not exist; otherwise, the |
| |procedure puts the cursor in the existing |
| |command window. When attached to a window |
| |containing a searchlist, the command window |
| |initially has the following use clause: |
| | |
| | use Editor, Search_List, Common; |
| | |
| |Thus, commands from package Search_List can be |
| |entered in the command window using their |
| |simple names. |
---------------------------------------------------------------------
| | |
|Common.Definition |Finds the library named by the designated |
| |searchlist component and visits or creates a |
| |window containing that library. The In_Place |
| |parameter specifies whether the current window |
| |should be used (the default is False). The |
| |Visible parameter has no effect when a |
| |searchlist component is designated. |
---------------------------------------------------------------------
| | |
|Common.Edit |Creates a command window and places in it the |
| |command: |
| | |
| | Replace (New_Component => "current value",|
| | Old_Component => "<SELECTION>", |
| | Session => "", |
| | User => ""); |
| | |
| |where current value is the designated |
| |searchlist component. The Old_Component |
| |parameter specifies the searchlist component to|
| |be replaced. Specifying a new library name for |
| |the New_Component parameter causes the name of |
| |that library to replace the old component. The |
| |User and Session parameters specify the user |
| |and session whose searchlist should be modified|
| |(by default, the current session and user). |
---------------------------------------------------------------------
| | |
|Common.Release |Ends the editing of the searchlist. The window |
| |is removed from the screen and from the window |
| |directory. When used from a searchlist, this |
| |procedure has the same effect as the Abandon |
| |procedure. |
---------------------------------------------------------------------
| | |
|Common.Revert |Refreshes the image of the searchlist in the |
| |current window. If the searchlist has been |
| |changed by another user or program, the new |
| |image reflects those changes. Refreshing the |
| |searchlist image generally is not necessary, |
| |because the searchlist image is refreshed each |
| |time you add, change, or delete a component. |
---------------------------------------------------------------------
| | |
|Common.Object.Child |Selects the searchlist component on which the |
| |cursor is located. |
---------------------------------------------------------------------
| | |
|Common.Object.Delete |Deletes from the searchlist the selected |
| |component or the component on which the cursor |
| |is located. |
---------------------------------------------------------------------
| | |
|Common.Object.First- |Selects the first component in the searchlist. |
|_Child | |
---------------------------------------------------------------------
| | |
|Common.Object.Insert |Creates a command window and places in it the |
| |command: |
| | |
| | Add (Component => "[STRING-expression]", |
| | Position => 1, |
| | Session => "", |
| | User => ""); |
| | |
| |where the Component parameter must be completed|
| |with the name of one or more libraries |
| |(separated with commas). The Position parameter|
| |specifies the location in which to insert the |
| |new components. The Position parameter is |
| |automatically completed with the position |
| |designated by the cursor. Promoting the |
| |parameters allows the user to specify another |
| |session or username's searchlist to which to |
| |add an entry. |
---------------------------------------------------------------------
| | |
|Common.Object.Last- |Selects the last component in the searchlist. |
|_Child | |
---------------------------------------------------------------------
| | |
|Common.Object.Move |Moves the selected searchlist component to the |
| |current cursor position. |
---------------------------------------------------------------------
| | |
|Common.Object.Next |Selects the next component in the searchlist. |
| |If no component is selected or if the cursor |
| |is not in the current selection, this procedure|
| |selects the component on which the cursor is |
| |located. If all components are selected, this |
| |procedure produces an error. |
---------------------------------------------------------------------
| | |
|Common.Object.Parent |Selects the parent of the designated object. If|
| |no component is selected, or if the cursor is |
| |not in the selection, this procedure selects |
| |the component on which the cursor is located. |
| |If a component is selected and the cursor is in|
| |that selection, this procedure selects the |
| |entire searchlist. If the entire searchlist is |
| |selected, this procedure has no effect. |
---------------------------------------------------------------------
| | |
|Common.Object- |Selects the previous component in the |
|.Previous |searchlist. If no component is selected or if |
| |the cursor is not in the current selection, |
| |this procedure selects the component on which |
| |the cursor is located. If all components are |
| |selected, this procedure produces an error. |
---------------------------------------------------------------------
@node !Commands.Search_List.Add
procedure Add (Component : String := ">>LIBRARY NAME<<";
Position : Integer := Integer'Last;
Session : String := "";
User : String := "");
DESCRIPTION
Adds one or more components to a searchlist.
This procedure adds one or more components to the searchlist for the
specified session and user (by default, the current session and user).
Searchlist components must name existing libraries. If the named library
does not exist, that name is not added to the searchlist. The components
are added in the position specified in the Position parameter (by default,
the cursor location or the end of the searchlist).
Changes to searchlists are automatically committed and take effect
immediately.
To replace an existing searchlist component with a new component, use the
Replace procedure.
PARAMETERS
Component : String := ">>LIBRARY NAME<<";
Specifies the library names to add to the searchlist. Multiple library
names can be separated with commas. If naming expressions (such as
wildcard characters) are used in the component, they are written into the
searchlist as specified; they are not resolved first. The default parameter
placeholder, ">>LIBRARY NAME<<", must be replaced or an error will result.
Position : Integer := Integer'Last;
Specifies the position within the searchlist for the new component. By
default, the new component is inserted at the position indicated by the
cursor. If the cursor is not in the searchlist, the new component is
inserted at the end of the searchlist.
Session : String := "";
Specifies the session for which the searchlist is to be modified. The
default is the current session.
User : String := "";
Specifies the user whose searchlist is to be modified. The default is the
current user.
RESTRICTIONS
To add a component to the searchlist for a specified user, you must have
read access to that user's home world.
ERRORS
If a nonexistent username, session, or library name is specified, an error
will result.
EXAMPLES
Suppose that you have a collection of tools in a library called
!Users.Your_Username.Personal_Tools. You want to be able to access these
tools by their simple names from any command window. To do so, you can add
a component for this library to your current searchlist using the
following command:
Search_List.Add (Component => "!Users.Your_Username.Tools'",
Position => Integer'Last,
Session => "",
User => "");
If your cursor is in a searchlist, the new component will be added at the
cursor position; otherwise, the component will be added to the end of your
searchlist. This change is automatically committed and takes effect
immediately.
REFERENCES
procedure Replace
@node !Commands.Search_List.Delete
procedure Delete (Component : String := "<SELECTION>";
Session : String := "";
User : String := "");
DESCRIPTION
Deletes the specified searchlist component.
This procedure deletes the specified component from the searchlist for the
specified user and session (by default, the current user and session). If
a component is not named, the current selection is used, provided it is in
a searchlist.
Changes to searchlists are implicitly committed and take effect
immediately.
PARAMETERS
Component : String := "<SELECTION>";
Specifies the component (library name) to be deleted from the searchlist.
The default is the selected component.
Session : String := "";
Specifies the session for which the searchlist is to be modified. The
default is the current session.
User : String := "";
Specifies the user whose searchlist is to be modified. The default is the
current user.
RESTRICTIONS
To delete a component from the searchlist for a specified user, you must
have read access to that user's home world.
ERRORS
If the searchlist is not displayed on the screen and a component name is
not specified for the Component parameter, nothing will be deleted.
If a nonexistent component, username, or session is specified, an error
will result.
EXAMPLES
The following command deletes a searchlist component for a library called
!Tools.Networking from the searchlist for the current user and session:
Search_List.Delete (Component => "!Tools.Networking",
Session => "",
User => "");
The change is implicitly committed and takes effect immediately.
@node !Commands.Search_List.Display
procedure Display (Session : String := "";
User : String := "");
DESCRIPTION
Displays the searchlist for the specified session and user.
This procedure displays a list of the components in the searchlist for the
specified user and session (by default, the current user and session). The
display is sent to Current_Output, which is, by default, an Environment
output window. The list produced by this procedure cannot be modified;
however, commands from package Search_List can be used from any window
to modify the actual searchlist.
To open a searchlist for editing, use the Show_List procedure.
To obtain a list of the libraries to which your searchlist resolves, use
the Display_Libraries procedure.
PARAMETERS
Session : String := "";
Specifies the session for which the searchlist is to be displayed. The
default specifies the current session.
User : String := "";
Specifies the user whose searchlist is to be displayed. The default
specifies the current user.
ERRORS
If a nonexistent user or session is specified, an error will result.
EXAMPLES
To display a list of the components in the searchlist for your current
session, you can execute the following command:
Search_List.Display
The resulting display is sent to an Environment output window. A sample of
the display produced for a user named JIM is shown below:
Search List for: <JIM,S_1>
1. $`
2. !USERS.JIM`
3. !COMMANDS
4. !LOCAL
5. !COMMANDS.ABBREVIATIONS`
6. !MACHINE.RELEASE.CURRENT.COMMANDS`
7. !IO
8. !TOOLS
9. !TOOLS.NETWORKING
REFERENCES
procedure Show_List
@node !Commands.Search_List.Display_Libraries
procedure Display_Libraries;
DESCRIPTION
Displays a list of the libraries to which the specified searchlist
resolves.
This procedure displays a list of the libraries named in the searchlist
for the specified user and session (by default, the current user and
session).The display is sent to Current_Output, which is, by default, an
Environment output window.
This procedure can be useful in determining which libraries are actually
being searched if the expected command name is not found. If you are
having trouble determining how a particular command name is being
resolved, you can also use the What.Search_List_Resolution procedure.
EXAMPLES
Assume that the current library is !Users.Fred and that Fred's searchlist
contains the following components:
$`
!TOOLS
!COMMANDS
When Fred executes the Display_Libraries procedure, it produces the
following display:
!USERS.FRED
!TOOLS
!COMMANDS
REFERENCES
procedure What.Search_List_Resolution
@node !Commands.Search_List.Release
procedure Release;
DESCRIPTION
Ends the editing of the searchlist.
This procedure closes the searchlist being edited. It then removes the
window containing the searchlist from the screen and from the window
directory. Any changes made to the searchlist are committed.
To close the searchlist, you can also use the !Commands.Common.Abandon or
!Commands.Common.Release procedures, which generally are bound to keys.
REFERENCES
procedure !Commands.Common.Abandon
procedure !Commands.Common.Release
@node !Commands.Search_List.Replace
procedure Replace (New_Component : String := ">>LIBRARY NAME<<";
Old_Component : String := "<SELECTION>";
Session : String := "";
User : String := "");
DESCRIPTION
Replaces the specified searchlist component with the new component.
This procedure deletes the searchlist component named in the Old_Component
parameter and replaces it with the component named in the New_Component
parameter. Changes are made in the searchlist for the specified user and
session (by default, the current user and session).
Changes to searchlists are implicitly committed and take effect
immediately.
PARAMETERS
New_Component : String := ">>LIBRARY NAME<<";
Specifies the component (library name) to be inserted into the searchlist.
Multiple library names can be separated with commas. If naming expressions
(such as wildcard characters) are used in the component, they are written
into the searchlist; they are not resolved first. The default parameter
placeholder, ">>LIBRARY NAME<<", must be replaced or an error will result.
Old_Component : String := "<SELECTION>";
Specifies the component to be replaced. The default specifies the currently
selected component.
Session : String := "";
Specifies the session for which the searchlist is to be modified. The
default is the current session.
User : String := "";
Specifies the user whose searchlist is to be modified. The default is the
current user.
RESTRICTIONS
To replace an entry in the searchlist for a specified user, you must have
read access to that user's home world.
ERRORS
If a nonexistent library name, user, or session is specified, an error will
result.
EXAMPLES
Suppose that one of your searchlist components names your local tools
library. Originally, your tools were in your home world
(!Users.Your_Username), but you have moved them to
!Users.Your_Username.Tools. To change the searchlist so that you still
have access to these tools, you can use the following command:
Search_List.Replace
(New_Component => "!Users.Your_Username.Tools`",
Old_Component => "!Users.Your_Username`",
Session => "",
User => "");
The change is made in the searchlist for your current session and takes
effect immediately. Note that the grave (`) symbol at the end of each
library name indicates that the links for that library are also searched
when resolving command names.
REFERENCES
procedure Add
procedure Delete
@node !Commands.Search_List.Reset_To_System_Default
procedure Reset_To_System_Default (Session : String := "";
User : String := "");
DESCRIPTION
Resets the searchlist for the specified session and user to the system
default.
This procedure destroys the contents of the searchlist for the specified
session and user (by default the current session and user) and replaces
the contents with the system default searchlist, shown below:
$`
!COMMANDS
!LOCAL
!COMMANDS.ABBREVIATIONS`
!MACHINE.RELEASE.CURRENT.COMMANDS`
!IO
!TOOLS
!TOOLS.NETWORKING
This default searchlist is copied from !Machine.Search_Lists.Default.
PARAMETERS
Session : String := "";
Specifies the session for which the searchlist is to be reset. The default
is the current session.
User : String := "";
Specifies the user whose searchlist is to be reset. The default is the
current user.
RESTRICTIONS
To modify the searchlist for a specified user, you must have read access to
that user's home world.
ERRORS
If a nonexistent user or session is specified, an error will result.
@node !Commands.Search_List.Revert
procedure Revert (File_Name : String := "";
Session : String := "";
User : String := "");
DESCRIPTION
Replaces the searchlist for the specified session and user with the
contents of the specified text file.
This procedure deletes the contents of the specified searchlist and
replaces them with the contents of the specified text file. Searchlists can
be saved in text files with the Save procedure.
To revert a searchlist to the system default searchlist, use the
Reset_To_System_Default procedure.
PARAMETERS
File_Name : String := "";
Specifies the file from which to revert the searchlist. The default is the
searchlist for the current user and session.
Session : String := "";
Specifies the session for which the searchlist is to be reverted. The
default is the current session.
User : String := "";
Specifies the user whose searchlist is to be reverted. The default is the
current user.
RESTRICTIONS
To modify the searchlist for a specified user, you must have read access to
that user's home world.
ERRORS
If a nonexistent user, session, or file is specified, an error will result.
REFERENCES
procedure Reset_To_System_Default
procedure Save
@node !Commands.Search_List.Save
procedure Save (File_Name : String := ">>FILE NAME<<";
Session : String := "";
User : String := "");
DESCRIPTION
Saves the searchlist for the specified session and user in a text file.
Note that searchlists do not need to be saved with this procedure to take
effect. Committing the searchlist for your username and session causes
that searchlist to take effect. This procedure is necessary only if you
want to save a searchlist into a file from which you can later copy the
contents into the searchlist for a particular session.
A saved searchlist can be made current using the Revert procedure.
PARAMETERS
File_Name : String := ">>FILE NAME<<";
Specifies the name of the file in which to save the searchlist. The default
parameter placeholder, ">>FILE NAME<<", must be replaced or an error
will result.
Session : String := "";
Specifies the session for which the searchlist is to be saved. The default
is the current session.
User : String := "";
Specifies the user whose searchlist is to be saved. The default is the
current user.
RESTRICTIONS
To modify the searchlist for a specified user, you must have read access to
that user's home world.
ERRORS
If a nonexistent user or session is specified, an error will result.
REFERENCES
procedure Revert
@node !Commands.Search_List.Set_Up
procedure Set_Up (Component : String := ">>SEARCH LIST<<";
Session : String := "";
User : String := "");
DESCRIPTION
Replaces the components of the searchlist for the specified user and
session with the specified component(s).
This procedure sets up the searchlist with the specified component(s)
supplied as a string. The previous searchlist is destroyed. Multiple
components for the new searchlist are separated by commas.
To change a specific searchlist component without affecting the entire
list, use the Add, Delete, or Replace procedure.
To replace the entire contents of a searchlist with the contents of a
specified file, use the Revert procedure.
To set the entire contents of a searchlist back to the system-defined
default searchlist, use the Reset_To_System_Default procedure.
PARAMETERS
Component : String := ">>SEARCH LIST<<";
Specifies the component(s) to be included in the searchlist. Multiple
components in the string are separated by commas. If naming expressions
(such as wildcard characters) are used in the component, they are written
into the searchlist as specified; they are not resolved first. The default
parameter placeholder, ">>SEARCH LIST<<", must be replaced or an error
will result.
Session : String := "";
Specifies the session for which the searchlist is to be set up. The default
is the current session.
User : String := "";
Specifies the user whose searchlist is to be set up. The default is the
current user.
RESTRICTIONS
To modify the searchlist for a specified user, you must have read access to
that user's home world.
ERRORS
If a nonexistent library name, user, or session is specified, an error will
result.
EXAMPLES
The following command sets up the searchlist for the current user and
session so that it includes only components for the current library ($`),
!Commands`, !Local`, and !Tools`:
Search_List.Set_Up
(Component => "$`, !Commands`, !local`, !Tools`",
Session => "",
User => "");
The resulting searchlist is shown below:
$`
!COMMANDS`
!LOCAL`
!TOOLS`
Any previous components in the searchlist are deleted. The change takes
effect immediately. Note that the grave symbol (`) is used to indicate
that the links for that library are also to be searched when resolving
command names.
REFERENCES
procedure Add
procedure Delete
procedure Replace
@node !Commands.Search_List.Show_Item
procedure Show_Item (Component : String := "<CURSOR>");
DESCRIPTION
Finds the definition of the specified component of the searchlist for the
current user and session.
This procedure creates a window and displays the library named by the
specified searchlist component. The current context is used to resolve any
context-dependent components. If no component is named or selected, the
component on which the cursor is located is displayed.
If you are having trouble determining how a particular command name is
being resolved, you can use the What.Search_List_Resolution procedure to
determine the name to which the command is being resolved and the
searchlist component used to resolve the name.
PARAMETERS
Component : String := "<CURSOR>";
Specifies the component for which to find the definition. The default is the
component on which the cursor is located.
EXAMPLES
Suppose that you are unable to resolve the name of a command you thought
was in !Commands. You decide to check !Commands to see if you are entering
a correct command name or if you should be using a related command name.
The following command displays the library to which the searchlist
component !Commands resolves:
Search_List.Show_Item (Component => "!Commands");
REFERENCES
procedure Display
procedure Display_Libraries
procedure What.Search_List_Resolution
@node !Commands.Search_List.Show_List
procedure Show_List (Session : String := "";
User : String := "");
DESCRIPTION
Opens a window containing the searchlist for the specified session and
user.
This procedure creates a window and displays the searchlist for the
specified session and user (by default the current session and user) in
that window. From the window, the searchlist can be edited using commands
from this package and operations from package !Commands.Common that
apply to searchlists (see the introduction to this package for details).
PARAMETERS
Session : String := "";
Specifies the session for which the searchlist is to be modified. The
default is the current session.
User : String := "";
Specifies the user whose searchlist is to be modified. The default is the
current user.
RESTRICTIONS
To modify the searchlist for a specified user, you must have read access to
that user's home world.
ERRORS
If a nonexistent user or session is specified, an error will result.
EXAMPLES
The following command opens a window containing the searchlist for your
current session:
Search_List.Show_List
From this window, you can edit the searchlist using commands from this
package and commands from package !Commands.Common that apply to
searchlists.
@node !Commands.What
Package What contains procedures for obtaining information about the
current system, users, jobs, and objects. It also includes the
Environment's help procedures, Command and Does.
For information on what a particular key does or is called, see the
!Commands.Editor.Key.Name procedure. See also the Keymap in the
Reference Summary (RS) book for information about keys.
For further information about obtaining help in the Environment, see the
Help section of the Editing Specific Types (EST) book or the Rational
Environment User's Guide. Also see the online information about the
Environment's help facility by executing: What.Does ("Help_On_Help").
RESOURCES IN PACKAGE WHAT
The commands in package What fall into several operational groups. Types
and constants are not in this list.
Obtaining information about the system: Jobs, Load, Message, Time,
Users, Version
Obtaining information about an object: Line, Locks, Object, Tabs
Obtaining help on a command: Command, Does
Determining the resolution of a command name: Search_List_Resolution
Traversing to your home world: Home_Library
COMMANDS FROM PACKAGE COMMON FOR USE IN HELP WINDOWS
The commands from package !Commands.Common in Table 1 are supported for
manipulating the help window created by the Command or Does procedure.
Commands from package Common typically are used through the key combina-
tions to which they are bound. For further information about these
commands, see the Editing Specific Types (EST) book, package Common.
Table 1 Commands from Package Common for Use in Help Windows
---------------------------------------------------------------------
| | |
|Key Bound To ... |Accomplishes ... |
---------------------------------------------------------------------
| | |
|Common.Abandon |Removes the window from the screen and from the|
| |window directory. This procedure has the same |
| |effect as the Release procedure. |
---------------------------------------------------------------------
| | |
|Common.Create_Command|Creates a command window associated with the |
| |current window if one does not exist; |
| |otherwise, the procedure puts the cursor in the|
| |existing command window. This command window |
| |initially has a use clause: |
| | |
| | use Editor, Common; |
| | |
| |This use clause provides direct visibility to |
| |the declarations in packages Editor and Common |
| |for names resolved in the command. |
---------------------------------------------------------------------
| | |
|Common.Definition |Opens a window containing the Ada specification|
| |for the selected unit. The selection must be on|
| |the specification part of a help entry. |
---------------------------------------------------------------------
| | |
|Common.Explain |Brings up the help entry for the designated |
| |item when a list of related entries has been |
| |displayed. |
---------------------------------------------------------------------
| | |
|Common.Release |Removes the window from the screen and from the|
| |window directory. This procedure has the same |
| |effect as the Abandon procedure. |
---------------------------------------------------------------------
| | |
|Common.Object.Child |Selects the line on which the cursor is |
| |located. |
---------------------------------------------------------------------
| | |
|Common.Object.First- |Selects the first line of the image. |
|_Child | |
---------------------------------------------------------------------
| | |
|Common.Object.Last- |Selects the last line of the image. |
|_Child | |
---------------------------------------------------------------------
| | |
|Common.Object.Next |Selects the next line, provided that the cursor|
| |is on a selected line. If the cursor is not on |
| |the currently selected line or if no line is |
| |selected, the procedure selects the line on |
| |which the cursor is located. If the entire |
| |image is selected, this procedure produces an |
| |error message. |
---------------------------------------------------------------------
| | |
|Common.Object.Parent |Selects the line the cursor is on. If the |
| |cursor is already on a selected line, this |
| |procedure selects the entire image. If the |
| |entire image is already selected, this |
| |procedure has no effect. |
---------------------------------------------------------------------
| | |
|Common.Object- |Selects the previous line, provided that the |
|.Previous |cursor is on the currently selected line. If |
| |the cursor is not on the currently selected |
| |line or if no line is selected, this procedure |
| |selects the line on which the cursor is |
| |located. If the entire image is selected, this |
| |procedure produces an error. |
---------------------------------------------------------------------
COMMANDS FROM PACKAGE COMMON FOR THE WHAT.JOBS DISPLAY
The commands from package !Commands.Common in Table 2 are supported for
manipulating the display produced by the What.Jobs procedure. Commands
from package Common typically are used through the key combinations to
which they are bound. For further information about these commands, see
the Editing Specific Types (EST) book, package Common.
Table 2 Commands from Package Common for the What.Jobs Display
---------------------------------------------------------------------
| | |
|Key Bound To ... |Accomplishes ... |
---------------------------------------------------------------------
| | |
|Common.Abandon |Removes the window from the screen and from the|
| |window directory. This procedure also |
| |terminates the What.Jobs procedure. This |
| |procedure has the same effect as the Release |
| |procedure. |
---------------------------------------------------------------------
| | |
|Common.Create_Command|Creates a command window associated with the |
| |current window if one does not exist; |
| |otherwise, the procedure puts the cursor in the|
| |existing command window. This command window |
| |initially has a use clause: |
| | |
| | use Editor, Common; |
| | |
| |This use clause provides direct visibility to |
| |the declarations in packages Editor and Common |
| |for names resolved in the command. |
---------------------------------------------------------------------
| | |
|Common.Elide |Changes the set of jobs being displayed. The |
| |display steps through the following sets of |
| |jobs, in the following order: |
| |* All jobs |
| |* All running jobs |
| |* All jobs associated with the current user |
| |* All running jobs associated with the current|
| | user |
| |* All user-initiated jobs |
| |* All running user-initiated jobs |
| |* All jobs initiated by the current user |
| |* All running jobs initiated by the current |
| | user |
---------------------------------------------------------------------
| | |
|Common.Expand |Changes the set of jobs being displayed. The |
| |display steps through the following sets of |
| |jobs, in the following order: |
| |* All running jobs initiated by the current |
| | user |
| |* All jobs initiated by the current user |
| |* All running user-initiated jobs |
| |* All user-initiated jobs |
| |* All running jobs associated with the current|
| | user |
| |* All jobs associated with the current user |
| |* All running jobs |
| |* All jobs |
---------------------------------------------------------------------
| | |
|Common.Release |Removes the window from the screen and from the|
| |window directory. This procedure also |
| |terminates the What.Jobs procedure. This |
| |procedure has the same effect as the Abandon |
| |procedure. |
---------------------------------------------------------------------
| | |
|Common.Revert |Redraws the set of jobs to reflect the current |
| |state of jobs on the system. |
---------------------------------------------------------------------
| | |
|Common.Object.Child |Selects the line on which the cursor is |
| |located. |
---------------------------------------------------------------------
| | |
|Common.Object.Delete |Kills the selected job or the job on which the |
| |cursor is located. Note that if the job is not |
| |for the current session and user, the command |
| |fails. This procedure is equivalent to |
| |Job.Kill. |
---------------------------------------------------------------------
| | |
|Common.Object.First- |Selects the first line of the image. |
|_Child | |
---------------------------------------------------------------------
| | |
|Common.Object.Last- |Selects the last line of the image. |
|_Child | |
---------------------------------------------------------------------
| | |
|Common.Object.Next |Selects the next line, provided that the cursor|
| |is on a selected line. If the cursor is not on |
| |the currently selected line or if no line is |
| |selected, the procedure selects the line on |
| |which the cursor is located. If the entire |
| |image is selected, this procedure produces an |
| |error message. |
---------------------------------------------------------------------
| | |
|Common.Object.Parent |Selects the line the cursor is on. If the |
| |cursor is already on a selected line, this |
| |procedure selects the entire image. If the |
| |entire image is already selected, this |
| |procedure has no effect. |
---------------------------------------------------------------------
| | |
|Common.Object- |Selects the previous line, provided that the |
|.Previous |cursor is on the currently selected line. If |
| |the cursor is not on the currently selected |
| |line or if no line is selected, this procedure |
| |selects the line on which the cursor is |
| |located. If the entire image is selected, this |
| |procedure produces an error. |
---------------------------------------------------------------------
@node !Commands.What.Command
procedure Command (Clue : String := "");
DESCRIPTION
Produces a description of the named package, procedure, function, type, or
other Environment facility in the help window.
This procedure uses the string provided in the Clue parameter as a keyword
to match with descriptions in the help files. When a match is found, this
procedure displays the help for that facility in a help window. The help
may include the Ada specification, a description, parameter descriptions,
and key binding, if applicable.
The help window opened by this procedure can be manipulated using commands
from package !Commands.Common; see the introduction to this package for
details.
This procedure brings up the same descriptions as the Does procedure.
However, whereas the Does procedure accepts simple names, name fragments,
and naming expressions, this procedure accepts only fully qualified
pathnames.
PARAMETERS
Clue : String := "";
Specifies the fully qualified pathname of the package, procedure, function,
type, or other Environment facility for which help is requested. Simple
names, name fragments, and naming expressions are not allowed.
EXAMPLES
The following command displays a help message for the
!Commands.Editor.Line.Join procedure:
What.Command ("!Commands.Editor.Line.Join");
The resulting description, shown below, is displayed in a help window:
!commands.editor.line.join is bound to: LINE.'J', LINE.'j'
procedure Join (Repeat : Integer := 1);
Joins the next Repeat lines to the current line, leaving the cursor on
the first character that came from the last line.
REFERENCES
procedure Does
Editing Specific Types (EST), Help
@node !Commands.What.Does
procedure Does (Name : String := "");
DESCRIPTION
Produces a description of the named package, procedure, function, type, or
other Environment facility.
This procedure uses the string provided in the Name parameter as a keyword
to match with descriptions in the help files. Simple names, name fragments,
and naming expressions can be used.
If a single match is found, this procedure displays a description of that
facility. If several matches are found, this procedure opens a help menu
displaying all the Environment facilities whose name contains the specified
string. Designating an item in the menu and executing the
!Commands.Common.Explain procedure produces the help for that item.
The help window opened by this procedure can be manipulated using commands
from package !Commands.Common; see the introduction to this package for
details.
This procedure brings up the same descriptions as the Command procedure.
However, the Command procedure accepts only fully qualified pathnames; it
does not accept simple names, name fragments, or naming expressions.
PARAMETERS
Name : String := "";
Specifies a keyword for which the help files are to be searched. The name
can be any portion of a full command name. Naming expressions are also
accepted. Specifying the value "Help_On_Help" brings up information
about the Environment help facility. The default is the null string.
EXAMPLES
Example 1
The following command displays the help message for the
!Commands.Operator.Change_Password procedure:
What.Does ("Change_Password");
Example 2
The following command requests information about the Write command:
What.Does ("Write");
Several Environment commands have the word write as part of their
pathname. Thus, the Does procedure displays a help menu listing all the
relevant entries:
Index entries related to "write"
!Commands.Access_List.Write
!Commands.Activity.Write
!Commands.Common.Write_File
!Commands.Switches.Write
!Commands.Tape.Write
!Commands.Tape.Write_Mt
!Io.Direct_Io.Write
!Io.Polymorphic_Sequential_Io.Operations.Write
!Io.Sequential_Io.Write
!Tools.Access_List_Tools.Write
To see the help entry for the !Commands.Common.Write_File procedure,
designate the entry using selection or cursor position and execute the
!Commands.Common.Explain procedure (generally bound to a key).
REFERENCES
procedure Command
Editing Specific Types (EST), Help
@node !Commands.What.Home_Library
procedure Home_Library;
DESCRIPTION
Finds the window containing the user's home library and puts the cursor in
that window.
If such a window does not exist, the Environment creates it.
@node !Commands.What.Jobs
procedure Jobs (Interval : Positive := 10;
User_Jobs_Only : Boolean := False;
My_Jobs_Only : Boolean := False;
Running_Jobs_Only : Boolean := True);
DESCRIPTION
Creates a display of jobs in the Environment and updates that display once
every Interval number of seconds.
This procedure creates a window listing the specified set of jobs. The
initial set of jobs is determined by the User_Jobs_Only, My_Jobs_Only, and
Running_Jobs_Only parameters. This set of jobs can be adjusted to
include more or fewer jobs, using the !Commands.Common.Expand and
!Commands.Common.Elide procedures, respectively.
From the window produced by this procedure, you can connect to, disable,
or kill your jobs using commands from packages Job and !Commands.Common.
See the introduction to this package for details about using commands from
package Common.
Note that the window produced by this procedure is continually monitored
by the system and updated every Interval number of seconds. Thus, while
the window exists on the screen or in the window directory, this command
continues to consume CPU time. To terminate the Jobs command and the
jobs display, execute the !Commands.Common.Abandon or the
!Commands.Common.Release procedure.
To temporarily stop the updating of the jobs display, select one of the
lines in the window.
The interpretation of the display is described below in the "Examples"
section.
PARAMETERS
Interval : Positive := 10;
Specifies the minimum interval, in seconds, between updates of the screen.
The default is 10 seconds.
User_Jobs_Only : Boolean := False;
Specifies whether the display is to include only user jobs. User jobs are
those that are initiated by a user. They do not include the user's editor
and command jobs, which are started by the system when the user logs in.
The default is to display all jobs, including those that are not user
jobs.
My_Jobs_Only : Boolean := False;
Specifies whether the display is to include only jobs associated with the
user who initiates this command. The user's editor and command jobs are
included when the value of this parameter is True. The default is to
display jobs associated with the system or any user.
Running_Jobs_Only : Boolean := True;
Specifies whether the display is to include only running jobs. Running jobs
include all those that are consuming or eligible to consume CPU time. The
default is to include only running jobs. When False, all jobs, including
those that are not consuming CPU time, are included in the display.
EXAMPLES
Example 1
The following command produces a display of the jobs currently running on
the system:
What.Jobs;
The resulting display, shown below, is continually updated until you
terminate it using the !Commands.Common.Abandon or the
!Commands.Common.Release procedure:
User Session Job S Elapsed CPU % CPU Cache Disk Job Name
======= ======= === = ========= ========= ===== ===== ==== ========
SYSTEM 4 R 05:10:15 34:52.294 5.77 11K 87k
DAEMON 5 R 05:13:35 00:17.238 0.02 131 468
TDG S_1 232 I 03:51.184 00:14.974 2.45 205 503 [EDITOR]
SJL S_1 236 I 03:01:08 01:01.499 1.04 197 513 [EDITOR]
TDG S_1 244 I 19:25.119 00:46.945 8.17 212 349 [COMMAND]
SYSTEM 253 I 09:08:47 00:33.975 3.26 22 1207 "!Tools.Ftp.
The display headings are described below:
User Indicates the username under which the job was started.
Entries for jobs started by the system appear with blanks
in this column.
Session Indicates the name of the session under which the job was
started. If the job was started by the system, then the system
facility that started the job (such as SYSTEM or DAEMON)
appears in this column.
Job Indicates the number of the job.
S Indicates the state of the job. Job states are defined by
the !Commands.Scheduler.Job_State type:
R (Run) Indicates that the job is executing; it is
consuming CPU time or is eligible to consume
CPU time.
I (Idle) Indicates that the job is not executing; it
is not consuming CPU time and has no
unblocked tasks. The job may be waiting for
input or requests for service.
W (Wait) Indicates that the job is able to run but is
temporarily ineligible for CPU time. A
waiting job returns to the RUN state when
the scheduler determines that the job is
eligible for resources again.
D (Disabled) Indicates that the job has been explicitly
disabled with the !Commands.Job.Disable
procedure or the Scheduler.Disable
procedure.
Q (Queued) Indicates that the job is waiting to run
in one of the background queues.
Elapsed Indicates the elapsed time since the job began. For each
user, the time for the editor and command jobs indicates
how long that user has been logged in. Time is indicated
in one of three formats:
mm:ss.fff Indicates the number of minutes, seconds,
and decimal fractions of seconds.
hh:mm:ss Indicates the number of hours, minutes, and
seconds.
dd/hh:mm Indicates the number of days, hours, and
minutes.
CPU Indicates the total amount of CPU time the job has used
since the job began executing.
% CPU Indicates the percent of the CPU time over the last Interval
that was consumed by the job.
Cache Indicates the number of pages of memory that the job is
currently using.
Disk Indicates the number of times the job has had to wait for
the disk since it began.
Job Name Indicates the name of the job. This can be either a command
name or the name of an editor job started automatically by
a user's login (enclosed in brackets). The job names in
brackets cannot be killed by the !Commands.Common.Object-
.Delete or !Commands.Job.Kill procedures.
Example 2
To obtain a list of all jobs explicitly initiated by you, including those
that are active but not currently running, execute the following command:
What.Jobs (Interval => 10,
User_Jobs_Only => True,
My_Jobs_Only => True,
Running_Jobs_Only => False);
Example 3
To obtain a list of all user-initiated jobs currently running on the
system, execute the following command:
What.Jobs (Interval => 10,
User_Jobs_Only => True,
My_Jobs_Only => False,
Running_Jobs_Only => False);
REFERENCES
procedure Users
Editing Specific Types (EST), package Common
System Management Utilities (SMU), package Scheduler
@node !Commands.What.Line
procedure Line;
DESCRIPTION
Displays the location of the cursor.
This procedure displays the line number and column position for the
cursor's location in the image in the current window. The display is sent
to the message window.
EXAMPLES
The following command produces a report of the current cursor location:
What.Line;
The resulting report indicates that the cursor is on line 22, column 12 of
the object in the current window:
Line Number 22, Column Number 12
@node !Commands.What.Load
procedure Load (Verbose : Boolean := True);
DESCRIPTION
Displays the current system load.
Depending on the value of the Verbose parameter, the procedure can display
either of two sets of information. When the Verbose parameter is set to
True (the default), the display includes:
* The average number of runnable tasks; that is, the average number of
tasks eligible for CPU time.
* The average number of tasks waiting on disk operations.
* The average number of tasks that were withheld from running. A task is
withheld from running if it is consuming more than its share of
resources or if it has been queued or disabled (see the System
Management Utilities (SMU) book, package Scheduler).
For each category, the procedure displays the number of tasks averaged
over one of four sampling intervals:
* The last 100 milliseconds
* The last minute
* The last 5 minutes
* The last 15 minutes
When the Verbose parameter is set to False, this procedure displays only
the average number of runnable tasks over the four sampling intervals.
The job report is sent to Current_Error, which is, by default, the message
window.
PARAMETERS
Verbose : Boolean := True;
Specifies whether to display the full set of load numbers. The default is
to display the full set. See "Description," above, for a list of the load
numbers included in the full set. When False, only the load numbers for
runnable tasks are displayed.
EXAMPLES
Example 1
The following command produces a list of the CPU load numbers, resulting
in the display below:
What.Load (False);
Load: 1.95, 0.25, 0.48, 0.41
In this display:
* 1.95 is the average number of tasks in the run queue during the last
100 milliseconds.
* 0.25 is the average number of tasks in the run queue in the last
minute.
* 0.48 is the average number of tasks in the run queue in the last 5
minutes.
* 0.41 is the average number of tasks in the run queue in the last 15
minutes.
Example 2
The following command produces the verbose list of the current system
load:
What.Load;
The verbose list appears as follows:
L: 1.98, 0.35, 0.62, 0.44 D: 0.00, 0.04, 0.06, 0.04 H: 0.00, 0.00, 0.00, 0.00
where:
* L (Load) lists the number of runnable tasks, averaged over the last 100
milliseconds, 1 minute, 5 minutes, and 15 minutes, respectively.
* D (Disk) lists the number of tasks waiting for pages from disk,
averaged over the last 100 milliseconds, 1 minute, 5 minutes, and 15
minutes, respectively.
* H (Held) lists the number of withheld jobs, averaged over the last 100
milliseconds, 1 minute, 5 minutes, and 15 minutes, respectively.
REFERENCES
System Management Utilities (SMU), procedure Scheduler.Get_Disk_Wait_Load
System Management Utilities (SMU), procedure Scheduler.Get_Run_Queue_Load
System Management Utilities (SMU), procedure Scheduler.Get_Withheld_Task_Load
@node !Commands.What.Locks
procedure Locks (Name : String := "<IMAGE>");
DESCRIPTION
Displays the locks that exist on the specified object.
The Environment places a lock on an object when a job or user is accessing
the object. This procedure displays the locks that exist on the specified
object. You may want to use this procedure to check for the locks on an
object if:
* An Io.Open command raises the Io_Exceptions.Use_Error error (lock
error).
* The editor reports a lock error.
* Other operations indicate problems accessing the object.
The locks are identified by job identity, job number, and kind. "Reader"
signifies that the indicated job or user is viewing the object but has not
opened it for editing. "Updater" signifies that the indicated job or user
is making changes to the object, such as editing or compiling it.
Note that the editor maintains separate locks on the DIANA representation
of an Ada unit and its image. Locks on the image of an Ada unit are
indicated by the suffix "'Image" attached to the unit's name in the locks
display.
The job display is sent to Current_Output, which is, by default, an
Environment output window. Errors are reported in the message window.
PARAMETERS
Name : String := "<IMAGE>";
Specifies the object whose locks should be displayed. Wildcards, context
characters, set notation, indirect files, and attributes can be used. The
default is the current image.
EXAMPLES
Suppose that you try to open for editing a unit called
!Projects.Numerical_Tools.Baseball_Statistics, but you encounter a lock
error. You can execute the following command to determine the cause of
the lock error:
What.Locks (Name => "!Projects.Numerical_Tools.Baseball_Statistics'Body");
The resulting display, shown below, indicates that job number 153,
belonging to user Lisk, has a write lock on Baseball_Statistics'Body. To
determine whether Lisk is editing the unit or compiling it, you could use
the Jobs procedure to list the names of the jobs on the system.
!PROJECTS.NUMERICAL_TOOLS.BASEBALL_STATISTICS'BODY'V(1)
Updater: LISK.S_1 Job 153
REFERENCES
procedure Jobs
@node !Commands.What.Message
procedure Message (File : String := "Daily_Message");
DESCRIPTION
Displays the message contained in the specified file.
This procedure typically is included in login procedures to display the
daily message contained in !Machine.Editor_Data.Daily_Message.
The job display is sent to Current_Output, which is, by default, an
Environment output window.
PARAMETERS
File : String := "Daily_Message";
Specifies the name of the message file to be displayed. If a relative
pathname is used, it is resolved with respect to the current context. If
the name is not defined in the current context, the procedure displays the
contents of !Machine.Editor_Data.Daily_Message, if such a file exists.
EXAMPLES
The following command reports the message contained in
!Machine.Editor_Data.Daily_Message:
What.Message;
A sample message for a machine called Rational_1 is displayed below. Note
that the contents of the Daily_Message file will be different for other
machines.
Welcome To Rational_1
---------------------
Environment Release 12_1_1
Mail Release 11_5_0
RDF Release 6_2_5
MC68020/UNIX Release 6_2_2
For release information, please see the release notes in library
!Machine.Release.Release_Notes.
For information about using nondefault message files and sending messages,
see the System Management Utilities (SMU) book or the System Manager's
Guide.
@node !Commands.What.Object
procedure Object (Name : String := "<IMAGE>");
DESCRIPTION
Displays the fully qualified name of the specified object.
This procedure resolves the specified name with respect to the current
library and displays the fully qualified pathname. The job display is sent
to Current_Error, which is, by default, the message window.
PARAMETERS
Name : String := "<IMAGE>";
Specifies the name for which the fully qualified pathname is to be
displayed. The default is the current image.
@node !Commands.What.Search_List_Resolution
Search_List_Resolution (Name : String := "<CURSOR>");
DESCRIPTION
Resolves the specified name in the context of the searchlist for the
current session.
This procedure resolves the value of the Name parameter in the same way
that command names are resolved. Thus, this procedure is useful as a
diagnostic tool when the names you enter in command windows fail to
resolve or resolve in unexpected ways.
Specifically, this procedure looks for an Ada unit (or a declaration in an
Ada unit) with the specified name, searching each of the libraries in the
current searchlist in succession.
* If such an object is found, its fully qualified pathname is displayed
along with the searchlist component that led to the resolution.
* If more than one of the libraries named in the searchlist contains an
Ada object with the specified name, this procedure resolves to the first
one it encounters.
* If no such object is found in any library on the searchlist, a message
is displayed to that effect.
The job report is sent to Current_Error, which is, by default, the message
window.
This procedure is similar to using the Library.Resolve command with the
searchlist context character \ (see Parameter-Value Conventions in the
Reference Summary (RS) book). However, unlike the Library.Resolve
procedure, this procedure also reports the searchlist component that was
used for the resolution.
PARAMETERS
Name : String := "<CURSOR>";
Specifies the Ada name to be resolved. The name can be simple or qualified.
If more than one name is specified (for example, using wildcards or set
notation), only the first name is resolved. The default is the name
designated by the cursor.
EXAMPLES
Assume that user Anderson has created a package called Debug in the Tools
subdirectory in his home library. Assume further that he is trying to
debug a program in another subdirectory of his home library. When he
enters the standard Environment command Debug.Break, a message reports
that the name Debug.Break is undefined. To diagnose this problem, he can
enter the following command:
What.Search_List_Resolution ("debug.break");
This command produces the following report:
DEBUG resolves, via searchlist component 1 ($`), to !USERS.ANDERSON.
TOOLS.DEBUG'SPEC'V(3), but DEBUG.BREAK is not defined because BREAK
is not defined in [!USERS.ANDERSON.TOOLS.DEBUG'SPEC'V(3)]
From this message, Anderson sees that the command name Debug.Break is
being resolved through the first component on his searchlist. This
component ($`) causes the Environment to search through the current
library and its links. Because the current library is a subdirectory of
Anderson's home world, the current library has internal links to units in
the Tools subdirectory. Thus, the name Debug is resolved to Anderson's
own package Debug, which has no Break procedure.
To be able to write tools against his own package Debug while still being
able to execute commands from !Commands.Debug, Anderson can change his
searchlist so that the component $` follows the component !Commands.
REFERENCES
package Search_List
Library Management (LM), procedure Library.Resolve
@node !Commands.What.Tabs
procedure Tabs;
DESCRIPTION
Displays all of the current tab stops.
The job display is sent to the message window.
EXAMPLES
The following command displays the current tab stops:
What.Tabs
The resulting display, below, indicates each tab stop with a vertical bar.
| | | | | | | | | | | | | | | | | |
@node !Commands.What.Time
procedure Time;
DESCRIPTION
Displays the current date and time of day.
The job display is sent to Current_Error, which is, by default, the
message window.
EXAMPLES
The following command produces the report below:
What.Time;
June 2, 1991 at 10:24:23 AM
@node !Commands.What.Users
procedure Users (All_Users : Boolean := True);
DESCRIPTION
Displays a list of users who are currently logged in and the active jobs
of each user or of the invoking user.
This command is useful for obtaining a user's port number before logging
that user off using the !Commands.Operator.Force_Logoff procedure or for
obtaining a job number to be used in the !Commands.Job.Kill procedure.
For each user currently logged in, this procedure lists:
* The user's login ID or username
* The port number on which the user is logged in
* The jobs associated with the user
* The state of each job
* The amount of time each job has been active
* The name of each job
If a user is logged into more than one session on the current system, each
session is listed separately.
The job display is static; that is, it is not updated automatically when
users log in and out or when jobs terminate. You must run the command
again to display a new list with current information.
The job display is sent to Current_Output, which is, by default, an
Environment output window.
To obtain an abbreviated list of the users logged into the system, use the
!Commands.Abbreviations.Users procedure.
PARAMETERS
All_Users : Boolean := True;
Controls whether the job display includes information for all the users
currently logged in (True) or only for the user who entered the Users
command (False). If False and the user is currently logged into more than
one session, only information for the current session is displayed.
EXAMPLES
Example 1
The following command produces the report below, containing a list of all
the users currently logged in:
What.Users;
User Status on May 5, 1991 at 1:58:10 PM
User Line Job S Time Job Name
============== ==== === ==== ======== =========================
*SYSTEM - 4 RUN 5/04:19 System
5 RUN 5/04:19 Daemons
131 IDLE 2/23:08 Print Spooler
199 IDLE 5/03:41 Mail LOCAL Carrier
248 IDLE 5/03:44 Smooth Snapshots
NETWORK_PUBLIC - 168 IDLE 5/03:41 Mail Distribute Server
185 IDLE 22:01:19 Print Queue Server
191 IDLE 1:56:12 Archive Server
JAF 239 140 RUN 0.806 !USERS.JAF % WHAT.USERS
159 RUN 2:09:02 [JAF.S_1 Editor]
193 IDLE 2:07:15 [JAF.S_1 Command]
SJB 247 169 IDLE 3/03:59 [SJB.S_1 Command]
179 IDLE 3/03:59 [SJB.S_1 Editor]
NAM 246 167 IDLE 4/04:01 [NAM.S_1 Command]
252 IDLE 4/04:01 [NAM.S_1 Editor]
JAF 240 135 IDLE 1:25:01 [JAF.S_2 Command]
176 IDLE 1:26:10 [JAF.S_2 Editor]
The headings are described below:
User Indicates the username under which the job was started. The
username is shown once for each active session. It is not
repeated for each job running under that session. The username
*SYSTEM indicates jobs that belong to the Environment itself.
Line Indicates the port number on which the user is logged in. A
dash (-) indicates that the user is not logged into the
Environment but has one or more jobs running.
Job Indicates the number of the job.
S Indicates the state of the job. Job states are defined by the
!Commands.Scheduler.Job_State type:
RUN Indicates that the job is executing; it is
consuming CPU time or is eligible to consume CPU
time.
IDLE Indicates that the job is not executing; it is
not consuming CPU time and has no unblocked tasks.
The job may be waiting for input or requests for
service.
WAIT Indicates that the job is able to run but is
temporarily ineligible for CPU time. A waiting job
returns to the RUN state when the scheduler
determines that the job is eligible for resources
again.
DISABLED Indicates that the job has been explicitly
disabled with the !Commands.Job.Disable procedure
or the Scheduler.Disable procedure.
QUEUED Indicates that the job is waiting to run in
one of the background queues.
Time Indicates the elapsed time since the job began. For each
user, the time for the editor and command jobs indicates how
long that user has been logged in. Time is indicated in one of
three formats:
mm:ss.fff Indicates the number of minutes, seconds, and
decimal fractions of seconds.
hh:mm:ss Indicates the number of hours, minutes, and
seconds.
dd/hh:mm Indicates the number of days, hours, and minutes.
Job Name Indicates the name of the job. The editor and command
jobs represent the user's session.
Example 2
The following command produces the display below, listing the jobs
currently running under user GZC's current session:
What.Users(False);
User Status on June 17, 1991 at 04:22:52 AM
User Line Job S Time Job Name
======== ==== ==== ==== ========= ==========================
GZC 241 188 IDLE 1:29:58 [GZC.S_1 Command]
228 RUN 2.187 GZC_WORK.REV1_WOR
250 RUN 1:30:14 [GZC.S_1 Editor]
REFERENCES
procedure Jobs
@node !Commands.What.Version
procedure Version;
DESCRIPTION
Displays the version (release) number of the current Environment.
The job display is sent to Current_Error, which is, by default, the
message window.