Index Janus/Java
API-Beschreibung


Inhalt dieses Dokuments

Der vorliegende Text beschreibt die Installation und den Gebrauch der API (Application Programming Interface) Janus/Java.

Index


Einführung

Funktionsumfang

Die vorliegende Software Janus/Java stellt eine Schnittstelle zwischen beliebigen Java-Clients und HP-NonStop-Pathway (TS/MP) dar. Sie ist als Client/Server-Paar implementiert, wobei der Client zu 100% in Java (ab Version 1.2) realisiert ist. In der vorliegenden Fassung werden folgende Funktionen unterstützt:

Die Initiative geht in dieser Konstellation immer vom Java-Client aus. Die Janus-Webanwendung erlaubt auch Serverfunktionen auf Basis der API und die Anbindung an SAP-Systeme mit RFC.

Tandem-Gatewayprozess TCPTAN

Die Kommunikation erfolgt über einen Prozess auf dem Tandemsystem, der die TCP/IP-Nachrichten in Aufrufe an das PATHSEND-Subsystem oder an einen benamten Prozess weitergibt. Der TCP/IP-LISTNER startet TCPTAN bei jeder Kommunikationsanforderung automatisch.

TCPTAN unterstützt WRITEREAD und die Transaktionssteuerung über TMF. Pathway-Server sind kontextfrei, das heißt, es gibt keine feste Beziehung vom Anwendungsprogramm (Client) zu einem definierten Serverprozess. Kontextinformationen müssen also in jeder Message mit ausgetauscht werden.

Die TCP/IP-Verbindung stellt nur den Kontext für die Transaktionssicherung zur Verfügung.

Übersicht


Installation

Installation des Tandem-Gateways TCPTAN

Der Gateway-Prozess TCPTAN muß auf dem Tandem-System installiert werden. Dazu sind Informationen in der Datei PORTCONF der TCP/IP-Konfiguration für den LISTNER einzutragen:

2000 $system.janus.tcptan

Danach ist der LISTNER-Prozess neu zu starten.

Die ausführbare Programm muß im Binärformat auf ihr NonStop-System, hier im Subvolume $SYSTEM.JANUS kopiert werden und den korrekten Filecode (700 bzw. 800) erhalten. Die Portnummer, hier 2000, kann frei gewählt werden.

Installation der Java-Klassen

Die Java-Klassen sind im Archiv janus.jar gespeichert, das dem Klassenpfad hinzugefügt werden muß. Innerhalb einer IDE wird dies normalerweise im Projekt eingetragen. Der Aufruf erfolgt mit

java -cp janus.jar MyClass

Geben sie den vollständigen Pfad der Jar-Datei an.

Sie können die Datei auch in Ihrer JVM (jre/lib/ext) installieren.

Installation von DDL2JAVA

DDL2JAVA ist ein ausführbares Programm, das im Moment nur für 32-Bit Windows-Plattformen verfügbar ist. Kopieren Sie das Programm in ein Verzeichnis in Ihrem Suchpfad. Das Programm setzt den Remote-Enscribe-Server RSQLSRV voraus, der ähnlich zu TCPTAN auf ihrem Entwicklungssystem installiert wird. Die zugehörige PORTCONF-Zeile sieht so aus:

3000 $system.janus.rsqlsrv

Gebrauch

API-Dokumentation

Die API-Dokumentation liegt im Javadoc-Format vor: Janus/Java API.

Generierung von Messages mit DDL2JAVA

In dem folgenden Beispiel sei Ihre Anwendung im Verzeichnis client mit dem Package-Namen client angelegt. Ein DDL-Dictionary mit Messages stehe auf dem Tandem-System mit der IP-Adresse tandem auf dem Subvolume $DATA.DDLDICT.

  1. Legen Sie ein Verzeichnis an, das ihre Java-Klassen enthalten soll, zum Beispiel client\msg. Der Packagename wird client.msg.

  2. Schreiben Sie ein Script nach folgendem Muster:

setlocal
set prog=c:\bin\ddl2java.exe
set opts=-uGROUP.USER -pGEHEIM -Pclient.msg -nopackages
set host=tandem:3000
set dict=$DATA.DDLDICT
cd msg

if not "%1"=="" goto single
:all
REM erzeuge alle Messages
%prog% %opts% -a %host% %dict% *

REM erzeuge alle Konstanten
%prog% %opts% -c %host% %dict% *
goto compile

:single
REM erzeuge eine Message neu
%prog% %opts% %host% %dict% %1

:compile
javac *.java

endlocal

Sie können nun durch Aufruf des Scripts alle Messages Ihres Dictionary in Java-Klassen verwandeln. In Ihrem Programm lassen sich diese nun nach dem Java-Befehl import client.msg.*; verwenden.

Tipp: Erzeugen Sie sich mit Javadoc eine Dokumentation ihrer generierten Klassen. DDL-Kommentare werden als Javadoc-Kommentare in die Quelltexte übernommen.

Die wichtigsten Funktionen

Für die folgenden Funktionen müssen sie die Packages janus.net.* und janus.util.* importieren.

Verbindungsaufbau

Zum Aufbau der Verbindung und Speichern der Verbindungsdaten legen sie ein janus.net.Connection-Objekt an:

Connection conn;

try {
conn = ConnectionFactory.create( "tandem", 2000, "$PM" );
}
catch ( CommException ce ) {
System.err.println( "Verbindungsaufbau gescheitert: " + ce.toString() );
}

Der Zugriff über die Factory ermöglicht es, bei Bedarf spezialisierte Versionen der Connection-Klasse zu erzeugen, zum Beispiel für den lokalen Einsatz innerhalb eines NonStop-Systems. Sollte die Verbindung abbrechen, kann Sie mit conn.connect() wieder hergestellt werden ohne ein neues Objekt zu erzeugen.

Connection-Pools

Alternativ können Connection-Objekte auch durch einen ConnectionPool bereitgestellt werden. Details entnehmen Sie bitte der API-Beschreibung. Sie benötigen neben dem Konstruktor für den Pool die Methoden getConnection und releaseConnection, um Verbindungen zu belegen und an den Pool zurückzugeben. Mit setIdleTime kann eine Zeit festgelegt werden, nach der unbenutzte Connections gelöscht werden. Der Serverprozess auf dem Tandem-System wird dadurch beendet.

Senden von Nachrichten

Wenn Ihre Nachricht in einer von DDL2JAVA erzeugten Message gespeichert ist, dann können Sie sie mit folgendem Aufruf von Connection.sendMessage an einen Pathway-Server senden:

try {
conn.sendMessage( "SERVER", msg, reply );
}
catch ( CommException ce ) {
// ...
}

Die Methode kennt auch noch andere Varianten die auf Arrays von Messages oder auf einfachen byte-Arrays basieren. Sie können auch einen Timeoutwert mitgeben oder den I/O im Nowait-Modus starten und dann mit conn.awaitIo(timeout) beenden oder conn.cancel() abbrechen.

Transaktionssteuerung

Sie können Transaktionen auf dem Tandem-System mit den Methoden Connection.beginTransaction, Connection.endTransaction, Connection.abortTransaction, Connection.autoCommitTransaction und Connection.singleTransaction steuern.

Zugriff auf Messages

Alle mit DDL2JAVA erzeugten Messages sind von janus.util.MessageElement abgeleitet. Diese Klasse unterstützt die gängigen mit DDL erzeugbaren Datenformate (bis auf Float und SQL-Typen) und auch Redefines und Occurs-Tabellen. Die Message wird in einem byte-Array gehalten und die einzelnen Komponenten werden bei jedem Zugriff mit get oder set-Methoden in Java-Typen umgesetzt. Dies ist flexibel, weil es eben auch die alternative Interpretation von Message-Bereichen erlaubt, aber natürlich auch aufwendig. Es empfielt sich daher, für die interne Programmierung im Client, die Message einmal zu Konstruieren bzw. auszulesen und mit den internen Typen weiterzuarbeiten.

Auf einen im DDL folgendermaßen definerten Typ Datum kann auf verschiende Weise zugegriffen werden.

DDL

def datum.
02 jahr pic 9(4).
02 monat pic 99.
02 tag pic 99.

Java

client.msg.Datum datum = new client.msg.Datum();
datum.set( "20080205" );

String dString = datum.toString();
int jahr = datum.jahr.get();
int monat = datum.monat.get();
int tag = datum.tag.get();

Der Typ Datum ist wie in COBOL ein String und kann als Ganzes gelesen und auch gesetzt werden, die einzelnen Felder lassen sich als ganze Zahlen (oder auch als Strings) manipulieren.


[Anfang]