Verwenden Sie diese Task, um eine Interaktion zwischen den APIs für abgehende Anforderungen und dem externen Adressraum oder Subsystem zu erstellen.
Vorbereitende Schritte
Stellen Sie eine Verbindung mit einem externen Adressraum oder Subsystem her. Verwenden Sie dazu die Beschreibung im Artikel
"Optimierte lokale Adapter für den Aufruf eines externen Adressraums oder Subsystems über eine Anwendung von
WebSphere Application
Server for z/OS verwenden".
Vorgehensweise
- Optional: Starten Sie eine lokale Transaktion des Ressourcenmanagers (RMLT, Resource Manager
Local Transaction), wenn Sie eine CICS-Server-Task (Customer Information Control
System) verwenden, die Transaktionen unterstützt. Zur Verwendung einer CICS-Server-Task, die Transaktionen unterstützt, wird das Schlüsselwort
TXN=Y beim Starten der Server-Task verwendet. Sie können eine lokale Transaktion des Ressourcenmanagers
starten, um mehrere Interaktionen in einer einzigen Arbeitseinheit zu kapseln.
Ihre Java EE-Anwendungskomponente (Java Enterprise Edition)
darf nicht in einer globalen Transaktion ausgeführt werden. Außerdem muss ihre
LocalTransaction-Grenze im zugehörigen Anwendungsimplementierungsdeskriptor auf "Application" gesetzt sein.
Das folgende Beispiel veranschaulicht, wie die lokale Transaktion mit dem
LocalTransaction-Objekt gestartet wird, nachdem der Implementierungsdeskriptor geändert wurde:
LocalTransaction lt = con.getLocalTransaction();
lt.begin();
Weitere Informationen zum Ändern der LocalTransaction-Einstellung in einem Anwendungsimplementierungsdeskriptor
finden Sie im Artikel "Attribute für die transaktionsorientierte Implementierung konfiguieren".
Wenn Ihre Java EE-Anwendungskomponente für die Verwendung der LocalTransaction-Grenze
ContainerAtBoundary konfiguriert ist, wird die Verbindung automatisch in einer
lokalen Transaktion des Ressourcenmanagers registriert, wenn die Verbindung abgerufen wird.
Die Arbeit ist abgeschlossen, wenn die Verwendung dieser Verbindung beim Beenden der Java EE-Anwendungskomponente automatisch beendet wird.
Wenn Ihre Java EE-Anwendungskomponente in einer globalen Transaktion gestartet wird, wird der Connector
beim Abrufen der Verbindung automatisch in der globalen Transaktion registriert.
Die Arbeit ist abgeschlossen, wenn die Verwendung dieser Verbindung beim Beenden der Java EE-Anwendungskomponente automatisch beendet wird. Im ConnectionFactory-Objekt, das zum Abrufen Ihrer Verbindung verwendet wird,
muss die angepasste Eigenschaft "RegisterName" gesetzt sein, damit die Teilnahme an einer globalen Transaktion möglich ist.
- Erstellen Sie eine Interaktion über das Verbindungsobjekt, z. B.:
Interaction int = con.createInteraction();
- Erstellen Sie ein InteractionSpecImpl-Objekt, und setzen Sie den Servicenamen in der Interaktionsspezifikation. Der Servicename beschreibt den Namen der Methode bzw. Funktion, die Sie auf dem fernen System aufrufen möchten.
Der Servicename wurde angegeben, als das ferne System die API "Host" oder eine der APIs "Receive Request" aufgerufen hat.
Wenn die CICS-Server-Task (Customer
Information Control System) verwendet wird, ist der Servicename der Name des Programms, das in CICS gestartet werden soll, z. B.:
InteractionSpecImpl isi = new InteractionSpecImpl();
isi.setServiceName("MYSERVICE");
Achtung: Wenn Sie optimierte lokale Adapter (OLA) über OTMA verwenden, ist der Servicename nicht definiert, und die
IMS-Zieltransaktion ist im Nachrichtendatenstrom angegeben.
Der Servicename kann zwar definiert werden, aber er wird nicht für OLA-Aufrufe
über OTMA verwendet. Weitere Informationen finden Sie im Artikel "Vorhandene IMS-Transaktionen mit optimierten lokalen Adaptern über
OTMA aufrufen".
- Führen Sie die Interaktion mit der erstellten Interaktionsspezifikation aus, z. B.:
int.execute(isi, null);
- Wenn Ihre Anwendung eine lokale Transaktion des Ressourcenmanagers (RMLT) verwendet, müssen
Sie die Arbeit nach Abschluss der letzten Interaktion festschreiben oder zurücksetzen. Verwenden Sie die Methoden "commit" und "rollback" im Objekt
"LocalTransaction", z. B.:
lt.commit();
Ergebnisse
Die Interaktion mit dem externen Adressraum oder Subsystem ist abgeschlossen.
Achtung: Wenn Sie eine lokale Transaktion des Ressourcenmanagers
oder globale Transaktion verwenden und die
CICS-Anwendung während der lokalen Transaktion des Ressourcenmanagers
oder globalen Transaktionen eine syncpoint-Operation aufruft, gibt die Server-Task während der
syncpoint-Operation einen BBOX-Abend-Code aus.
Dies führt zum Scheitern der syncpoint-Operation, und es wird ein ASPx-Abend-Code von
CICS generiert. Die CICS-Anwendung
muss warten, bis WebSphere Application
Server die sync-point-Operation ausführt. Dies geschieht, indem die Methode "commit" oder "rollback"
im LocalTransaction-Objekt aufgerufen oder aber zugelassen wird, dass die Java™ EE-Anwendungskomponente beendet wird.
Achtung: Wenn Sie die maximale Ausführungsdauer
für eine
CICS-Transaktion beim Import eines globalen Transaktionskontextes
oder einer lokalen Transaktion des Ressourcenmanagers in
CICS from WebSphere definieren
möchten, ändern Sie den Wert des Parameters OTSTIMEOUT in der Transaktionsdefinition, die zum Starten
der Link-Task des CICS-Link-Servers verwendet wird.
Standardmäßig lautet der Transaktionsname BBO#. Wenn die Laufzeit der
CICS-Transaktion die mit dem Parameter
OTSTIMEOUT angegebene Zeit überschreitet, wird die
CICS-Task, die die
CICS-Transaktion abnormal beendet, was
dazu führt, dass die gesamte globale Transaktion bzw. lokale Transaktion des Ressourcenmanagers
rückgängig gemacht wird.
Informationen zum Codieren des Parameters
OTSTIMEOUT in der Transaktionsdefinition finden Sie in der Veröffentlichung
"CICS Transaction Server for z/OS Resource
Definition Guide".
Wenn Ihre Java EE-Anwendungskomponente an einer
lokalen Transaktion des Ressourcenmanagers oder globalen Transaktion teilnimmt und die
Anwendung mit einem Stapelprogramm oder einem
CICS-Link-Server, der mit dem Schlüsselwort
TXN=N gestartet wurde, kommuniziert, kann die optimierte lokale Adapterverbindung keine Verbindung zum Zielprogramm
herstellen.
Das Zielprogramm kann die von der Java EE-Anwendung benötigten Transaktionsfunktionen nicht bereitstellen.
Es wird eine Ausnahme mit dem Nebencode 0xC9C24C3B angezeigt. Dieser Code gibt an, dass der Zielregistrierungsname
zwar gefunden wurde, aber nicht für Transaktionen aktiviert ist.
Nur CICS-Link-Server, die mit dem Schlüsselwort TXN=Y aktiviert werden,
können die Weitergabe von Transaktionen von
WebSphere Application
Server for z/OS unterstützen.
Beispiel
Die folgende Methode zeigt, wie eine Interaktion mit Eingabe- und Ausgabedaten als Bytefeldgruppe
(byte[]) gestartet wird:
public byte[] driveInteraction(javax.resource.cci.ConnectionFactory cf,
javax.resource.cci.Connection con,byte[] inputDataBytes),throws javax.resource.ResourceException
{
// Interaktion über die Verbindung des optimierten lokalen Adapters erstellen
javax.resource.cci.Interaction i = con.createInteraction();
// Das InteractionSpec-Objekt beschreibt den aufzurufenden Service
com.ibm.websphere.ola.InteractionSpecImpl isi = new com.ibm.websphere.ola.InteractionSpecImpl();
isi.setServiceName("MYSERVICE");
// Die Eingabedaten werden mit einem IndexedRecord-Objekt angegeben. Der erste Abschnitt im
// indexierten Datensatz enthält die Eingabedatenbytes.
javax.resource.cci.RecordFactory rf = cf.getRecordFactory();
javax.resource.cci.IndexedRecord ir = rf.createIndexedRecord(null);
ir.add(inputDataBytes);
// Die Interaktion gibt ein anderes IndexedRecord-Objekt zurück, dessen erster
// Abschnitt die Ausgabedatenbytes enthält.
javax.resource.cci.Record or = i.execute(isi, ir);
byte[] outputDataBytes = null;
if (or != null)
{
outputDataBytes = (byte[])((javax.resource.cci.IndexedRecord)or).get(0);
}
// Ausgabedaten an den Caller (Aufrufenden) zurückgeben
return outputDataBytes;
}
Die folgende Methode zeigt, wie eine Interaktion über ein von
Rational Application Developer generiertes Copybook-Record-Objekt gestartet wird:
/**
* Ein Beispiel für die Steuerung einer Interaktion des optimierten lokalen Adapters über
* eine Copybook-Zuordnungsklasse von Rational Application Developer als Eingabe
* (inputRecord) und den Empfang einer Copybook-Zuordnung von Rational Application Developer
* als Ausgabe.
*/
public javax.resource.cci.Record driveInteraction(
javax.resource.cci.Connection con,
javax.resource.cci.Record inputRecord)
throws javax.resource.ResourceException
{
// Interaktion über die Verbindung des optimierten lokalen Adapters erstellen
javax.resource.cci.Interaction i = con.createInteraction();
// Das InteractionSpec-Objekt beschreibt den aufzurufenden Service (com.ibm.websphere.ola.InteractionSpecImpl isi =)
new com.ibm.websphere.ola.InteractionSpecImpl();
isi.setServiceName("MYSERVICE");
// Das von Rational Application Developer generierte Copybook implementiert
// javax.resource.cci.Record und kann direkt an die Interaktion übergeben werden.
// Die Interaktion gibt ein IndexedRecord-Objekt zurück, dessen erster Abschnitt
// die Ausgabedatenbytes enthält.
javax.resource.cci.Record or = i.execute(isi, inputRecord);
javax.resource.cci.Record outputRecord = null;
if (or != null)
{
// In diesem Beispiel ist RADGeneratedOutputType der Name der von Rational Application Developer
// generierten Copybook-Zuordnungsklasse.
outputRecord = new RADGeneratedOutputType();
// Die Ausgabebytess werden in dem Ausgabedatensatz gespeichert, der in der
// Interaktion zurückgegeben wird, einem IndexedRecord-Objekt.
byte[] outputDataBytes =
(byte[])((javax.resource.cci.IndexedRecord)or).get(0);
// Zum Konvertieren der Ausgabebin ein anderes von Rational Application Developer generiertes Copybook
// die Methode setBytes(byte[]) dieser Klasse aufrufen. Die Klasse implementiert die
// Schnittstelle com.ibm.etools.marshall.RecordBytes.
((com.ibm.etools.marshall.RecordBytes)outputRecord)
.setBytes(outputDataBytes);
}
// Ausgabedaten an den Caller (Aufrufenden) zurückgeben
return outputRecord;
}