Auswertung der Returncodes

Die Makros SM2GMS und SM2GDAT hinterlegen die Returncodes in einer Struktur vom Typ ESMFHDR, die über das Strukturelement „hdr“ der Struktur vom Typ SM2GMS_get_measurement_stat_mdl (bei SM2GMS) bzw. der Struktur vom Typ SM2GDAT_get_data_mdl (bei SM2GDAT) angesprochen werden kann.

Die Struktur ESMFHDR ist in FHDR.H deklariert und folgendermaßen aufgebaut:

struct  ESMFHDR {
        struct FHDRifid_mdl if_id;      /* interface identifier     */
        struct FHDRretc_mdl returncode; /* returncode               */
};

Das Strukturelement „if_id“ vom Typ FHDRifid_mdl wird von den Makros SM2GMS und SM2GDAT intern verwendet und ist für die Auswertung der Returncodes ohne Bedeutung.

Das Strukturelement „returncode“ vom Typ FHDRretc_mdl hat folgenden Aufbau:

/* returncode structure                                             */
struct FHDRretc_mdl {
        union /* rc */ {
                struct {
                        struct {
                                unsigned char subcode2;
                                unsigned char subcode1;
                        } subcode;
                        union /* mc */ {
                                unsigned short maincode;
                                struct {
                                unsigned char maincode2;
                                unsigned char maincode1;
                                } main_returncode;
                        } mc;
                } structured_rc;
                unsigned long rc_nbr;   /* general return code:       */
        } rc;
};

Zur Auswertung der Returncodes stehen symbolische Namen und Konstanten zur Verfügung, die in FHDR.H und SM2RC.H definiert sind und deren Verwendung im Folgenden erläutert wird.

Zur Überprüfung der Returncodes muss der Anwender zunächst das Strukturelement „returncode.rc.structured_rc.mc.maincode“ der ESMFHDR-Struktur abfragen. Dieses Strukturelement (im weiteren mit MAINCODE bezeichnet) kann über den symbolischen Namen FHDR_RC_MAINCODE angesprochen werden.

Beispiele

SM2GMS.hdr.FHDR_RC_MAINCODE
SM2GDAT.hdr.FHDR_RC_MAINCODE

Bei erfolgreicher Ausführung des Makros hat MAINCODE den Wert FHDRsuccessful_processing.

Im Fehlerfall liefern MAINCODE und das Strukturelement returncode.rc.structured_rc.subcode.subcode1 Fehlerinformationen. Das Strukturelement „returncode.rc.structured_rc.subcode.subcode1“ (im weiteren mit SUBCODE1 bezeichnet) kann über den symbolischen Namen FHDR_RC_SUBCODE1 angesprochen werden.

Beispiele

SM2GMS.hdr.FHDR_RC_SUBCODE1
SM2GDAT.hdr.FHDR_RC_SUBCODE1

Die folgende Übersicht erläutert die wichtigsten Returncodes:

SUBCODE1	MAINCODE	Bedeutung und Maßnahme
0	0	Der Aufruf war erfolgreich.
1	65535	Die angeforderte Funktion wird nicht unterstützt (falsche Angabe für UNIT oder FUNCTION im Standardheader). Nicht behebbarer Fehler. Maßnahme: Keine
3	65535	Die angegebene Version der Schnittstelle wird nicht unterstützt (falsche Versionsangabe im Standardheader). Nicht behebbarer Fehler. Maßnahme: Keine
4	65535	Parameterliste ist nicht auf Wortgrenze ausgerichtet. Nicht behebbarer Fehler. Maßnahme: Keine
65	65535	Das Subsystem SM2 ist nicht vorhanden. Maßnahme: Das Subsystem muss explizit erzeugt werden.
128	65535	Das Subsystem SM2 ist kurzfristig nicht reaktionsfähig. Maßnahme: Kurz warten und Aufruf wiederholen.
129	65535	Das Subsystem SM2 ist längerdauernd nicht reaktionsfähig. Maßnahme: Längere Zeit warten und Aufruf wiederholen.
1	1	Kann nur beim Makro SM2GDAT auftreten. Die im Parameter „length_buffer“ angegebene Größe reicht zur Aufnahme der angeforderten SM2-Datenpuffer nicht aus. In diesem Fall hinterlegt der Makro im Strukturelement „length_buffer“ der Struktur vom Typ SM2GDAT_get_data_mdl, die dem Makro beim Aufruf als Parameter übergeben wurde, die tatsächlich benötigte Größe. Maßnahme: Parameter „length_buffer“ mit dem Wert des Strukturelements „length_buffer“ versorgen, Ausgabebereich in dieser Größe bereitstellen und den Aufruf wiederholen.
1	2	Kann nur beim Makro SM2GDAT auftreten. Die im Parameter „length_buffer“ angegebene Größe reicht zur Aufnahme der angeforderten Datenpuffer aus, aber SM2 kann den Ausgabebereich nicht validieren, d.h. er stellt fest, dass er (vom Beginn des Ausgabebereichs an gerechnet) nicht auf den Speicherbereich schreiben darf, der zur Aufnahme der angeforderten Datenpuffer nötig ist. Dieser Fehlercode deckt nicht den Fall ab, dass der Aufrufer zwar in „length_buffer“ eine ausreichende Größe angibt, aber zu wenig Speicherplatz für den Ausgabebereich bereitstellt. SM2 kann nämlich nicht feststellen, ob der Aufrufer sich eigene Datenbereiche oder eigenen Programmcode überschreibt. Maßnahme: Programm korrigieren – Speicherplatz immer mindestens in der beim Parameter „length_buffer“ angegebenen Größe bereitstellen!
64	3	Kann nur beim Makro SM2GDAT auftreten. SM2 hat keine neuen Daten. Maßnahme: Warten (z.B. 5 Sekunden) und erneut versuchen. Eventuell das Aufruf-Intervall mit dem SM2-Messintervall synchronisieren. Das aktuell eingestellte SM2-Messintervall liefert der Makro SM2GMS.
32	4	Systemfehler. Maßnahme: Keine
32	5	Die SM2-Messtask läuft nicht. Maßnahme: Keine
64	6	Angegebener Rechner nicht erreichbar.

Für die in der Tabelle aufgeführten Werte für MAINCODE und SUBCODE1 stehen folgende symbolische Konstanten in FHDR.H und SM2RC.H zur Verfügung.

Symbolische Konstanten für MAINCODE:

#define FHDRsuccessful_processing	0
#define SM2RCbuffer_too_short	1
#define SM2RCbuffer_not_valid	2
#define SM2RCno_data	3
#define SM2RCsystem_error	4
#define SM2RCgatherer_down	5
#define SM2RChost_not_available	6
#define FHDRlinkage_error	65535

Symbolische Konstanten für SUBCODE1:

#define FHDRfct_not_supported	1
#define FHDRver_not_supported	3
#define FHDRalignment_error	4
#define FHDRss_not_created	65
#define FHDRwait_short_term	128
#define FHDRwait_long_term	129

Eine praktische Anleitung zur Auswertung der Returncodes gibt das Beispiel im folgenden Abschnitt.

SM2RC.H befindet sich in der Bibliothek SYSLIB.SM2.<ver> und kann mit dem folgenden Kommando ausgedruckt werden:

/PRINT-DOCUMENT 
   FROM-FILE=*LIBRARY-ELEMENT(
      LIBRARY=SYSLIB.SM2.<ver>,
      ELEMENT=SM2RC.H,TYPE=S)

FHDR.H befindet sich in der Bibliothek SYSLIB.BS2CP.<ver> und kann auf analoge Weise ausgedruckt werden.