Last update: M.Erdmann - 16 Jan 00 / 15:17
This package proves an binding to the MySQL server. A DB application follows always the same sequence of calles to procedures in this package:
Queries performed by the application are strings of sql commands. All procedures of this packages do opperate on the datatbase object provided by this package.
with Ada.Strings.Unbounded; use Ada.Strings.Unbounded;
type Object is tagged private; type Handle is access Object'Class; procedure Initialize( this : in out Object'Class); procedure Finalize( this : in out Object'Class );
Usage_Error : exception; Not_Initialized : exception;
Out_Of_Resource : exception;
type Query_ID is new Positive range 1..10; subtype Field_Number is Integer range 1..100;
subtype Blob is String;
procedure User( this : in out Object'Class; Name : in String ); procedure Connect( this : in out Object'Class; Server : in String ); procedure Disconnect( this : in out Object'Class ); Connect_Failure : exception;
procedure Select_DB( this : in out Object'Class; Name : in String ) DB_Name_Failure : exception;
function Query( this: in Object'Class; query : in String) return Query_ID;
No_Query_Result : exception;
function Nbr_Of_Rows( this : in Object'Class; id : Query_ID ) return Integer;
procedure Drop_Query( this : in out Object'Class; id : in Query_ID );
procedure Next( this : in out Object'Class; query : in Query_ID);
No_More_Rows : exception;
function Get_Field_Number( this : in Object; id : in Query_ID; name : in String ) return Field_Number
; Unknown_Field : exception; Field_Type_Error : exception; Field_Parse_Error : exception;function String_Field( this : in Object; id : in Query_ID; name : in String ) return Unbounded_String; function String_Field( this : in Object; id : in Query_ID; fNumber : in Field_Number ) return Unbounded_String;
function Date_Field( this : in Object; id : in Query_ID; fNumber : in Field_Number ) return Time; function Date_Field( this : in Object; id : in Query_ID; name : in String ) return Time;
function Blob_Field( this : in Object; id : in Query_ID; fNumber : in Field_Number ) return Blob; function Blob_Field( this : in Object; id : in Query_ID; name : in String ) return Blob;
function Integer_Field( this : in Object; id : in Query_ID; fNumber : in Field_Number ) return Integer; function Integer_Field( this : in Object; id : in Query_ID; name : in String ) return Integer;
function Float_Field( this : in Object; id : in Query_ID; fNumber : in Field_Number ) return Float; function Float_Field( this : in Object; id : in Query_ID; name : in String ) return Float;
This type represents the connection to the data base server. It maintains the state of all queries.
This type is a pointer to the Object.
To each query performed by the client a query identifier is assigned. This identifier is used i.e. to access the results from different queries. If a query is not used any more it should be droped.
Each colume field returned by a query is numberd starting from 1. The prcoedures for accessing are using either the colume number or the name. It is possible to translate between colume name and number by means of the Get_Field_Number function.
Type - Blob
This type represents the binary large object. It is simply a string of characters which is not structured. The application has to interpret the contents of the blob.
This exception indiactes an semantical error in the usage of a method.
Exception - Not_Initialized
Indicates that the object has not been initialized by an Initialize call.
This exception dicates, that the query issued does not yield any result. This might be due to a failure in the Syntax of the SQL command or a failure in the server.
This exception indicates, that no more rows are available for the relevant query. This exception is thrown by the Next procedure if no more rows for a query are available.
This exception indicates, that an field name connot be translated into a field number.
Database does not exist.
Exception - Unknown_Field
The field name requested in the result access procedure was not found.
The field type of the result does not match the requested type.
The result handling procedure was not able to parse the contents of the data field according to the field type.
The connection to the SQL server did fail for some reason.
Indicates that som internal resource is not available, i.e. no query slot are available etc...
Preconditions:
Object is not yet initialized.
Postconditions:
Function:
This procedure initializes the instance data. there are no actions towards the server performed.
Exceptions:
Usage_Error - raised if the precondition is not matched.
Preconditions:
The object has been initialized.
Postconditions:
Function:
The object is finialized, which means memory is deallocated and any active server connection and associated queries are released.
Exceptions:
Not_Initialized - raised if no initializaton has been performed previously.
Preconditions:
Object has to be initialized and the server connection is not exstablished.
Postconditions:
Server connection is not affected.
Function:
The user name for the login at the server is set. This makes only sense before the connection to the server is established. If the session is already esatblished, the value set will used when the next connect is issued.
Exceptions:
Preconditions:
Not yet connected to the server and the login name has been set by using the User attribute function.
Postconditions:
Function:
This method connects to the server given in the hostname and login into the MYSQL Server using the given user id. The verification of the login is done by the server. The package does no prechecking at all.
Exceptions:
Preconditions:
A server connection does exist.
Postconditions:
Function:
Exceptions:
Preconditions:
Connection the server is established.
Postconditions:
Function:
This methods sends a select data base command to the server. All following query command will operate on this data base.
Exceptions:
Preconditions:
Database object has been initialized and the used query id is valid.
Postconditions:
Function:
This function translates the given name into a field number based upon the referenced query.
Exceptions:
Preconditions:
The database connections has been initialized and the server is connected.
Postconditions:
Function:
This methods allows to sent a sql query string to the server. The query string has to follow the sql syntax as it is supported by the server. If the query returns no result due to an error the No_Query_Result exception is thrown. The function returns the id of the query context. If it is not possible to allocate the query context the exception Out_Of_Resource is issued. In such an case of server resources are allocted any more.
Exceptions:
Preconditions:
The database connections has been initialized and the server is connected.
The given query identifier has to be valid.
Postconditions:
Function:
This method retrieves the next result row for the given query context. If no more rows are available, the exception NO_More_Rows is thrown.
Exceptions:
Preconditions:
Valid server connection
Query_Id is valid
Postconditions:
Function:
This method drops a query context. This realses all local and remote resources for the given query.
Exceptions:
Preconditions:
1. Object has been initialized
2. Valid server connection and database selected
3. Valid Query id
Postconditions:
Function:
This function returns the number of rows which are found by the references query.
Exceptions:
Preconditions:
Server connection valid
Query context is valid
Postconditions:
Function:
This function allows to access a field for the given type which ia part of the method name. Field may be accessed either by a number or the name of the field. For exampl the following query:
select Name, value from Test;
The field value could be accessed by the name or the field position 2.
If the referenced field does not match the field type as indicated by the server an Field_Type_Error exception is thrown.
If the field type matches, but the data structure does not comply to the data type the Field_Parse_Error is thrown.
Exceptions:
The interface defined by this package does not depend on the architecture of MySQL. There for there is a good chance that code wirten for this binding can be reused for other data base servers as long as they are complying to SQL. This is proably the largest problem, because MySQL does not comply to SQL completely.
The simple example below shows how to query and access the result of a query.
with Ada.Text_IO; use Ada.Text_IO; with Ada.Strings.Unbounded; use Ada.Strings.Unbounded; with Ada.Calendar; use Ada.Calendar;
with DB; use DB;
procedure Test is dBase : DB.Object; qId : DB.Query_ID; Nbr_Tuples : Integer := 0;
begin
Initialize( dBase );
User( dBase, "ACDE"); Connect( dBase, "localhost" );
Select_DB( dBase, "TestDB" );
--------------------------------------------------------------------------------------
begin qID := Query( dBase, "select * from Test");
while true loop declare Insert_Time : Time; begin
Nbr_Tuples := Nbr_Tuples + 1; Put_Line( "'" & To_String( String_Field( dBase, qId, "id" ) ) & "'" ); Insert_Time := Date_Field( dBase, qID, 2); Next( dBase, qID );
exception when Field_Parse_Error => Put_Line("Field parse error"); Next( dBase, qID );
when Others => raise; end; end loop;
exception when Field_Type_Error => Put_Line("Field type error"); when No_Query_Result => Put_Line("Query Failed"); when No_More_Rows => Put_Line( "End of Query Tuples:" & Integer'Image( Nbr_Tuples ) ); when The_Error : Others => Put_Line( "An error has occured at:" & Integer'Image( Nbr_Tuples ) ); end;
Drop_Query( dBase, qID ); Finalize( dBase );
end Test;
MySQL - http://www.tcx.se/