|
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 - downloadIndex: ┃ R T ┃
Length: 65039 (0xfe0f)
Types: TextFile
Names: »RPC_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 !Tools.Networking.Interchange
This package defines a collection of types for data interchange.
Each type has:
o A local representation dependent on the characteristics of the
local architecture and compiler
o A machine-independent interchange representation (as a byte
sequence)
This package provides operations for converting between the local
and interchange representations. The types provided are analogous
to types in the Ada predefined language environment (packages
Standard and Calendar; see the Rational Environment Reference
Manual, Programming Tools (PT book). The conversion operations are
generic on a procedural byte stream, so that they can be used on a
variety of interchange media (communication channels, tapes, and
disks).
The interchange representation does not carry type information.
Thus, to convert interchanged data back to their local
representations, their types must be known beforehand.
The interchange representation largely follows the rules of
Courier, the Xerox System Integration Standard for remote
procedure call protocol. In particular, all interchange values
are a multiple of two bytes (16 bits) in length. Values that
occupy several bytes are represented with their most significant
byte first.
The algorithms for conversion to and from the interchange form can
be extended to any Ada type except access values and task types.
The rules for forming new type conversion algorithms are:
o A discrete (integer subtype or enumeration type) is represented
by its 'Pos, converted to a Short_Integer type. This
representation rule is implemented by the generic package
Operations.Discrete.
o A vector (one-dimensional array) is represented by its 'Length,
followed by its elements in index order. The 'Length is
represented as a Natural subtype. This kind of representation
loses information about the 'First of the vector (as does Ada
slice assignment). This representation rule is implemented by
the generic package Operations.Vector.
o A record is represented by the sequence of its fields, in
the order of their declaration. Inaccessible fields in
variant records are omitted. In other words, the interchange
representation is ordered in the same way as its value would be
written as an Ada aggregate.
@node !Tools.Networking.Interchange.Byte
subtype Byte is Byte_Defs.Byte;
Defines an eight-bit byte.
The interchange representation is like a Short_Integer type.
@node !Tools.Networking.Interchange.Byte_String
subtype Byte_String is Byte_Defs.Byte_String;
Defines a string of bytes indexed by Standard.Integer.
The interchange representation is a byte count (represented as
an Integer type) followed by the bytes themselves in index order.
The bytes are packed so that consecutive bytes in the string are
represented as consecutive bytes in the interchange form. An
extra padding byte is added if the string contains an odd number of
bytes. This padding makes the entire value a multiple of two bytes
in length.
@node !Tools.Networking.Interchange.Constraint_Error
Constraint_Error : exception;
Occurs when an interchange conversion procedure encounters an
out-of-range value.
This exception is analogous to the Standard.Constraint_Error
exception.
@node !Tools.Networking.Interchange.Convert
function Convert (X : Calendar.Time) return Interchange.Time;
function Convert (X : Interchange.Time) return Calendar.Time;
function Convert (X : Standard.Duration) return Interchange.Duration;
function Convert (X : Interchange.Duration) return Standard.Duration;
Converts between time representations.
@node !Tools.Networking.Interchange.Day_Duration
subtype Day_Duration is Interchange.Duration;
Defines the interchange analog of Calendar.Day_Duration.
@node !Tools.Networking.Interchange.Day_Number
subtype Day_Number is Interchange.Short_Integer range 1 .. 31;
Defines the interchange analog of Calendar.Day_Number.
@node !Tools.Networking.Interchange.Duration
type Duration is
record
Seconds : Interchange.Integer;
Nanoseconds : Interchange.Nanosecond_Count;
end record;
Defines the interchange analog of Standard.Duration.
The interchange representation is the sequence of the fields in the
order of their declaration (seconds, nanoseconds).
@node !Tools.Networking.Interchange.Float
type Float is new Interchange_Defs.Float;
Defines the interchange analog of Standard.Float.
The interchange representation is IEEE single-precision (32-bit)
floating point.
@node !Tools.Networking.Interchange.Integer
type Integer is new Interchange_Defs.Longest_Integer
range - (2 ** 30) - (2 ** 30) .. (2 ** 30) + ((2 ** 30) - 1);
Defines the interchange analog of a Standard.Integer.
The interchange representation is 32 bits, given in two's-
complement notation.
@node !Tools.Networking.Interchange.Long_Float
type Long_Float is new Interchange_Defs.Long_Float;
Defines the interchange analog of a Standard.Long_Float.
The interchange representation is IEEE double-precision (64-bit)
floating point.
@node !Tools.Networking.Interchange.Long_Integer
type Long_Integer is new Interchange_Defs.Longest_Integer;
Defines the interchange analog of Standard.Long_Integer.
The range of Long_Integer is machine-dependent and so should be
chosen to be as large as possible.
The interchange representation is of arbitrary precision. Thus,
as many bytes are used as are required to contain the value,
represented as a Byte_String subtype (a byte count followed by
the bytes). Two's-complement notation is used.
@node !Tools.Networking.Interchange.Long_Natural
subtype Long_Natural is Long_Integer range 0 .. Long_Integer'Last;
Defines the interchange analog of Standard.Long_Natural.
@node !Tools.Networking.Interchange.Long_Positive
subtype Long_Positive is Long_Integer range 1 .. Long_Integer'Last;
Defines the interchange analog of Standard.Long_Positive.
@node !Tools.Networking.Interchange.Month_Number
subtype Month_Number is Interchange.Short_Integer range 1 .. 12;
Defines the interchange analog of Calendar.Month_Number.
@node !Tools.Networking.Interchange.Nanosecond_Count
subtype Nanosecond_Count is Interchange.Natural range 0 .. 10 ** 9 - 1;
Defines the set of digits to the right of the decimal point in a
Duration type.
@node !Tools.Networking.Interchange.Natural
subtype Natural is Integer range 0 .. Integer'Last;
Defines the interchange analog of Standard.Natural.
@node !Tools.Networking.Interchange.Positive
subtype Positive is Integer range 1 .. Integer'Last;
Defines the interchange analog of Standard.Positive.
@node !Tools.Networking.Interchange.Short_Integer
type Short_Integer is range - (2 ** 14) - (2 ** 14) .. (2 ** 14) =
((2 ** 14) - 1);
Defines the interchange analog of Standard.Short_Integer.
The interchange representation is 16 bits, given in two's-
complement notation.
@node !Tools.Networking.Interchange.Short_Natural
subtype Short_Natural is Short_Integer range 0 .. Short_Integer'Last;
Defines the interchange analog of Standard.Short_Natural.
@node !Tools.Networking.Interchange.Short_Positive
subtype Short_Positive is Short_Integer range 1 .. Short_Integer'Last;
Defines the interchange analog of Standard.Short_Positive.
@node !Tools.Networking.Interchange.Time
type Time is
record
Year : Year_Number;
Month : Month_Number;
Day : Day_Number;
Seconds : Day_Duration;
end record;
Defines the interchange analog of Calendar.Time.
The interchange representation is the sequence of the field
values given in the order of their declaration (year, month, day,
seconds).
@node !Tools.Networking.Interchange.Year_Number
subtype Year_Number is Interchange.Short_Integer;
Defines the interchange analog of Calendar.Year_Number.
@node !Tools.Networking.Interchange.Discrete
Given a discrete type, this package provides operations for
interchanging values of that type.
The specification of the package is:
generic
type Discrete_Type is (<>);
package Discrete is
...
end Discrete;
@node !Tools.Networking.Interchange.Discrete.Discrete_Type
type Discrete_Type is (<>);
Defines the type to be interchanged.
The interchange representation of a value of this type is the 'Pos
of the value converted to a Short_Integer type.
@node !Tools.Networking.Interchange.Discrete.Get
procedure Get (From : Stream_Id;
Data : out Discrete_Type);
Converts a value of the Discrete_Type type from its interchange
representation to its local representation.
@node !Tools.Networking.Interchange.Discrete.Put
procedure Put (Into : Stream_Id;
Data : Discrete_Type);
Converts a value of the Discrete_Type type from its local
representation to its interchange representation.
@node !Tools.Networking.Interchange.Operations
Given a facility for interchanging bytes, package Operations
provides a facility for interchanging values of other types.
For each type, Put and Get operations are defined. Put converts
any value to a sequence of bytes; Get reconstructs the original
value.
The specification of the package is:
generic
type Stream_Id is limited private;
with procedure Put (Into : Stream_Id;
Data : Byte_String) is <>;
with procedure Get (From : Stream_Id;
Data : out Byte_String) is <>;
package Operations is
...
end Operations;
The generic formal parameters define an abstract byte stream and
operations for interchanging bytes on it. To function, a stream
must not lose bytes and must deliver bytes in order.
A stream must perform fragmentation and reassembly. That is, the
sequence of operations:
Put (Into, Data (1 .. X));
Put (Into, Data (X + 1 .. N));
must be equivalent to the single operation:
Put (Into, Data (1 .. N));
for any value of X in the range 1 .. N. Likewise, the sequence of
operations:
Get (From, Data (1 .. X));
Get (From, Data (X + 1 .. N));
must be equivalent to the single operation:
Get (From, Data (1 .. N));
for any value of X in the range 1 .. N.
@node !Tools.Networking.Interchange.Operations.Get
procedure Get (From : Stream_Id;
Data : out Byte);
procedure Get (From : Stream_Id;
Data : out Interchange.Duration);
procedure Get (From : Stream_Id;
Data : out Interchange.Float);
procedure Get (From : Stream_Id;
Data : out Interchange.Integer);
procedure Get (From : Stream_Id;
Data : out Interchange.Long_Float);
procedure Get (From : Stream_Id;
Data : out Interchange.Long_Integer);
procedure Get (From : Stream_Id;
Data : out Interchange.Short_Integer);
procedure Get (From : Stream_Id;
Data : out Interchange.Time);
procedure Get (From : Stream_Id;
Data : out Standard.Boolean);
procedure Get (From : Stream_Id;
Data : out Standard.Character);
Converts a value from its interchange representation to its local
representation.
The interchange representation of a Standard.Boolean is given as
a Short_Integer type, with the value 0 for false and 1 for true.
The interchange representation of a Standard.Character is its 'Pos
converted to a Short_Integer type.
@node !Tools.Networking.Interchange.Operations.Get
with procedure Get (From : Stream_Id;
Data : out Byte_String) is <>;
Gets some bytes from a stream.
@node !Tools.Networking.Interchange.Operations.Get_Byte_String
function Get_Byte_String (From : Stream_Id) return Byte_String;
Converts a byte string from its interchange representation to its
local representation.
Get_Byte_String is a function because Byte_String is an
unconstrained subtype.
@node !Tools.Networking.Interchange.Operations.Get_String
function Get_String (From : Stream_Id) return Standard.String;
Converts a string from its interchange representation to its local
representation.
Get_String is a function because String is an unconstrained type.
The interchange representation of a Standard.String is given as a
Byte_String subtype, with one character per byte. Each character
is represented by its 'Pos (its ASCII code).
@node !Tools.Networking.Interchange.Operations.Put
procedure Put (Into : Stream_Id;
Data : Byte);
procedure Put (Into : Stream_Id;
Data : Interchange.Duration);
procedure Put (Into : Stream_Id;
Data : Interchange.Float);
procedure Put (Into : Stream_Id;
Data : Interchange.Integer);
procedure Put (Into : Stream_Id;
Data : Interchange.Long_Float);
procedure Put (Into : Stream_Id;
Data : Interchange.Long_Integer);
procedure Put (Into : Stream_Id;
Data : Interchange.Short_Integer);
procedure Put (Into : Stream_Id;
Data : Interchange.Time);
procedure Put (Into : Stream_Id;
Data : Standard.Boolean);
procedure Put (Into : Stream_Id;
Data : Standard.Character);
Converts a value from its interchange representation to its local
representation.
The interchange representation of a Standard.Boolean is given as
a Short_Integer type, with the value 0 for false and 1 for true.
The interchange representation of a Standard.Character is its 'Pos
converted to a Short_Integer type.
@node !Tools.Networking.Interchange.Operations.Put
with procedure Put (Into : Stream_Id;
Data : Byte_String) is <>;
Puts some bytes into a stream.
@node !Tools.Networking.Interchange.Operations.Put_Byte_String
procedure Put_Byte_String (Into : Stream_Id;
Data : Byte_String);
Converts a Byte_String from its local representation to its
interchange representation.
@node !Tools.Networking.Interchange.Operations.Put_String
procedure Put_String (Into : Stream_Id;
Data : Standard.String);
Converts a Standard.String from its local representation to its
interchange representation.
The interchange representation of a Standard.String is a
Byte_String subtype, with one character per byte. Each character
is represented by its 'Pos (its ASCII code).
@node !Tools.Networking.Interchange.Operations.Stream_Id
type Stream_Id is limited private;
Specifies that data be taken from the selected stream of bytes.
The interchange representation of values is put into or taken from
a stream.
@node !Tools.Networking.Interchange.Vector
A vector is a one-dimensional array of elements. Given a vector
type (an unconstrained array type), this package provides
interchange operations on that type.
The specification of the package is:
generic
type Element_Type is private;
with procedure Put (Into : Stream_Id;
Data : Element_Type) is <>;
with procedure Get (From : Stream_Id;
Data : out Element_Type) is <>;
type Index_Type is (<>);
with procedure Put (Into : Stream_Id;
Data : Index_Type) is <>;
with procedure Get (From : Stream_Id;
Data : out Index_Type) is <>;
type Vector_Type is array (Index_Type range <>) of Element_Type;
package Vector is
...
end Vector;
@node !Tools.Networking.Interchange.Vector.Element_Type
type Element_Type is private;
Specifies the type of each element of a vector.
The interchange representation of this type is supplied by the user
as Put and Get generic formal procedures.
@node !Tools.Networking.Interchange.Vector.Get
function Get (From : Stream_Id) return Vector_Type;
Converts a vector from its interchange representation to its local
representation.
@node !Tools.Networking.Interchange.Vector.Get
with procedure Get (From : Stream_Id;
Data : out Element_Type) is <>;
with procedure Get (From : Stream_Id;
Data : out Index_Type) is <>;
Converts a value from its interchange representation to its local
representation.
@node !Tools.Networking.Interchange.Vector.Index_Type
type Index_Type is (<>);
Specifies the index type of a vector.
The interchange representation of this type is supplied by the user
as Put and Get generic formal procedures.
@node !Tools.Networking.Interchange.Vector.Put
procedure Put (Into : Stream_Id;
Data : Vector_Type);
Converts a vector from its local representation to its interchange
representation.
@node !Tools.Networking.Interchange.Vector.Put
with procedure Put (Into : Stream_Id;
Data : Element_Type) is <>;
with procedure Put (Into : Stream_Id;
Data : Index_Type) is <>;
Converts a value from its local representation to its interchange
representation.
@node !Tools.Networking.Interchange.Vector.Vector_Type
type Vector_Type is array (Index_Type range <>) of Element_Type;
Represents a one-dimensional array of elements.
This is the type for which package Vector provides interchange
operations.
The interchange representation of a value of this type is the
number of elements (given as an Integer type) followed by the
elements in index order.
@node !Tools.Networking.Interchange_Defs
Package Interchange_Defs defines numeric types and operators for
package Interchange. When porting this package, you should modify
it to indicate the appropriate types on your system.
@node !Tools.Networking.Interchange_Defs."="
function "=" (X, Y : Longest_Integer) return Boolean renames Standard."=";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs.">"
function ">" (X, Y : Longest_Integer) return Boolean renames Standard.">";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs."<"
function "<" (X, Y : Longest_Integer) return Boolean renames Standard."<";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs.">="
function ">=" (X, Y : Longest_Integer) return Boolean
renames Standard.">=";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs."<="
function "<=" (X, Y : Longest_Integer) return Boolean
renames Standard."<=";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs."+"
function "+" (X, Y : Longest_Integer) return Longest_Integer
renames Standard."+";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs."--"
function "-" (X, Y : Longest_Integer) return Longest_Integer
renames Standard."-";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs."*"
function "*" (X, Y : Longest_Integer) return Longest_Integer
renames Standard."*";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs."/"
function "/" (X, Y : Longest_Integer) return Longest_Integer
renames Standard."/";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs."mod"
function "mod" (X, Y : Longest_Integer) return Longest_Integer
renames Standard."mod";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs."rem"
function "rem" (X, Y : Longest_Integer) return Longest_Integer
renames Standard."rem";
Renames the standard operator.
@node !Tools.Networking.Interchange_Defs.Duration_Magnitude
function Duration_Magnitude return Standard.Integer;
This function returns a constant that is:
o An integral power of 10 (10, 100, 1,000, and so on)
o <= 10 ** 9
o <= Standard.Duration'Last
o <= Standard.Integer'Last
This constant is used by the Interchange.Convert procedure.
@node !Tools.Networking.Interchange_Defs.Float
type Float is new Standard.Float;
Represents IEEE floating-point, single-precision format.
@node !Tools.Networking.Interchange_Defs.Long_Float
type Long_Float is new Standard.Float;
Represents IEEE floating-point, double-precision format.
@node !Tools.Networking.Interchange_Defs.Longest_Integer
subtype Longest_Integer is Standard.Long_Integer;
Acts as a signed integer of the highest available precision.
This type is used for internal arithmetic by the Interchange
conversion algorithms.
Package Interchange_Defs must define the following arithmetic and
comparison operators for type Longest_Integer:
=, >, <, >=, <=, +, --, *, /, mod, rem
In the Rational implementation, these are defined by renaming the
operators from package Standard.
@node !Tools.Networking.Rpc
This package defines the data types used to represent programs,
versions, procedures, and exceptions.
@node !Tools.Networking.Rpc.Defined_Versions
Defined_Versions : constant Version_Range := (3, 5);
Defines RPC protocol versions.
@node !Tools.Networking.Rpc.Error_Type
type Error_Type is (Error_Other, Error_Constraint, Error_Numeric,
Error_Program, Error_Storage, Error_Tasking,
Status_Error, Mode_Error, Name_Error, Use_Error,
Device_Error, End_Error, Data_Error, Layout_Error,
Error_Server_Defined, Error_Username_Or_Password);
Represents exceptions in RPC response message headers.
Each value corresponds to an exception or class of exceptions.
Refer to the table of "Error Messages" in the reference entry for
the Get_Message function.
This type indicates a server-defined error. These exceptions
indicate the general cause of an error. The exact cause depends on
the particulars of the user's server.
Error_Other
Indicates any of a variety of errors, excluding the following
errors.
Data_Error
Indicates data error.
Device_Error
Indicates device error.
End_Error
Indicates end error.
Error_Constraint
Indicates contraint error.
Error_Numeric
Indicates numeric error.
Error_Program
Indicates program error.
Error_Server_Defined
Indicates other server-defined error.
Error_Storage
Indicates storage error.
Error_Tasking
Indicates tasking error.
Error_Username_Or_Password
Indicates username or password error.
Layout_Error
Indicates layout error.
Mode_Error
Indicates mode error.
Name_Error
Indicates name error.
Status_Error
Indicates status error.
Use_Error
Indicates use error.
@node !Tools.Networking.Rpc.Exception_Number
type Exception_Number is new Interchange.Integer;
Represents server-defined exceptions in RPC response headers.
Each value corresponds to an exception. The correspondence is
determined by the service that raises the exception.
@node !Tools.Networking.Rpc.Exception_Versions
Exception_Versions : constant Version_Range := (4, Version_Number'Last);
Defines RPC protocol versions that support server-defined
exceptions.
@node !Tools.Networking.Rpc.Get
procedure Get (From : Stream_Id;
Data : out Version_Range);
procedure Get (From : Stream_Id;
Data : out Exception_Number);
Gets a value of the Version_Range or Exception_Number types from a
stream.
@node !Tools.Networking.Rpc.Get_Message
function Get_Message (From : Stream_Id) return Message_Header;
Gets a value of the Message_Header type from a stream.
Refer to the table of "Error Messages" on the following page.
@node !Tools.Networking.Rpc.Invalid_Argument
Invalid_Argument : exception;
Occurs when the interchange form of an argument is invalid.
An example would be the encoding of a value outside the legal
range.
@node !Tools.Networking.Rpc.Max
function Max (X, Y : Version_Range) return Version_Number;
Returns the largest version that is common to both X and Y.
If the server supports a range of protocol versions and the client
supports a separate range of protocol versions, this function
returns the largest version of the protocol that is common to both
the client and the server.
@node !Tools.Networking.Rpc.Message_Header
type Message_Header (Kind : Message_Kind := Return_Message) is
record
Id : Transaction_Id :=0;
case Kind is
when Call_Message =>
Program : Program_Number;
Version : Version_Number;
Proc : Procedure_Number;
when Reject_Message =>
Details : Reject_Details;
when Return_Message =>
null;
when Abort_Message =>
Error : Error_Type;
end case;
end record;
Begins each RPC message (request or response) with introductory
information about the message.
@node !Tools.Networking.Rpc.Message_Kind
type Message_Kind is (Call_Message, Reject_Message, Return_Message,
Abort_Message);
Acts as the discriminant of the Message_Header type.
Each RPC message (request or response) must be one of the above
kinds.
Abort_Message
Indicates that an exception was raised by the called subprogram.
Call_Message
Indicates the initial request for service sent by client to server.
Reject_Message
Indicates some problem with the requested program number, version
number, or procedure number.
Return_Message
Indicates normal completion of the requested operation.
@node !Tools.Networking.Rpc.No_Such_Procedure
No_Such_Procedure : exception;
Occurs when a nonexistent procedure is called.
This exception is raised when a server receives a request message
containing a procedure number that does not identify an existing
procedure. The exception may indicate a disagreement between
client and server about procedure numbering.
@node !Tools.Networking.Rpc.No_Such_Program
No_Such_Program : exception;
Occurs when a nonexistent program is called.
This exception is raised when a server receives a request message
containing a program number that does not identify an existing
program. The exception may indicate a disagreement between client
and server about program numbering.
@node !Tools.Networking.Rpc.No_Such_Version
No_Such_Version : exception;
Occurs when a nonexistent version is called.
This exception is raised when a server receives a request message
containing a version number that does not identify a supported
version.
@node !Tools.Networking.Rpc.Other_Error
Other_Error : exception;
Occurs under a variety of circumstances.
This exception is raised by the Get_Message function to indicate
that an unknown exception has been raised in the server.
@node !Tools.Networking.Rpc.Overlaps
function Overlaps (X, Y : Version_Range) return Boolean:
Checks whether two ranges of version numbers overlap.
@node !Tools.Networking.Rpc.Procedure_Number
type Procedure_Number is new Interchange.Short_Integer;
Identifies a procedure within a program.
The correspondence between procedure numbers and procedures is
determined by each service.
@node !Tools.Networking.Rpc.Program_Number
type Program_Number is new Interchange.Integer;
Identifies a program.
@node !Tools.Networking.Rpc.Protocol_Error
Protocol_Error : exception;
Occurs when an event happens that is not legal in the RPC protocol.
An example event would be a server receiving a response message.
@node !Tools.Networking.Rpc.Put
procedure Put (Into : Stream_Id;
Data : Exception_Number);
Puts a value of the Exception_Number type into a stream.
@node !Tools.Networking.Rpc.Put
procedure Put (Into : Stream_Id;
Data : Version_Range);
Puts a value of the Version_Range type into a stream.
@node !Tools.Networking.Rpc.Put_Message
procedure Put_Message (Into : Stream_Id;
Data : Message_Header);
Puts a value of the Message_Header type into a stream.
@node !Tools.Networking.Rpc.Reject_Details
type Reject_Details (Kind : Reject_Kind := Rej_Invalid_Argument) is
record
case Kind is
when Rej_No_Such_Version =>
Supported : Version_Range;
when other =>
null;
end case;
end record;
Identifies the reason for rejecting an RPC request.
@node !Tools.Networking.Rpc.Reject_Kind
type Reject_Kind is (Rej_No_Such_Program, Rej_No_Such_Version,
Rej_No_Such_Procedure, Rej_No_Such_Argument);
Acts as the discriminant of the Reject_Details type.
@node !Tools.Networking.Rpc.Server_Defined_Error
Server_Defined_Error : exception;
Indicates that some server-defined exception has been raised.
@node !Tools.Networking.Rpc.Stream_Id
subtype Stream_Id is Transport_Stream.Stream_Id;
Identifies a bidirectional stream of bytes.
@node !Tools.Networking.Rpc.Transaction_Id
type Transaction_Id is new Interchange.Short_Integer;
Identifies a transaction.
A transaction is associated with each remote procedure call. This
type is not used currently.
@node !Tools.Networking.Rpc.Username_Or_Password_Error
Username_Or_Password_Error : exception;
Occurs when the username and/or password supplied with a remote
procedure call is rejected by the server machine.
This exception is raised when either there is no such username or
the password is incorrect.
@node !Tools.Networking.Rpc.Username_Versions
Username_Versions : constant Version_Range := (5, Version_Number'Last);
Defines RPC protocol versions that support passing username and
password information with each call.
@node !Tools.Networking.Rpc.Version_Number
type Version_Number is new Interchange.Short_Integer;
Identifies a particular version of a program (service).
@node !Tools.Networking.Rpc.Version_Range
type Version_Range is
record
First, Last : Version_Number;
end record;
Identifies a range of versions.
By convention, a value X of the Version_Range type represents
versions in the Ada range: X.First .. X.Last.
@node !Tools.Networking.Rpc_Access_Utilities
Package Rpc_Access_Utilities is used by RPC client programs to
obtain usernames and passwords to control the identity of RPC
servers running on other machines.
@node !Tools.Networking.Rpc_Access_Utilities.Remote_Password
function Remote_Password
(Host_Name : String;
Response : Profile.Response_Profile := Profile.Get) return String;
Returns a password to be used by the machine named by the Host_Name
parameter.
This function reads the object named by the Remote_Passwords switch
in the given response profile, searching for a line that matches
the given Host_Name. If a matching line is found, and the password
field in that line is "<PROMPT>", the calling user is prompted
to enter a password in an I/O window, and the entered password is
returned. If the password field is not "<PROMPT>", the field is
returned. If there is no line in the Remote_Passwords file that
matches the Host_Name, the null string ("") is returned.
@node !Tools.Networking.Rpc_Access_Utilities.Remote_Session
function Remote_Session
(Host_Name : String;
Response : Profile.Response_Profile := Profile.Get) return String;
Returns a session (account) name to be used by the machine named by
the Host_Name parameter.
This function reads the object named by the Remote_Sessions switch
in the given response profile, searching for a line that matches
the given Host_Name. If a matching line is found, and the session
field in that line is "<PROMPT>", the calling user is prompted
to enter a session in an I/O window, and the entered session is
returned. If the session field is not "<PROMPT>", the field is
returned. If there is no line in the Remote_Sessions file that
matches the Host_Name, the null string ("") is returned.
@node !Tools.Networking.Rpc_Access_Utilities.Remote_Username
function Remote_Username
(Host_Name : String;
Response : Profile.Response_Profile := Profile.Get) return String;
Returns a username to be used by the machine named by the Host_Name
parameter.
This function reads the object named by the Remote_Passwords switch
in the given response profile, searching for a line that matches
the given Host_Name. If a matching line is found, and the username
field in that line is "<PROMPT>", the calling user is prompted
to enter a username in an I/O window, and the entered username is
returned. If the username field is not "<PROMPT>", the field is
returned. If there is no line in the Remote_Passwords file that
matches the Host_Name, the null string ("") is returned.
@node !Tools.Networking.Rpc_Access_Utilities.Start_Request_Generic
generic
Default_Host_Name : String;
Default_Socket : Transport_Defs.Socket_Id;
Default_Program : Rpc.Program_Number;
Default_Version : Rpc.Version_Number;
Default_Username : String := "";
Default_Password : String := "";
procedure Start_Request_Generic
(Stream : out Transport_Stream.Stream_Id;
Proc : Rpc.Procedure_Number;
Host_Name : String := Default_Host_Name;
Socket : Transport_Defs.Socket_Id := Default_Socket;
Program : Rpc.Program_Number := Default_Program;
Version : Rpc.Version_Number := Default_Version;
Username : String := Default_Username;
Password : String := Default_Password;
Response : Profile.Response_Profile := Profile.Get);
Allocates a stream and transmits a request header with the
specified program, version, procedure, username, and password
values.
Host_Name is resolved to a Host_Id and a Network_Name by
package Transport_Name. If Username = "", it is replaced by
Remote_Username (Host_Name, Response). If Password = "", it is
replaced by Remote_Password (Host_Name, Response).
This procedure is similar to
the Rpc_Client.Start_Request_With_Username generic procedure,
with the addition of Host_Name resolution and Remote_Password file
processing.
@node !Tools.Networking.Rpc_Client
Package Rpc_Client provides operations used by clients to initiate
remote procedure calls.
@node !Tools.Networking.Rpc_Client.End_Request
procedure End_Request (Stream : Transport_Stream.Stream_Id);
Flushes the transmit buffer and gets a response header.
Either this procedure or the End_Request_With_Exception procedure
must be called by each client procedure after transmitting all
request parameters but before receiving any response parameters.
Flushes the transmit buffer and gets a response header.
If the reponse header contains a server-defined exception, it is
raised by the Raise_Exception procedure. Either this procedure
or the End_Request procedure is called by each client procedure
after transmitting all request parameters but before receiving any
response parameters.
The formal parameters to the generic procedure are:
generic
with procedure Raise_Exception (Excep : Rpc.Exception_Number);
procedure End_Request_With_Exception
(Stream : Transport_Stream.Stream_Id);
@node !Tools.Networking.Rpc_Client.End_Request_With_Exception
procedure End_Request_With_Exception
(Stream : Transport_Stream.Stream_Id);
Flushes the transmit buffer and gets a response header.
If the reponse header contains a server-defined exception, it is
raised by the Raise_Exception procedure. Either this procedure
or the End_Request procedure is called by each client procedure
after transmitting all request parameters but before receiving any
response parameters.
@node !Tools.Networking.Rpc_Client.Raise_Exception
with procedure Raise_Exception (Excep : Rpc.Exception_Number);
Raises a server-defined exception.
@node !Tools.Networking.Rpc_Client.End_Response
procedure End_Response (Stream : Transport_Stream.Stream_Id);
Deallocates the stream.
This procedure is called by each client procedure after getting all
response parameters.
Allocates a stream from the pool and transmits a request message
header with the given program, version, and procedure values.
The Stream parameter returns the identification number of the
stream into which to put request parameters and from which to get
response parameters.
The Proc parameter specifies the number of the remote procedure
called.
The formal parameters to the generic procedure are:
generic
Default_Network : Transport_Defs.Network_Name;
Default_Host : Transport_Defs.Host_Id;
Default_Socket : Transport_Defs.Socket_Id;
Default_Program : Rpc.Program_Number;
Default_Version : Rpc.Version_Number;
procedure Start_Request_Generic
(Stream : out Transport_Stream.Stream_Id;
Proc : Rpc.Procedure_Number;
Network : Transport_Defs.Network_Name := Default_Network;
Host : Transport_Defs.Host_Id := Default_Host;
Socket : Transport_Defs.Socket_Id := Default_Socket;
Program : Rpc.Program_Number := Default_Number;
Version : Rpc.Version_Number := Default_Version);
@node !Tools.Networking.Rpc_Client.Default_Host
Default_Host : Transport_Defs.Host_Id;
Defines the host identifier that is to be used as the default host
by the Start_Request_Generic procedure.
@node !Tools.Networking.Rpc_Client.Default_Network
Default_Network : Transport_Defs.Network_Name;
Defines the network name that is to be used as the default name by
the Start_Request_Generic procedure.
@node !Tools.Networking.Rpc_Client.Default_Program
Default_Program : Rpc.Program_Number;
Defines the program number that is to be used as the default number
by the Start_Request_Generic procedure.
@node !Tools.Networking.Rpc_Client.Default_Socket
Default_Socket : Transport_Defs.Socket_Id;
Defines the socket identifier that is to be used as the default
socket by the Start_Request_Generic procedure.
@node !Tools.Networking.Rpc_Client.Default_Version
Default_Version : Rpc.Version_Number;
Defines the version number that is to be used as the default number
by the Start_Request_Generic procedure.
@node !Tools.Networking.Rpc_Client.Start_Request_Generic
procedure Start_Request_Generic
(Stream : out Transport_Stream.Stream_Id;
Proc : Rpc.Procedure_Number;
Network : Transport_Defs.Network_Name := Default_Network;
Host : Transport_Defs.Host_Id := Default_Host;
Socket : Transport_Defs.Socket_Id := Default_Socket;
Program : Rpc.Program_Number := Default_Number;
Version : Rpc.Version_Number := Default_Version);
Allocates a stream from the pool and transmits a request message
header with the given program, version, and procedure values.
Allocates a stream from the pool and transmits a request message
header with the given program, version, and procedure values.
The Stream parameter returns the identification number of the
stream into which to put request parameters and from which to get
response parameters.
The Proc parameter specifies the number of the remote procedure
called.
The Username and Password parameters can be passed to the server
when the server must assume an identity in the access control
system of the server machine.
The formal parameters to the generic procedure are:
generic
Default_Network : Transport_Defs.Network_Name;
Default_Host : Transport_Defs.Host_Id;
Default_Socket : Transport_Defs.Socket_Id;
Default_Program : Rpc.Program_Number;
Default_Version : Rpc.Version_Number;
Default_Username : String := "";
Default_Password : String := "";
procedure Start_Request_With_Username
(Stream : out Transport_Stream.Stream_Id;
Proc : Rpc.Procedure_Number;
Network : Transport_Defs.Network_Name := Default_Network;
Host : Transport_Defs.Host_Id := Default_Host;
Socket : Transport_Defs.Socket_Id := Default_Socket;
Program : Rpc.Program_Number := Default_Program;
Version : Rpc.Version_Number := Default_Version;
Username : String := Default_Username;
Password : String := Default_Password);
@node !Tools.Networking.Rpc_Client.Default_Host
Default_Host : Transport_Defs.Host_Id;
Defines the host identifier that is to be used as the default host
by the Start_Request_With_Username procedure.
@node !Tools.Networking.Rpc_Client.Default_Network
Default_Network : Transport_Defs.Network_Name;
Defines the network name that is to be used as the default name by
the Start_Request_With_Username procedure.
@node !Tools.Networking.Rpc_Client.Default_Password
Default_Password : String := "";
Defines the password that is to be used as the default by the
Start_Request_With_Username procedure.
@node !Tools.Networking.Rpc_Client.Default_Program
Default_Program : Rpc.Program_Number;
Defines the program number that is to be used as the default number
by the Start_Request_With_Username procedure.
@node !Tools.Networking.Rpc_Client.Default_Socket
Default_Socket : Transport_Defs.Socket_Id;
Defines the socket identifier that is to be used as the default
socket by the Start_Request_With_Username procedure.
@node !Tools.Networking.Rpc_Client.Default_Username
Default_Username : String := "";
Defines the username that is to be used as the default by the
Start_Request_With_Username procedure.
@node !Tools.Networking.Rpc_Client.Default_Version
Default_Version : Rpc.Version_Number;
Defines the version number that is to be used as the default number
by the Start_Request_With_Username procedure.
@node !Tools.Networking.Rpc_Client.Start_Request_With_Username
procedure Start_Request_With_Username
(Stream : out Transport_Stream.Stream_Id;
Proc : Rpc.Procedure_Number;
Network : Transport_Defs.Network_Name := Default_Network;
Host : Transport_Defs.Host_Id := Default_Host;
Socket : Transport_Defs.Socket_Id := Default_Socket;
Program : Rpc.Program_Number := Default_Program;
Version : Rpc.Version_Number := Default_Version;
Username : String := Default_Username;
Password : String := Default_Password);
Allocates a stream from the pool and transmits a request message
header with the given program, version, and procedure values.
The Username and Password parameters can be passed to the server
when the server must assume an identity in the access control
system of the server machine.
@node !Tools.Networking.Rpc_Product
Package Rpc_Product provides a way to check whether the RPC product
has been installed on your machine.
@node !Tools.Networking.Rpc_Product.Is_Installed
function Is_Installed return Boolean;
Returns true if the RPC product has been installed on your machine.
@node !Tools.Networking.Rpc_Product.Is_Not_Installed
Is_Not_Installed : exception;
Occurs when an RPC subprogram is called, if the RPC product is not
installed on your machine.
@node !Tools.Networking.Rpc_Server
Package Rpc_Server provides operations used
by servers to handle remote procedure calls.
@node !Tools.Networking.Rpc_Server.Begin_Response
procedure Begin_Response (Stream : Transport_Stream.Stream_Id;
Id : Rpc.Transaction_Id);
Transmits a response header.
This procedure is called from the body of the Process_Call
procedure after request parameters are got from the stream but
before response parameters are put into the stream.
@node !Tools.Networking.Rpc_Server.Return_Exception
procedure Return_Exception (Stream : Transport_Stream.Stream_Id;
Id : Rpc.Transaction_Id;
Excep : Rpc.Exception_Number);
Transmits an exception message in response to an RPC request.
This procedure is called by the Process_Call procedure.
Services an incoming RPC connection.
This procedure:
o Allocates a transport stream.
o Checks compatibility of incoming package and version. An
exception message is returned if there is a mismatch.
o Processes calls until the connection is disconnected.
o Catches, on each call, any propagated exceptions, transmitting
them and flushing the transmit buffer.
o Deallocates resources after disconnection.
The formal parameters to the generic procedure are:
generic
Program : Rpc.Program_Number;
Supported : Rpc.Version_Range := (0, Rpc.Version_Number'Last);
with procedure Process_Call (Stream : Transport_Stream.Stream_Id;
Id : Rpc.Transaction_Id;
Version : Rpc.Version_Number;
Proc : Rpc.Procedure_Number) is <>;
procedure Serve (Connection : Transport.Connection_Id);
@node !Tools.Networking.Rpc_Server.Process_Call
with procedure Process_Call (Stream : Transport_Stream.Stream_Id;
Id : Rpc.Transaction_Id;
Version : Rpc.Version_Number;
Proc : Rpc.Procedure_Number) is <>;
Processes one remote procedure call.
This procedure is supplied by the RPC server user and is called by
an instantiation of the Serve_With_Username procedure.
@node !Tools.Networking.Rpc_Server.Program
Program : Rpc.Program_Number;
Supplies the number of the program (package) supported by this RPC
server.
@node !Tools.Networking.Rpc_Server.Serve
procedure Serve (Connection : Transport.Connection_Id);
Serves an incoming RPC connection by allocating a transport
stream, checking the incoming package and version for a match,
and processing calls until the connection is disconnected.
For each RPC call, this procedure catches any propagated
exceptions, transmits them, and then flushes the transmit buffer.
When the connection is disconnected or a protocol error occurs, the
procedure deallocates the transport stream and returns.
@node !Tools.Networking.Rpc_Server.Supported
Supported : Rpc.Version_Range := (0, Rpc.Version_Number'Last);
Indicates the range of versions supported by this RPC server.
Services an incoming RPC connection.
This procedure:
o Allocates a transport stream
o Checks compatibility of incoming package and version. An
exception message is returned if there is a mismatch
o Processes calls until the connection is disconnected
o Catches, on each call, any propagated exceptions, transmitting
them and flushing the transmit buffer
o Deallocates resources after disconnection
The formal parameters to the generic procedure are:
generic
Program : Rpc.Program_Number;
Supported : Rpc.Version_Range := (0, Rpc.Version_Number'Last);
with procedure Process_Call (Stream : Transport_Stream.Stream_Id;
Id : Rpc.Transaction_Id;
Version : Rpc.Version_Number;
Proc : Rpc.Procedure_Number;
Username : String;
Password : String) is <>;
procedure Serve_With_Username (Connection : Transport.Connection_Id);
@node !Tools.Networking.Rpc_Server.Process_Call
with procedure Process_Call (Stream : Transport_Stream.Stream_Id;
Id : Rpc.Transaction_Id;
Version : Rpc.Version_Number;
Proc : Rpc.Procedure_Number;
Username : String;
Password : String) is <>;
Processes one remote procedure call.
This procedure is supplied by the RPC server user and is called by
an instantiation of the Serve procedure.
@node !Tools.Networking.Rpc_Server.Program
Program : Rpc.Program_Number;
Supplies the number of the program (package) supported by this RPC
server.
@node !Tools.Networking.Rpc_Server.Serve_With_Username
procedure Serve_With_Username (Connection : Transport.Connection_Id);
Serves an incoming RPC connection by allocating a transport
stream, checking the incoming package and version for a match,
and processing calls until the connection is disconnected.
For each RPC call, this procedure catches any propagated
exceptions, transmits them, and then flushes the transmit buffer.
When the connection is disconnected or a protocol error occurs, the
procedure deallocates the transport stream and returns.
@node !Tools.Networking.Rpc_Server.Supported
Supported : Rpc.Version_Range := (0, Rpc.Version_Number'Last);
Indicates the range of versions supported by this RPC server.
@node !Tools.Networking.Transport_Interchange
Instantiates package Interchange for use on a transport stream.
Package Transport_Interchange provides procedures for
interchanging various standard types over transport connections.
This package is used by RPC programs for interchanging the
parameters and results of remote procedure calls.
The specification of the package is:
with Interchange;
with Transport_Stream;
package Transport_Interchange is new Interchange.Operations
(Stream_Id => Transport_Stream.Stream_Id,
Put => Transport_Stream.Transmit,
Get => Transport_Stream.Receive);
@node !Tools.Networking.Transport_Server
This package handles the creation of server tasks in response to
incoming connections. The algorithm to be used for serving each
connection is supplied by the user as a generic parameter.
This package is used by RPC servers to manage the tasks providing
an RPC service.
The specification of the package is:
with Transport;
with Transport_Defs;
generic
with procedure Serve (Connection : Transport.Connection_Id) is <>;
package Transport_Server is
type Pool_Id is private;
function Create (Network : Transport_Defs.Network_Name;
Local_Socket : Transport_Defs.Socket_Id;
Max_Servers : Natural := Natural'Last)
return Pool_Id;
procedure Finalize (Abort_Servers : Boolean := False);
function Local_Socket (Pool : Pool_Id)
return Transport_Defs.Socket_Id;
function Max_Servers (Pool : Pool_Id) return Natural;
function Network (Pool : Pool_Id)
return Transport_Defs.Network_Name;
procedure Set_Max_Servers (Pool : Pool_Id;
Max_Servers : Natural);
function Servers (Pool : Pool_Id) return Natural;
end Transport_Server;
@node !Tools.Networking.Transport_Server.Create
function Create
(Network : Transport_Defs.Network_Name;
Local_Socket : Transport_Defs.Socket_Id;
Max_Servers : Natural := Natural'Last)
return Pool_Id;
Creates a pool of server tasks.
Each pool contains a waiter task that waits for incoming
connections on the specified network and local socket. The waiter
task starts waiting when the pool is created.
When a connection arrives, a server task is allocated to serve it.
The server task calls the Serve procedure and passes it the newly
arrived connection. When the Serve procedure returns, there is
nothing more to be done with the connection. The server task then
closes the connection and terminates.
The waiter task continues to wait for more incoming connections.
In addition, the waiter task keeps track of the number of active
servers. If this number reaches the given Max_Servers limit, the
waiter task stops waiting for incoming connections.
@node !Tools.Networking.Transport_Server.Finalize
procedure Finalize (Abort_Servers : Boolean := False);
Terminates all tasks dependent on this instantiation of package
Transport_Server and closes all transport connections.
This procedure permits the caller to exit the scope in which
package Transport_Server was instantiated. See the Ada Language
Reference Manual, Section 9.4.
@node !Tools.Networking.Transport_Server.Local_Socket
function Local_Socket (Pool : Pool_Id) return Transport_Defs.Socket_Id;
Returns the local socket on which the given pool is waiting for
incoming connections.
This value is set when the pool is created.
@node !Tools.Networking.Transport_Server.Max_Servers
function Max_Servers (Pool : Pool_Id) return Natural;
Returns the maximum number of server tasks that can be active
simultaneously in the given pool.
This value is initialized when the pool is created and subsequently
can be set by the user.
@node !Tools.Networking.Transport_Server.Network
function Network (Pool : Pool_Id) return Transport_Defs.Network_Name;
Returns the network on which the given pool waits for incoming
connections.
This value is set when the pool is created.
@node !Tools.Networking.Transport_Server.Pool_Id
type Pool_Id is private;
Identifies a pool of server tasks.
@node !Tools.Networking.Transport_Server.Serve
procedure Serve (Connection : Transport.Connection_Id) is <>;
Serves a connection.
This procedure is called once for each incoming connection. The
tasks that call the Serve procedure are created and managed by
manipulating pool objects.
@node !Tools.Networking.Transport_Server.Servers
function Servers (Pool : Pool_Id) return Natural;
Returns the number of server tasks currently active in the given
pool.
This number is initially 0. The value increases each time a
connection arrives and decreases each time a server terminates.
@node !Tools.Networking.Transport_Server.Set_Max_Servers
procedure Set_Max_Servers (Pool : Pool_Id;
Max_Servers : Natural);
Sets the maximum number of server tasks that can be active in the
given pool.
Once the number of active servers reaches this limit, the pool's
waiter task stops waiting for incoming connections.
If the Max_Servers parameter is set to a number less than the
current number of active servers, the existing servers will
continue to run until they terminate by themselves.
@node !Tools.Networking.Transport_Server_Job
This package handles the creation of server jobs in response
to incoming connections. The algorithm used for serving each
connection is supplied by the user as a generic parameter.
This package is used by RPC servers to manage the jobs providing a
RPC service.
The specification of the package is:
with Transport;
with Transport_Defs;
package Transport_Server_Job is
generic
Network : Transport_Defs.Network_Name;
Local_Socket : Transport_Defs.Socket_Id;
with procedure Server_Start;
with procedure Serve (Connection : Transport.Connection_Id);
procedure Server_Generic;
procedure Change_Identity (Username : String;
Password : String);
end Transport_Server_Job;
@node !Tools.Networking.Transport_Server_Job.Change_Identity
procedure Change_Identity (Username : String;
Password : String);
Sets the calling job's access control identity to the specified
username and password.
If Username = Password = "", the calling job's identity is set
back to its original value---that is, the identity with which the
job was first run.
@node !Tools.Networking.Transport_Server_Job.Local_Socket
Local_Socket : Transport_Defs.Socket_Id;
Denotes a socket within the context of a machine.
For TCP/IP, the socket identifier is a TCP port number.
@node !Tools.Networking.Transport_Server_Job.Network
Network : Transport_Defs.Network_Name;
Denotes one of several networks to which this machine can be
attached.
Only TCP/IP is currently defined.
@node !Tools.Networking.Transport_Server_Job.Serve
procedure Serve (Connection : Transport.Connection_Id);
Processes incoming requests from the connection.
This procedure is called once for each incoming connection.
@node !Tools.Networking.Transport_Server_Job.Server_Generic
procedure Server_Generic;
Waits for an incoming request for connection on the specified
network and local socket.
When a connection request arrives, this procedure executes
procedures Server_Start and Serve(Connection). The procedure
repeats this process until the local socket is in use, and then it
returns.
@node !Tools.Networking.Transport_Server_Job.Server_Start
procedure Server_Start;
Starts another server job, using the network specified by the
Network parameter at the socket specified by the Local_Socket
parameter.
@node !Tools.Networking.Transport_Stream
This package handles the details of allocating and using transport
connections.
A transport stream combines a transport connection with some
buffering and provides a simplified transmit/receive interface.
This package provides a facility for creating pools of streams.
Allocating and deallocating streams occurs very quickly and
introduces little overhead. If a stream remains deallocated for a
few minutes, the transport connection associated with it is closed.
This package is useful for programs needing to communicate with
another machine, without setting up and disconnecting transport
connections, or for handling transport status codes.
@node !Tools.Networking.Transport_Stream.Allocate
procedure Allocate (Stream : out Stream_Id;
Connection : Transport.Connection_Id);
Creates a stream without a pool around the given connection.
The connection is closed when the stream is deallocated.
@node !Tools.Networking.Transport_Stream.Allocate
procedure Allocate (Stream : out Stream_Id;
Is_New : out Boolean;
Network : Transport_Defs.Network_Name;
Host : Transport_Defs.Host_Id;
Socket : Transport_Defs.Socket_Id);
Locates or sets up a stream to the given network/host/socket
combination.
@node !Tools.Networking.Transport_Stream.Allocate
procedure Allocate (Stream : out Stream_Id;
Pool : Pool_Id;
Is_New : out Boolean);
Locates an idle stream from the specified pool.
If no idle stream is available, the procedure sets up an idle
stream, opens and connects a transport connection, and returns
Is_New = True.
@node !Tools.Networking.Transport_Stream.Connection
function Connection (Stream : Stream_Id) return Transport.Connection_Id;
Returns the transport connection to which the stream is bound.
@node !Tools.Networking.Transport_Stream.Create
function Create (Network : Transport_Defs.Network_Name;
Remote_Host : Transport_Defs.Host_Id;
Remote_Socket : Transport_Defs.Socket_Id;
Local_Socket : Transport_Defs.Socket_Id
:= Transport_Defs.Null_Socket_Id) return Pool_Id;
Creates a pool of active streams.
@node !Tools.Networking.Transport_Stream.Deallocate
procedure Deallocate (Stream : Stream_Id);
Returns a stream to its pool.
Once a stream has been deallocated, it must not be used
subsequently because it may be reallocated to another program.
@node !Tools.Networking.Transport_Stream.Destroy
procedure Destroy (Pool : Pool_Id);
Disconnects all streams in the pool and terminates all tasks
associated with the pool.
@node !Tools.Networking.Transport_Stream.Disconnect
procedure Disconnect (Stream : Stream_Id);
Disconnects the transport connection to which the stream is bound.
@node !Tools.Networking.Transport_Stream.Finalize
procedure Finalize;
Destroys all pools and terminates all tasks.
This procedure is used when exiting a subprogram in which package
Transport_Stream (and by extension the tasks within it) was
elaborated. See the Ada Language Reference Manual, Section 9.4.
@node !Tools.Networking.Transport_Stream.Flush_Receive_Buffer
function Flush_Receive_Buffer (Stream : Stream_Id)
return Byte_Defs.Byte_String;
Empties and gives as the return value the contents of a stream's
receive buffer.
@node !Tools.Networking.Transport_Stream.Flush_Transmit_Buffer
procedure Flush_Transmit_Buffer (Stream : Stream_Id);
Transmits any data currently in the stream's transmit buffer.
This procedure does not return until all buffered data have been
transmitted.
@node !Tools.Networking.Transport_Stream.Get_User_Id
function Get_User_Id (Stream : Stream_Id) return Integer;
Returns the User_Id integer that is associated with the current
stream.
@node !Tools.Networking.Transport_Stream.Not_Connected
Not_Connected : exception;
Occurs when an attempt is made to operate on a unconnected stream.
@node !Tools.Networking.Transport_Stream.Pool_Id
type Pool_Id is private;
Identifies a pool of streams.
@node !Tools.Networking.Transport_Stream.Receive
procedure Receive (From : Stream_Id;
Data : out Byte_Defs.Byte_String);
Receives data over a transport stream.
This call does not return until Data'Length bytes are received.
@node !Tools.Networking.Transport_Stream.Scavenge
procedure Scavenge (Pool : Pool_Id);
Disconnects any deallocated streams in the pool.
@node !Tools.Networking.Transport_Stream.Scavenge
procedure Scavenge;
Scavenges all pools for unused streams.
Periodically, a task within package Transport_Stream automatically
scavenges all pools.
@node !Tools.Networking.Transport_Stream.Set_User_Id
procedure Set_User_Id (Stream : Stream_Id;
User_Id : Integer := 0);
Maps the stream identification number to a user identification
number.
The user identification number is not used by package
Transport_Stream but is provided so that you can associate higher-
level information with each stream.
@node !Tools.Networking.Transport_Stream.Stream_Id
type Stream_Id is private;
Identifies a data pipe, called a stream, consisting of a transport
connection and some associated buffers.
@node !Tools.Networking.Transport_Stream.Transmit
procedure Transmit (Into : Stream_Id;
Data : Byte_Defs.Byte_String);
Transmits data over a transport stream.
The given data are either transmitted or stored in a buffer
for later transmission. The buffer can be cleared using the
Flush_Transmit_Buffer procedure.
@node !Tools.Networking.Transport_Stream.Unique
function Unique (Stream : Stream_Id) return Unique_Id;
Converts the stream identification number to a unique number.
Stream_Id is a private type and its image cannot be obtained
directly. Converting Stream_Id to Unique_Id provides a handle
to allow you to use the identification number for printing hash
tables, for example.
@node !Tools.Networking.Transport_Stream.Unique_Id
subtype Unique_Id is Integer;
Identifies a unique value of the stream identification number.
The unique identification number can be used as a handle for
printing hash tables, for example.