⟦608b61f38⟧

E3 Source Code



with Calendar;
with Ftp_Profile;
with Simple_Status;

pragma Private_Eyes_Only;
with Remote_Commands;

package Remote_Command_Interface is

    -- This package handles all file transfer and remote execution functions of
    -- the RCF.

    -- It can be used either with DTIA, Rational's RPC interface, or with FTP.
    -- DTIA provides facilities to efficiently manage RPC connections.  It
    -- caches (or pools) connections on a session basis to reduce the overhead
    -- that is required to build each remote connection.  FTP, the standard
    -- File Transfer Protocol, may be somewhat less efficient, but it can be
    -- chosen to manage the connections when DTIA is not available for a
    -- particular remote machine.
    --
    -- Clients that make repeated calls to this package in a relatively short
    -- period of time should not bracket each Acquire with a Release.

    -- The suggested methodology for use with these routines is as follows:
    --
    --   begin
    --      Acquire              -- Build a remote connection
    --      Set_Remote_Directory -- Set remote directory for upcoming operation
    --      {remote_operation}   -- Execute_Command, Put, Get, Unit_Update_Time
    --      Release              -- Break down the connection
    --   end;
    --
    -- Acquire causes a connection to be built between the host and the
    -- Remote_Machine, under Username and Password.  If a connection already
    -- exists for the current session with these attributes, it will be used.
    --
    -- Release and Destroy break down the remote connection.
    --
    -- Set_Remote_Directory sets the target directory (and optionally the
    -- target program library) in which remote operations will be performed.
    --
    -- Put copies a file from the HOST R1000 to the TARGET system.
    --
    -- Get copies a file from the TARGET system to the HOST R1000.
    --
    -- Execute_Command calls the remote command-line interpreter to execute the
    -- specified command.  Normally, a completion status should be returned in
    -- Status.  In some cases, it may be necessary to parse the output from the
    -- remote machine in order to detect errors.  Parse_... and Error_Pattern
    -- specify whether to parse the output, what output to parse, and what
    -- pattern to look for.
    --
    -- Unit_Update_Time returns the time at which a remote file was last
    -- updated.
    --
    -- File_Exists determines whether or not a particular file exists on a
    -- remote machine.
    --
    -- Confirmation messages which trace the actions of the Remote_Commands
    -- routines will be written if the Trace_Command parameter is set to True.


    type File_Type is (Text, Binary);

    type Context is private;


    -- Build a connection to Remote_Machine using Username and Password, and
    -- return the handle for that connection in Remote_Connection.  If the
    -- given Username is null, use the user name and password values from the
    -- Profile.Remote_Password file.  If the connection already exists, use it.
    procedure Acquire (Remote_Connection : out Context;
                       Status : in out Simple_Status.Condition;
                       Target_Key : String;
                       Remote_Machine : String := Ftp_Profile.Remote_Machine;
                       Username : String := Ftp_Profile.Username;
                       Password : String := Ftp_Profile.Password;
                       Trace_Command : Boolean := False);


    -- This combines the actions of building a connection (Acquire) and setting
    -- the target directory (Set_Remote_Directory).
    procedure Acquire (Remote_Connection : out Context;
                       Status : in out Simple_Status.Condition;
                       Target_Key : String;
                       Set_Directory : String;
                       Set_Library : String := "";                      Remote_Machine : String := Ftp_Profile.Remote_Machine;
                       Username : String := Ftp_Profile.Username;
                       Password : String := Ftp_Profile.Password;
                       Trace_Command : Boolean := False);


    -- Release a remote connection.  The connection is not destroyed
    -- immediately, so it will be possible to re-use it if a subsequent Acquire
    -- is executed.
    procedure Release (Remote_Connection : Context;
                       Status : in out Simple_Status.Condition;
                       Trace_Command : Boolean := False);


    -- Given the already acquired connection specified by Remote_Connection,
    -- execute the command Set_Directory on the remote machine to change its
    -- remote context to a new directory, and, if Set_Library is not null,
    -- execute the command Set_Library to change to a new program library
    -- within that context.
    procedure Set_Remote_Directory (Set_Directory : String;
                                    Remote_Connection : Context;
                                    Status : in out Simple_Status.Condition;
                                    Set_Library : String := "";
                                    Trace_Command : Boolean := False);


    -- Copy the file Host_File_Name to Target_File_Name over the connection
    -- specified by Remote_Connection.
    procedure Put (Host_File_Name : String;
                   Target_File_Name : String;
                   Remote_Connection : Context;
                   Status : in out Simple_Status.Condition;
                   The_Type : File_Type := Text;
                   Trace_Command : Boolean := False);


    -- Retrieve Host_File_Name from the file Target_File_Name over the
    -- connection specified by Remote_Connection.
    procedure Get (Host_File_Name : String;
                   Target_File_Name : String;
                   Remote_Connection : Context;
                   Status : in out Simple_Status.Condition;
                   The_Type : File_Type := Text;
                   Trace_Command : Boolean := False);


    -- Execute the command specified by Command_Line on the remote machine
    -- whose connection is specified by Remote_Connection.
    --
    -- Error_Pattern is the sequence of characters in the output string which
    -- initiates the reporting of an error, i.e., if Parse_@ is True, the
    -- output will be searched for Error_Pattern to see if there has been a
    -- reported error.  If Parse_Error_Output is True, Error_Output will be
    -- scanned (for Error_Pattern) to determine whether the remote machine
    -- reported any errors during execution of the command.  If
    -- Parse_Standard_Output is True, Standard_Output will be scenned instead
    -- of Error_Output.  If Show_Parsed_Output is True, the output which is to
    -- be parsed will also be sent along to the caller; otherwise it will not
    -- be passed along.
    procedure Execute_Command (Command_Line : String;
                               Remote_Connection : Context;
                               Status : in out Simple_Status.Condition;
                               Error_Pattern : String := "";
                               Parse_Error_Output : Boolean := False;
                               Parse_Standard_Output : Boolean := False;
                               Show_Parsed_Output : Boolean := True;
                               Trace_Command : Boolean := False);


    -- Get the update time for the unit whose target is Target_File_Name on the
    -- remote machine whose connection is specified by Remote_Connection.
    procedure Unit_Update_Time (Target_File_Name : String;
                                Remote_Connection : Context;
                                Status : in out Simple_Status.Condition;
                                Result : out Calendar.Time;
                                Trace_Command : Boolean := False);


    -- Destroy a remote connection.
    procedure Destroy (Remote_Connection : Context;
                       Status : in out Simple_Status.Condition;
                       Trace_Command : Boolean := False);


    -- Determine whether or not The_File exists on the remote machine whose
    -- connection is specified by Remote_Connection.
    procedure File_Exists (The_File : String;
                           Remote_Connection : Context;
                           Status : in out Simple_Status.Condition;
                           Exists : out Boolean;
                           Trace_Command : Boolean := False);


    pragma Module_Name (4, 4141);
    pragma Bias_Key (32);
private
    type Context is new Remote_Commands.Context;
end Remote_Command_Interface;
DataMuseum.dk

Rational R1000/400

⟦608b61f38⟧ Ada Source

Derivation

E3 Source Code

E3 Meta Data
