Rückinformation und Fehleranzeigen (Returncodes)

Rückinformation

Bei einigen Makros ist die Übergabe von Daten an das aufrufende Programm wesentlicher Teil ihrer Funktion. Diese Information wird gelegentlich in Register R1 übergeben oder auch in einen Bereich des Programms übertragen, dessen Adresse im Makroaufruf angegeben wurde. Die Übergabeart solcher Informationen ist in der Funktionsbeschreibung der jeweiligen Makros angegeben.

Fehleranzeigen (Returncodes)

Nach der Ausführung eines Makros wird das aufrufende Programm über den Erfolg oder Misserfolg des Makroaufrufs informiert. Dies geschieht durch die Übergabe eines Returncodes.

In Abhängigkeit von der jeweiligen Makroschnittstelle werden zwei Fälle unterschieden: die Übergabe im Register R15 und die Übergabe im Standardheader. Bei einigen Makros ist auch eine Kombination beider Fälle möglich.

• Übergabe des Returncodes im Standardheader

Teil vom Standardheader:

+---------------+
|   |   |   |   |
|c|c|b|b|a|a|a|a|
+---------------+

aaaa = Maincode
bb = Subcode1
cc = Subcode2

In den zwei rechten Byte wird der sog. Maincode übergeben. Er kennzeichnet das Ergebnis der Funktionsausführung. Subcode1 dient der Fehlerklassifizierung.
Subcode2 dient der weiteren Unterteilung des Fehlers in Fehlerklassen oder enthält zusätzliche Diagnoseinformationen.
Alle Teile des Returncodes werden sedezimal angegeben. Zu Aufbau und Inhalt des Standardheaders siehe "Standardheader".

• Übergabe des Returncodes im Register R15

R15:

+---------------+
|   |   |   |   |
|b|b| | | | |a|a|
+---------------+

aa = primärer Returncode
bb = sekundärer Returncode

Im rechtsbündigen Byte des Registers R15 wird der primäre Returncode übergeben. Er besagt, ob die Funktion erfolgreich ausgeführt werden konnte oder nicht. Trat während der Ausführung kein Fehler auf, so enthält das rechtsbündige Byte den Code X'00'. Wenn ein Fehler während der Ausführung eines Makros aufgetreten ist, bringt der Ablaufteil als Fehlerkennzeichen einen anderen sedezimalen Code in dieses Byte. (Die drei linksbündigen Byte enthalten jeweils X'00', solange nicht ausdrücklich etwas anderes vereinbart wird).

In einigen Fällen wird die Information des primären Returncodes durch einen sekundären Returncode im linksbündigen Byte des Register R15 ergänzt. Mit dieser zusätzlichen Informationen ist es möglich, die Fehlerursache genauer zu bestimmen. Der sekundäre Returncode wird ebenfalls sedezimal dargestellt. Es liegt in der Verantwortung des Benutzers, diesen Code zu prüfen und geeignete Maßnahmen zu ergreifen.
Die Werte des Returncodes und deren Bedeutung sind in der jeweiligen Makrobeschreibung im Abschnitt „Rückinformation und Fehleranzeigen“ angegeben.

Sind die Codewerte des primären Returncodes im Abstand X'04' und ein garantierter Maximalwert festgelegt, kann der Returncode durch eine Sprungtabelle (bestehend aus 4 Byte langen Sprungbefehlen) verarbeitet werden.
Die Returncodes vieler Makros haben keine solche feste Strukturierung. In diesen Fällen ist eine Returncode-Verarbeitung mit expliziten Abfragen (Compare-Befehle) erforderlich.

Für beide Arten ist im Folgenden ein Beispiel aufgeführt.

Returncode des Makros OPCOM

X'aa'	Erläuterung
X'00'	Die ITC-Teilnahme ist eröffnet
X'04'	Fehler in der Operandenangabe. Die ITC-Teilnahme ist nicht eröffnet
X'08'	ITC-Name ist schon vergeben. Die ITC-Teilnahme ist nicht eröffnet
X'0C'	Kein Systemspeicher zur Eröffnung der ITC verfügbar oder die systeminterne Größe für Empfangswarteschlangen ist überschritten. Die ITC-Teilnahme ist nicht eröffnet.
X'10'	Die ITC-Teilnahme wurde bereits erklärt.

Beispiel für Returncode-Verarbeitung mit Sprungtabelle

  RCTAB    START
           PRINT NOGEN
           BALR  3,0
           USING *,3
  *        :
           OPCOM ITCNAME       * Declare ITC participation
1                 *,MACRO: OPCOM, VERSION: VER041
           B     RS00(15)
  CONTINUE EQU   *
  *        :
  END      TERM
  RS00     B     CONTINUE      * R15=00: No error handling
           B     OPERR         * R15=04
           B     NAMEERR       * R15=08
           B     MEMERR        * R15=0C
  EXIST    NOP   EXIST         * R15=10:
  *                              EXISTING ITC PARTICIPATION handling
           B     END
  OPERR    NOP   OPERR         *         OPERAND ERROR handling
           B     END
  NAMEERR  NOP   NAMEERR       *         DUPLICATE NAME handling
           B     END
  MEMERR   NOP   MEMERR        *         MEMORY ERROR handling
           B     END
           END

Beispiel für Returncode-Verarbeitung mit expliziter Abfrage

  RCEXPL   START
           PRINT NOGEN
           BALR  3,0
           USING *,3
  *         :
           OPCOM ITCNAME       * Declare ITC participation
1                 *,MACRO: OPCOM, VERSION: VER041
           LTR   15,15
           BZ    CONTINUE      * R15 = X'00'
           C     15,=F'4'
           BE    OPERR         * R15 = X'04'
           C     15,=F'8'
           BE    NAMEERR       * R15 = X'08'
           C     15,=F'12'
           BE    MEMERR        * R15 = X'0C'
           C     15,=F'16'
           BE    EXIST         * R15 = X'10'
  *        :                   ***
  *        :                   * Handling of other return codes
  *        :                   ***
  CONTINUE EQU   *
  *        :
  END      TERM
  *
  OPERR    NOP   OPERR         * OPERAND ERROR handling
           B     END
  NAMEERR  NOP   NAMEERR       * DUPLICATE NAME handling
           B     END
  MEMERR   NOP   MEMERR        * MEMORY ERROR handling
           B     END
  EXIST    NOP   EXIST         * EXISTING ITC PARTICIPATION handling
           B     END
  *        :
           END