Tips und Techniken für die AS/400

Der 3. Teil der jährlichen Tips und Techniken jetzt online:
Thema: APIs

Blitz Links:
  Senden von Benutzernachrichten mit API QEZSNDMG
Liste der eingetragenen Benutzer
Nachrichten senden mit QMHSNDPM
Anzeige langer Texte

APIs

 

Senden von Benutzernachrichten mit API QEZSNDMG

Mit dem API QEZSNDMG (Nachricht senden) können Sie Durchbruchnachrichten an einen oder mehrere Benutzer senden (und auch Antworten empfangen). Damit bietet QEZSNDMG einen deutlichen Vorteil gegenüber dem Befehl SNDBRKMSG (Durchbruchnachricht senden), mit dem die Nachricht nur an eine Workstation gesendet werden kann. Wenn Sie QEZSNDMG interaktiv von der Befehlszeile aus aufrufen, wird die Anzeige „Operational Assistant Send a Message“ eingeblendet. Geben Sie hier die Nachricht ein, die gesendet werden soll. Sie können QEZSNDMG auch in einem Stapelprogramm verwenden, indem Sie das API aufrufen und die notwendigen Parameter ohne eine Anzeige weitergeben. (Siehe das Beispiel in Abbildung 7.) Weitere Infomationen zu QEZSNDMG finden Sie in der Dokumentation OS/400 Operational Assistant APIs (SC41-5867).

Liste der eingetragenen Benutzer

Mit dem API QEZLSGNU (Eingetragene Benutzer auflisten) können Sie eine Liste aller eingetragenen Benutzer erstellen. QEZLSGNU plaziert die Liste in einem Benutzerbereich, den Sie anschließend mit anderen Benutzerbereich-APIs bedienen können, um die Benutzerliste zu extrahieren. Verwenden Sie QEZLSGNU als Teil eines täglichen Sicherungsprogramms, um sicherzustellen, daß sich alle Benutzer abgemeldet haben, bevor Sie die Datenbibliothek abspeichern. Das API kann auch getrennte Benutzer anzeigen – eine wichtige Funktion, da auch durch diese Benutzer Dateien gesperrt sein können. Abbildung 8 zeigt ein Beispiel des API-Aufrufs. Weitere Infomationen zu QEZLSGNU finden Sie in der Dokumentation OS/400 Operational Assistant APIs (SC41-5867).

Nachrichten senden mit QMHSNDPM

Das API QMHSNDPM (Programmnachricht senden) sendet eine Nachricht an eine Programmnachrichten-Warteschlange. Das API wird häufig zum Senden von Nachrichten an das aufrufende Programm verwendet, um Fehler zu melden.

Die folgenden C-Spezifikationen zeigen, wie QMHSNDPM aufgerufen wird:

C   Call    ‘QMHSNDPM’
C   Parm                  MsgId
C   Parm                  QMsgFile
C   Parm                  MsgText
C   Parm                  MsgTextLen
C   Parm                  MsgType
C   Parm                  MsgQueue
C   Parm                  MsgStack
C   Parm                  MsgKey
C   Parm                  APIErrDs

Laut Dokumentation müssen Sie beim Senden einer Nachricht an die aufrufende Prozedur in dem aktuellen Programmstapel MsgQueue auf „*“ und MsgStack auf 1 setzen. In dem hier diskutierten Beispiel wird vorausgesetzt, daß das Programm A das RPG IV-Programm B aufruft. Programm B stellt daraufhin einen Fehler fest, auf den es Programm A aufmerksam machen will. Also ruft Programm B QMHSNDPM auf, um die Nachricht zu senden. Dabei wird 1 für MsgStack festgelegt. Nun sollte laut Dokumentation die Nachricht in der Nachrichten-Warteschlange von Programm A warten.

Das ist jedoch nicht der Fall. Wenn Sie ein RPG IV-Programm aufrufen, ruft die ILE-Laufzeitunterstützung eine PEP-Prozedur auf, die dann im Gegenzug Ihr Programm aufruft. Wenn also Programm A Programm B aufruft, werden die beiden Programme auf dem Aufrufstapel durch die PEP-Prozedur von Programm B getrennt. Aus diesem Grunde befindet sich Programm A zwei Stufen über dem Aufrufstapel von Programm B. Wenn Programm B eine Nachricht an Programm A senden möchte, muß der MsgStack auf 2 gesetzt werden, damit die Nachricht wieder den Aufrufstapel hochgeschickt werden kann und Programm B dabei die eigene PEP-Prozedur umgehen kann.

Anzeige langer Texte

Über das Benutzeroberflächen-API QUILNGTX (Langen Text anzeigen) können Sie interaktive Benutzer von einem HLL-Programm aus benachrichtigen. Das API ruft ein Einblendfenster mit einer festgelegten Textfolge auf. Geben Sie eine Zeichenfolge (bis zu 157,287,640 Bytes lang), die Länge der Zeichenkette, eine optionale Nachrichten-ID, den Dateinamen der Nachrichten und einen API-Fehlerparameter ein. Die erste Textebene der Nachricht – identifiziert durch die Nachrichten-ID – enthält eine Titelzeile für die Nachrichtenanzeige. Wenn Sie keinen Parameter für die Nachrichten-ID eingeben, bleibt die Titelzeile leer. Wenn Sie keinen Parameter für den Namen der Nachrichtendatei eingeben, wird der Standardname QSYS/QCPFMSG verwendet.

Beispiel: Angenommen es ist ein Programmfehler aufgetreten, und Sie möchten dem Benutzer einige Zusatzinformationen zu dem Fehler anzeigen, z.B. die Ursachen für den Fehler und mögliche Lösungsvorschläge. Die folgenden Beispiele verwenden die Nachrichtendatei UserMsg der Nachrichten-ID USR0001 in der Titelzeile. Der Text der ersten Ebene der Nachrichten-ID USR0001 lautet „Invalid option selected“. Abbildung 9A zeigt ein RPG-Beispielprogramm, das API QUILNGTX verwendet, um ein Informationsfeld für diese Nachrichten-ID anzuzeigen. Das API kann auch von einer langen Befehlszeile aus aufgerufen werden, indem Sie die Call-Anweisung eingeben und die Eingabetaste drücken. Weitere Informationen finden Sie in dem Handbuch OS/400 User Interface APIs (SC41-5876).

 

---

Ein sechster Teil folgt.
Mit freundlichen Grüßen

Ihr Burgy Zapp