##############################################################################
#
# README.OC      *** readme f. ODBC Testbatterie
#
# @(#)README.OC/README 6.2.7.10      1996-01-27
#
# Autor: Burkhard Diesing
#
##############################################################################
echo
echo "Start the ODBC Testsuite with "
echo "'odbctest'"
echo
echo "Before starting the ODBC Testsuite please cleanup the reference files "
echo "with 'odbctest -cleanup'."
echo
echo "For questions about the ODBC Testsuite please consult the file "
echo "$OWN/test/pc/odbc/README (german only)."
echo
exit 
                O D B C   T E S T B A T T E R I E

Dieses Dokument soll die Schritte und Anforderung erklaeren um die Testlaufe 
fuer das Callinterfaces ODBC unter UNIX erfolgreich zu durchlaufen. 
Des weiteren soll es Erlaeutern, wie die Testbatterie arbeitet und was 
fuer die Auswertung wichtig ist. 
    
Fuer Fragen und Anregungen zur Verbesserung diese README oder Erweiterungen 
und Aenderungen der Testlaeufe stehe ich gerne zur Verfuegung.

Gruss
Burkhard

-----------------------------------------------------------------------------

1.  Einrichten der Testbatterie

2.  Vorbereiten der Testbatterie
2.1 Vorraussetzungen an die Datenbank.
2.2 Vorraussetzungen an die Systemumgebung
2.3 Benoetigte Verzeichnisstruktur

3.  Aendern der default Einstellungen
3.1 Aendern der Usernamen und Passwoerter
3.2.1 Aufbau der Konfigurationsdatei (odbc.ini) 
3.2.2 Einrichten der Datasources (Windows) 

4.  Starten der ODBC Testbatterie
4.1 Alle Test durchfuehren (Normalfall)
4.2 Einzelne Test durchfuehren
4.3 Loeschen Alter Testausgaben

5.  Arbeitsweise der ODBC Testbatterie
5.1 Erzeugte Testausgaben
5.2 Ueberpruefen des Testlaufs

----------------------------------------------------------------------------


1.  Einrichten der Testbatterie

    Die Testsprogramme  werden mit 'imf odbctest' erzeugt. Die Testprogramme
    fuer ODBC haben die mfExtra Extension .OC und .OH und werden aus der 
    Schicht ox genommen. Des weiteren in diesem Makelauf Shellscripte aus 
    der Schicht px generiert.

2.  Vorbereiten der Testbatterie

2.1 Vorraussetzungen an die Datenbank.

    Die Datenbank muss gestartet sein. 
    Die Environmentvariable DBROOT  muss gesetzt sein, es wird aber keine
    locale Datenbank benoetigt.
    Der Benutzername und Password fuer den Superdba sollten SUPERDBA,ADMIN 
    sein um Differenzen in den Teststroemen zu vermeiden. 
    Sollte dies nicht der Fall oder nicht moeglich sein, siehe 3.1.

2.2 Vorraussetzungen an die Systemumgebung
    
    Der Makelauf 'imf odbc' muss erfolgreich gewesen sein.
    
    Die Testbatterie legt im ersten Testprogramm (initodbc.c) den User ODBC
    als DBA an dies geschieht ueber den Superdba. Existiert der Benutzer ODBC 
    wird er zuerst geloescht. Die im Verlauf der Testbatterie angelegten 
    Benutzer, Tabellen und Proceduren gehen nun immer von Benutzer ODBC aus.

    Die Connectparameter fuer den Datenbanknamen und Datenbankknoten werden 
    nicht !!! ueber DBNAME und DBNODE geholt, sondern werden aus der 
    Datei /usr/spool/sql/config/odbc.ini ermittelt. Die Datei Konfigurations-
    datei odbc.ini muss einmal angelegt werden, da das Verzichniss normaler
    Weise root gehoert, exitstiert im Verzeichniss $OWN/test/pc/odbc eine
    Default Konfigurationsdatei odbc.ini diese Datei allerdings von Hand nach
    /usr/spool/sql/config kopiert werden. Fuer die Testbatterie in 6.2 
    wird der Datasourcename 'ADABAS D 6.2.8' in der Konfigurationsdatei verwandt. 
    Aenderungen, falls notwendig, sind im Abschnitt 3.2 beschrieben.

2.3 Benoetigte Verzeichnisstruktur

    $TOOL/bin		; Shellscripte fuer die Testbatterie

    $OWN/test/pc/odbc	; C Testprogramme und Headerdateien

    $OWN/test/pc/dia 	; Commandodateien f. Stored Procedures

    $OWN/test/pc/wrk    ; Arbeitsverzeichniss und Testaugaben.
			  Erzeugt werden folgende Dateien:
			  Bildschirmausgaben	> Lo.<progname>.o
			  Traceprotokolle 	> Lo.<progname>.t

    $OWN/test/pc/old	; Alte Bildschirmausgaben und Traceprotokolle
			  Diese Dateien werden ueber die Hirachie waerend 
			  des Testlaufes geholt. 

    $OWN/test/pc/dif	; Differenzen der Testausgaben zwischen old wrk.

3.  Aendern der default Einstellungen

    Unter gewissen Vorraussetzungen kann es noetig sein, die standard 
    Einstellungen zu aendern. Das folgende Kapitel soll die Erforderlichen
    Massnahmen beschreiben.

3.1 Aendern der Usernamen und Passwoerter

    Die Benutzerangaben fuer den Superdba koennen in der Datei 
    $OWN/test/pc/odbc/winhead.h geandert werden. Dazu muessen die C-Macros

	#define USERNAME "SUPERDBA"
	#define PASSWORD "ADMIN" 

    entsprechend angepasst werden. (Achtung Casesensitive)

3.2.1 Aufbau der Konfigurationsdatei (odbc.ini) 

    Die Connectparameter werden aus der Datei odbc.ini im Verzeichniss
    /usr/spool/sql/config geholt. Die Datei ist wie folgt aufgebaut.
    Die Eintraege in dieser Datei bestehen aus zwie Teilen.
    Erstens dem Datasourcenamen (in eckigen Klammern). Dieser Eintrag dient 
    der Identifikation der Datenquelle und entspricht ungefaehr unserem 
    XUSER Key. Zweitens der Connectparameter dies sind unter anderem der
    Datenbankname, der Knoten und eventuell der SQLMode. Genaueres siehe 
    Dokumentation des ODBC Treibers. Usernamen und Passwoerter werden aus
    Sicherheitsaspekten von ODBC nicht gespeichert.

	[ADABAS D]		;Datasourcename 
	ServerDB=DB62		;Datenbankname
	ServerNode=all2		;Datenbankknoten
        ....			; weitere Datasource spezifische Eintraege
				; z.B SQLMODE=ORACLE

3.2.2 Einrichten der Datasources (Windows) 

    Die Connectparameter werden aus der Datei odbc.ini (16-Bit oder der 
    Registrierdatenbank (32-Bit) geholt. Die Datasource wird mittels
    des ODBC Administrators eingerichtet. Dazu waehlt man unter den Button
    Neu und sucht sich den ADABAS D ODBC Treiber.
    In dem dann folgendem Dialog muessen die Eintraege ServerDB und ServerNode
    gemacht werden.

4.  Starten der ODBC Testbatterie
  
    Die Testbatterie lauft ueber Shellscripte ab, die im Makelauf erzeugt 
    wurden.

4.1 Alle Test durchfuehren (Normalfall)

    Sollen alle Tests durchgefuehrt werden, so geschieht dies mit dem Aufruf
    des Shellscripts odbctest. Als Protokolldatei wird eine Datei mit dem 
    Namen pctest.prot im Verzeichniss $OWN/test/pc/wrk angelegt.

4.2 Einzelne Test durchfuehren

    Sollen nur einzelne Tests durchgefuehrt werden, so geschieht dies mit
    dem Aufruf des Shellscripts 'pctest'. Als Protokolldatei wird eine Datei
    mit dem Namen pctest.prot im Verzeichniss $OWN/test/pc/wrk angelegt.

    Aufgerufen werden kann 'pctest' in zweierlei Weise:

	pctest odbc/<progname>

	SQLOPT=-X; pctest odbc/<progname>	# mit Kommandotrace 

4.3 Loeschen Alter Testausgaben

    Wurde die Testbatterie schon einmal oder im letzten CL gestartet, so
    ist es angebracht die Alten Referenceprotokolle zu loeschen. Dazu kann
    das Shellscript pctodbc mit der Option -clean aufgerufen werden. Die
    Option -clean bewirkt, dass die Referenceprotokolle im ../old Verzeichniss
    geloescht werden. Geloescht werden die Files 
	Lo.<testname>.o und Lo.<testname>.t

5.  Arbeitsweise der ODBC Testbatterie

    Die Testbatterie compiliert, linkt und startet die jeweiligen Testprogramme
    selbsttaendig. Die Programme werden in der Reihenfolge ausgefuerht, wie sie
    im Shellscript pctodbc aufgefuehrt sind. Einzelne Test lasses sich aber
    auch mit pctest odbc/<testname> seperat ausfuehren.

5.1 Erzeugte Testausgaben

    Jedes Testprgramm erzeugt 1-2 Dateien, die mit alten Testausgaben, die von
    mir als OK eingestuften wurden, automatisch verglichen werden. Es werden
    hierbei die Ausgaben nach stdout (Lo.<progname>.o) und die Kommando traces
    (Lo.<prgname>.t verglichen wobei die alten Testausgaben per _icp aus der 
    eingestellten Hirachie geholt werden. 

    Kommandotraces werden vorher automatisch mit einem sed script von den 
    meisten immer unterschiedlichen Datums/Zeitangaben, Parsids und 
    Connectparametern bereinigt.

    Gab es Unterschiede im Testlauf, so werden die Unterschiede im 
    Verzeichniss $OWN/test/pc/dif festgehalten. Die Testausgaben des neuen 
    Laufes stehen im Falle von Differenzen im Verzeichniss $OWN/test/pc/wrk.
    Eine Kopie des Originals befindet sich dann unter $OWN/test/pc/old. 

    Jedes Ausgefuehrte Testprogramm wird in der Datei pctest.prot im 
    Verzeichniss $OWN/test/pc/wrk protokolliert. Hierbei werden auch
    Uebersetzungs/Link fehler oder Cores erfasst. 
    Das Object, Testprogramm und evtl. Cores werden nach dem lauf geloescht.

5.2 Ueberpruefen des Testlaufs
    
    Die Ergebnisse (diffs, cores, usw) stehen in der Datei pctest.prot im 
    Verzeichniss $OWN/test/pc/wrk.

    Die meisten Testprogramme laufen ohne Differenzen durch. Normalerweise
    sind nur Versions Nummern, Datums und Zeitwerte unterschiedlich. Die 
    Datum/Zeit Werte tragen das Aktualdatum (Kandiaten hiefuer sind die 
    Programme dattim, pcbval, ...). 
    Der Versionsstring wird in einigen Programmen ausgegeben und kann 
    somit unterschiedlich sein (getinfo, execdsel, ...).

    Bei einigen Testprogrammen wird auf den Systemkatalog zugegriffen,
    so dass es bei diesen Programmen (tables, columns, etc) zu mehr Ausgaben
    von Tabellen und Usernamen sowie des Rowcounts kommen kann. 
    
    Wer Probleme mit der Auswertung hat oder sich nicht sicher ist ob der eine
    oder andere Test erfolgreich war kann mir die Testausgaben gerne zeigen
    ich brauche in diesem Falle die Dateien Lo.*.* aus den Verzeichnissen
    
    	$OWN/test/pc/old/Lo.*.*
        $OWN/test/pc/wrk/Lo.*.*
        $OWN/test/pc/dif/Lo.*.*

    und 
        $OWN/test/pc/wrk/pctest.prot


