REIMERS CONSULT Company Logo

REIMERS CONSULT GmbH

Home Feedback Contents

RC.Sql Tutorial

RC.Sql Product Logo medium

Datenbankzugriffsbibliothek


Inhalt


Einleitung
Dieses Tutorial bietet eine knappe Einführung in die Gebrauchsweise der C# Klassenbibliothek RC.Sql. Es geht zuerst auf ein paar allgemeine Sachverhalte ein und erklärt anschließend an einem kleinen Beispiel, wie eine Anwendung aufbauend auf RC.Sql aussehen kann. Die Beispielanwendung ist in C# geschrieben. Es handelt sich um ein einfaches Programm mit Konsolenausgabe, das den Inhalt einer Tabelle löscht, zwei Datensätze in eine Tabelle schreibt und anschließend den Inhalt der Tabelle in der Konsole ausgibt. Den Quelltext zu dem Beispiel finden Sie hier. Abschnitte des Quelltextes, die sich in diesem Tutorial befinden, sind grau unterlegt und in der Schriftart Courier.

nach oben


Voraussetzungen
  • gültige Lizenz von RC.Sql (Test- oder Entwicklerlizenz). Zu näheren Informationen kontaktieren Sie bitte unseren Support (siehe Hauptseite RC.Sql).
  • Microsoft .NET Framework SDK Version 1.1
  • vorhandene Datenbank mit mindestens einer Tabelle. Die Datenbank muss auf dem Rechner, auf dem die Beispielanwendung ausgeführt werden soll, eingerichtet sein.
  • Grundkenntnisse im Programmieren allgemein und speziell in C#

nach oben


Allgemeines zu RC.Sql
RC.Sql ist eine Klassenbibliothek für Datenbankzugriffe im Rahmen des .NET Frameworks. Die zentrale Klasse ist RcsqlDatabase. Sie erzeugt alle Statements und in Implementierungen dieser Klasse sind alle notwendigen Informationen zu Eigenschaften von spezifischen Datenbanken (Access, Sybase, DB2,...) enthalten.
In einer Anwendung wird als erstes eine Instanz der entsprechenden Datenbankklasse erzeugt (z.B. RcsqlOdbcDatabase). Danach wird sie mit den Anmeldedaten eines Datenbank Benutzers (Datenbankname, Login,...) versorgt. Anschließend werden daraus die gewünschten Statementobjekte für Datenmanipulationen (INSERT, UPDATE,...) in der Datenquelle erzeugt und ausgeführt.

nach oben


Beispielprogramm
Das Beispielprogramm bezieht sich auf eine Tabelle namens BENUTZER in einer Microsoft  Access Datenbank. Die Tabelle besteht aus den Spalten USER_RECNO, USER_USERID und USER_NAME. USER_RECNO ist der Primärschlüssel eines Datensatzes und wird von der Tabelle automatisch beim Einfügen eines Datensatzes erzeugt. USER_USERID ist als UNIQUE definiert.
1) Die Datenbankklasse
Basisklasse für alle Datenbankklassen ist RcsqlDatabase. Davon abgeleitet sind datenbank- bzw. treiberspezifische Implementationen. Hier wird eine Instanz der Klasse RcsqlOdbcDatabase benutzt.
RcsqlOdbcDatabase accessDatabase = new RcsqlOdbcDatabase();
Mit der Methode CreateNewConnection wird eine neue Instanz der Klasse RcsqlConnection initialisiert, und durch die Übergabe des Anmeldestrings an accessDatabase kann die Verbindung zur Datenbank geöffnet werden.
string connectionString = "DSN=" + dsn +
                          ";UID=" + userID +
                          ";Pwd=" + password +
                          ";Database=" + database;
...
accessDatabase.CreateNewConnection();
accessDatabase.SetConnString(connectionString);
accessDatabase.Open();
2) Delete-Statement erzeugen und ausführen
Die Klasse zum Löschen von Datensätzen heißt RcsqlDeleteStmt . Dazu wird ein Objekt für die Tabelle BENUTZER benötigt, aus der Daten entfernt werden sollen. Das Tabellenobjekt erzeugt dann für die dadurch repräsentierte Tabelle ein Delete-Objekt. Gibt man keine weiteren Anweisung an das Statement, löscht es den gesamten Tabelleninhalt.
tableUser = accessDatabase.GetTable("BENUTZER");
RcsqlDeleteStmt delete = tableUser.CreateDeleteStmt();
delete.Execute();
Um bestimmte Datensätze aus einer Tabelle zu löschen, muss die Where-Klausel des RcsqlDeleteStmt gesetzt werden. Das folgende Beispiel zeigt den Aufbau der Bedingungen in RC.Sql, um einen Benutzereintrag mit dem Namen XXX oder dem Kürzel Z zu löschen.
delete.Where = tableUser["USER_NAME"] == "Xxx"
               | tableUser["USER_ID"] == "z";
3) Insert-Statement erzeugen und ausführen
Ein Insert-Objekt wird auf die gleiche Weise erzeugt wie ein Delete-Objekt. Danach setzt man die Namen der Spalten, in die neue Werte eingefügt werden sollen.
string[] colNames = new string[]{"USER_USERID" "USER_NAME"};
RcsqlInsertStmt insert = tableUser.CreateInsertStmt(colNames);
Die neuen Werte werden an die entsprechende Indexeigenschaft von insert übergeben, und das Statement wird ausgeführt.
insert[colNames[0]].Set("TU");
insert[colNames[1]].Set("Test User");
insert.Execute();
4) einfaches Select-Statement erzeugen und ausführen
Ein Select-Statement bezieht sich im Allgemeinen nicht nur auf eine einzelne Tabelle. Aus diesem Grund wird es nicht wie ein Insert- oder Delete-Statement durch die Tabellenklasse sondern durch die Datenbankklasse selber erzeugt.
RcsqlSelectStmt select = accessDatabase.CreateSelectStmt();
Die Methode AddSelect übernimmt als Parameter alle Spalten, die gelesen werden sollen. In diesem Beispiel wird die ganze Tabelle übergeben, da alle Spalten gelesen werden sollen.
select.AddSelect(tableUser);
Zum Lesen der Daten wird dann die Methode ExecReader benutzt. Sie liefert als Rückgabe nach erfolgreichem Zugriff einen RcsqlReader . Der Reader stellt die gelesenen Daten zur Verfügung.
RcsqlReader reader = select.ExecReader();
while ( reader.Read() ) {
for (int i = 0; i < reader.ColumnCount; i++)
  Console.Write( reader.Object + "\t");
  Console.WriteLine();
}
5) Select Statement mit bedingter Where-Klausel
Das folgende Beispiel bezieht sich auf eine Datenbank mit den Tabellen BENUTZER, KONTRAHENT und UMSATZ. Die Felder USER_RECNO, KD_RECNO und UM_RECNO sind jeweils Primärschlüssel eines Datensatzes und werden von der Tabelle automatisch beim Einfügen eines Datensatzes erzeugt.
Hier wird aus verschiedenen Tabellen gelesen und die Ergebnisse geordnet.
RcsqlTable tableKd = accessDatabase.GetTable("KONTRAHENT");
RcsqlTable tableUm = accessDatabase.GetTable("UMSATZ");
sel.Where = tableUser["USER_KD"] == tableKd["KD_RECNO"] &
       tableUm["UM_KD"] == tableKd["KD_RECNO"] &
       ( tableUm["UM_BETRAG"] > 1000 &
         ( RcsqlExpr.UpCase(tableKd["KD_ORT"]) == "LONDON" |
         tableKd["KD_ADDNR"].Between(1000, 2000) ) |
         !tableUm["UM_BOOK"].In(RcsqlExpr.Text("('GGC', 'XYZ')"))
       );
sel.Where &= tableUser["USER_LEVEL"] != 5;
sel.OrderBy(tableUser["USER_NAME"])
    .OrderByDescending(tableUser["USER_SALE"])
    .OrderBy(tableKd["KD_ID"]);
RC.Sql erzeugt automatisch das folgende (ODBC)SQL-Statement:
SELECT t1.* FROM BENUTZER t1, KONTRAHENT t2, UMSATZ t3 WHERE t1.USER_KD = t2.KD_RECNO AND t3.UM_KD = t2.KD_RECNO AND (t3.UM_BETRAG > 1000 AND ({fn UCASE (t2.KD_ORT)} = 'LONDON' OR t2.KD_ADDNR BETWEEN 1000 AND 2000) OR NOT (t3.UM_BOOK IN ('GGC', 'XYZ'))) AND t1.USER_LEVEL <> 5 ORDER BY t1.USER_NAME ASC, t1.USER_SALE DESC, t2.KD_ID ASC
Eine genauere Beschreibung der im letzten Beispiel benutzten Tabellen wäre hier zu lang. Es soll lediglich der Aufbau von komplexen Ausdrücken mit RC.Sql gezeigt werden.

nach oben


Troubleshooting

RC.Sql im GAC
Damit ein Programm eine Klassenbibliothek benutzen kann, die nicht aus dem Standard-.NET Framework stammt, muss die Bibliothek im Global Assembly Cache (GAC) registriert sein. Alternativ muss sich die entsprechende DLL-Datei der Bibliothek in jedem Verzeichnis befinden, aus dem eine solche Anwendung gestartet wird. Da RC.Sql lizenziert ist, muss sich auch die Lizenz-Implementierung (RC.Lic) im GAC befinden.
gültige Lizenz für RC.Sql
Die Klassenbibliothek RC.Sql ist eine im Rahmen des .NET Frameworks lizenzierte Bibliothek. Beim Erstellen eines Programms wird der Lizenz-Compiler der .NET Frameworks gestartet. Er überprüft, ob eine gültige Lizenz vorliegt und integriert sie im kompilierten Programm. Beim Ausführen des Programms ist die Lizenzdatei dann nicht mehr vonnöten. Es wird allerdings eine Exception geworfen, wenn beim Kompilieren keine gültige Lizenz vorlag oder der Lizenz-Compiler aus anderen Gründen nicht gestartet wurde. Die Lizenzdatei ( RCSql.lic ) muss sich dabei im selben Verzeichnis befinden wie RC.Sql.dll . Ist dies nicht der Fall, wird beim Ausführen eines Programms eine Exception geworfen.
Lizenzhilfedatei im Anwendungsverzeichnis
Die Lizenzhilfedatei ( licenses.licx ) für RC.Sql muss sich im Quellverzeichnis der Anwendung befinden. Microsoft Visual Studio .NET 2003 und Borland C# Builder benutzen diese Datei, um den Lizenzkompiler des Framework mit den dort eingetragenen Klassen aufzurufen.
Datenbank Verbindung
Falls keine Verbindung zur Datenbank hergestellt werden kann, kann dieses Beispiel nicht ausgeführt werden. Falls diese Situation vorliegt, sollten die Datenbank Parameter geprüft werden.

nach oben