|
|
label
Angabe einer symbolischen Adresse für den ersten Befehl der Makroauflösung (optional).
cmd-buff-addr
Adresse einer Verweisliste, die ihrerseits wieder Adressen enthält, die u.a. auf den Kommando-String verweisen. Diese Liste muss auf Ganzwort-Grenze beginnen, der genaue Aufbau ist unten beschrieben.
Anstelle einer symbolischen Adresse kann auch in Klammern die Nummer eines Registers angegeben werden, das diese Adresse enthält. Es dürfen die Register 2 bis 12 verwendet werden.
msg-buffer
Adresse eines Puffers für die Meldungen bzw. für zurückgemeldete Informationen. Dieser Puffer muss auf Ganzwort-Grenze beginnen und beim Aufruf des Makros OPENFT den folgenden Aufbau haben:
-+--+--+--+--+--+--+--+--+--+--+- - - - -+| lp | . . . | -+--+--+--+--+--+--+--+--+--+--+- - - - -+-
Nach der Ausführung des Makros OPENFT hat dieser Puffer den folgenden Inhalt:
-+--+--+--+--+--+--+- - - -+--+--+- - - -+- - - | lp | lm | lm1 | msg1 | lm2 | msg2 | -+--+--+--+--+--+--+- - - -+--+--+- - - -+- - -
lp
Längenfeld von 2 Bytes. Enthält die Länge des Puffers in Bytes (einschließlich Längenfeld).
lm
Längenfeld von 2 Bytes. Vor der Ausführung eines Kommandos muss dieses Feld mit X'0000' besetzt sein. Nach der Ausführung eines Kommandos enthält dieses Feld die Länge der zurückgelieferten Texte in Bytes ohne die Länge der Längenfelder lp und lm, aber mit den Längen der Längenfelder lm1, lm2,... Wenn die Summe der auszuliefernden Texte länger ist als der zur Verfügung gestellte Puffer, dann wird zum einen der Return-Code '10' (hexadezimal) gemeldet, zum andern enthält das Feld "lm" die Länge in Bytes, die erforderlich wäre, um den kompletten Text aufzunehmen.
lm1
Längenfeld von 2 Bytes. Enthält die Länge des Meldungstextes msg1 in Bytes ohne die Länge dieses Längenfeldes.
msg1
In dieses Feld wird die erste Zeile des Meldungstextes eingetragen, der auf Grund des ausgeführten Kommandos am Terminal ausgegeben würde.
lm2
Längenfeld von 2 Bytes. Enthält die Länge des Meldungstextes msg2 in Bytes ohne die Länge dieses Längenfeldes.
msg2
In dieses Feld wird die zweite Zeile des Meldungstextes eingetragen, der auf Grund des ausgeführten Kommandos am Terminal ausgegeben würde.
Auf diese Weise werden alle Zeilen des Meldungstextes in den Puffer ausgegeben, bis entweder der Meldungstext vollständig ausgegeben wurde oder bis die Pufferlänge "lp" erreicht ist. Die letzte in den Puffer ausgegebene Zeile ist eventuell unvollständig! Obwohl in diesem Fall keine weiteren Zeilen in den Puffer ausgegeben werden, wird dennoch der Wert für "lm" weiter aufsummiert, so dass anschließend in "lm" die Größe enthalten ist, die als Puffergröße "lp" für die vollständige Ausgabe erforderlich wäre (ohne die Länge der beiden Längenfelder "lp" und "lm").
Die Größe des Ausgabepuffers sollte ungefähr der zu erwartenden Datenmenge angepasst werden. Für das Absetzen eines NCOPY reichen 200 Bytes, für ein FTSHWLOG auf 100 Loggingsätze sind ca 8kB erforderlich
Das Format der Texte ist identisch zur Terminal-Ausgabe, d.h. gegebenenfalls sind auch Steuerzeichen enthalten. Diese Texte sind im Abschnitt "Meldungen des FT-Systems für den Benutzer" im Anhang beschrieben.
Anstelle einer symbolischen Adresse kann auch in Klammern die Nummer eines Registers angegeben werden, das diese Adresse enthält. Es dürfen die Register 2 bis 12 verwendet werden.
VERS=
In der Version V10.0 von openFT wurden die Returncodes umgestellt. Dadurch werden andere Meldungsnummern als bisher (openFT <= V9.0) ausgegeben. Der Parameter VERS dienst dazu, die Kompatibilität älterer Programme zu erhalten:
1: Es werden die alten Returncodes ausgegeben, Standardwert
2: Es werden die neuen Retunrcodes ausgegeben.
Der Parameter VERS bietet die Möglichkeit, zwischen alter und neuer Returncode-Ausgaben zu wählen:
Wenn Sie die alte Returncode-Ausgabe wünschen (Standardwert), bleibt die Kompatibilität älterer Programme erhalten, d.h. sie können ohne Anpassung eingesetzt werden und brauchen auch nicht neu übersetzt werden.
Wenn Sie die neuen Returncodes verwenden möchten, müssen Sie explizit den Parameter VERS=2 setzen, die Programme anpassen und neu übersetzen.
Aufbau der Verweisliste (cmd-buff-addr)
Der Parameter cmd-buff-addr verweist auf eine Liste, deren Aufbau nachfolgend beschrieben ist.
Übergabe eines Benutzer-Kommandos
Für den Fall, dass ein Benutzer-Kommando mittels Makro OPENFT übergeben wird, enthält der Parameter cmd-buff-addr die Adresse einer Liste von vier Ganzworten, die der "command processor parameter list" (CPPL) des TSO entspricht:
-+--+--+--+--+-
cmd-buff-addr ==> | CPPLCBUF |
-+--+--+--+--+-
| Nullpointer |
-+--+--+--+--+-
| Nullpointer |
-+--+--+--+--+-
| Nullpointer |
-+--+--+--+--+--
| -
Das Feld CPPLCBUF enthält die Adresse des Kommando-Puffers. Der Kommando-Puffer, auf den die im Feld CPPLCBUF enthaltene Adresse verweist, muss auf Ganzwort-Grenze beginnen und muss genau so aufgebaut sein wie für einen TSO-Command-Processor.
-+--+--+--+--+--+--+--+--+--+--+- - - -+-
CPPLCBUF ==> | lng | off | kommando-string . . . |
-+--+--+--+--+--+--+--+--+--+--+- - - -+-
lng
Längenfeld von 2 Bytes. Dieses Feld enthält die Länge des Kommando-Strings plus der Länge der Felder lng und off (also plus 4).
off
Offset-Feld von 2 Bytes. Dieses Feld enthält den Offset des ersten Parameters, bezogen auf den Beginn des Kommando-Strings (nicht auf den Beginn dieses Puffers!).
kommandostring
Dieses Feld enthält das auszuführende Kommando als Zeichenstring. Die Länge dieses Strings ist auf maximal 2000 Zeichen begrenzt. Die Kommandos sind im Kapitel „openFT-Kommandos“ beschrieben.
In Register 15 wird dem Anwenderprogramm ein Return-Code zurückgeliefert (rechtsbündig). Return-Code (hexadezimal) in R15:
'00' | Normale Beendigung |
'04' | Warnung |
'0C' | Syntaxfehler, Zugriffsbedingungen ungültig |
'10' | Der Puffer für die Rückmeldung war zu klein, der Text wurde nicht vollständig |
'12' | Die Ressourcen (z.B. VTAM-Verbindung) sind belegt. |
Beispiel für den Aufruf eines Benutzer-Kommandos
Es soll folgendes Kommando ausgeführt und dabei die neuen Returncodes verwendet werden:
|
|
Der folgende Assembler-Code ist dafür erforderlich:
LA 13,SAVAREA SAVE AREA BEREITSTELLEN
OPENFT CMD=CMDBUFF,MSG=MSGBUFF,VERS=2
.
.
CMDBUFF DC A(CBUFF) ADR. DES KOMMANDO-PUFFERS
DC A(0) NICHT VERWENDET
DC A(0) NICHT VERWENDET
DC A(0) NICHT VERWENDET
SPACE
CBUFF DS 0F KOMMANDO-PUFFER
DC Y(CLNG) LAENGENFELD
DC Y(L'CNAME) OFFSET AUF 1. PARAMETER
CNAME DC C'NCOPY ' KOMMANDO-NAME
DC C'TRANS=TO' 1. PARAMETER
DC C',PARTNER=BS2' 2. PARAMETER
DC C',LOC=(' LOCAL PARAMETER
DC C'FILE=DAT' DATEI-NAME
DC C',TRANS=('
DC C'OTTO,A1234,PASSWORD' TRANSFER-ADMISSION
DC C')),'
DC C'REM=*BS2000(' REMOTE PARAMETER
DC C'DATEN' DATEI-NAME
DC C',TRANS=('
DC C'ANTON,4567ABC,''GEHEIM''' TRANSFER-ADM.
DC C'))'
CBFFEND EQU *
CLNG EQU CBFFEND-CBUFF LAENGE DES PUFFERS
SPACE
MSGBUFF DS 0F MELDUNGS-PUFFER
DC Y(MSGLNG) LAENGE DES PUFFERS
DC X'0000'
DS CL200 MELDUNGS-TEXT
MSGEND EQU *
MSGLNG EQU MSGEND-MSGBUFF
SPACE
SAVAREA DC 18F'0' SAVE AREA