invoke()

Die Systemfunktion 'javaLib.invoke()' ruft eine Methode für ein lokales Java™-Objekt oder eine lokale Java-Klasse im EGL-Java-Objektbereich auf und kann einen Wert zurückgeben.

Weitere Informationen zum EGL-Java-Objektbereich, in dem 'javaLib.invoke()' und ähnliche Funktionen ausgeführt werden, finden Sie im Abschnitt zum Thema 'EGL-Basiselemente zu Java zuordnen'. EGL verwaltet diese Methode für Java-Zugriff zwecks Kompatibilität mit früheren Versionen. Verwenden Sie für neuen Code die leistungsfähigere ExternalType-Syntax. Weitere Informationen finden Sie in 'ExternalType (Abschnitt)'.

Syntax

  javaLib.invoke(
    Kennung_oder_Klasse javaObjIdOrClass in,
    Methode STRING in
    {, Argument anyEglPrimitive in})
  returns (Ergebnis anyJavaPrimitive)
Kennung_oder_Klasse
Jede der folgenden Entitäten kann hier als Argument verwendet werden:
  • Eine Java-Objekt-ID (objID) zum Aufrufen einer Methode für ein Objekt im Java-Objektbereich.
  • Eine Zeichenfolge zum Aufrufen einer Methode für eine Klasse (eine statische Methode). EGL schneidet Einzel- und Doppelbyteleerzeichen am Anfang und Ende des Argumentwertes ab. Bei der Angabe des Wertes muss die Groß-/Kleinschreibung beachtet werden.

Ihr Code kann erst dann eine Methode für ein Objekt aufrufen, wenn Sie eine Kennung für das Objekt erstellt haben. Eines der nachstehenden Beispiele veranschaulicht dies anhand von 'java.lang.System.out' bezogen auf ein PrintStream-Objekt.

Methode
Der Name der aufzurufenden Methode. Bei der Angabe dieses Namens muss die Groß-/Kleinschreibung beachtet werden.

Bei der Eingabe kann es sich um eine beliebige Variable oder einen beliebigen Ausdruck handeln, die/der mit dem Typ STRING zuordnungskompatibel ist. Einzel- und Doppelbyteleerzeichen werden am Anfang und Ende der Zeichenfolge abgeschnitten.

Argument
Ein an die Methode übergebener Wert.

Es gelten die Regeln für die Java-Typenkonvertierung. Möglicherweise ist eine Umsetzung erforderlich; Informationen hierzu enthält das Thema 'EGL-Basiselemente zu Java zuordnen.' Um einen Verlust an Genauigkeit zu vermeiden, sollte eine EGL-Variable FLOAT für einen Java-Datentyp 'double' und eine EGL-Variable SMALLFLOAT für einen Java-Datentyp 'float' verwendet werden. Bei Verwendung eines der anderen EGL-Typen kann es zu einem Rundungsfehler kommen.

Ein Wert eines externen EGL-Typs ist gültig, wie nachfolgend gezeigt:
SharedResourcePowerServer srps = JavaLib.getSharedResourcePowerServer();
JavaLib.invoke("anObject" as "objID:java", "aMethod", srps);

Der Speicherbereich im aufrufenden Programm wird unabhängig von den Aktionen der Methode nicht geändert.

Ergebnis
Das Ergebnisfeld (sofern vorhanden) empfängt einen Wert von der lokalen Java-Methode.

Wenn die lokale Java-Methode einen Wert zurückgibt, ist das Ergebnisfeld optional.

Es gilt Folgendes:

  • Wenn es sich bei dem zurückgegebenen Wert um den Typ 'BigDecimal', 'BigInteger', 'byte', 'short', 'int', 'long', 'float' oder 'double' handelt, muss das Ergebnisfeld ein Feld eines numerischen Datentyps sein. Die Merkmale des Felds brauchen nicht dem Wert zu entsprechen. So kann beispielsweise ein Wert des Typs 'float' in einem Ergebnisfeld gespeichert werden, das ohne Dezimalstellen deklariert ist. Details zur Handhabung von Überläufen finden Sie unter 'handleOverflow' und 'overflowIndicator'.
  • Wenn der zurückgegebene Wert ein boolescher Wert ist, muss das Ergebnisfeld ein Feld eines numerischen Basiselementtyps sein. Der Wert 1 steht für 'true' (wahr), der Wert 0 steht für 'false' (falsch).
  • Wenn der zurückgegebene Wert eine Bytefeldgruppe ist, muss das Ergebnisfeld ein Feld vom Typ HEX sein. Details zu abweichenden Längen finden Sie im Thema 'Zuordnungen'.
  • Wenn der zurückgegebene Wert den Typ 'String' oder 'Char' aufweist, muss das Ergebnisfeld ein Feld vom Typ CHAR, DBCHAR, MBCHAR, STRING oder UNICODE sein:
    • Wenn das Ergebnisfeld vom Typ MBCHAR, STRING oder UNICODE ist, ist der zurückgegebene Wert immer angemessen.
    • Wenn das Ergebnisfeld vom Typ CHAR ist, können Probleme auftreten, wenn der zurückgegebene Wert Zeichen enthält, die DBCHAR-Zeichen entsprechen.
    • Wenn das Ergebnisfeld vom Typ DBCHAR ist, können Probleme auftreten, wenn der zurückgegebene Wert Unicode-Zeichen enthält, die Einzelbytezeichen entsprechen.

    Details zu abweichenden Längen finden Sie im Thema 'Zuordnungen'.

  • Wenn die lokale Java-Methode keinen Wert oder eine Null zurückgibt, gilt Folgendes:
    • Es treten keine Fehler auf, wenn kein Ergebnisfeld vorhanden ist.
    • Zur Laufzeit tritt ein Fehler auf, wenn ein Ergebnisfeld vorhanden ist. Dies ist der später erläuterte Fehler 00001004.

Beispiel

Im folgenden Beispiel ist die Umsetzung in den Java-Typ 'objID' (mithilfe des Operators 'as') erforderlich, mit Ausnahme wie angegeben:
  // Konstruktor der
Java-Klasse 'Date' aufrufen und
  // das neue Objekt der Kennung 'date' zuordnen
  javaLib.storeNew("date" as "objID:java", "java.util.Date");

  // Methode 'toString' des neuen Objekts 'Date' aufrufen
  // und die Ausgabe ('today's date' für heutiges Datum) zur Zeichenvariablen 'charVar' zuordnen
  charVar = javaLib.invoke("date" as "objID:java", "toString" );

  // Zuordnen des Standardausgabestroms der 
  // Java-System-Klasse zur Kennung 'systemOut'
  javaLib.storeField("systemOut" as "objID:java", "java.lang.System", "out" );

  // Methode 'println' des Ausgabedatenstroms aufrufen 
  // und 'today's date' ausgeben
  javaLib.invoke("systemOut" as "objID:java", "println", charVar );
Die Verwendung von 'java.lang.System.out' als erstes Argument in der vorherigen Zeile ist nicht gültig, da das Argument entweder eine bereits vorhandene Kennung im Objektbereich oder ein Klassenname sein muss. Das Argument kann nicht auf ein statisches Feld verweisen.

Hinweise zu Fehlern

Ist die Programmeigenschaft 'v60ExceptionCompatibility' nicht oder auf NO gesetzt, führt eine Ausnahmebedingung dazu, dass EGL eine Ausnahmebedingung vom Typ 'JavaObjectException' auslöst. Andere Fehler führen dazu, dass EGL eine Ausnahmebedingung vom Typ 'RuntimeException' auslöst.

Ist die Programmeigenschaft 'v60ExceptionCompatibility' auf YES gesetzt, kann ein Fehler während der Verarbeitung von 'javaLib.invoke()' dazu führen, dass 'sysVar.errorCode' auf einen in der nächsten Tabelle aufgeführten Wert gesetzt wird.

Tabelle 1. Fehlercodewerte (errorCode) für 'invoke()'
Wert in 'sysVar.errorCode' Beschreibung
00001000 Es wurde eine Ausnahmebedingung durch eine aufgerufene Methode oder infolge einer Klasseninitialisierung ausgelöst.
00001001 Das Objekt ist leer (null), oder die angegebene Kennung ist nicht im Objektbereich vorhanden.
00001002 Eine öffentliche Methode, ein öffentliches Feld oder eine öffentliche Klasse mit dem angegebenen Namen ist nicht vorhanden oder kann nicht geladen werden.
00001003 Der EGL-Basiselementtyp stimmt nicht mit dem in Java erwarteten Typ überein.
00001004 Die Methode hat Null oder keinen Wert zurückgegeben, oder der Wert eines Feldes war null.
00001005 Der zurückgegebene Wert entspricht nicht dem Typ der Rückkehrvariablen.
00001006 Die Klasse einer Argumentumsetzung in null konnte nicht geladen werden.
00001007 Bei dem Versuch, Informationen zu einer Methode oder einem Feld abzurufen, wurde eine Ausnahmebedingung vom Typ 'SecurityException' oder 'IllegalAccessException' ausgelöst. Oder es wurde versucht, den Wert eines als 'final' deklarierten Feldes zu setzen.
00001009 Anstelle eines Klassennamens muss eine Kennung angegeben werden. Die Methode oder das Feld ist nicht statisch.

Feedback