DDL2HTML.ZIP (ca 380 KB)

Remote Enscribe Handbuch

Remote Enscribe

Remote-Zugriff auf HP NonStop-Datenbanken

Das vorliegende Dokument beschreibt die C-API. Remote Enscribe ist jetzt auch als Java-API erhältlich.

Inhaltsverzeichnis

Einsatzbereich

Remote Enscribe ist ein Produkt, das es C-Programmierern unter DOS, Windows (3.x, 9x, NT/2000/XP), OS/2 oder Unix/Linux erlaubt, von einem PC oder Unix-Client aus Dateizugriffe auf HP NonStop-Hosts auszuführen.

Remote Enscribe unterstützt die üblichen NonStop-Dateitypen (UNSTRUCTURED, EDIT, ENTRY-SEQUENCED, KEY-SEQUENCED, RELATIVE) und Zugriffsmethoden (READ, WRITE, READUPDATE, WRITEREAD, LOCK/UNLOCK.) Remote Enscribe unterstützt auch den Einsatz von TMF zur Transaktionskapselung.

Alle Zugriffe sind über Benutzer und Kennwort auf dem Host geschützt. Die Zugriffszeiten beim sequentiellen Lesen und Schreiben lassen sich durch Auswahl der Pufferung optimieren.

Sollen auch SQL-Tabellen bearbeitet werden, so ist das Produkt Remote SQL erforderlich. Dieses Produkt setzt allerdings C++ auf der Client-Seite voraus. Remote SQL enthält Remote Enscribe vollständig, unterstützt aber bisher noch nicht so viele Plattformen.

[Top]

Installation

Die Verbindung zum NonStop-Host erfolgt über TCP/IP. Es ist in der LISTNER-Konfiguration lediglich ein neuer Dienst einzutragen, analog etwa zu FTP und das Programm ENSERV bzw. RSQLSRV ist zu installieren. Weitere Maßnahmen auf der Hostseite sind nicht notwendig.

Installation von ENSERV bzw. RSQLSRV

Kopieren Sie ENSERV.BIN bzw RSQLSRV.BIN auf das NonStop-System im Binärformat und ändern Sie den Filecode auf 100. Dies kann mit folgenden FTP-Befehlen geschehen:

FTP nsk1
(User und Passwort)
bin
put a:\nonstop\enserv.bin $SYSTEM.UTIL.ENSERV,100

oder 

put a:\nonstop\rsqlsrv.bin $SYSTEM.UTIL.RSQLSERV,100

Änderung der TCP/IP-LISTNER-Konfiguration

Die LISTNER-Konfiguration ist in einer Edit-Datei gespeichert und heißt normalerweise PORTCONF. Fügen Sie die folgende Zeile hinzu:

741 $SYSTEM.UTIL.ENSERV

bzw. 

741 $SYSTEM.UTIL.RSQLSRV

Ersetzen Sie dabei den Dateinamen durch den, den Sie dem Server bei der Installation gegeben haben. Die Zahl 741 ist die TCP-Portnummer. Sie kann auch anders gewählt werden. 741 ist der Standardwert.

Nach der Änderung müssen Sie den LISTNER-Prozess neu starten, genauso wie dies in der TCP/IP-Startphase Ihres Systems geschieht.

Installation auf dem Client

Auf der Clientseite wird ein TCP/IP-Stack benötigt (zum Beispiel WINSOCK). Die Anbindung an die Client-Software erfolgt über die Include-Datei renscrib.h und eine linkbare Bibliothek (LIB, OBJ und/oder DLL, je nach Plattform).

[Top]

Beispielanwendung DDL2HTML

DDL2HTML ist eine Beispielanwendung für Remote ENSCRIBE, die kostenfrei zum

Download verfügbar ist. Das Programm wandelt ein DDL-Dictionary in einen HTML-Dateibaum um, der bequem mit einem Internetbrowser betrachtet werden kann. Als Beispiel können Sie hier das Ergebnis der Umwandlung des DDL-Schemas sehen.

NEU: DDL2HTML liegt jetzt für Linux und OS/2 vor.

Aufruf

Starten Sie das Programm DDL2HTML auf einer Kommandozeile:

DDL2HTML -uGROUP.USER -pPASSWORD nsk1:741 $SYSTEM.SYSDICT

Im aktuellen Verzeichnis wird jetzt das Dictionary in eine HTML-Dokumentation umgewandelt.

DDL2HTML gibt ohne Parameter eine kurze Anleitung aus.

[Top]

API-Funktionen

Es folgt eine Liste der Funktionen, die der Programmierer nutzen kann. Die Funktionen und Datentypen sind alle in der Include-Datei renscrib.h definiert.

Die Aufrufe sind an die C-stdio-Funktionen angelehnt.

Alle unten aufgeführten Funktionen hinterlassen einen Fehlercode in der Variablen errno. Die Funktion estrerror() erlaubt es, daraus einen Fehlertext zu generieren.

[Top]

Serververbindung herstellen

HOST *econnect( char *hostname, int port, char *user, char *password );

Die Funktion öffnet eine Verbindung zum NonStop-System. Der TCP/IP-Server wird dabei vom LISTNER automatisch gestartet.

Parameter

Rückgabewert

Ein Zeiger auf eine HOST-Struktur. Dieser Zeiger wird von einigen weiteren Aufrufen benötigt.

Format der HOST-Struktur

typedef struct _host {
    int is_connected;
    int socket;
    char volume[ 8+1+8+1+8+1 ];  /* "\1234567.$1234567.12345678" */
    struct _efile *next_file;
} HOST;

[Top]

Serververbindung auflösen

int edisconnect( HOST *host );

Die Funktion beendet die Verbindung zum NonStop-System und gibt alle Resourcen frei. Alle Dateien werden geschlossen.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Datei eröffnen

EFILE *eopen( HOST *host, char *filename, char *access, 
              int flags, int recsize );

Die Funktion öffnet eine Datei auf dem NonStop-System.

Parameter

Rückgabewert

Ein Zeiger auf eine EFILE-Struktur. Dieser Zeiger wird bei allen Zugriffen auf die Datei benötigt.

Format der EFILE-Struktur

typedef struct _efile {
    int is_open;
    int is_eof;
    int flags;
    HOST *host;
    unsigned short file;
    char *buffer;
    int buffer_type;
    int buffer_count;
    int buffer_pointer;
    char filename[ 35 ];
    struct _efile *next_file;
} EFILE;

[Top]

Datei schließen

int eclose( EFILE *file );

Die Funktion schließt die durch eopen geöffnete Datei. Danach sind keine Zugriffe mehr möglich.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

Schreib- und Lesepuffer leeren

int eflush( EFILE *file );

Die Funktion leert die Puffer einer geöffneten Datei.

int eflushall( HOST *host );

Die Funktion leert die Puffer aller geöffneten Dateien einer Hostverbindung.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Satz sequentiell lesen

int eread( EFILE *file, void *buffer, int maxlen, int lock_flag );

Die Funktion liest Daten aus einer göffneten Datei. Remote Enscribe führt keinerlei Interpretation der Daten durch. Die Umwandlung in PC-Konforme Datentypen ist Aufgabe der Anwendung. Damit verhält sich Remote Enscribe ähnlich wie das HP-Produkt RSC.

Wurde die Datei mit OPEN_BUFFERED oder OPEN_BUFFERED_INPUT geöffnet, greift Remote Enscribe nur dann auf das NonStop-System zu, wenn der 4096 Byte große Puffer keine Daten mehr enthält. Bei einem Zugriff wird der Puffer wieder komplett gefüllt. Tritt hierbei ein Fehler auf, wird er an das Programm gemeldet, obwohl der eigentlich zu lesende Satz gar nicht betroffen gewesen sein muß.

Parameter

Rückgabewert

Die gelesene Länge oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Satz für Update lesen

int ereadupdate( EFILE *file, void *buffer, int maxlen, int lock_flag );

Die Funktion funktioniert analog zu eread benutzt auf dem NonStop-System aber die Systemfunktion READUPDATE statt READ. Die Pufferung wird nicht benutzt.

[Top]

Satz sequentiell schreiben

int ewrite( EFILE *file, void *buffer, int len );

Die Funktion schreibt einen Datensatz in eine geöffnete Datei. Wurde die Datei mit OPEN_BUFFERDED oder OPEN_BUFFERED_OUTPUT geöffnet, weden erst bis zu 4096 Bytes gespeichert, bevor die Daten an das NonStop-System übertragen werden. Tritt beim Schreiben ein Fehler auf, ist nicht mehr feststellbar bei welchen Satz das geschehen ist. Für den speziellen Fall doppelter Sätze in strukturierten Dateien erzwingt OPEN_FORCE_UPDATE einen Update auf den entsprechenden Satz. Ein Fehler wird dann nicht gemeldet.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Satz updaten

int ewriteupdate( EFILE *file, void *buffer, int len, int unlock );

Die Funktion arbeitet analog zu ewrite, benutzt aber die Systemfunktion WRITEUPDATE statt WRITE. Die Pufferung wird nicht benutzt.

[Top]

Satz mit Prompt schreiben

int ewriteread( EFILE *file, void *buffer, int writelen, int readlen );

Die Funktion kombiniert einen Schreib- mit einem Lesezugriff und ist für Prozesse oder Terminals gedacht. Die Pufferung wird nicht benutzt.

Parameter

Rückgabewert

Die Länge der Antwort oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Positionieren auf einen Key

int eseek( EFILE *file, void *keyvalue,
           int keyspec, int keylen, int cmplen,
           unsigned mode );

Die Funktion positioniert den Schreib- und Lesezeiger einer strukturierten Datei mit einem primary oder alternate Key.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Positionieren auf eine relative Position oder Edit-Zeile

long elseek( EFILE *file, long value, unsigned mode );

Die Funktion positioniert mit Hilfe der Funktion POSITION auf eine Byteposition innerhalb drer Datei. Bei Edit-Dateien erfolgt die Positionierung mit der C-Funktion edlseek auf das tausendfache einer Zeilennummer.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Position ermitteln

long eltell( EFILE *file );

Die Funktion liefert die Dateiposition einer geöffneten Datei zurück. Nicht alle Dateitypen unterstützen diese Funktion.

[Top]

Locking

int elockfile( EFILE *file );

Die Funktion lockt eine komplette Datei.

int eunlockfile( EFILE *file );

Die Funktion gibt alle Locks einer Datei frei.

int eunlockrecord( EFILE *file );

Die Funktion den Locks auf den aktuellen Record einer Datei frei.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Setmode und Control

int esetmode( EFILE *file, int code, int p1, int p2, int *pold );

Die Funktion führt einen SETMODE-Aufruf durch.

int econtrol( EFILE *file, int code, int p1 );

Die Funktion führt einen CONTROL-Aufruf durch.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Löschen und Anlegen von Dateien

char *epurge( HOST *host, char *filename );

Die Funktion löscht eine NonStop-Datei.

char *ecreate( HOST *host, char *filename, int type, int code,
               int recsize, int pext, int sext, int maxextents );

Die Funktion legt eine NonStop-Datei an. Es können einige Parameter für strukturierte Dateien gesetzt werden. Primary oder alternate Keys und partitionierte Dateien werden von dieser Funktion nicht unterstützt. Benutzen Sie dazu die Werkzeuge auf dem NonStop-System. Strukturierte Dateien werden als ENTRY-SEQUENCED-Dateien erzeugt.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Datei-Informationen ermitteln

char *einfo( HOST *host, char *filename,
             FILEDATE *timestamp, long *size, int *code, int *type,
             int *recsize, char *security );

Die Funktion liefert einige Dateiattribute zurück.

Parameter

Rückgabewert

Der voll qualifizierte Dateiname.

Die FILEDATE-Struktur

typedef struct _filedate {
    int year;
    int month;
    int day;
    int hour;
    int minute;
    int second;
} FILEDATE;

[Top]

Volume wechseln

char *evolume( HOST *host, char *volume );

Die Funktion wechselt das Default-Volume für nicht voll qualifizierte Dateinamen. Nach dem Verbindungsaufbau gilt das Default-Verzeichnis des angemeldeten Benutzers.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Timestamp umrechnen

short *econtime( HOST *host, char *timestamp, short *result );

Die Funktion rechnet einen 48-Bit-Timestamp in einen Array von Zahlen um, die das Datum in Jahre bis Bruchteilen einer Sekunde darstellen. Es wir der CONTIME-Aufruf des NonStop-Systems benutzt.

Parameter

Rückgabewert

Zeiger auf result. Bei Fehlern NULL.

[Top]

Transaktionssteuerung

int etransact( HOST *host, int type );

Die Funktion steuert TMF-Transaktionen. Zu jeder Hostverbindung kann eine Transaktion offengehalten werden.

Parameter

Rückgabewert

OK oder NOT_OK. Bei NOT_OK steht die Fehlernummer in errno.

[Top]

Fehlertext ermitteln

char *estrerror( int error );

Die Funktion liefert einen Text zu einer Fehlernummer. Dieser wird bei NonStop-Fehlern durch Aufruf des Programmes ERROR ermittelt und kann mehrere Zeilen enthalten.

Parameter

Rückgabewert

Zeiger auf den Fehlertext.

[Top]


Defines

int eloaddef( char *cmd );

Defines der Form "=NAME" können mit dieser Methode gesetzt werden. Das Argument ist ein Befehl aus folgender Liste:

DELETE DEFINE **

Alle Defines löschen.

DELETE DEFINE =<name>

Einzelnes Define löschen.

ADD DEFINE =<name>, <attribut> <wert>, ...

Define hinzufügen (oder ändern, wenn es existiert).

ALTER DEFINE =<name>, <attribut> <wert>, ...

Define ändern.

[OBEY] <Dateiname>

Die Befehle in <Dateiname> auf dem Host werden ausgeführt. Sie müssen der obigen Syntax folgen. Der Befehl OBEY kann auch weggelassen werden. OBEY kann auch rekursiv in der Datei vorkommen.

LOADINFO <Dateiname>

Analysiere die Ausgabe des TACL-Befehls
"INFO/OUT <Dateiname>/ DEFINE"
setze die entsprechenden Defines.

TACL <Befehl>

Der Befehl wird (via system) ausgeführt. Danach wird ein INFO DEFINE Befehl abgesetzt und dessen Ausgabe wie oben analysiert. Das erlaubt zum Beispiel die Verwendung von TACL-Segment-Files.



[Top]

Pseudodateien

Die Methoden zum Öffnen und Lesen von Dateien erlauben die Verwendung von zwei Pseudo-Dateien: $DEFINES$ zum Lesen der aktuell gesetzten Defines und $FILES$ zum Lesen von Datei- oder Prozessnamen. Die Zeilen sind mit Linefeed getrennt.

Datei

Beispielausgabe (1. Zeile ist Kommentar)

$DEFINES$

 
<----- Name (24) ------> <Klasse> <Attri> <----------- Wert (34) ---------->
=CTYPEH                  MAP      FILE    \GZE.$SYSTEM.SYSTEM.CTYPEH
=GNSCTLG                 CATALOG  SUBVOL  \GZE.$DEV06.GNSCTLGL

$FILES$

 
<----------- Name (34) ----------> DevTyp SubDev ObjTyp FilTyp FilCod
\GZE.$DEV03.CUBERSQL.TESTFILE           3     39      0      2   7890
\GZE.$DEV03.CUBERSQL.TESTIN             3     39      0      0    101
\GZE.$DEV03.CUBERSQL.TESTTAB            3     39      2      3      0



Die Informationen können mit Hilfe der eseek-Methode eingeschränkt werden.

Datei

Key-Specifier

Bedeutung

$DEFINES$

DEFINES_KEY_NAME

Der Define-Name muss mit den Key anfangen.

$DEFINES$

DEFINES_KEY_CLASS

Der CLASS-Name muss mit den Key anfangen.

$DEFINES$

DEFINES_KEY_ATTR

Der Attribut-Name muss mit den Key anfangen.

$DEFINES$

DEFINES_KEY_VALUE

Der Attribut-Wert muss mit den Key anfangen.

$FILES$

0

Der Key hat mehrere Felder, die durch Space, Tab oder die folgenden Zeichen getrennt werden: ",;:".

  1. Pattern mit "*" und "?";

  2. Auflösung: -1 (Node) bis 2 (Name), Default ist Node;

  3. Devicetype (3: Disk), Default ist alle;

  4. Subdevice, Default ist alle;

  5. Objecttype (0: File, >0: SQL);

  6. Filetype (siehe EFileInfo);

  7. Filecode (z. B. 101: Editfile).

Ein "*" setzt den Default. Parameter am Ende können weggelassen werden. Die Parameter 3 und 4 können mit "~" anfangen, um sie zu negieren. Die Parameter 5 bis 7 erlauben einen Vergleichsoperator: "=~<>".

Beispiel: "\\GZE.$*.GANSDB*L.* -1 3 * >0" findet alle SQL-Objekte in den entsprechenden Subvolumes und gibt den Node mit aus.



[Top]

TACL-Befehle

int esystem( char *command );

Diese Methode erlaubt die Ausführung beliebiger TACL-Kommandos. Der Implementierung liegt die Funktion system der C-Bibliothek zugrunde. Diese startet beim ersten Aufruf einen TACL-Prozess mit $RECEIVE als IN und ohne OUT-File. Dieser TACL startet weder TACLLOCL noch TACLCSTM, sie können dies aber selber nachholen. Dem Prozess werden dann alle weiteren system-Aufrufe übergeben.

Es bietet sich an, alle Programme mit expliziter OUT-Datei zu starten und diese Datei dann per API zu lesen.

[Top]