⟦cfc802fc4⟧

TextFile


Introduction
------------
This is a users' manual for the console command interpreter.
The console command interpreter is a user interface for the
R1000 system console.  It allows an operator to run environment
programs, such as Backup and Source_Archive, from the console.
The other functions of the console (EEDB and Kernel commands)
are not changed.

The purpose of the console command interpreter is to allow the
system operator to perform common system maintenance functions
at the console.  It is NOT intended for software development.


Installation
------------
The console command interpreter requires the Delta release of
the Rational Environment for correct operation.

The console command interpreter is distributed as an Environment
program, in the subsystem !Tools.CI.  Use the most recent version
(view) of this subsystem.  When you install the !Tools.CI world, 
you should also update the current release world (!Machine.Release
.Current), as follows:

  - Current.Activity should include an entry for !Tools.CI,
    specifying the most recent load view.  Correct operation
    of Ci.Login depends on this.

  - Current.Commands should include links to !Tools.CI.<revn>
    .Units.Commands.@.  These are command programs intended for 
    use by command interpreter users.
    
To enable the command interpreter, execute the procedure Ci.Login.
Ordinarily you will do this in the !Machine.Initialize procedure, 
like this:

    Program.Run_Job (Program.Current
                        ("!tools.ci",
                         "ci.login",
                         Activity => "!machine.release.current.activity"),
                     Context => "!machine.error_logs",
                     Options => "output=!machine.error_logs.ci_output"
                              & ",error=!machine.error_logs.ci_error");
                              
Be sure to specifiy output and error files in the Options string.
If you don't do this, Ci.Login will not run.

In some early versions of the Delta environment, consecutive calls to 
Program.Run_Job from one job must be seperated in time by about 3 minutes
for correct operation.  Do this with "delay 180.0" in !Machine.Initialize.
    
Ci.Login takes parameters:

    Terminal  the terminal on which to prompt for input.  
              The default value is the system console.
              
    Timeout   if the interpreter is prompting for a command,
              and the user doesn't type anything for this period
              of time, then the user will be automatically logged
              out.  The default value is one minute.
              
Ci.Login will prompt for a username and password, and then start
interpreting commands under that identity.  When the user logs out,
either by command or timeout, Login will once again prompt for a
username and password.

Another procedure Ci.Interpret is available, which will simply
prompt for commands and execute them under the caller's identity.
When the user logs out, either by command or timeout, Interpret
will return.  This procedure was written mainly for testing.

It is possible but not recommended to run several interpreters at
once.  Doing this will create some confusion, since the console
user will have to keep track of multiple interpreter prompts, with
potentially different user_ids.


Users' Overview
---------------
Go to the R1000 system console, and type ^Z (control-Z) a few times.
If the system is running normally, this will cycle through several
prompts, including the kernel prompt, the EEDB prompt, and the
console command interpreter prompt:

    ====> job 234 <====
    username:                          
                       
The job number shown in your banner line will vary.  If you don't 
find an interpreter prompt, see the installation section, above.
Enter a username, a password, and (if you wish) a session name.
Each line is terminated by a carriage return or line feed.

    ====> job 234 <====
    username: operator
    password:
    session: fred
                                                               
The password is not echoed, to increase security.  If you don't 
enter a session name, the Login program will use "S_1".
The interpreter will write a few messages, and prompt you for a
command:

    ====> job 253 <====
    command:
    
The job number in your banner will vary.  At this point, you can 
type in any environment command, and the interpreter will execute it.  
For example,

    ====> job 253 <====
    command: what.time;
    
    ====> job 246 <====
    December 8, 1986 at 12:35:11 PM

    ====> job 253 <====
    command:
    
Notice the banner lines.  The console command interpreter, like
the Rational Environment, runs each command as a user job, with
its own input and output streams.  Output for each job is identified 
on the console screen by banner lines, giving the job number of the
job which did the output.  You can see the relationship between jobs
and programs by running What.Users: 

    ====> job 253 <====
    command: what.users;
    
    ====> job 240 <====
    User Status on December 8, 1986 at 12:40:46 PM
    
     USER    LINE  JOB   STATUS    TIME                JOB NAME
    =======  ====  ====  ======  =========  ==============================
    *SYSTEM     -         RUN      1:06:34  session'(*SYSTEM)
    JMK       240         RUN    57:35.643  session'(S_1)
                    246   RUN        2.523  CI.REV8_6_1.UNITS % WHAT.USERS
    PHIL      241         IDLE   56:46.633  session'(S_1)
    SRP       242         IDLE   55:27.982  session'(S_1)
    
    ====> job 253 <====
    command:
    
When you're done with the command interpreter, enter the Quit command:

    ====> job 253 <====
    command: quit

The interpreter will write some messages to the console, and once
again prompt you for a username.

If you don't respond to the command prompt within a certain period
of time, the interpreter will Quit automatically.  This is intended
to improve security.  The timeout period is chosen when the Login
program is started.  The default value is 60 seconds.
                                                     

User Commands
-------------
Most of the time you'll use the command interpreter to execute
Environment commands.  Refer to the Rational Environment manuals
for commands and their parameter profiles.

The command interpreter, like all jobs, has a "current context".
This is an object (usually a library, but it can be a file or an
Ada object) in whose context names are resolved.  The initial
value is your home library.  You can change the current context 
using the command interpreter "def" command:

    ====> job 253 <====
    command: def ("!");
    86/12/08 12:47:51 ::: [Library.Context ("!", PERSEVERE);].
    86/12/08 12:47:53 +++ Current context is now !
    86/12/08 12:47:53 ::: [End of Library.Context command].
    command:           
    
Def works like an Ada procedure, with the same parameter profile and
effect as Library.Context (see the Workspace Management section
of the Rational Environment Reference Manual).  Def is special,
however, in that it changes the context of the command interpreter
itself, not a command job.  This means that Def changes the context 
in which subsequent commands are executed, whereas Library.Context 
just affects one command.

The command interpreter can execute user-written programs in the
same way as Environment commands.  Just enter a call to the program,
with the appropriate arguments.

One program you may find useful is Typ.  It takes a single argument,
which is a string name, and writes the text representation of the
named objects to the output stream (i.e. the console).  The name
may contain wildcards, in which case multiple objects will be typed.
Typ is distributed with the command interpreter software, and should
be included in the default searchlist during installation.

Input to the command interpreter can be edited a little bit.
Delete or Control-H will erase a character, Control-U will erase 
all of the current line, and Control-A or Control-B will replace 
the current line with the previous line.

Each input line is treated as a little Ada program, so you can
enter multiple environment commands seperated by semicolons on
a single line, and they will be executed in sequence.  You can
also build loops, conditional statements, and so on, altough there
is a limit (256 characters) to the length of a single line.
Don't do this with the Def or Quit commands, however: those 
commands should be executed on a line by themselves.

If a program is running, and you'd like to enter another command,
type Control-G.  The running program will continue to run, at the 
same time that you are typing at the command interpreter.  You can
do this multiple times, each time starting another concurrent job.
DataMuseum.dk

Rational R1000/400

⟦cfc802fc4⟧ TextFile

Derivation

TextFile
