[Cyan]<CedarPS>NSExec>NSExec.mesa!1

NSExec.mesa

Last revised by McManis on: 29-Apr-85 15:53:46

Tim Diebert: October 23, 1986 10:34:58 am PDT

DIRECTORY

CHNameP2V0 USING [Name],

IO USING [STREAM],

NSString USING [String],

Rope USING [ROPE],

TTY USING [Handle],

XFormat USING [Handle],

XNS USING [Address],

XNSAuth USING [Identity];

NSExec: CEDAR DEFINITIONS = BEGIN

OPEN CHName: CHNameP2V0;

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Copied Types

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

ROPE: TYPE ~ Rope.ROPE;

STREAM: TYPE ~ IO.STREAM;

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Types

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

ClientID: TYPE = RECORD [CARDINAL];

unique for each exec client

ClientProcs: TYPE = RECORD [

init: PROCEDURE [exec: Handle, normal: BOOLEAN],

normal indicates whether the client should consider this a "normal" startup.

start: ExecProc, -- called to start a client

stop: PROCEDURE [exec: Handle, stopMode: StopMode],

called to stop a client

unload: ExecProc,

<< is called when a client is unloaded from the exec. The client should use this proc to perform any necessary cleanup, including removing any commands it may have registered. >>

expunge: ExecProc,

<< called when a client is being permanently removed from a server. The client should use this proc to delete any data files which it created during runtime, but will not be needed after the client is permanently removed. >>

logon: ExecProc ← NIL, -- called when a user logs on

logoff: ExecProc ← NIL, -- called when a user logs off

name: PROCEDURE [nameProc: PROCEDURE [clientName: NSString.String]] ← NIL,

Returns the name of the client by calling nameProc with the appropriate value for clientName.

status: PROCEDURE [statusProc: PROCEDURE [status: ClientStatus, comment: NSString.String]] ← NIL

Returns the client status and a short comment about that status by calling statusProc.

];

ClientStatus: TYPE = MACHINE DEPENDENT {started, starting, stopped, stopping};

Command: TYPE = RECORD [

name: NSString.String, -- the word(s) composing the command

proc: ExecProc, -- performs the command

activityCheck: Predicate ← NIL, -- called to see if the command is active

helpProc: ExecProc ← NIL]; -- called when the user requests help for the command

Commands: TYPE = REF CommandsRep;

CommandsRep: TYPE ~ RECORD [command: SEQUENCE length: CARDINAL OF Command];

Context: TYPE = LONG UNSPECIFIED;

EnumerateClientProc: TYPE = PROCEDURE [id: ClientID, command: Command, acronym: ROPE, procs: ClientProcs] RETURNS [continue: BOOLEAN ← TRUE];

EnumerateExecProc: TYPE = PROCEDURE [exec: Handle] RETURNS [continue: BOOLEAN ← TRUE];

ExecProc: TYPE = PROCEDURE [exec: Handle];

Handle: TYPE [2];

Predicate: TYPE = PROCEDURE [exec: Handle] RETURNS [BOOLEAN];

Returns TRUE iff the command associated with the predicate is available to the user.

StopMode: TYPE = {quiesce, quitCold};

TerminationHandler: TYPE = PROCEDURE [exec: Handle, context: Context];

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Constants :

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

nullHandle: Handle = LOOPHOLE[LONG[NIL]];

nullClientID: ClientID = [LAST[CARDINAL]];

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Variables :

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

localExec: READONLY Handle; -- handle for the local TTY

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Errors:

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Error: ERROR [type: Errortype];

Errortype: TYPE = {cannotExpunge, cannotInitialize, duplicateCommand, invalidExec, invalidID, invalidString, noContextSet, noUser};

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Operations:

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Creating and Manipulating Exec Clients:

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

AssignClientID: PROCEDURE RETURNS [ClientID];

CreateClient: PROCEDURE [id: ClientID, command: Command, procs: ClientProcs,
acronym: NSString.String];

<< adds a client to the executive. id is obtained from AssignClientID. command is registered as an exec command. The command name should be the generic name of the client (File Service, Mail Service, Print Service, etc). acronym is a two or three character abbreviation for the command name and is used as a shorthand way to identify the client when interacting with the user. The command proc is executed whenever the user gives command name as a command. Also, if any client commands have been added via AddClientCommands they will then become available and the user will be prompted by acronym followed by a ">", e.g. FS>, PS>, etc.

Error[invalidString] is raised if the command name is a null string or contains illegal characters. Error[duplicateCommand] is raised if command name duplicates an existing command. Error[invalidID] if id is nil or obsolete.>>

DestroyClient: PROCEDURE [id: ClientID];

removes a client AND any commands it may have added. Raises Error[invalidID] if id is nil or obsolete.

EnumerateClients: PROCEDURE [enumProc: EnumerateClientProc];

enumProc is called for each exec client.

ClientState: PROCEDURE [id: NSExec.ClientID] RETURNS [activated, initialized: BOOLEAN];

indicates whether client is activated or has been initialized. May raise NSExec.Error[invalidID]

AddClientCommands: PROCEDURE [id: ClientID, commands: Commands];

<< adds commands to the client represented by id. commands will only be available to the user after the client's name command is executed AND the activityCheck procs for the individual commands return TRUE. After the client's name command is executed, the user will be prompted by the client acronym followed by a ">", e.g. FS>, PS>, etc.

Raises Error[invalidID] if id is nil or obsolete. Raises Error[invalidString] if any of the command name are nil or contain illegal characters. Raises Error[duplicateCommand] if any command names duplicate existing commands. >>

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Creating and Manipulating Execs:

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

CreateExec: PROCEDURE [tty: STREAM, host: XNS.Address];

creates a new executive which continually accepts and processes user commands. CreateExec does not return until the exec is destroyed, e.g. the remote connection is broken.

EnumerateExecs: PROCEDURE [enumProc: EnumerateExecProc];

calls enumProc for each active exec

AddExecCommand: PROCEDURE [command: Command, unload: PROCEDURE ← NIL];

adds command to the executive. This command is available regardless of which client commands are currently accessable. unload is called if the command is unloaded from the executive.

RemoveExecCommand: PROCEDURE [name: NSString.String];

removes name as an exec command, having no effect if name is not a command.

GetTTY: PROCEDURE [exec: Handle] RETURNS [tty: TTY.Handle];

returns the tty handle for exec. May raise Error[invalidExec].

CheckForAbort: PROCEDURE [exec: Handle] RETURNS [abort: BOOLEAN];

returns true is the user abort flag has been set

All of the context operations may raise Error[invalidID] or Error[invalidExec] if id or exec is nil or obsolete.

SetContext: PROCEDURE [exec: Handle, id: ClientID, context: Context,
terminationHandler: TerminationHandler];

adds client defined context to exec. terminationHandler is called when exec is destroyed.

GetContext: PROCEDURE [exec: Handle, id: ClientID] RETURNS [context: Context];

returns current context for exec and id. May raise Error[noContextSet].

DestroyContext: PROCEDURE [exec: Handle, id: ClientID];

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

String Output:

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

BroadcastAsyncMessage: PROCEDURE [string: NSString.String, id: ClientID];

outputs string asynchronously to all current executives. id identifies the originator of the msg. May raise Error[invalidID].

PutAsyncMessage: PROCEDURE [exec: Handle, string: NSString.String, id: ClientID];

outputs string asynchronously to exec. id identifies the originator of the msg. May raise Error[invalidID].

PutIndentedMessage, PutErrorMessage: PROCEDURE [exec: Handle, string: NSString.String];

outputs string to exec, indented 8 spaces from the margin. May raise ABORTED if exec has been destroyed.

PutMessage: PROCEDURE [exec: Handle, string: NSString.String];

outputs string to exec. May raise ABORTED if exec has been destroyed.

OutputHandle: PROCEDURE [exec: Handle] RETURNS [XFormat.Handle];

the returned XFormat.Handle can be used by XFormat procedures to output to exec. May raise Error[invalidExec].

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

User Data:

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

All operations return values for the user logged on at exec. May raise Error[noUser].

UserName: PROCEDURE [exec: Handle] RETURNS [name: CHName.Name];

UserIdentity: PROCEDURE [exec: Handle] RETURNS [identity: XNSAuth.Identity];

UserFilingSession: PROCEDURE [exec: Handle] RETURNS [session: NSFile.Session];

UserState: PROCEDURE [exec: Handle] RETURNS [loggedOn, serverSA, enabled: BOOLEAN];

UserLoggedOn, UserAServerSA, UserEnabled: Predicate; -- will not raise Error[noUser]

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Genesis:

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

These predicates are used when commands should be available during Genesis.

Genesis: NSExec.Predicate; -- TRUE if server is in genesis

GenesisOrEnabledSA: NSExec.Predicate; -- same as (Genesis OR UserEnabled)

GenesisOrSA: NSExec.Predicate; -- same as (Genesis OR UserAServerSA)

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Server and System Data:

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

ServerName: PROCEDURE RETURNS [name: CHName.Name];

ServerIdentity: PROCEDURE RETURNS [identity: XNSAuth.Identity];

SystemFilingSession: PROCEDURE RETURNS [session: NSFile.Session];

SystemDirectory: PROCEDURE RETURNS [directory: ROPE];

directory where client software may create files.

WorkingDirectory: PROCEDURE RETURNS [directory: ROPE];

general purpose directory containing files which can be manipulated users.

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Running Additional Software:

-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --

Run: PROCEDURE [name: ROPE, exec: Handle, codeLinks: BOOLEAN ← FALSE];

loads and starts the file given by name. May raise Runtime.ConfigError.

END.

LOG [Time - Person - Action]

14-Nov-83 8:54:49 - McManis - Created file.

3-Jan-84 15:16:44 - McManis - Added nullHandle, nullClientID, Context and TerminationHandler. Changed SetContext and GetContext to use Context and TerminationHandler. Renamed OutputObject to OutputHandle and changed it to return XFormat.Handle. Changed CreateExec to take "host: System.NetworkAddress" rather than credentials.

29-Apr-85 15:52:51 - McManis - Added cannotExpunge and cannotInitialize to ErrorType. Removed notInitialized from ClientStatus. Added predicates for Genesis.