Auf IBM i-Programme als Web-Services zugreifen: Übersicht

Mit EGL können Sie die Logik in einem aufgerufenen IBM® i-Programm oder -Serviceprogramm mittels eines externen EGL-Typs zugänglich machen. Der EGL-Generator verwendet diesen externen Typ, um einen EGL-REST-Service oder SOAP-Service zu erstellen, damit eine Anwendung, die als Serviceanforderer dient, auf die folgenden Typen von IBM i-Programmen zugreifen kann: rpgle, cbl, cblle, sqlrpgle, sqlcbl, sqlcblle.
Gehen Sie folgendermaßen vor, um auf ein IBM i-Programm zuzugreifen:
  1. Erstellen Sie einen externen Typ (Typ HostProgram).
  2. Wählen Sie im Editor für EGL-Implementierungsdeskriptoren im Abschnitt für die Serviceimplementierung diesen externen Typ aus und geben Sie weitere geeignete Informationen ein.
  3. Implementieren Sie den resultierenden Web-Service auf einem Anwendungsserver, der mit Java™ EE kompatibel ist.
  4. Codieren Sie im Anforderer eine Anweisung call für den Zugriff auf den IBM i-Code.
Ausführliche Anweisungen finden Sie unter 'Auf IBM i-Programme als Web-Services zugreifen: Details zu Tastenanschlägen'.
Der Entwurf der Datensatzabschnitte, die als Basis für die Datensätze verwendet werden, die während des Serviceaufrufs verwendet werden, ist eine komplexe Aufgabe. Sie können jedoch Rational Developer for Power Systems Software: RPG and COBOL Development Tools for IBM i verwenden. In diesem Fall können Sie mit einem Assistenten Inhalt in zwei Projekten erstellen:
  • Das Serviceprojekt, das ein Webprojekt ist, enthält die folgenden Komponenten, die zum Entwickeln des Codes für den Zugriff auf das IBM i-Programm verwendet werden:
    • Externen Typ, den Stereotyp HostProgram, der Funktionsprototypen enthält, die die Signaturen von Funktionen im betreffenden IBM i-Programm spiegeln.
    • Strukturierte EGL-Datensatzabschnitte, auf die in den Funktionsprototypen durch Parameter und Rückgabewerte verwiesen wird.
    • Implementierungsdeskriptor mit einem Eintrag, der die folgenden Details umfasst: eine URI für den Zugriff auf den Service, einen Verweis auf den externen Typ und eine Reihe von Verbindungsparametern für den Zugriff auf das Programm aus IBM WebSphere Application Server oder Apache Tomcat.
    • PCML-Datei (siehe unten).
  • Das Clientprojekt, das ein Rich-UI-Projekt ist, enthält die folgenden Komponenten, die zum Entwickeln der EGL-Rich-UI-Anwendung für den Zugriff auf den Service verwendet werden:
    • Schnittstellenabschnitt, der dem externen Typ im Serviceprojekt entspricht.
    • Gruppe von nicht strukturierten Datensatzabschnitten, auf die in den Funktionsprototypen des Schnittstellenabschnitts durch Parameter und Rückgabewerte verwiesen wird. Die Felder in diesen Datensatzabschnitten entsprechen den untergeordnetsten Feldern (Blattelementen) in den strukturierten Datensatzabschnitten.
    • Implementierungsdeskriptor mit einem Eintrag, der auf den Service zugreift.
Einige (nicht in EGL geschriebene) IBM i-Programme sind statusabhängig:
  • Ein statusabhängiges Programm behält Informationen aufrufübergreifend bei, damit der Benutzer und das Programm an einem Dialog teilnehmen können, der aus mehreren Schritten besteht.
  • Wenn Sie den Zugriff auf ein statusabhängiges Hostprogramm bereitstellen und den Implementierungsdeskriptor des Webprojekts definieren, das den externen Typ enthält, müssen Sie angeben, dass der Service ein REST-Service und kein SOAP-Service ist. Um anzugeben, dass das Hostprogramm statusabhängig ist, passen Sie den Implementierungsdeskriptor im Editor für Implementierungsdeskriptoren an, indem Sie das Kontrollkästchen Stateful auswählen.
  • Der statusabhängige Aspekt des Hostprogrammszugriffs wird durch ein Sitzungscookie ermöglicht, das vom Service bereitgestellt wird. Das Cookie enthält eine Kennung für die HTTP-Sitzung. Wenn Sie in der Rich-UI arbeiten, geben Sie das Sitzungscookie beim Deklarieren einer Variablen an, die auf dem Schnittstellenabschnitt basiert.
  • Nachdem Sie den Service zum letzten Mal in Ihrer Anwendung aufgerufen haben, rufen Sie die Funktion serviceLib.endStatefulServiceSession() auf, um die Laufzeitressourcen freizugeben.
  • Anmerkung: Die Ausführung oder das Debug eines Codes, der Operationen für HTTP-Sitzungen erforderlich macht, kann erst nach dem Implementieren des Codes auf einem Anwendungsserver erfolgen.

Die Details über die HTTP-Sitzung werden in der Servicezugriffsvariablen beibehalten. Die Lebensdauer der Sitzung des Anforderers ist davon abhängig, wo die Variable deklariert ist. Ist die Variable beispielsweise in einem Funktionsaufruf deklariert, bleibt die Sitzung des Anforderers so lange bestehen, wie sich die Funktion im Geltungsbereich befindet. Ist die Variable in einer Bibliothek deklariert, bleibt die Sitzung des Anforderers erhalten, bis die Bibliothek den Geltungsbereich verlässt. Falls Sie auf einen statusabhängigen EGL-REST-Service zugreifen, deklarieren Sie die Variable so, dass sie den Geltungsbereich nicht vorzeitig verlässt.

Beispiel: Externer Typ für den Zugriff auf ein IBM i-Programm

Das folgende Beispiel zeigt einen externen Typ, der den Zugriff auf ein IBM i-Programm ermöglicht.
ExternalType GETREC type HostProgram {platformData=[@i5OSProgram{ programName="GETREC", 
                         programType=NATIVE, isServiceProgram=false, libraryName="*LIBL"}]}
   function GETREC(CUST CUSTa10, EOF char(1), COUNT decimal(2,0)){ hostName="GETREC"};
end
Die Eigenschaft platformData akzeptiert eine Feldgruppe. In diesem Beispiel hat die Feldgruppe einen einzigen Eintrag für die komplexe Eigenschaft @i5OSProgram. Die Eigenschaftsfelder für @i5OSProgram sind Folgende:
programName
Der Name des Programms unter IBM i. Standardwert ist der Name des externen Typs.
programType
Entweder 'EGL' (für ein in EGL geschriebenes Programm) oder 'native' (für ein in COBOL oder RPG geschriebenes Programm). Standardwert ist NATIVE.
isServiceProgram
Ein boolescher Wert, der angibt, ob es sich bei dem Programm um ein IBM i-Serviceprogramm handelt. Der Standardwert ist false.
libraryName
Die IBM i-Bibliothek. Der Standardwert ist *LIBL.

Die Eigenschaft hostName ist für einen Funktionsprototyp verfügbar und gibt den Namen der Programmfunktion an. Standardwert ist der Name des Funktionsprototyps.

Datentypen in IBM i- und EGL-Datensatzfeldern

Die Workbench konvertiert die IBM i-Datentypen aus der Hostquelle in eine PCML-Definition. Anschließend verwendet die Workbench diese Definition, um den externen Typ und die Datensätze zu erstellen.

Die PCML-Datei wird aus zwei Gründen beibehalten. Erstens können Sie die Datei aktualisieren und als Eingabe bei nachfolgenden Ausführungen des Assistenten verwenden. Sie könnten beispielsweise eine PCML-Definition zusammenstellen, die den Eingangspunkten in mehreren Programmen entspricht. Falls Sie diese Definition als Eingabedatei verwenden, kann der vom Assistenten erstellte externe Typ alle Eingangspunkte wiedergeben. Zweitens können die IBM Technical Support-Mitarbeiter die beibehaltene PCML-Datei bei Bedarf als Debugging-Tool verwenden.

In der folgenden Tabelle sind die korrespondierenden Datentypen in strukturierten IBM i-Datensätzen und in strukturierten EGL-Datensätzen aufgeführt.

Tabelle 1. Korrespondierende Datentypen in strukturierten IBM i-Datensätzen und strukturierten EGL-Datensätzen
IBM i Regeln EGL-Datentyp im externen EGL-Typ
char charType = Einzelbyte CHAR (PCML-Länge)
charType = Doppelbyte UNICODE (PCML-Länge)
int 2 Byte mit Vorzeichen Genauigkeit != 16, Länge=2 SMALLINT
2 Byte ohne Vorzeichen Genauigkeit = 16, Länge = 2 INT
4 Byte mit Vorzeichen Genauigkeit != 32, Länge = 4 BIGINT
4 Byte ohne Vorzeichen Genauigkeit = 32, Länge = 4 BIGINT
8 Byte mit Vorzeichen Länge = 8 BIGINT
packed     DECIMAL (PCML-Länge, PCML-Genauigkeit)
zone     NUM (PCML-Länge, PCML-Genauigkeit)
float   Länge = 4 SMALLFLOAT
  Länge = 8 FLOAT
byte     HEX (PCML-Länge * 2)

Möglicherweise müssen Sie die von der Workbench erstellten EGL-Datensatzfelder aktualisieren, die IBM i-Typen entsprechen, welche nicht von EGL unterstützt oder nicht von PCML konvertiert werden. Details über PCML sind online im Information Center von IBM WebSphere Development Studio Client for iSeries unter der Adresse http://publib.boulder.ibm.com/infocenter/iadthelp/v7r0/topic/com.ibm.etools.iseries.webtools.doc/topics/rdtcattr.html verfügbar.

Für einige Hoststrukturen gibt es keine korrespondierenden EGL-Typen. Beispiel für COBOL:
01 P1 PIC 9(5) USAGE BINARY.
01 P2.
       02 P2A PIC X(5) OCCURS 1 to 10 TIMES 
                       DEPENDING ON P1.

Datentypen in EGL-Datensatzfeldern

In der folgenden Tabelle sind die korrespondierenden Datentypen für strukturierte und nicht strukturierte Datensätze aufgeführt. Möglicherweise müssen Sie die von der Workbench erstellten nicht strukturierten Datensatzfelder aktualisieren, die den Typ HEX oder INTERVAL besitzen.

Tabelle 2. Korrespondierende Datentypen in strukturierten und nicht strukturierten Datensätzen
Datentyp im strukturierten Datensatz Datentyp im nicht strukturierten Datensatz
BOOLEAN BOOLEAN
CHAR, DBCHAR, MBCHAR, STRING, UNICODE STRING
HEX HEX
DATE DATE
TIME TIME
TIMESTAMP TIMESTAMP
INTERVAL INTERVAL
DECIMAL, BIN(length), BIGINT, INT, MONEY, NUM, SMALLINT, SMALLFLOAT Korrespondierende numerische Typen
BIN(length, decimalPlaces), wobei gilt: decimalPlaces > 0 NUM(length, decimalPlaces)
NUMC(length, decimalPlaces) NUM(length, decimalPlaces)
PACF(length, decimalPlaces) NUM(length, decimalPlaces)