DataMuseum.dk

Presents historical artifacts from the history of:

Rational R1000/400 Tapes

This is an automatic "excavation" of a thematic subset of
artifacts from Datamuseum.dk's BitArchive.

See our Wiki for more about Rational R1000/400 Tapes

Excavated with: AutoArchaeologist - Free & Open Source Software.


top - download
Index: ┃ T V

⟦94f7351dd⟧ TextFile

    Length: 21962 (0x55ca)
    Types: TextFile
    Names: »V«

Derivation

└─⟦5f3412b64⟧ Bits:30000745 8mm tape, Rational 1000, ENVIRONMENT 12_6_5 TOOLS 
    └─ ⟦91c658230⟧ »DATA« 
        └─⟦458657fb6⟧ 
            └─⟦a5bbbb819⟧ 
                └─⟦this⟧ 
└─⟦8ee07855d⟧ Bits:30000545 8mm tape, Rational 1000, DTIA 2_1_6
    └─ ⟦0c25cb74a⟧ »DATA« 
        └─⟦0182c9918⟧ 
            └─⟦ed024cadb⟧ 
└─⟦d0624311f⟧ Bits:30000529 8mm tape, Rational 1000, DTIA 2_1_7
    └─ ⟦f494b5154⟧ »DATA« 
        └─⟦3ddce7122⟧ 
            └─⟦ed024cadb⟧ 
                └─⟦this⟧ 
└─⟦d10a02448⟧ Bits:30000409 8mm tape, Rational 1000, ENVIRONMENT, D_12_7_3
    └─ ⟦fc9b38f02⟧ »DATA« 
        └─⟦9b46a407a⟧ 
            └─⟦eec0a994f⟧ 
                └─⟦this⟧ 

TextFile

with Profile;
with Calendar;
with Simple_Status;
with Device_Independent_Io;

package Remote_Operations is

    subtype Error_Status is Simple_Status.Condition;

    ---------------------------
    -- CONNECTION MANAGEMENT --
    ---------------------------
    --
    -- Connections are implicitly established and recorded in an active
    -- connection pool during the target operations listed below.  The
    -- connection management operations listed here provide a means of
    -- directly querying and modifying the active connection pool.  When
    -- a new connection is required after the open connection limit has
    -- been reached, the least recently used connection is displaced by
    -- the new connection.
    --
    -- The active connection pool is maintained on a per login session
    -- basis.  When a particular job ACQUIRE's access to a new target
    -- context, a CONTEXT object is created, recorded in the active
    -- connection pool, and marked 'in use'.  When the job RELEASE's
    -- access on the object, it is made available to other jobs on the
    -- session via the active connection pool and the target connection
    -- is left open.  When a job DESTROY's a context object, the target
    -- connection is closed and the object is removed from the active
    -- connection pool.


    type Context is private;
    --
    -- Represents the context of a particular connection within the
    -- active connection pool.  Objects of this type are logically
    -- composed of a set of fields that uniquely name a particular
    -- remote operations server on a given machine.

    Nil_Context : constant Context;


    procedure Acquire (A_Context : out Context;
                       Status    : out Error_Status;
                       Machine   :     String;  
                       Instance  :     String := "");

    procedure Acquire (A_Context : out Context;
                       Status    : out Error_Status;
                       Machine   :     String;  
                       User      :     String;
                       Password  :     String;
                       Session   :     String;
                       Instance  :     String := "");
    --
    -- Acquires a connection context for the given <machine, user, session,
    -- instance> quadruple.  All subsequent target operations that use
    -- this CONTEXT will be executed on the target server running on
    -- MACHINE on behalf of USER for the given INSTANCE.  The values for
    -- password and session are derived implicitly from the given
    -- values.


    type Connection_Timeout is new Duration;
    --
    -- Determines how long an open connection is allowed to
    -- persist in the active connection pool when not in use.

    None            : constant Connection_Timeout := Connection_Timeout'Last;
    After_Operation : constant Connection_Timeout := 0.0;
    Default         : constant Connection_Timeout := -1.0;

    procedure Release (A_Context    : in out Context;
                       Status       : out    Error_Status;
                       Idle_Timeout :        Connection_Timeout :=  
                          Remote_Operations.Default);
    --
    -- Returns A_CONTEXT back to the active connection pool.  IDLE_TIMEOUT
    -- can be used to reset the timeout value for A_CONTEXT.  Subsequent
    -- operations that require the same context will reuse A_CONTEXT if
    -- the request occurs before IDLE_TIMEOUT.

    procedure Destroy (A_Context : in out Context;  
                       Status    : out    Error_Status);
    --
    -- Explicitly disconnects A_CONTEXT and removes it from the
    -- active connection pool.  When not IS_CONNECTED (A_CONTEXT),
    -- a STATUS value of NOT_CONNECTED is returned.

\f

    function Is_Nil (A_Context : Context) return Boolean;
    --
    -- Indicates whether A_CONTEXT has been initialized.

    function Machine (Of_Context : Context) return String;
    --
    -- Returns the machine name associated with of OF_CONTEXT.  When
    -- IS_NIL (OF_CONTEXT), "" is returned.

    function User (Of_Context : Context) return String;
    --
    -- Returns the username associated with of OF_CONTEXT.  When
    -- IS_NIL (OF_CONTEXT), "" is returned.

    function Password (Of_Context : Context) return String;
    --
    -- Returns the password associated with of OF_CONTEXT.  When
    -- IS_NIL (OF_CONTEXT), "" is returned.

    function Session (Of_Context : Context) return String;
    --
    -- Returns the session associated with of OF_CONTEXT.  When
    -- IS_NIL (OF_CONTEXT), "" is returned.

    function Instance (Of_Context : Context) return String;
    --
    -- Returns the instance associated with of OF_CONTEXT.  When
    -- IS_NIL (OF_CONTEXT), "" is returned.


    function Is_Connected (A_Context : Context) return Boolean;
    --
    -- Indicates whether A_CONTEXT is currently a member of
    -- the active connection pool and is still connected to
    -- MACHINE (A_CONTEXT).

    function Timeout (Of_Context : Context) return Connection_Timeout;
    --
    -- Indicates the number of seconds remaining before
    -- OF_CONTEXT will reach its idle timeout.  Returns 0.0
    -- when not IS_CONNECTED (OF_CONTEXT).

\f

    ---------------------
    -- FILE MANAGEMENT --
    ---------------------
    --
    -- Each of the file management operations listed below operates
    -- in the naming context established during ACQUIRE (i.e. the
    -- user's home directory.  N.B. This naming context is not affected
    -- by command execution.  Whenever an error prevents the successful
    -- completion of a given operation, an error status and diagnostic
    -- message are constructed and returned to the caller.  This status
    -- information is suitable for display to a user.
    --
    -- For a listing of the error status values returned through these
    -- interfaces, see the file management error statuses listed at the
    -- end of this package


    subtype Form_Options is String;
    --
    -- Represents the options that can be applied in the context of
    -- a particular file manipulation operation.
    --!!! DETAILS: [TO BE SPECIFIED] (ACLs, File Format, et al) !!!

    subtype Rational_Pathname is String;
    --
    -- Represents a Rational object naming expression.

    Nil_Device : constant Rational_Pathname := "!MACHINE.DEVICES.NIL";

    subtype Remote_Pathname is String;
    --
    -- Represents a valid unambiguous naming expression on a given
    -- remote machine.  The format and semantics for parameters of
    -- this type are dependent on the remote machine type.

    procedure Create_Directory (In_Context         :     Context;
                                With_Name          :     Remote_Pathname;
                                Status             : out Error_Status;
                                Create_Directories :     Boolean      := True;
                                Options            :     Form_Options := "");
    --
    -- Creates a remote directory named WITH_NAME on remote
    -- machine IN_CONTEXT.  When CREATE_DIRECTORIES, any naming
    -- components in the prefix of WITH_NAME are created implicitly.

    procedure Create_File (In_Context         :     Context;
                           With_Name          :     Remote_Pathname;
                           Status             : out Error_Status;
                           Create_Directories :     Boolean      := True;
                           Options            :     Form_Options := "");
    --
    -- Creates a remote file named WITH_NAME on remote machine
    -- IN_CONTEXT.  When CREATE_DIRECTORIES is True, any directories
    -- missing from the pathname of the remote file are created
    -- implicitly.

    procedure Put (From_File  :     Rational_Pathname;
                   To_File    :     Remote_Pathname;
                   In_Context :     Context;
                   Status     : out Error_Status;
                   Append     :     Boolean      := False;
                   Options    :     Form_Options := "");
    --
    -- Copies the contents of local_file FROM_FILE to the remote file
    -- TO_FILE on machine IN_CONTEXT.  When TO_FILE already exists, its
    -- contents are overlayed.  When TO_FILE does not exist, it will be
    -- CREATE_FILE'd with parameter CREATE_DIRECTORIES => FALSE and then
    -- copied.

    procedure Put (From_File  :     Device_Independent_Io.File_Type;
                   To_File    :     Remote_Pathname;
                   In_Context :     Context;
                   Status     : out Error_Status;
                   Append     :     Boolean      := False;
                   Options    :     Form_Options := "");
    --
    -- PRECONDITION: Dio.Is_Open (From_File) and then
    --               Dio.Mode (From_File) = Dio.In_File
    --
    -- Copies the contents of FROM_FILE to the remote file TO_FILE on
    -- machine IN_CONTEXT.  When TO_FILE already exists, its contents
    -- are overlayed.  When TO_FILE does not exist, it will be CREATE'd
    -- with parameter CREATE_DIRECTORIES => FALSE and then copied.

    procedure Get (From_File  :     Remote_Pathname;
                   In_Context :     Context;
                   To_File    :     Rational_Pathname;
                   Status     : out Error_Status;
                   Append     :     Boolean      := False;
                   Options    :     Form_Options := "");
    --
    -- Copies the contents of remote file FROM_FILE on remote machine
    -- IN_CONTEXT into local file TO_FILE.

    procedure Get (From_File  :     Remote_Pathname;
                   In_Context :     Context;
                   To_File    :     Device_Independent_Io.File_Type;
                   Status     : out Error_Status;
                   Options    :     Form_Options := "");
    --
    -- PRECONDITION: Dio.Is_Open (To_File) and then
    --               Dio.Mode (To_File) = Dio.Out_File
    --
    -- Copies the contents of remote file FROM_FILE on remote machine
    -- IN_CONTEXT into local file TO_FILE.

    procedure Update_Time (Of_File    :     Remote_Pathname;
                           In_Context :     Context;
                           Result     : out Calendar.Time;
                           Status     : out Error_Status;
                           Options    :     Form_Options := "");
    --
    -- Returns the time that remote file OF_FILE on remote machine
    -- IN_CONTEXT was last modified.

    procedure File_Exists (The_File   :     Remote_Pathname;
                           In_Context :     Context;
                           Status     : out Error_Status;
                           Exists     : out Boolean);
    --
    -- Returns whether the remote file THE_FILE exists on the remote machine
    -- IN_CONTEXT.

    procedure Copy (From_File  :     Remote_Pathname;
                    To_File    :     Remote_Pathname;
                    In_Context :     Context;
                    Status     : out Error_Status;
                    Options    :     Form_Options := "");
    --
    -- Copies remote file FROM_FILE to remote file TO_FILE.  Both
    -- files must be on the same remote machine IN_CONTEXT.

    procedure Link (From_File  :     Remote_Pathname;
                    To_File    :     Remote_Pathname;
                    In_Context :     Context;
                    Status     : out Error_Status;
                    Options    :     Form_Options := "");
    --
    -- Creates a link remote file FROM_FILE to remote file TO_FILE.
    -- Both files must be on the same remote machine IN_CONTEXT.
    -- May not be supported on all remote platforms.

    procedure Delete_Directory (In_Context :     Context;
                                With_Name  :     Remote_Pathname;
                                Status     : out Error_Status;
                                Recursive  :     Boolean      := True;
                                Options    :     Form_Options := "");
    --
    -- Removes the remote directory WITH_NAME on remote machine
    -- IN_CONTEXT.  When RECURSIVE is True, the named directory
    -- and its contents are deleted; otherwise, the directory
    -- must be empty.

    procedure Delete_File (In_Context :     Context;
                           With_Name  :     Remote_Pathname;
                           Status     : out Error_Status;
                           Options    :     Form_Options := "");
    --
    -- Removes the remote file FILE from remote machine IN_CONTEXT.

    procedure Expunge (In_Context :     Context;
                       Object     :     Remote_Pathname;
                       Status     : out Error_Status;
                       Options    :     Form_Options := "");
    --
    -- Assures that deleted versions or retained copies of OBJECT
    -- are destroyed on IN_CONTEXT.

    procedure Move (From_File  :     Remote_Pathname;
                    To_File    :     Remote_Pathname;
                    In_Context :     Context;
                    Status     : out Error_Status;
                    Options    :     Form_Options := "");
    --
    -- This operation is functionally equivalent to Copy/Delete, but may
    -- perform more efficiently on some targets.

\f

    -----------------------
    -- COMMAND EXECUTION --
    -----------------------

    subtype Command_Input is String;
    --
    -- Represents a sequence of one or more commands in the command
    -- language of the given remote machine.  The format and semantics
    -- for parameters of this type are dependent on the remote machine
    -- type.

    type Command_Timeout is new Duration;

    Wait_Forever : constant Command_Timeout := Command_Timeout'Last;

    procedure Execute (Command    :     Command_Input;
                       In_Context :     Context;
                       Status     : out Error_Status;
                       Timeout    :     Command_Timeout :=  
                          Remote_Operations.Wait_Forever);
    --
    -- Executes the command string COMMAND on remote machine IN_CONTEXT.
    -- The standard input, output, and error files of the remote command
    -- are logically mapped to the Io.Current_Input, Io.Current_Output,
    -- and Io.Current_Error respectively.

    procedure Execute (Command    :     Command_Input;
                       In_Context :     Context;
                       Input      :     Rational_Pathname :=
                          Remote_Operations.Nil_Device;  
                       Output     :     Rational_Pathname;  
                       Error      :     Rational_Pathname;  
                       Status     : out Error_Status;
                       Timeout    :     Command_Timeout   :=  
                          Remote_Operations.Wait_Forever);
    --
    -- Executes the command string COMMAND on remote machine IN_CONTEXT.
    -- The standard output and error files of the remote command are
    -- copied into OUTPUT and ERROR respectively.

    procedure Execute (Command    :     Command_Input;
                       In_Context :     Context;
                       Input      :     Device_Independent_Io.File_Type;
                       Output     :     Device_Independent_Io.File_Type;
                       Error      :     Device_Independent_Io.File_Type;
                       Status     : out Error_Status;
                       Timeout    :     Command_Timeout :=  
                          Remote_Operations.Wait_Forever);
    --
    -- PRECONDITION: Dio.Is_Open (Input) and then
    --               Dio.Is_Open (Output) and then
    --               Dio.Is_Open (Error) and then
    --               Dio.Mode    (Input)  = Dio.In_File and then
    --               Dio.Mode    (Output) = Dio.Out_File and then
    --               Dio.Mode    (Error)  = Dio.Out_File
    --
    -- Executes the command string COMMAND on remote machine IN_CONTEXT.
    -- The standard output and error files of the remote command are
    -- copied into OUTPUT and ERROR respectively.

    type Command_Response is  
       (Nil,             -- Reset the timeout clock and continue.
        Read_Input,      -- Call the Read_Input formal and continue.
        Abort_Command    -- Terminate the command job.
        );

    generic

        type Execution_State is limited private;
        --
        -- Can be used to associated state information with a
        -- particular command sequence.

        with procedure Process_Output (Text     :        String;
                                       Severity :        Profile.Msg_Kind;
                                       State    : in out Execution_State;
                                       Response : in out Command_Response);
        --
        -- Called for each buffer of command output generated during
        -- the calls to EXECUTE below.  TEXT contains the raw output
        -- received during command execution, and the client is
        -- responsible for processing any format effectors that may
        -- appear in the buffer.

        with procedure Read_Input (State    : in out Execution_State;
                                   Buffer   : out    String;
                                   Last     : out    Natural;
                                   Response : in out Command_Response);
        --
        -- Called on demand whenever the response to a timeout event
        -- indicates that input should be read.  This operation is
        -- called repeatedly until RESPONSE /= READ_INPUT.

        with procedure Timeout_Handler (State    : in out Execution_State;
                                        Response : in out Command_Response);
        --
        -- Called when the specified timeout interval has been reached
        -- without response from the given command.

    procedure Execution_Generic (Command    :        Command_Input;
                                 In_Context :        Context;
                                 State      : in out Execution_State;
                                 Status     : out    Error_Status;
                                 Timeout    :        Command_Timeout :=  
                                    Remote_Operations.Wait_Forever);


    -------------------------
    -- ERROR STATUS VALUES --
    -------------------------

    type Error_Kinds is range 0 .. 255;

    function Error_Kind (Of_Status : Error_Status) return Error_Kinds;
    --
    -- Returns the associated Error_Kinds value for OF_STATUS.  When
    -- OF_STATUS does not indicate an error condition, NOT_AN_ERROR is
    -- returned.  When OF_STATUS indicates an error but has no
    -- associated Error_Kinds value, UNKNOWN_ERROR is returned.

    Not_An_Error  : constant Error_Kinds := Error_Kinds'First;
    Unknown_Error : constant Error_Kinds := Error_Kinds'Last;

    Connection_Error   : constant Error_Kinds := 001;
    Bad_User           : constant Error_Kinds := 002;
    Access_Error       : constant Error_Kinds := 003;
    Device_Error       : constant Error_Kinds := 004;
    Lock_Error         : constant Error_Kinds := 005;
    Name_Error         : constant Error_Kinds := 006;
    Policy_Error       : constant Error_Kinds := 007;
    Status_Error       : constant Error_Kinds := 008;
    Storage_Error      : constant Error_Kinds := 009;
    Unsupported        : constant Error_Kinds := 010;
    Use_Error          : constant Error_Kinds := 011;
    Command_Error      : constant Error_Kinds := 012;
    Command_Terminated : constant Error_Kinds := 013;
    Command_Timed_Out  : constant Error_Kinds := 014;
    Execution_Error    : constant Error_Kinds := 015;
    Resource_Limit     : constant Error_Kinds := 016;
    Internal_Error     : constant Error_Kinds := 017;


    -----------------------------------
    -- SERVER VERSIONS AND PLATFORMS --
    -----------------------------------

    type Revision_Ids is range 0 .. 255;
    Nil_Revision_Id : constant Revision_Ids := Revision_Ids'First;

    Major : constant := 1;
    Minor : constant := 2;
    type Version_Ids is array (Major .. Minor) of Revision_Ids;
    Nil_Version_Id : constant Version_Ids :=  
       Version_Ids'(Major => Nil_Revision_Id,  
                    Minor => Nil_Revision_Id);

    function Image (Of_Version : Version_Ids) return String;
    --
    -- Returns the image of OF_VERSION with a period ('.') separator
    -- between the major and minor revision identifiers.  When
    -- OF_VERSION = NIL_VERSION, "???" is returned.

    function Server_Version (Of_Context : Context) return Version_Ids;
    --
    -- Returns the target server version associated with OF_CONTEXT.
    -- When IS_NIL (OF_CONTEXT), NIL_VERSION_ID is returned.

    function Server_Version (Of_Context : Context) return String;
    --
    -- Returns IMAGE (SERVER_VERSION (OF_CONTEXT)).


    type Platforms is range 0 .. 255;
    Unknown : constant Platforms := Platforms'First;

    Sun    : constant Platforms := 001;
    Apollo : constant Platforms := 002;
    Ibm    : constant Platforms := 003;
    Hp     : constant Platforms := 004;
    Vax    : constant Platforms := 005;

    Vax_Ultrix : constant Platforms := 006;
    Ibm_Os2    : constant Platforms := 007;
    function Image (Of_Platform : Platforms) return String;
    --
    -- Returns an image of the platform name indicated by
    -- OF_PLATFORM.  Returns "Unknown" when OF_PLATFORM = UNKNOWN.

    function Platform (Of_Context : Context) return Platforms;
    --
    -- Returns the target platform associated with OF_CONTEXT.
    -- When IS_NIL (OF_CONTEXT), UNKNOWN is returned.

    function Platform (Of_Context : Context) return String;
    --
    -- Returns IMAGE (PLATFORM (OF_CONTEXT)).


    pragma Subsystem (Tools_Integration);
    pragma Module_Name (4, 4128);
    pragma Bias_Key (29);

private

    type Context_Data;

    type Context is access Context_Data;
    pragma Segmented_Heap (Context);

    Nil_Context : constant Context := null;

end Remote_Operations;