Um die Parameterübergabe an die KDCS-Schnittstelle zu vereinfachen, werden in der Include-Datei kcmac.h Makros für die einzelnen KDCS-Aufrufe zur Verfügung gestellt. Diese Makros enthalten alle für einen KDCS-Aufruf benötigten Angaben als Makroparameter. Sie führen den gewünschten Aufruf aus und stellen danach einen Returncode zur Verfügung (siehe auch "Programmierung der KDCS-Fehlerbehandlung").
In den folgenden Abschnitten werden die Namengebung für die Makros, sowie die Namen und die Eigenschaften der verschiedenen Makroparameter erklärt. Es wird erläutert, welche vorbereitenden Maßnahmen getroffen werden müssen, um die Include-Datei kcmac.h einsetzen zu können. Am Ende des Abschnitts finden Sie ein Beispiel für einen Makro-Aufruf und das Listing eines ablauffähigen KDCS-Programms, das den Einsatz der Include-Datei kcmac.h verdeutlicht.
KDCS_SET zur Vorbereitung
In jeder Übersetzungseinheit, in der Sie einen KDCS-Makro aufrufen wollen, müssen Sie vor dem ersten Makro-Aufruf die folgenden beiden Aktionen ausführen:
die Include-Datei kcmac.h in die Übersetzungseinheit kopieren
Bei der Verwendung von kcmac.h werden die vier Include-Dateien kcca.h, kcpa.h, kcapro.h und kcdf.h implizit verwendet, d.h. diese Definitionen stehen dem Programmierer jederzeit zur Verfügung.
das Makro KDCS_SET(pb,hdr,rti) zur Initialisierung aufrufen
pb: Zeiger auf den KDCS-Parameterbereich.
hdr: Zeiger auf den Kopfbereich des Kommunikationsbereichs (Struktur ca_hdr).
rti: Zeiger auf den Rückgabebereich des Kommunikationsbereichs (Struktur ca_rti).
Der KDCS_SET-Aufruf stellt die Verbindung zwischen den KDCS-Makros und den Definitionen des Programmierers für Parameterbereich und Kommunikationsbereich her. Sie können dieses Makro auch mehrfach aufrufen. So ist es beispielsweise möglich mehrere verschiedene Parameterbereiche zu verwenden.
Makronamen
Die Namen der Makros ergeben sich nach folgenden Regeln:
Ein KDCS-Makroname beginnt immer mit dem Präfix "KDCS_". Es folgt der Operationscode des gewünschten KDCS-Aufrufs in Großbuchstaben. An diesen wird, falls benötigt, die Operationsmodifikation angehängt (ebenfalls in Großbuchstaben).
Beispiele:
KDCS_INIT, KDCS_LPUT, KDCS_MGET
KDCS_MPUTNT, KDCS_PENDFI, KDCS_SPUTMS
Eine Ausnahme bilden dabei die DPUT-Aufrufe zusammen mit einem "+T", "-T", "+I" oder "-I" als kcom-Parameter. Diese Makros heißen: KDCS_DPUTPT, KDCS_DPUTMT, KDCS_DPUTPI bzw. KDCS_DPUTMI.
Eine weitere Ausnahme bilden die APRO-Aufrufe zur Adressierung von OSI TP-Partnern:
KDCS_APRODM_OSI, KDCS_APROAM_OSI, KDCS_APRODM_OSI_O, KDCS_APROAM_OSI_O
Makroparameter
Die Makroparameter sind jeweils nach den KDCS-Parametern benannt, die sie mit Werten versorgen sollen (kcrn, kclt, kchour, kcpi,...). Der Nachrichtenbereich heißt nb und wird, falls benötigt, immer als erster Parameter angegeben.
Man unterscheidet zwischen drei verschiedenen KDCS-Parametertypen: Char-Arrays, Zeichen und Zahlen:
Char-Arrays
An der KDCS-Schnittstelle haben diese Parameter die Länge zwei, drei oder acht Zeichen. An der C/C++-Makro-Schnittstelle werden diese Parameter als Zeiger auf einen C-String beliebiger Länge angegeben.
Intern werden diese Parameter in Char-Arrays der benötigten Länge umgewandelt. Entweder durch Anhängen eventuell fehlender Leerzeichen, oder durch Ignorieren überflüssiger Zeichen an Ende des C-Strings. Wird daher ein Array der Länge acht z.B. mit drei Leerzeichen " " oder keinem Zeichen "" versorgt, dass mit Leerzeichen auf acht Leerzeichen " " aufgefüllt wird. Bei der Angabe "xyz" wird mit fünf Leerzeichen zu "xyz " aufgefüllt. Die Umwandlung erfolgt jeweils ohne dass ein Stringendekennzeichen "\0" erzeugt wird.Parameter dieses Typs: kcrn, kcfn, kclt, kcpa, kcus, kcadrlt, kcact, kcpi, kcpos, kcneg, kccomid, kclangid, kcterrid, kccsname.
Zeichen
An der KDCS-Schnittstelle sind diese Parameter vom Typ Character.
An der C/C++-Makro-Schnittstelle werden diese Parameter auch als character (per value) angegeben. Die Angaben sind daher von der Form: 'Parameter dieses Typs: kcmod, kcof.
Zahlen
An der KDCS-Schnittstelle gibt es verschiedene Arten von Zahlen: short, unsigned short und Zahlen, die in Form eines abdruckbaren Texts erwartet werden. An der C/C++-Makro-Schnittstelle werden diese Parameter immer als Zahlen (per value) angegeben. Diese Zahlen werden intern auf das gewünschte Format umgewandelt. Short und unsigned short Zahlen werden direkt übergeben. Zahlen, die als Text bereitgestellt werden müssen, werden umgewandelt.
Parameter dieses Typs: kcla, kclm, kcdf, kclcapa, kclspa, kcday, kchour, kcmin, kcsec, kcli.
Vereinfachte Parameterübergabe
Die Makros kennen die geforderte Länge jedes Parameters und sorgen für eine korrekte Übergabe (Kürzere Strings werden bis zur erforderlichen Länge mit Leerzeichen aufgefüllt). Ein Parameter wird nur noch in der Makroparameterliste angegeben und muss nicht mehr mit memcpy übertragen werden. Die Makros verarbeiten auch alle Angaben, die bisher bei memcpy verwendet wurden. Die Zuweisung der Parameter auf die entprechenden KDCS-Parameterfelder erfolgt implizit durch die C/C++-Makros. Die Parametertypen werden durch die C/C++-Makro-Definitionen festgelegt.
Zum Vergleich ein Beispiel für die Versorgung des Parameters kcrn:
Bei unmittelbarem Aufruf:
memcpy(pb.kcrn,"rnam",8) /* nur Versorgung von kcrn*/Bei Verwendung eines Makros:
Makroname(...,"rnam",...) /* vollstaendiger KDCS-Aufruf*/
Nicht verwendete Parameterfelder werden implizit mit binär null versorgt. Beim Aufruf geben Sie für Felder, die mit Leerzeichen versorgt werden sollen, die Konstante KDCS_SPACES an.
Einige der KDCS-Parameter, die bisher auch als Char-Array übergeben werden mussten, liegen in C üblicherweise als Integer-Werte vor. Dies sind zum Beispiel die Parameter für die Zeitangabe: kcday, kchour, kcmin, kcsec. Solche Parameter werden in den neuen Makroaufrufen als Zahlen (integer) erwartet. Die Makros sorgen für eine korrekte Übergabe an die Schnittstelle.
Zum Vergleich die Versorgung eines KDCS-Aufrufs mit einer Zeitangabe:
Bei unmittelbarem Aufruf:
memcpy(pb.kcext.kcdput.kcday,"003",3); memcpy(pb.kcext.kcdput.kchour,"11",2); memcpy(pb.kcext.kcdput.kcmin,"55",2); memcpy(pb.kcext.kcdput.kcsec,"00",2);
Bei Verwendung eines Makros:
Makroname(...,3,11,55,0)
Format des KDCS-Aufrufs über die C/C++-Makroschnittstelle
KDCS-Aufrufe über die C/C++-Makroschnittstelle haben folgendes Format:
KDCS_ operationscode [ operationsmodifikation ]( parameterliste )
Falls ein Nachrichtenbereich benötigt wird, ist dessen Adresse immer als erster Parameter zu übergeben. Die Parameterliste kann auch leer sein.
Bei der Bildung der Makronamen gibt es einige Ausnahmen (siehe "C/C++-Makroschnittstelle").
KDCS_INIT(länge_KB_programmbereich, länge_SPAB); KDCS_SGETRL(zeiger_auf_NB, nachrichtenlänge, LSSB_Name) KDCS_PGWTKP()
Beispiel: Makroaufruf KDCS_MPUTNT
Nachfolgend wird die Verwendung der KDCS-Makros am Beispiel eines MPUT NT- Aufrufs gezeigt. Zunächst die Beschreibung des Makros:
KDCS_MPUT NT(nb,kclm,kcrn,kcfn,kcdf)
char *nb | Zeiger auf Nachrichtenbereich |
short kclm | Länge |
char kcrn[8] | Leerzeichen/TAC/Vorgangs-ID |
char kcfn[8] | Format/Leerzeichen/Editprofil |
unsigned short kcdf | Bildschirmfüllzeichen / bin.null / --- |
Das Makro KDCS_MPUTNT verlangt fünf Parameter, unter anderem einen Zeiger auf den Nachrichtenbereich nb. Dieser wird immer als erster Parameter übergeben. Die weiteren Parameter des Makros stammen aus dem KDCS-Parameterbereich. Die erforderlichen Typen und Bedeutungen der Parameter werden jeweils angegeben (z.B. ist kclm vom Typ short und gibt die Länge an, in der die Nachricht übermittelt werden soll). Im folgenden Beispiel ist NB ein Zeiger auf den verwendeten Nachrichtenbereich und kc_pa der KDCS-Parameterbereich.
Ein typischer Makroaufruf sieht z.B. wie folgt aus:
KDCS_MPUTNT(NB,10,KDCS_SPACES,KDCS_SPACES,KCNODF);
Derselbe Aufruf ohne Makro (unmittelbarer Aufruf der KDCS-Schnittstelle):
memcpy(PB.kcop,MPUT,4); memcpy(PB.kcom,NT,2); kc_pa.kclm=10; memcpy(kc_pa.kcrn," ",8); memcpy(kc_pa.kcfn," ",8); kc_pa.kcdf=0; KDCS(&kc_pa,NB);
DEBUG-Funktion
Sie können für die KDCS-Aufrufe, die durch die Makros abgesetzt werden, zur Laufzeit eine Protokollierung einschalten. Es werden das aufrufende Modul, die Quellzeile, und die KDCS-Felder KCOP, KCOM, KCRCCC und KCDCDC protokolliert.
Die Protokollierung wird wie folgt eingeschaltet:
Unix-, Linux- und Windows-Systeme
Durch Setzen und Exportieren der Umgebungsvariablen KDCS_C_DEBUG. Die Protokollierung erfolgt auf stdout.
BS2000-Systeme
Durch Setzen des Jobvariablen-Links *KDCSCDB.
Die Protokollierung erfolgt auf SYSOUT.
Bitte beachten Sie, dass der Jobvariablen-Link auf eine Jobvariable verweisen muss, die einen nicht-leeren Inhalt hat.Beispiel/CREATE-JV JV-NAME = KDCSCDB /MODIFY-JV JV-CONTENTS = KDCSCDB, SET-VALUE = 'YES' /SET-JV-LINK LINK-NAME = *KDCSCDB, JV-NAME = KDCSCDB
Weitere Informationen hierzu finden Sie im openUTM-Handbuch „Meldungen, Test und Diagnose“.
Hinweis: Makros als Statement-Folgen
Es handelt sich bei den KDCS-Makros nicht um einzelne C/C++-Funktionen. Vielmehr handelt es sich um eine Folge von mehreren Statements. Das bedeutet, dass ein einzelnes Makro genau so behandelt werden muss, wie es eine Folge mehrerer Statements erfordert. Normalerweise ist diese Eigenart nicht relevant, und die Makros können wie normale C/C++-Funktionen benutzt werden. Es gibt allerdings Programmstrukturen, die einzelne Statements erfordern, z.B. innerhalb eines if-Statements:
if (Bedingung) STATEMENT else STATEMENT;
Da die Makros aus mehreren einzelnen Statements bestehen, ist es nicht ohne weiteres möglich, sie für ein (einzelnes) STATEMENT einzusetzen. Sie müssen ein Makro daher zuerst als einen zusammengehörigen Block kennzeichnen. Dies geschieht mittels geschweifter Klammern: {Makro;}. Statt also fälschlicherweise zu schreiben
ist es richtig Folgendes zu verwenden:
|
|