von Birgitta Hauser
Für einen Windows-Programmierer ist es einfach eine Message-Box zu erstellen und darin einen beliebigen Text anzuzeigen, z.T. auch deshalb, weil er kaum eine andere Möglichkeit hat. Im Zeitalter der „Windows-Kinder“, werden solche Techniken auch von Green Screen-Anwendungen erwartet. Für viele iSeries/System i Programmierer, die für den Green Screen programmieren, scheinen solche „Spielchen“ jedoch zu aufwändig:
Eine Display-File muss erstellt werden · Zeilen-Umbrüche müssen gesteuert werden, ansonsten gibt es u.U. unschöne Umbrüche mitten im Wort. · Wenn dann auch noch mit Mehrsprachigkeit gearbeitet wird und die Texte aus Message-Files ermittelt und aufbereitet werden müssen, wird das ganze noch komplizierter. · Werden längere Texte angezeigt, müssen auch noch Seitenwechsel gesteuert werden. Oder man muss mit Subfiles arbeiten.
Dabei kann man solche Popup-Windows über API (Application Programming Interface) QUILNGTX (Display Long Text) ganz einfach generieren ohne eine Display-File verwenden zu müssen.
Vorteile:
- · Es wird keine Display-File benötigt, der anzuzeigende Text wird als Parameter übergeben. · Das API beinhaltet eine eigene Wordwrap-Steuerung, so dass keine Umbrüche mitten im Wort erfolgen. · Bei längeren Texte wird automatisch eine Blätter-Funktion aktiviert.
Nachteile:
- · Man hat bei diesem API keine Möglichkeit den Text zu formatieren, d.h. Leer-Zeilen oder Absätze sind nicht möglich. · Weder die Fenstergröße, noch die Position des Fensters kann beeinflusst werden.
Parameter-Beschreibung für API QUILNGTX:
Bezeichnung
|
Input/Output | Definition |
| Text String | Input | Alphanumerisch Max. 16MB |
| Länge Text String | Input | 4 Byte Binär entspricht in RPG: 9B 0 oder besser 10I 0 |
| Message-Id Wenn angegeben wird der entsprechende Message-Text als Überschrift angezeigt. Ohne Message-Id wird keine Überschrift angezeigt | Input | >Alphanumerisch 7 Bytes |
| Qualifizierte Message-File für Überschrift Stelle 01-10 = Message-File Stelle 11-20 = Bibliothek | Input | Alphanumerisch 20 Bytes |
| Error-Datenstruktur | Input/Output | Error Code Parameter |
Tabelle 1: Parameter-Beschreibung für API QUILNGTX Aufruf des APIs QUILNGTX aus einem CL-Beispiel-Programm:
PGM
/* Definieren Variable */
DCL VAR(&TEXT) TYPE(*CHAR) LEN(256)
DCL VAR(&LENTEXT) TYPE(*CHAR) LEN(4) +
VALUE(X'00000100')
DCL VAR(&MSGID) TYPE(*CHAR) LEN(7)
DCL VAR(&MSGFILE) TYPE(*CHAR) LEN(20)
DCL VAR(&ERRORDS) TYPE(*CHAR) LEN(256) +
VALUE(X'0000010000000000')
/* Anzeigen Text in Fenster */
CHGVAR VAR(&TEXT) +
VALUE('über API QUILNGTX ist es möglich +
beliebige Texte in einem Fenster +
anzuzeigen, ohne eine Display-File +
zu verwenden!')
CALL PGM(QUILNGTX) +
PARM(&TEXT /* Anzuzeigender Text */ +
&LENTEXT /* Länge Text binär */ +
&MSGID /* Message-Id Überschrift */ +
&MSGFILE /* Qual. Message-File */ +
&ERRORDS) /* Error-Datenstruktur */
ENDE: ENDPGM
Bild 01: Aufruf des APIs QUILNGTX aus einem CL-Programm
Das obige Beispiel-Programm wurde unter Release V5R2M0 erstellt. Aus diesem Grund wurde der zweite Parameter (&LENTEXT = Länge des übergebenen Textes) alphanumerisch mit einer Länge von 4 Byte definiert. Um einen Initial-Wert zu setzen, musste die hexadezimale Darstellung verwendet werden. Ab Release V5R3M0 ist es möglich diesen Parameter direkt als Integer mit dem Datentyp *INT und einer Länge von 4 Byte zu definieren. Da es sich bei Integer-Feldern um numerische Felder handelt, ist eine Initialisierung mit hexadezimalen Werten nicht mehr erforderlich, vielmehr können die numerischen Werte direkt angegeben werden.
Ab Release V5R4M0 kann dann die Error-Datenstruktur als echte Datenstruktur definiert werden. Die beiden ersten Felder dieser Datenstruktur, (zurückgegebene Bytes und übergebene Bytes) können dann direkt als Integer-Felder (Datentyp *INT) mit einer Länge von 4 Byte angelegt werden. Da es sich dann um numerische Felder handelt, kann für die Anzahl der übergebenen Bytes direkt der numerische Wert übergeben werden.
Aufruf des APIs QUILNGTX aus RPG:
Prototypen und Error-Datenstruktur für Aufruf aus RPGIV (DSPWDWTXT)
D DspWdwTxt PR ExtPgm('QUILNGTX')
D ParmText 65535 const options(*VarSize)
D ParmLenText 10I 0 const
D ParmMsgId 7A const
D ParmQualMsgFile...
D 20A const
D ParmError1 likeDS(DS_Error1)
* Error Datenstruktur
D DS_Error1 DS Qualified
D ByteProv 10I 0 inz(%Size(DS_Error1))
D ByteAvail 10I 0 inz(*Zeros)
D MsgId 7 inz(*Blanks)
D Reserved 1 inz(x'00')
D ExceptData 256 inz(*Blanks)
Bild 02: Prototyp für den Aufruf des APIs QUILNGTX und Error-Datenstruktur
Da es sich bei allen Parametern des APIs QUILNGTX mit Ausnahme des Error-Parameters um Input only-Parameter handelt, wurde in dem Prototypen jeweils das Schlüssel-Wort CONST angegeben. Bei der Verwendung des Schlüssel-Wortes CONST erfolgt eine Parameter-Übergabe by Reference, d.h. es wird nur die Adresse des Parameters-Feldes übergeben. Weicht die Länge des übergebenen Parameters, von der erwarteten Länge ab, oder wird ein Parameter-Feld mit compatiblem Datentypen übergeben (z.B. gepackt, wenn integer erwartet wird) oder wird ein entsprechender Ausdruck übergeben, wird ein temporäres Feld mit dem erwarteten Datentypen und der erwarteten Länge erstellt. Der übergebene Wert wird in dieses temporäre Feld kopiert. Anschließend wird die Adresse dieses temporären Feldes an das API übergeben.
Die Angabe des Schlüssel-Wortes OPTIONS(*VarSize) bewirkt, dass für dieses Parameter-Feld auch bei abweichender Länge kein Duplikat erstellt wird, sondern die Adresse des ursprünglichen Feldes übergeben wird. Das Erstellen eines Duplikates hier ist auch nicht unbedingt erforderlich, da die Länge des Textes im dritten Parameter übergeben wird. Ausgehend von der Adresse des zweiten Parameters werden im API die nächsten n Bytes (abhängig von der Angabe im dritten Parameter) verarbeitet.
Die Länge des übergebenen Textes (zweiter Parameter) kann bis zu 15.728.640 Zeichen betragen. Da in RPG jedoch die Maximal-Länge für ein alphanumerisches Feld bei 65.535 Byte liegt, wurde diese Länge im Prototypen angegeben.
Diesen Code-Schnipsel legt man am besten in einer eigenen Teil-Datei ab, und bindet diese in jede Quelle ein, aus der das API QUILNGTX aufgerufen wird.
Das folgende Beispiel zeigt den Aufruf des APIs QUILNGTX aus einem RPG-Programm. Der Prototype und die Error-Datenstruktur wurden über die Copy-Strecke DSPWDWTXT in der Datei QPROLESRC eingebunden. .
D/COPY QPROLESRC,DSPWDWTXT
D BspText S 65535 varying
*-----------------------------------------------------------------*
/Free
BspText = 'Dies soll nur ein kurzer Text sein, um das +
API QUILNGTX auszuprobieren! +
Das UIM API QUILNGTX (Display Long Text) stellt eine +
einfache Möglichkeit dar, einen beliebigen Text +
in einem Fenster anzuzeigen. +
Das Erstellen einer Display-File +
ist dazu nicht erforderlich.';
DspWdwTxt(BspText: %Len(BspText): *Blanks: *Blanks: DS_Error1);
*InLR = *On;
/End-Free
Bild 03: Aufruf des APIs QUILNGTX aus einem RPG Programm
Um sich die Arbeit noch etwas zu erleichtern, kann man zusätzlich eine Wrapper-Prozedur um den Aufruf des APIs QUILNGTX bauen. An diese Prozedur wird lediglich der Text übergeben. Alle anderen, für den Aufruf des APIs erforderlichen Parameter, werden in dieser Prozedur versorgt.
Der Prototyp für die Wrapper-Prozedur DSPWDW sieht wie folgt aus.
D DspWDW PR ExtProc('DSPWDW')
D ParmText 65535 const varying
Bild 04: Prototyp für die Wrapper-Prozedur DSPWDW
Die eigentliche Prozedur empfängt nur den übergebenen Text und ruft das API QUILNGTX auf, wobei der übergebene Text durchgereicht wird und die restlichen Parameter mit Default-Werten versorgt übergeben werden. Hier ist die Prozedur DSPWDW:
H DEBUG NoMain
********************************************************************
D/COPY QPROLESRC,DSPWDWTXT
********************************************************************
P DspWDW B Export
D DspWdW PI
D ParmText 65535 const varying
*------------------------------------------------------------------
/Free
DspWdWTxt(ParmText: %Len(ParmText): *Blanks: *Blanks: DS_Error1);
Return;
/End-Free
Bild 05: Wrapper-Prozedur DSPWDW
Wie diese Prozedur aus RPG aufgerufen wird, zeigt das folgende Beispiel.
H DEBUG
*------------------------------------------------------------------*
D/COPY QPROLESRC,DSPWDWTXT
D BspText S 1024A varying
*-------------------------------------------------------------------*
/Free
BspText = 'Dies soll nur ein kurzer Text sein, um das +
API QUILNGTX auszuprobieren!';
DspWDW(BspText);
DspWDW('Der Text kann auch direkt übergeben werden.');
*INLR = *ON;
/End-Free
Bild 06: Aufruf der Wrapper-Prozedur DSPWDW
So einfach geht’s!
Und nun viel Spaß beim Ausprobieren!
Notiz: Erstveröffentlichung in den iNN eNews.
Ähnliche Artikel:
