EXEC TAA INTERN

SYNTAX:

EXEC TAA INTERN OM
OM-OPERATION = (<variable> | <literal>) 
OM-OBJECT = (<variable> | <literal>) 
[ OM-POSITION = (<variable> | <literal>) ]
[ OM-POSTYPE = (<variable> | <literal>) ]
[ OM-INDEX = (<numeric variable> | <numeric literal>) ]
[ INFO-ITEMS = (<variable> ) ] 
[ INFO-LENGTH = (<variable> ) ]
[ INFO-TYPE = (<variable> ) ] 
[ INFO-CLASS = (<variable> ) ]
[ INFO-SCHWEBE = (<variable> ) ]
END-EXEC

Hinweise:

• Nutzbar ist die Syntax mit den Operationen NEW, GET, PUT, DELETE, ADD, INSERT, RESETCONTENTS, GETINFO. Nicht unterstützt sind prinzipiell alle Operationen, die mehr als ein Objekt benötigen, z.B. ADDLIST, COPY, SORT. Außerdem sind DECLARE, CHECK und DUMP über die INTERN-Syntax nicht unterstützt.
• Alle Informationen für die OM-Anweisung werden als OM-… übergeben; Informationen, die die OM-Anweisung zurückliefert, stehen in den mit INFO-… angegebenen Variablen.
• Wenn Operation, Objekt, Position und Positionstyp als Variable angegeben werden, muß der Inhalt der Variablen in Großbuchstaben bestückt werden, da sonst in Evaluates (teils im generierten Code, teils in taaim.dll) die Strings nicht erkannt werden. Bei Angabe von Literalen erfolgt die Konvertierung im Generator.
• Wenn für das Objekt eine Variable angegeben ist, wird eine EVALUATE-Struktur über alle in dem Modul bekannten Objekte erzeugt, um zur Laufzeit das betreffende Objekt herausfinden zu können. Dies kann bei vielen Objekten zu einer erheblichen Codemenge führen, vor allem wenn mehrere INTERN OM-Anweisungen benutzt werden.
• Wenn als Operation GETINFO, RESETCONTENTS, DELETE oder INSERT angegeben ist, ermittelt der Generator daraus den 3-stelligen OpCode für TAAIM. Wenn die Operation als COBOL-Variable angegeben ist, erfolgt die Umsetzung zur Laufzeit, sonst bei der Generierung.
• Die INFO-Werte werden nur aus der TX-TAA abgeholt, wenn die Operation GETINFO war. Ansonsten werden die Inhalte der dafür zugeordneten Variablen nicht verändert.
• Als Empfangsfelder für INFO-… müssen COBOL-Variablen angegeben werden.
• Als OM-Postype muß bei Listenobjekten die Art der Positionierung angegeben werden:
  • Ist ein numerisches Literal als Index angegeben, ist der Positionstyp „ABS“ (absolut),
  • wird eine Variable als Index angegeben, ist der Positionstyp „DYN“ (dynamisch),
  • wird über FIRST/NEXT/CURRENT usw. positioniert, ist der Positionstyp „REL“ (relativ).
• Bei relativer Positionierung muß die Position in OM-POSITION angegeben werden, bei absoluter oder dynamischer Positionierung in OM-INDEX.
• Der Index für eine absolute Positionierung muß entweder als numerische Variable oder als (numerische!) COBOL-Variable angegeben werden; andere Angaben führen zu Laufzeitfehlern.

Warnung:

Wenn ungültige Angaben für eine Operation gemacht werden (z.B. GET FIRST auf ein Record-Objekt, oder ABS-Positionstyp mit Positionsangabe „FIRST“, oder Kleinbuchstaben), wird dies bei Generierung und Compilierung nicht erkannt. Wie sich dies zur Laufzeit auswirkt, ist nicht definiert. Da die Laufzeit-Infrastrukturen bisher davon ausgehen konnten, daß die Angaben in gewissem Umfang geprüft sind, werden dort keine entsprechenden Überprüfungen mehr vorgenommen. Es kann daher zu Laufzeitfehlern kommen, aber auch zu einer stillschweigenden Nicht-Ausführung des Befehls; die Reaktion kann unter verschiedenen Laufzeitumgebungen unterschiedlich sein. Es ist deshalb wichtig, sicherzustellen, daß nur sinnvolle Operations/Objekt-Kombinationen übergeben werden.

Syntax:

EXEC TAA INTERN SORT 
     OM-OBJECT=<NAME>
     SORTFIELDTABLE = <TABELLENNAME>
     SORTFIELDCOUNT =  {<num. variable> | <num. literal> }
     [ SORTORDER =  {0 | 1 | <num. variable> } ]
 END-EXEC

Die dynamische Sortierung ist ein Sonderfall der OM-Intern-Aufrufe. Sie bietet die Möglichkeit, die Kriterien, nach denen ein Objekt sortiert werden soll, zur Laufzeit festzulegen.

• OM-OBJECT und SORTFIELDTABLE sind als alphanumerische Literale ohne Anführungszeichen anzugeben.
• SORTORDER und SORTFIELDSCOUNT sind enweder als numerische Literale (ohne Anführungszeichen) oder als COBOL-Variablen anzugeben.
• Die Angabe SORTORDER ist optional; Default ist 0 (= ASCENDING), 1 steht für DESCENDING. Die Angabe an dieser Stelle bezieht sich auf die gesamte Sortierung, für einzelne Felder kann ein abweichende Reihenfolge festgelegt werden.

Als Tabelle für die Sortierkriterien (Angabe SORTFIELDTABLE) muss im Programm eine Tabelle angelegt werden, die wie folgt aufgebaut ist

sample.cbl

01 <name>.
     02 <name-rec> OCCURS <anzahl>.
         05 FIELDNAME   PIC X(24).
         05 SORTORDER   PIC S9(9) COMP.

Diese Tabelle muss im Programm mit den Namen der Sortierfelder und der für das jeweilige Feld geltende Sortierreihenfolge bestückt werden. Dabei ist zu beachten:

• <name> ist der Name der Tabelle und frei wählbar.
• Auch <name-rec> ist ein frei wählbarer Name. Die Stufe ist notwendig, da nicht in allen Umgebungen OCCURS-Angaben auf Stufe 1 zulässig sind.
• Die Namen FIELDNAME und SORTORDER sind zu übernehmen, sie werden so im Generat referenziert, z.B. „FIELDNAME OF <tabelle> (<index>)“..
• Das Feld FIELDNAME muss alphanumerisch sein. Die Länge ist frei wählbar, jedoch können kürzere Felder u.U. nicht alle Feldnamen aufnehmen. Wenn es länger als 24 Stellen ist, werden nachfolgende Stellen abgeschnitten.
• Das Feld SORTORDER muss numerisch sein. Inwiefern andere numerische Formate möglich sind, ist von der Laufzeitumgebung abhängig.
• Gülige Werte für SORTORDER sind: 0 = aufsteigend/ascending, 1 = absteigend/descending. Wird ein anderer Wert angegeben, gilt der Default (Ascending).
• Die Occurs-Klausel muss mindestens dem in SORTFIELDSCOUNT angegebenen Wert entsprechen, sonst kommt es zu Laufzeitfehlern.
• Die maximale Anzahl von Feldern, die übergeben werden kann, ist 20. Wenn die Tabelle mehr als 20 enthält, werden die überzähligen Felder nicht berücksichtigt.

Achtung: Wenn die Tabelle einen Feldnamen enthält, der in dem Objekt nicht vorkommt, wird eine Condition mit Severity Warning ausgegeben; es wird keine Sortierung durchgeführt oder das Sortierergebnis ist undefiniert.

Syntax:

EXEC TAA INTERN MODULECALL 
  MODULENAME =   {<variable> | <literal>}
  MODULEEVENT =   {<variable> | <literal> }
  MODULEAPPL = "<literal>" 
  MODULETYPE = "<literal>" 
  [BYVALUEn = TRUE]
  PARMn = "<literal>" 
  ARGn = "<literal>" 
  [...]
END-EXEC

Zu beachten:

• Name, Event, Typ und Appl müssen angegeben werden, aber in beliebiger Reihenfolge.
• Die gerufenen Module müssen den gleichen Typ haben, und dieselben Parameterobjekte erwarten. Außerdem müssen sie zur selben Anwendung gehören.
• Bei den Parameterzuweisungen muß die Reihenfolge stimmen (Parm1, Arg1, Parm2, Arg2, usw.), und die Angaben müssen paarig sein (keine Abkürzung bei Namensgleichheit).
• Byvalue1 etc. kann optional vor Parm1 etc. angegeben werden. Der zugewiesene Wert ist dabei irrelevant, die Tatsache, dass Byvalue angegeben ist, führt zur By-Value-Zuweisung des Arguments. Ist Byvalue nicht angegeben, erfolgt die Zuweisung By Reference.

Daraus wird generiert:

Daraus wird generiert:

• Eine Evaluate-Struktur, in der der zu dem Langnamen gehörige Kurzname des Moduls ermittelt wird.
• Anschließend wird der PUT für die betroffenen Objekte generiert. Da wir nicht wissen, wie die verschiedenen Module die Objekte verwenden, geht die Generierung immer von „MOD“ aus, d.h. alle übergebenen Objekte werden vorher an den OM übergeben.
• Darauf folgt der ganz normale Code für einen Modulaufruf.
• Anschließend wird in einer zweiten Evaluate-Struktur der zurückgereichte Zustand für das aufgerufene Modul gesetzt.
• Nach dem erfolgten Call werden die Parameterobjekte (alle!) wieder vom Objekt-Manager gelesen, ebenso die globalen Objekte, sofern vorhanden.

Es ist auch möglich, für MODULENAME oder MODULEEVENT einen String (in Anführungszeichen) anzugeben, um entweder ein Modul mit verschiedenen Events, oder mehrere Module mit gleichem Event aufrufen zu können. Das ist natürlich auch durch entsprechende Bestückung von COBOL-Variablen erreichbar, aber: Wenn der Modulname ein String ist, wird kein Evaluate generiert, nur einfache Moves.

Die Evaluates berücksichtigen alle Module, die in der Aufrufstruktur definiert sind, und die dem angegebenen MODULTYPE entsprechen.

Auswirkung, wenn ein Modul aufgerufen wird, das nicht in der Aufrufstruktur definiert ist: Auf dem PC erfolgt die Überprüfung der Aufrufstruktur zur Laufzeit, sodass dort der Fehler entsprechend gemeldet wird. Auf dem Host zu wird es zu einem Fehler kommen, da der Shortname = Space und damit ungültig ist.

Zu Testzwecken ist es möglich ¹⁾, einen Timestamp-Offset zu setzen:

 EXEC TAA INTERN TIMESTAMPOFFSET
    OFFSET = <wert>
 END-EXEC  

<wert> muss einen String im gültigen Timestampoffset-Format enthalten (vgl. hier). Dieser Wert darf, wenn er als Konstante übergeben wird, nicht länger als 59 Stellen sein, wegen der max. Länge der Cobol-Zeile. Wenn der Wert als Cobol-Feld übergeben wird, sind bis zu 128 Stellen möglich (Begrenzung durch Übergabebereich in der TXTAA), was in aller Regel mehr als genug sein dürfte. Da es sich um einen Intern-Befehl handelt, erfolgt im Generator keine Überprüfung von Länge oder Syntax des Werts; beim Setzen des Offset für den BC wird die Gültigkeit natürlich geprüft.

Die Funktionalität zum Setzen des Timestampoffset im BC ist nur für nicht-Enduser ausführbar. Sollte die Anweisung in produktiven Modulen benutzt werden, wird geOOpst und der Timestampoffset ignoriert.

Syntax:

EXEC TAA INTERN RESIZE
      OM-OBJECT   = <Objektname>
      OM-INDEX      = <Anzahl Sätze>       
      [OM-INITIALIZED = TRUE]
 END-EXEC

Gibt an, wie viele Sätze in einem Listobjekt anschließend vorhanden sein sollen. Enthält das Objekt mehr Sätze, werden (von vorn anfangend) die Sätze, die über die angegebene Anzahl hinausgehen, gelöscht. Enthält es weniger Sätze, wird die entsprechende Anzahl leerer Sätze hinzugefügt.

Wenn die Sätze initialisiert werden sollen, enthält das Objekt anschließend die angegebene Anzahl initialisierter Sätze; ggf. in den Sätzen enthalten Daten werden dabei gelöscht.

Wenn die Sätze nicht initialisiert werden sollen, bleiben bereits vorhandene Dateninhalte erhalten; der Inhalt von neu hinzugefügten Sätzen ist undefiniert.

Beim Initialisieren wird auch der Inhalt der Datenstruktur im COBOL-Programm initialisiert. Ohne Initialisierung wird der Inhalt der Datenstruktur im COBOL-Programm nicht verändert.

Nach dem RESIZE ist die aktuelle Position im Objekt (Currency) undefiniert.

Regeln:

• OM-OBJEKT muss ein Literal sein.
• OM-Index kann ein num. Literal oder num. Variable sein.
• Wenn für OM-Initialized irgendetwas angegeben ist, gilt es als TRUE. Um nicht zu initialisieren, darf OM-INITIALIZED nicht angegeben werden. Wenn das Objekt Sätze enthält, und keine „INI“ angegeben ist, bleibt der Satzinhalt erhalten. Es wird kein Satzinhalt in der Objektstruktur im Modul bereitgestellt.

In der TX-TAA enthält:

Syntax:

EXEC TAA INTERN FILLRAW
         OM-OBJECT         = <Objektname>
         SOURCENAME     = <Pointer auf die Daten>       
         SOURCESIZE       = <Gesamtlänge der Daten>         
         [OM-OFFSET        = <Offset zum Einfügepunkt ab Satzanfang]
         [OM-SIZE              = <Länge der einzufügenden Daten pro Satz>]
 END-EXEC

Regeln:

• OM-OBJEKT muss ein Literal sein.
• OM-Offset, Sourcesize, OM-Size können num. Literale oder num. Variablen sein. „LENGTH OF …“ ist nicht erlaubt, wird nicht korrekt erkannt.
• SOURCENAME ist der Name des Bereichs, der die Daten enthält. Wird als „ADDRESS OF <SourceName>“ übergeben.

Es werden am Ende des Objekts, also hinter ggf. bereits vorhandene Sätze, solange neue Sätze hinzugefügt (ADD) und gefüllt, wie Daten vorhanden sind.

Mindest-Voraussetzungen, die überprüft werden, damit der FillRaw ausgeführt wird:

• Das Objekt ist ein Listenobjekt.
• Das Objekt darf verändert werden (Rolle nicht NOP oder REF).
• Länge des Datenbereichs ist ohne Rest teilbar durch die angegebene Satzlänge.
• Satzlänge + Offset ist nicht größer als die bekannte Objektsatzlänge.

In der TX-TAA enthält: