Mit KC_GET_OBJECT können Sie Informationen über alle Objekte der Konfiguration und die Einstellung der Anwendungsparameter abfragen.
Es können verschiedene Arten von Informationen abgefragt werden. Welche Informationen UTM zurückliefern soll, können Sie über den Parameter subopcode1 steuern.
Folgende Informationen können von UTM geliefert werden:
Eine Liste der Namen von Objekten eines Objekttyps (subopcode1=KC_NAME oder KC_NAME_NEXT).
Eigenschaften, Status- und Statistikinformationen zu den Objekten eines Objekttyps (subopcode1=KC_ATTRIBUTES oder KC_ATTRIBUTES_NEXT).
Unter Eigenschaften versteht man die Parameter, die beim Konfigurieren der Objekte gesetzt wurden. UTM liefert die aktuellen Werte der Parameter zurück, d.h. Modifikationen durch die Administration werden berücksichtigt.
Statusinformationen beschreiben den aktuellen Zustand eines Objekts, z.B. ob eine Verbindung gerade aufgebaut oder ein Benutzer gerade angemeldet ist.
Statistikinformationen sind Zählerstände und intern gemessene Wartezeiten. UTM liefert z.B. folgende Werte zurück: die Anzahl der Nachrichten, die die Anwendung seit dem Start mit einer Partner-Anwendung bzw. einem Client ausgetauscht hat, oder die Anzahl der in einer Partner-spezifischen Message Queue zwischengespeicherten Nachrichten oder die Anzahl der Teilprogrammläufe, die über einen Transaktionscode gestartet wurden.
Die Eigenschaften, Status- und Statistikinformationen zu einem Objekt liefert UTM im Datenbereich in der Datenstruktur des Objekttyps (siehe "Datenstrukturen zur Beschreibung der Objekteigenschaften") zurück. Liefert UTM Informationen zu mehreren Objekten zurück, dann legt UTM einen Vektor von Datenstrukturen des Objekttyps über den Datenbereich.
Ist im Folgenden von den Eigenschaften eines Objektes die Rede, dann sind Objekteigenschaften, Status- und Statistikinformationen gemeint.
Die aktuelle Einstellung der Anwendungsparameter(subopcode1=KC_APPLICATION_PAR)
Welche Werte UTM zurückliefert, ist abhängig vom Parametertyp, den Sie in obj_type angeben. Sie können z.B. wählen zwischen den bei der KDCDEF-Generierung festgelegten Maximalwerten der Anwendung, den Systemparametern, den aktuellen Time-Einstellungen oder Statistikinformationen über die momentane Auslastung der Anwendung. Unter Punkt obj_type in diesem Kapitel sind die Parametertypen aufgelistet, die Sie auswählen können.
Zu jedem Parametertyp existiert eine eigene Datenstruktur, in der UTM die angeforderten Anwendungsparameter zurückliefert. Die Datenstrukturen sind im Abschnitt "Datenstrukturen zur Beschreibung der Anwendungsparameter" beschrieben.
Steuerung der Ausgabe von Objektnamen und Objekteigenschaften
UTM liefert die Objektnamen alphabetisch sortiert zurück. Entsprechend werden auch die Eigenschaften der Objekte in der Reihenfolge der Objektnamen zurückgeliefert. Im subopcode2 können Sie angeben, ob UTM die Namen in alphabetisch aufsteigender (KC_ASCENDING) oder absteigender (KC_DESCENDING) Reihenfolge zurückliefern soll.
Da gerade bei der Abfrage von Objekteigenschaften der Umfang der Information für alle Objekte eines Objekttyps sehr groß sein kann, sollten Sie die Menge der Informationen beschränken, die Sie anfordern. Dazu stehen Ihnen folgende Möglichkeiten zur Verfügung:
Im Identifikationsbereich können Sie angeben, an welcher Stelle der alphabetischen Liste die Ausgabe beginnen soll. Dazu geben Sie einen beliebigen String an.
Entspricht der String keinem Objektnamen des angegebenen Objekttyps, dann beginnt UTM die Ausgabe mit dem nächstfolgenden Objekt, d.h. mit dem alphabetisch nächstgrößeren bzw. nächstkleineren Objekt, je nachdem, was Sie in subopcode2 angegeben haben.
Entspricht der im Identifikationsbereich angegebene String einem Objektnamen, dann ist der Startpunkt der Ausgabe abhängig von subopcode1:
Bei subopcode1=KC_NAME und KC_ATTRIBUTES beginnt die Ausgabe mit diesem Objekt.
Bei subopcode1=KC_NAME_NEXT und KC_ATTRIBUTES_NEXT beginnt die Ausgabe mit dem nächstfolgenden Objekt, d.h. mit dem alphabetisch nächstgrößeren bzw. nächstkleineren Objekt, je nachdem, was Sie in subopcode2 angegeben haben.
Die Liste der ausgegebenen Namen bzw. Eigenschaften geht maximal bis zum letzten (subopcode2=KC_ASCENDING) bzw. bis zum ersten (subopcode2=KC_DESCENDING) Objekt in der alphabetischen Reihenfolge.
Sollen Namen bzw. Eigenschaften der Objekte ab dem alphabetisch ersten Objekt eines Objekttyps gelesen werden, dann müssen Sie subopcode2=KC_ASCENDING angeben und den Identifikationsbereich mit binär null belegen.
Sollen Namen bzw. Eigenschaften der Objekte in alphabetisch absteigender Reihenfolge ab dem letzten Objekt eines Objekttyps gelesen werden, dann müssen Sie subop code2=KC_DESCENDING angeben und im Identifikationsbereich den String X'FF...' übergeben.
Im Feld obj_number des Parameterbereichs können Sie die maximale Anzahl der Objekte angeben, für die UTM Informationen zurückliefern soll.
Im Selektionsbereich können Sie Selektionskriterien an UTM übergeben.
UTM liefert dann nur Informationen zu den Objekten zurück, die diese Selektionskriterien erfüllen. Unter einem Selektionskriterium versteht man bestimmte Objekteigenschaften. So können Sie sich z.B. die Namen aller Clients/Drucker ausgeben lassen, die z.Zt. mit der Anwendung verbunden sind (obj_type=KC_PTERM). Unter Punkt Selektionsbereich in diesem Kapitel sind alle Selektionskriterien aufgelistet, die Sie angeben können.
Mit der Angabe von Selektionskriterien können gezielt Objekte ausgewählt und so die Menge der Übergabedaten beschränkt werden. Die Angabe von Selektionskriterien hat jedoch Einfluss auf die Performance des Aufrufs. Insbesondere dann, wenn nur die Objektnamen abgefragt werden. UTM muss dann für jedes Objekt die Eigenschaften lesen und überprüfen, ob die entsprechende Eigenschaft mit dem Selektionskriterium übereinstimmt. D.h. ein Aufruf mit Selektionskriterien verursacht in diesem Fall wesentlich mehr Aufwand als ein Aufruf ohne Selektionskriterien.
Bei der Abfrage von Informationen ist Folgendes zu beachten
Beim Abfragen der Objektnamen bzw. der Objekteigenschaften werden auch Informationen für Objekte zurückgeliefert, die als gelöscht gekennzeichnet sind. Sie können mit Hilfe des Selektionskriteriums (delete='N') die Ausgabe auf die Objekte beschränken, die nicht gelöscht sind. Mit dem Selektionskriterium delete='Y' können Sie sich aber auch alle gelöschten Objekte des Objekttyps ausgeben lassen.
Hinweis für UTM-Cluster-Anwendungen (Unix-, Linux- und Windows-Systeme):
In UTM-Cluster-Anwendungen werden nur Informationen über die Objekte der Knoten-Anwendung geliefert, an der der Aufruf ausgeführt wird.
Über die Angabe KC_NO_READ_GSSBFILE und KC_NO_READ_USERFILE in subopcode2 können Sie steuern, ob bei Folgeaufrufen für Objekte vom Typ GSSB oder USER auf die Cluster-GSSB-Datei bzw. die Cluster-User-Datei zugegriffen wird oder nicht. Damit lässt sich bei einer größeren Anzahl von Folgeaufrufen die Performance verbessern.
Bei subopcode2=KC_NO_READ_GSSBFILE oder KC_NO_READ_USERFILE werden die Objekte immer in aufsteigender Reihenfolge geliefert.
Die verbesserte Performance geht dabei einher mit einer gewissen Ungenauigkeit der Information, die in den Folgeaufrufen zurückgegeben wird. Da die Daten nicht erneut von Datei gelesen werden, sind sie möglicherweise nicht auf dem neuesten Stand.
Anwendungsmöglichkeiten
Folgende Punkte sollten Sie bei der Verwendung der Subopcodes KC_... und KC_..._NEXT berücksichtigen:
KC_ATTRIBUTES bzw. KC_NAME sollten Sie verwenden, wenn Sie überprüfen wollen, ob bereits ein Objekt mit dem angegebenen Objektnamen existiert. Dazu geben Sie den Objektnamen im Identifikationsbereich an und setzen obj_number=1. Dem Returncode des Aufrufs können Sie entnehmen, ob das Objekt existiert (Sub-Returncode=KC_SC_SAME) oder nicht (Sub-Returncode=KC_SC_NEXT).
KC_ATTRIBUTES bzw. KC_NAME können Sie als „Einstieg“ einer sukzessiven Abfrage verwenden, wenn Sie die Objektnamen ab einem bestimmten String abfragen möchten, aber nicht wissen, ob zu diesem String ein Objekt existiert oder nicht.
Z.B. kann als Name der String 'Sbbbbbb' (b=Leerzeichen) angegeben werden, wenn ab dem ersten mit „S“ beginnenden Objektnamen gelesen werden soll (solange gesichert ist, dass die Binär-Repräsentation von Leerzeichen lexikographisch kleiner ist als die von Buchstaben und Ziffern).
KC_ATTRIBUTES und KC_NAME sind nicht geeignet für einen Folgeaufruf, bei dem Sie das zuletzt gelesene Objekt des vorherigen Aufrufs im Identifikationsbereich als Startpunkt übergeben (sukzessive Abfrage). Bei diesen Parameterwerten wird der angegebene Objektname wieder mit zurückgegeben. Bei Angabe von obj_number=1 und sukzessiver Abfrage würde dann immer nur das gleiche Objekt gelesen werden.
In diesem Fall müssen Sie KC_ATTRIBUTES_NEXT bzw. KC_NAME_NEXT angeben, dann wird das folgende Objekt als erstes gelesen.
Ein Beispiel für die sukzessive Abfrage von Objekten finden Sie im Abschnitt "Beispiel für eine sukzessive Abfrage mit KC_ATTRIBUTES_NEXT".
 | KDCINF ("KDCINF - Informieren über Objekte und Anwendungsparameter") Der Umfang der zurückgelieferten Informationen ist bei KDCINF jedoch geringer als an der Programmschnittstelle. |
Versorgung der zu übergebenden Bereiche
Funktion des Aufrufs | Angabe im | |||
Parameterbereich 1 | Identifikationsbereich | Selektionsbereich | Datenbereich | |
Namen aller Objekte eines bestimmten Objekttyps ausgeben | subopcode1: | Name des Objektes mit/nach dem die Ausgabe der Namen beginnen soll | —— | (Beim Aufruf muss der Zeiger auf einen Datenbereich für die Rückgaben von UTM übergeben werden.) |
Namen aller Objekte eines bestimmten Objekttyps mit bestimmten Eigenschaften ausgeben | Selektionskriterien, nach denen UTM die Ausgabe einschränken soll | |||
Eigenschaften und Statistikinformationen von Objekten eines bestimmten Objekttyps mit bestimmten Eigenschaften ausgeben | subopcode1: | |||
Eigenschaften und Statistikinformation von Objekten eines bestimmten Objekttyps ausgeben | subopcode1: | —— | ||
Anwendungsparameter ausgeben. | subopcode1: | —— | —— | |
1 In allen Fällen muss im Parameterbereich der Operationscode KC_GET_OBJECT angegeben werden.
Versorgung der Parameter | |
Parameterbereich | |
Feldname | Feldinhalt |
version | KC_ADMI_VERSION_1 |
retcode | KC_RC_NIL |
version_data | KC_VERSION_DATA_11 |
opcode | KC_GET_OBJECT |
KC_NAME_NEXT / KC_NAME / KC_ATTRIBUTES_NEXT / KC_ATTRIBUTES / KC_APPLICATION_PAR | |
KC_ASCENDING | |
Objekttyp / Parametertyp | |
Anzahl Objekte / 0 | |
Länge Objektname im Identifikationsbereich / 0 | |
Länge Daten | |
Länge des Datenbereichs | |
Objektname/ — | |
Datenstruktur des Objekttyps mit Selektionskriterien / — | |
Datenbereich | |
— | |
KDCADMI-Aufruf |
KDCADMI (¶meter_area, &identification_area, &selection_area, &data_area) oder |
Rückgaben von UTM | |
Parameterbereich | |
Feldname | Feldinhalt |
Returncode | |
Anzahl der Objekte | |
Länge der zurückgelieferten Daten | |
Datenstrukturen des Objekt- bzw. Parametertyps / Vektor von Objektnamen | |
subopcode1
In subopcode1 geben Sie an, welche Art der Information UTM zurückliefern soll. Folgende Werte können Sie angeben:
KC_NAME
UTM soll Namen von Objekten des Objekttyps obj_type zurückliefern.
Entspricht der im Identifikationsbereich angegebene String einem Objektnamen, dann soll die Ausgabe mit dem Namen dieses Objekts beginnen.
Entspricht der String im Identifikationsbereich keinem Objektnamen des angegebenen Objekttyps, dann soll UTM die Ausgabe mit dem nächstfolgenden Objekt beginnen, d.h. mit dem alphabetisch nächstgrößeren (bei subopcode2=KC_ASCENDING) bzw. nächstkleineren Objekt (bei subopcode2=KC_DESCENDING).
KC_NAME_NEXT
UTM soll Namen von Objekten des Objekttyps obj_type zurückliefern.
Die Ausgabe soll mit dem Objektnamen beginnen, der auf den im Identifikationsbereich angegebenen String folgt, d.h. mit dem alphabetisch nächstgrößeren bei subopcode2=KC_ASCENDING bzw. nächstkleineren Objekt bei subopcode2=KC_DESCENDING (siehe unter Punkt ).
KC_ATTRIBUTES
UTM soll Eigenschaften von Objekten des Objekttyps obj_type zurückliefern.
Entspricht der im Identifikationsbereich angegebene String einem Objektnamen, dann soll die Ausgabe mit den Eigenschaften dieses Objekts beginnen.
Entspricht der String im Identifikationsbereich keinem Objektnamen des angegebenen Objekttyps, dann soll UTM die Ausgabe mit dem nächstfolgenden Objekt beginnen, d.h. mit dem alphabetisch nächstgrößeren (bei subopcode2=KC_ASCENDING) bzw. nächstkleineren Objekt (bei subopcode2=KC_DESCENDING).
KC_ATTRIBUTES_NEXT
UTM soll Eigenschaften von Objekten des Objekttyps obj_type zurückliefern.
Die Ausgabe soll mit dem Objekt beginnen, dessen Name auf den im Identifikationsbereich angegebenen String folgt, d.h. mit dem alphabetisch nächstgrößeren (bei subopcode2=KC_ASCENDING) bzw. nächstkleineren Objekt (bei subopcode2=KC_DESCENDING).
KC_APPLICATION_PAR
UTM soll die Anwendungsparameter des in obj_type angegebenen Parametertyps zurückliefern.
subopcode2
Die Angaben, die Sie im Feld subopcode2 machen müssen, sind abhängig von dem in subopcode1 gesetzten Wert.
bei subopcode1=KC_APPLICATION_PAR müssen Sie subopcode2 mit binär null (KC_NO_SUBOPCODE) versorgen.
bei KC_NAME_NEXT, KC_NAME, KC_ATTRIBUTES_NEXT, KC_ATTRIBUTES müssen Sie in subopcode2 einen der folgenden Werte setzen:
KC_ASCENDING,
UTM gibt die Informationen zu den Objekten in alphabetisch aufsteigender Reihenfolge der Objektnamen zurück, d.h. die alphabetisch nächstgrößeren.
KC_DESCENDING
UTM gibt die Informationen zu den Objekten in alphabetisch absteigender Reihenfolge der Objektnamen zurück, d.h. die alphabetisch nächstkleineren.
KC_READ_NO_GSSBFILE
Dieser Wert darf nur bei Folgeaufrufen in einer UTM-Cluster-Anwendung mit Objekttyp=KC_GSSB angegeben werden.
KC_READ_NO_GSSBFILE bewirkt, dass UTM nicht erneut auf die Cluster-GSSB-Datei zugreift, sondern die Daten aus dem letzten Aufruf mit KC_ASCENDING verwendet. Das Lesen von GSSBs wird dadurch performanter, siehe Hinweis unten.
UTM gibt die Informationen zu den GSSBs in aufsteigender Reihenfolge der Objektnamen zurück.
KC_READ_NO_USERFILE
Dieser Wert darf nur bei Folgeaufrufen in einer UTM-Cluster-Anwendung mit Objekttyp=KC_USER angegeben werden.
KC_READ_NO_USERFILE bewirkt, dass UTM nicht erneut auf die Cluster-User-Datei zugreift, sondern die Daten aus dem letzten Aufruf mit KC_ASCENDING verwendet. Das Lesen einer größeren Anzahl von Benutzerkennungen wird dadurch performanter, siehe Hinweis.
UTM gibt die Informationen zu den Benutzerkennungen in aufsteigender Reihenfolge der Objektnamen zurück.
Wenn Sie in UTM-Cluster-Anwendungen GSSBs oder Benutzerkennungen mit subopcode2=KC_ASCENDING oder subopcode2=KC_DESCENDING einlesen, dann werden alle Objekte von der Cluster-GSSB-Datei bzw. der Cluster-User-Datei lokal eingelesen und sortiert. Bei jedem neuerlichen Lesen von GSSBs/Benutzerkennungen mit diesem subopcode2 werden wieder alle GSSBs (max. 30000) bzw. alle Benutzerkennungen eingelesen und sortiert.
Wenn hohe Performance gewünscht ist, dann geben Sie KC_ASCENDING nur beim ersten Aufruf an und verwenden bei allen Folgeaufrufen KC_READ_NO_GSSBFILE bzw. KC_READ_NO_USERFILE. Änderungen, die nach dem ersten Aufruf stattfinden, werden dann jedoch nicht angezeigt.
obj_type
Im Feld obj_type müssen Sie den Typ der Objekte bzw. der Anwendungsparameter angeben, zu denen UTM Informationen liefern soll. Welche Angaben Sie in obj_type machen können, ist abhängig von dem in subopcode1 gesetzten Wert. Die erlaubten Angaben entnehmen Sie bitte der folgenden Tabelle. Die Bedeutung der Objekt-/Parametertypen ist im Abschnitt "Beschreibung der zu versorgenden Datenbereiche" (Objekt- und Parametertypen für Standard-Operationen).
Objekt-/Parametertyp | dürfen Sie angeben bei subopcode1 = |
Objekttyp: |
|
Objekttyp: |
|
Objekttyp: |
|
Parametertyp: |
|
Für obj_type=KC_USER, KC_USER_DYN1, KC_USER_DYN2 und KC_USER_FIX ist Folgendes zu beachten:
Für die Objekttypen KC_USER, KC_USER_DYN1, KC_USER_DYN2 und KC_USER_FIX sind die Datenstrukturen kc_user_str, kc_user_fix_str, kc_user_dyn1_str und kc_user_dyn2_str definiert.
In stand-alone UTM-Anwendungen können die Daten zu einem Benutzer immer über die Struktur kc_user_str abgefragt werden.
Die in den drei Datenstrukturen kc_user_fix_str, kc_user_dyn1_str und kc_user_dyn2_str enthaltenen Felder sind auch in der Datenstruktur kc_user_str enthalten. Die Aufteilung auf die drei Datenstrukturen wurde vorgenommen, um gezielt auf bestimmte Werte der Benutzerinformationen zugreifen zu können und auf diese Weise insbesondere die Performance beim Lesen der Benutzerinformation in UTM-Cluster-Anwendungen zu verbessern.
Alle Daten, die die Cluster-User-Datei betreffen, liegen in der Datenstruktur kc_user_dyn2_str.
Zum Lesen dieser Daten muss openUTM auf die Cluster-User-Datei zugreifen. Deswegen sollten Sie in UTM-Cluster-Anwendungen zum Lesen der Benutzerinformationen bevorzugt die neuen Objekttypen verwenden und KC_USER_DYN2 nur dann anfordern, wenn die von diesem Aufruf zurückgelieferten Daten aktuell benötigt werden.
Für obj_type=OSI_ASSOCIATION ist Folgendes zu beachten:
- Bei subopcode1=KC_NAME und KC_NAME_NEXT liefert UTM die bei der KDCDEF-Generierung festgelegten Namen der OSI TP-Associations zurück. Diese bestehen aus dem Association-Präfix, das in einer OSI-LPAP-Anweisung angegeben wurde, und einer laufenden Nummer.
Bei diesen Werten von subopcode1 können Sie im Identifikationsbereich einen Association-Namen angeben. Bei subopcode1=KC_ATTRIBUTES und KC_ATTRIBUTES_NEXT liefert UTM bei einem Aufruf nur die Eigenschaften von Associations zurück, die zu einer bestimmten Partner-Anwendung gehören und die entweder aufgebaut sind oder sich im Aufbau befinden. Aus diesem Grund müssen Sie beim Aufruf den OSI-LPAP-Partner der Partner-Anwendung als Selektionskriterium angeben. Dazu übergeben Sie im Selektionsbereich die Datenstruktur kc_osi_association_str mit dem Namen des OSI-LPAP-Partners (siehe "kc_osi_association_str - Associations zu OSI TP-Partner-Anwendungen").
Die Eigenschaften einer Association sind intern nicht unter dem Association-Namen abgelegt, sondern unter einer Association-Id. Die Association-Id ordnet UTM der Association zu, solange diese aufgebaut ist. Die Zuordnung der Association-Id zu dem Namen der Association ist nicht möglich. UTM interpretiert den im Identifikationsbereich angegebenen String (Feld kc_name8 der Union kc_id_area) deshalb als Association-ID. UTM liefert die Eigenschaften der aktiven Associations zu einer Partner-Anwendung nach den Association-Ids sortiert zurück. Es ist nicht möglich, die Eigenschaften zu einem Association-Namen abzufragen.
- Bei subopcode1=KC_NAME und KC_NAME_NEXT liefert UTM die bei der KDCDEF-Generierung festgelegten Namen der OSI TP-Associations zurück. Diese bestehen aus dem Association-Präfix, das in einer OSI-LPAP-Anweisung angegeben wurde, und einer laufenden Nummer.
Für obj_type=KC_HTTP_DESCRIPTOR ist Folgendes zu beachten:
- subopcode2 muss mit KC_ASCENDING versorgt werden.
- Der Identifikationsbereich kann verwendet werden.
- Der Selektionsbereich darf nicht verwendet werden.
- Die Ausgabe der Informationen zu den HTTP-Deskriptoren ist nicht nach Namen sortiert, sondern sie erfolgt in der Reihenfolge, in der die Anweisungen beim Empfang eines HTTP-Request ausgewertet werden um einen TAC zu bestimmen.
Für obj_type=KC_CHARACTER_SET ist Folgendes zu beachten:
- subopcode2 muss mit KC_ASCENDING versorgt werden.
- Der Identifikationsbereich kann verwendet werden.
- Der Selektionsbereich darf nicht verwendet werden.
- Die Ausgabe der Informationen zu den Character Sets ist nach Namen sortiert.
Für obj_type=KC_SUBNET ist Folgendes zu beachten:
- subopcode2 muss binär Null enthalten (KC_NO_SUBOPCODE).
- Der Identifikationsbereich kann verwendet werden.
- Der Selektionsbereich darf nicht angegeben werden.
Die Ausgabe der Informationen zu den Subnetzen ist nicht nach den Subnetznamen (mapped_name) sortiert, sondern sie erfolgt in der Reihenfolge, in der die Anweisungen bei der Generierung angegeben wurden - getrennt nach IPv4- und IPv6-Subnetzen.
Dies entspricht der Reihenfolge, in der die SUBNET-Einträge bei einem Verbindungsaufbau von außen ausgewertet werden.
obj_number
In obj_number können Sie die Anzahl der Objekte angeben, für die UTM Informationen zurückliefern soll. Folgende Angaben können Sie machen:
bei subopcode1=KC_NAME, KC_NAME_NEXT, KC_ATTRIBUTES und KC_ATTRIBUTES_NEXT:
obj_number legt die maximale Anzahl der Objekte fest, zu denen UTM Informationen zurückliefern soll.
Geben Sie obj_number=0 an, dann liefert UTM Informationen zu so vielen Objekten zurück, wie Daten in den Datenbereich passen, bzw. weniger, wenn keine weiteren Objekte des Objekttyps mehr vorhanden sind.
Bei obj_type=KC_CLUSTER_NODE ist zusätzlich Folgendes zu beachten:
Wenn Sie eine obj_number > 32 angeben, setzt openUTM die obj_number auf 32.bei subopcode1=KC_APPLICATION_PAR müssen Sie immer obj_number=0 setzen.
id_lth
Welche Angabe Sie im Feld id_lth machen müssen, ist abhängig von der Angabe im Feld subopcode1:
bei subopcode1=KC_NAME, KC_NAME_NEXT, KC_ATTRIBUTES und KC_ATTRIBUTES_NEXT:
In id_lth müssen Sie die Länge der Datenstruktur angeben, die Sie im Identifikationsbereich an UTM übergeben.
bei subopcode1=KC_APPLICATION_PAR müssen Sie immer id_lth=0 setzen. Der Inhalt des Identifikationsbereichs ist irrelevant.
select_lth
In select_lth müssen Sie einen Wert !=0 setzen, wenn Sie im Selektionsbereich Selektionskriterien an UTM übergeben wollen.
Bei subopcode1=KC_APPLICATION_PAR dürfen Sie keine Selektionskriterien an UTM übergeben, deshalb muss in diesem Fall immer select_lth=0 gesetzt werden.
Bei subopcode1=KC_ATTRIBUTES bzw. KC_ATTRIBUTES_NEXT und
obj_type= KC_OSI_ASSOCIATION müssen Sie im Selektionsbereich die Datenstruktur kc_osi_association_str mit dem Namen eines OSI-LPAP-Partners übergeben. In diesem Fall ist in select_lth die Länge der Datenstruktur kc_osi_association_str anzugeben.
Bei obj_type=KC_SUBNET und KC_HTTP_DESCRIPTOR müssen Sie immer select_lth=0 setzen.
data_lth
In data_lth müssen Sie die Länge des Datenbereichs angeben, den Sie UTM für die Rückgabe der angeforderten Informationen zur Verfügung stellen.
Bei subopcode1=KC_NAME, KC_NAME_NEXT, KC_ATTRIBUTES und KC_ATTRIBUTES_NEXT gilt:
Geben Sie obj_number!=0 an, dann muss der Datenbereich für die Rückgabe der angegebenen Anzahl groß genug sein. Bei obj_number=n (siehe .) müssen Sie für data_lth mindestens die Länge (n * maximale Länge des Objektnamens bzw.
n * Länge der Datenstruktur des Objekttyps in obj_type) angeben.
bei subopcode1=KC_APPLICATION_PAR müssen Sie mindestens die Länge der Datenstruktur des in obj_type gesetzten Parametertyps angeben.
Identifikationsbereich
Welche Angaben Sie im Identifikationsbereich machen müssen, ist abhängig von der Angabe im Feld subopcode1 und dem Wert von obj_type:
bei subopcode1=KC_NAME, KC_NAME_NEXT, KC_ATTRIBUTES und KC_ATTRIBUTES_NEXT:
Im Identifikationsbereich müssen Sie einen String an UTM übergeben. Der String gibt an, bei welchem Objekt UTM mit der Informationsausgabe beginnen soll.
Sie können im Identifikationsbereich auch binär null oder einen String aus nicht abdruckbaren Zeichen übergeben. UTM nimmt den angegebenen String wie er ist und sucht dazu den nächstgrößeren (bei subopcode2=KC_ASCENDING) bzw. nächstkleineren (bei subopcode2=KC_DESCENDING) Objektnamen.
Über den Identifikationsbereich legen Sie eine Union kc_id_area (siehe "Beschreibung der zu versorgenden Datenbereiche" (Identifikationsbereich: identification_area)). Der String muss in dem Unionelement übergeben werden, das zu dem in obj_type angegebenen Objekttyp gehört.
Bei obj_type=KC_PROGRAM und KC_LOAD_MODULE
übergeben Sie den String im Element kc_name32. Der Name muss linksbündig abgelegt werden, das restliche Feld muss entweder mit Leerzeichen aufgefüllt oder mit dem Null-Byte (\0) abgeschlossen werden.
Der angegebene String muss kein Objektname sein.Bei obj_type=KC_CON und KC_PTERM
müssen Sie den String im Unionelement kc_long_triple_str übergeben. In kc_long_triple_str kann ein Namenstripel (Objektname, Rechnername, Name der lokalen Anwendung) angegeben werden. Der Objektname und der Name der lokalen Anwendung können bis zu 8 Zeichen lang sein, der Rechnername bis zu 64 Zeichen.
Sie können für jeden der drei Namen einen beliebigen String angeben. Das müssen keine existierenden Namen zu sein. Es reicht auch, nur einen String für den Objektnamen anzugeben. Rechnername und den Namen der lokalen Anwendung müssen Sie nicht angeben, diese können Sie binär null setzen. Bei der Auswertung des Strings im Identifikationsbereich interpretiert UTM das Namenstripel als einen 80-stelligen Objektnamen. Der Startpunkt der Ausgabe wird entsprechend festgelegt.Bei obj_type=KC_MUX
müssen Sie den String im Unionelement kc_triple_str übergeben. In kc_triple_str kann ein Namenstripel (Objektname, Rechnername, Name der lokalen Anwendung) angegeben werden. Jeder Name kann bis zu 8 Zeichen lang sein. Sie können für jeden der drei Namen einen beliebigen String angeben. Das müssen keine existierenden Namen zu sein. Es reicht auch, nur einen String für den Objektnamen anzugeben. Rechnername und den Namen der lokalen Anwendung müssen Sie nicht angeben, diese können Sie binär null setzen. Bei der Auswertung des Strings im Identifikationsbereich interpretiert UTM das Namenstripel als einen 24-stelligen Objektnamen. Der Startpunkt der Ausgabe wird entsprechend festgelegt.
Bei obj_type=KC_DB_INFO
können Sie im Unionelement kc_name2 eine Ziffer zur Identifikation einer Datenbank angeben. Diese Ziffer repräsentiert die Datenbanken in der Reihenfolge, wie sie im KDCDEF-Lauf generiert wurden. Geben Sie einen anderen String an, wird der Aufruf abgewiesen.Bei obj_type=KC_SFUNC
können Sie im Unionelement kc_name4 eine gültige Funktionstaste angeben. Geben Sie einen anderen String an, wird der Aufruf abgewiesen.Gültige Angaben sind:
auf BS2000-Systemen: F1 bis F20 und K1 bis K14
auf Unix-, Linux- und Windows-Systemen: F1 bis F20Verzichten Sie auf eine Angabe im Identifikationsbereich, dann liefert UTM Informationen über alle Funktionstasten zurück.
Geben Sie eine gültige Funktionstaste an, dann beginnt UTM bei der Informationsausgabe mit dieser Funktionstaste.
Bei obj_type=KC_TACCLASS
können Sie im Unionelement kc_name2 die Werte einer existierenden TAC-Klasse angeben. Geben Sie einen anderen String an, wird der Aufruf abgewiesen.Bei obj_type=KC_OSI_ASSOCIATION
müssen Sie den String im Unionelement kc_name8 übergeben.
Bei subopcode1=KC_NAME und KC_NAME_NEXT interpretiert UTM den String als Namen einer OSI TP-Association.
Bei subopcode1=KC_ATTRIBUTES und KC_ATTRIBUTES_NEXT interpretiert UTM den String als Association-Id. Siehe dazu die Beschreibung unter obj_type.Bei obj_type=KC_CLUSTER_NODE
müssen Sie im Identifikationsbereich LOW VALUE, HIGH VALUE oder Leerfelder übergeben. Andernfalls wird der Aufruf abgewiesen. Es wird kein bestimmter Knoten angesprochen. Wählen Sie data_lth so groß, dass die Information zu allen Knoten ausgegeben werden kann.
Bei allen anderen Objekttypen muss der String im Unionelement kc_name8 übergeben werden. Der String muss linksbündig abgelegt werden, das restliche Feld sollte mit Leerzeichen aufgefüllt werden.
Der angegebene String muss kein Objektname sein.Wird bei obj_type=KC_SUBNET der Identifikationsbereich verwendet, dann muss der dort angegebene Name ein Objektname sein, d.h. er muss einem generierten Subnetznamen (mapped_name) entsprechen, da die Information zu den Subnetzen nicht alphabetisch sortiert, sondern in der bei der Generierung angegebenen Reihenfolge abgelegt ist. Wird kein generierter mapped_name angegeben, dann wird als Returncode KC_MC_NO_ELT mit Subcode KC_SC_NOT_EXISTENT zurückgegeben.
- Wird bei obj_type=KC_HTTP_DESCRIPTOR der Identifikationsbereich verwendet, dann muss der dort angegebene Name ein Objektname sein, d.h. er muss einem generierten HTTP-Deskriptor Namen entsprechen, da die Information zu den HTTP-Deskriptoren nicht alphabetisch sortiert, sondern in der bei der Auswertung maßgeblichen Reihenfolge abgelegt ist. Wird kein generierter Name angegeben, dann wird als Returncode KC_MC_NO_ELT mit Subcode KC_SC_NOT_EXISTENT zurückgegeben.
bei subopcode1=KC_APPLICATION_PAR sollte für den Identifikationsbereich der Nullpointer übergeben werden.
Selektionsbereich
Im Selektionsbereich müssen Sie bei select_lth !=0 die Datenstruktur des Objekttyps mit den Selektionskriterien an UTM übergeben. Die restlichen Felder der Datenstruktur müssen mit binär null versorgt werden.
Die Datenstrukturen sind im Abschnitt „Datenstrukturen zur Beschreibung der Objekteigenschaften" beschrieben. Der Name jeder Datenstruktur ist wie folgt aufgebaut: Zum Objekttyp „TYP“ gehört die Datenstruktur „typ_ str “, also z.B. zu KC_LTERM gehört die Datenstruktur kc_lterm_str.
Bei select_lth=0 wird der Selektionsbereich, d.h. die Selektionskriterien, nicht ausgewertet.
Ein Selektionskriterium ist eine Objekteigenschaft. Sind Selektionskriterien angegeben, so führt UTM eine Auswahl der Objekte durch. Es werden nur Informationen zu den Objekten zurückgeliefert, die den Selektionskriterien entsprechen. Im Folgenden ist für jeden Objekttyp aufgeführt, welche Selektionskriterien Sie angeben können.
Mögliche Selektionskriterien
obj_type=KC_CON: Verbindungen zu LU6.1-Partner-Anwendungen
Im Selektionsbereich übergeben Sie die Datenstruktur kc_con_str mit den Selektionskriterien. Folgende Angaben sind erlaubt:
Feldname
Bedeutung
connect_mode='Y'
UTM liefert Informationen über LU6.1-Verbindungen, die z.Zt. aufgebaut sind.
pronam_long
UTM liefert Informationen über LU6.1-Verbindungen zu Partner-Anwendungen, die auf einem bestimmten Rechner ablaufen. In pronam_long geben Sie den Namen des Rechners an.
delete
delete='Y':
UTM liefert Informationen über LU6.1-Verbindungen, die aus der Konfiguration gelöscht wurden.
delete='N':
UTM liefert Informationen über LU6.1-Verbindungen, die nicht aus der Konfiguration gelöscht wurden.Sie können auch mehrere Selektionskriterien zusammen angeben, d.h. mehrere Felder zusammen setzen.
obj_type=KC_LPAP: LPAP-Partner
Im Selektionsbereich übergeben Sie die Datenstruktur kc_lpap_str mit den Selektionskriterien. Folgende Angaben sind erlaubt:
Feldname
Bedeutung
master
master enthält den Namen eines Master-LPAPs eines LPAP-Bündels.UTM liefert Informationen über die Slave-LPAPs dieses LPAP-Bündels,
obj_type=KC_LSES: Sessions zu LU6.1-Partner-Anwendungen
Im Selektionsbereich übergeben Sie die Datenstruktur kc_lses_str mit den Selektionskriterien. Folgende Angaben sind erlaubt:
Feldname
Bedeutung
connect_mode='Y'
UTM liefert Informationen über Sessions, für die z.Zt. eine Transportverbindung aufgebaut ist.
lpap
UTM liefert Informationen über Sessions, die einer bestimmten LU6.1-Partner-Anwendung zugeordnet sind. In lpap geben Sie den Namen des LPAP-Partners an, der dieser Partner-Anwendung zugeordnet ist.
delete
delete='Y':
UTM liefert Informationen über Sessions, die aus der Konfiguration gelöscht wurden.
delete='N':
UTM liefert Informationen über Sessions, die nicht aus der Konfiguration gelöscht wurden.Sie können auch mehrere Selektionskriterien zusammen angeben, d.h. mehrere Felder zusammen setzen.
obj_type=KC_LTERM: LTERM-Partner
Im Selektionsbereich übergeben Sie die Datenstruktur kc_lterm_str mit den Selektionskriterien. Folgende Angaben sind erlaubt:
Feldname
Bedeutung
master
master enthält den Namen eines Master-LTERM in einem LTERM-Bündel:
UTM liefert Informationen über die Slave-LTERMs des LTERM-Bündels zum angegebenen Master-LTERM, master enthält den Namen eines Primary-LTERM in einer LTERM-Gruppe:
UTM liefert Informationen über die Gruppen-LTERMs der LTERM-Gruppe zum angegebenen Primary-LTERM.delete
delete='Y':
UTM liefert Informationen über LTERMs, die aus der Konfiguration gelöscht wurden.
delete='N':
UTM liefert Informationen über LTERMs, die nicht aus der Konfiguration gelöscht wurden.Sie können auch beide Selektionskriterien zusammen angeben, d.h. beide Felder zusammen setzen.
obj_type=KC_MUX: Multiplexanschlüsse (nur auf BS2000-Systemen)
Im Selektionsbereich übergeben Sie die Datenstruktur kc_mux_str mit den Selektionskriterien. Folgende Angaben sind erlaubt:
Feldname
Bedeutung
connect_mode='Y'
UTM liefert Informationen über Multiplexanschlüsse, für die z.Zt. eine Transportverbindung zum Nachrichtenverteiler aufgebaut ist.
pronam
UTM liefert Informationen über Multiplexanschlüsse, die für Nachrichtenverteiler auf einem bestimmten Rechner definiert sind. In pronam geben Sie den Namen des Rechners an.
Sie können auch beide Selektionskriterien zusammen angeben, d.h. beide Felder zusammen setzen.
obj_type=KC_OSI_ASSOCIATION: Associations zu OSI TP-Partner-Anwendungen
Bei subopcode1=KC_NAME und KC_NAME_NEXT darf kein Selektionskriterium angegeben werden.
Bei subopcode1=KC_ATTRIBUTES und KC_ATTRIBUTES_NEXT müssen Sie das folgende Selektionskriterium an UTM übergeben (siehe dazu die Beschreibung unter Punkt obj_type). Dazu übergeben Sie im Selektionsbereich die Datenstruktur kc_osi_association_str mit folgender Angabe:
Feldname
Bedeutung
osi_lpap
UTM liefert Informationen über Associations, die einer bestimmten OSI TP-Partner-Anwendung zugeordnet sind. In osi_lpap geben Sie den Namen des OSI-LPAP-Partners an, der dieser Partner-Anwendung zugeordnet ist.
obj_type=KC_OSI_LPAP: Eigenschaften von OSI TP-Partner-Anwendungen
Im Selektionsbereich übergeben Sie die Datenstruktur kc_osi_lpap_str mit den Selektionskriterien. Folgende Angaben sind erlaubt:
Feldname
Bedeutung
master
master enthält den Namen eines Master-LPAP in einem OSI-LPAP-Bündel:
UTM liefert Informationen über die Slave-LPAPs des LPAP-Bündels zum angegebenen Master-LPAP,obj_type=KC_PROGRAM: Teilprogramme
Im Selektionsbereich übergeben Sie die Datenstruktur kc_program_str mit den Selektionskriterien. Folgende Angaben sind erlaubt:
Feldname
Bedeutung
load_module
UTM liefert Informationen über Teilprogramme und VORGANG-Exits, die in einem bestimmten Lademodul, Shared Object, DLL eingebunden sind.
In load_module geben Sie den Namen des Lademoduls/Shared Objects/DLLs an.delete
delete='Y':
UTM liefert Informationen über Teilprogramme, die aus der Konfiguration gelöscht wurden.
delete='N':
UTM liefert Informationen über Teilprogramme, die nicht aus der Konfiguration gelöscht wurden.Sie können auch beide Selektionskriterien zusammen angeben, d.h. beide Felder zusammen setzen.
obj_type=KC_PTERM: Clients und Drucker
Im Selektionsbereich übergeben Sie die Datenstruktur kc_pterm_str mit den Selektionskriterien. Folgende Angaben sind erlaubt:
Feldname
Bedeutung
lterm
ist nur sinnvoll bei Druckern: UTM soll Informationen über die Drucker eines Druckerbündels zurückliefern. Die Drucker eines Druckerbündels sind demselben LTERM-Partner zugeordnet.
In lterm ist der Name des LTERM-Partners anzugeben.connect_mode='Y'
UTM liefert Informationen über Clients/Drucker, die z.Zt. mit der Anwendung verbunden sind.
pronam_long
UTM liefert Informationen über Clients/Drucker, die auf einem bestimmten Rechner ablaufen bzw. an diesem Rechner angeschlossen sind. In pronam_long geben Sie den Rechnernamen an.
delete
delete='Y':
UTM liefert Informationen über Clients/Drucker, die aus der Konfiguration gelöscht wurden.
delete='N':
UTM liefert Informationen über Clients/Drucker, die nicht aus der Konfiguration gelöscht wurden.Das Selektionskriterium lterm können Sie nur alleine angeben. Alle anderen Felder der Datenstruktur müssen dann mit binär null versorgt werden.
connect_mode und pronam_long bzw. pronam_long und delete können Sie zusammen angeben. connect_mode und delete dürfen nicht zusammen gesetzt werden.obj_type=KC_USER, KC_USER_DYN1, KC_USER_DYN2, KC_USER_FIX: Benutzerkennungen
Im Selektionsbereich übergeben Sie die Datenstruktur kc_user_str bzw. kc_user_dyn1_str mit den Selektionskriterien. Folgende Angaben sind erlaubt:
Feldname
Bedeutung
connect_mode='Y'
UTM liefert Informationen über Benutzerkennungen, mit denen z.Zt. ein Benutzer/Client bei der Anwendung angemeldet ist.
delete
delete='Y':
UTM liefert Informationen über Benutzerkennungen, die aus der Konfiguration gelöscht wurden.
delete='N':
UTM liefert Informationen über Benutzerkennungen, die nicht aus der Konfiguration gelöscht wurden.Die Selektionskriterien dürfen nicht zusammen angegeben werden, d.h. pro Aufruf darf nur ein Feld gesetzt werden.
obj_type=KC_LTAC oder KC_TAC: Transaktionscodes
Im Selektionsbereich übergeben Sie die Datenstruktur kc_ltac_str (KC_LTAC) oder kc_tac_str (KC_TAC) mit den Selektionskriterien. Folgende Angaben sind erlaubt:
Feldname
Bedeutung
delete
delete='Y':
UTM liefert Informationen über Transaktionscodes, die aus der Konfiguration gelöscht wurden.
delete='N':
UTM liefert Informationen über Transaktionscodes, die nicht aus der Konfiguration gelöscht wurden.
retcode
Im Feld retcode liefert UTM den Returncode des Aufrufs zurück. Neben den im Abschnitt „Returncodes" aufgelisteten Returncodes können zusätzlich folgende Returncodes auftreten.
Maincode = KC_MC_OK Der Aufruf wurde fehlerfrei bearbeitet. Subcodes: |
KC_SC_SAME Es wurde subopcode1=KC_NAME oder KC_ATTRIBUTES gesetzt und zu dem im Identifikationsbereich angegebenen Objektnamen existiert ein Objekt. Dieses Objekt wird im Datenbereich als erstes übergeben. |
KC_SC_NEXT Es wurde subopcode1=KC_NAME_NEXT oder KC_ATTRIBUTES_NEXT gesetzt. Oder es wurde subopcode1=KC_NAME oder KC_ATTRIBUTES gesetzt und zu dem im Identifikationsbereich angegebenen Objektnamen existiert jedoch kein Objekt. Das nächstgrößere bzw. nächstkleinere Objekt (abhängig von subopcode2) wird im Datenbereich als erstes übergeben. |
Maincode = KC_MC_LAST_ELT Der Aufruf wurde fehlerfrei bearbeitet, es wurden jedoch weniger Objekte gelesen als angefordert, da das letzte Objekt erreicht wurde. Subcodes: |
KC_SC_SAME Es wurde subopcode1=KC_NAME oder KC_ATTRIBUTES gesetzt. Zu dem im Identifikationsbereich angegebenen Objektnamen existiert ein Objekt. |
KC_SC_NEXT Es wurde subopcode1=KC_NAME_NEXT oder KC_ATTRIBUTES_NEXT gesetzt. Oder es wurde subopcode1=KC_NAME oder KC_ATTRIBUTES gesetzt und zu dem im Identifikationsbereich angegebenen Objektnamen existiert jedoch kein Objekt. Das nächstgrößere bzw. nächstkleinere Objekt (abhängig von subopcode2) wird im Datenbereich als erstes übergeben. |
Maincode = KC_MC_NO_ELT Es wurde subopcode1=KC_NAME, KC_NAME_NEXT, KC_ATTRIBUTES oder KC_ATTRIBUTES_NEXT gesetzt. Es ist kein bzw. kein nächstes Element zu dem angegebenen Objektnamen vorhanden. Subcode: |
KC_SC_NO_INFO |
KC_SC_NOT_EXISTENT (nur auf Unix-, Linux- und Windows-Systemen) Bei obj_type=KC_SUBNET wurde der im Identifikationsbereich angegebene Objektname nicht gefunden. |
Maincode = KC_MC_MEMORY_INSUFF UTM kann die Funktion nicht ausführen, da UTM für die Bearbeitung intern mehr Speicherplatz benötigt, als zur Verfügung steht. Subcode: |
KC_SC_NO_INFO |
Maincode = KC_MC_REJECTED Der Aufruf wurde von UTM abgewiesen, da kein Objekt des angegebenen Objekttyps existiert. Subcode: |
KC_SC_NOT_GEN Ist obj_type=KC_DB_INFO, dann wurde bei der KDCDEF-Generierung keine Datenbank generiert. |
KC_SC_NO_F_KEYS_GENERATED Sie haben obj_type=KC_SFUNC angegeben, es wurden für die Anwendung jedoch keine Funktionstasten generiert. (Siehe openUTM-Handbuch „Anwendungen generieren“) |
KC_SC_CCFG_FILE_READ_ERROR Nur bei UTM-Cluster-Anwendungen: |
KC_SC_CCFG_INVAL_NODE_BUFF_LTH Nur bei UTM-Cluster-Anwendungen: |
KC_SC_CCFG_FILE_LOCK_ERROR Nur bei UTM-Cluster-Anwendungen: |
KC_SC_CCFG_RT_CODE_NOT_OK Nur bei UTM-Cluster-Anwendungen: |
KC_SC_CUSF_USER_NOT_FOUND Nur bei UTM-Cluster-Anwendungen: |
KC_SC_CUSF_RT_CODE_NOT_OK Nur bei UTM-Cluster-Anwendungen: |
Maincode = KC_MC_NOT_EXISTENT Das angegebene Objekt existiert nicht. Subcode: |
KC_SC_NO_INFO obj_type=KC_DB_INFO, KC_SFUNC oder KC_TACCLASS: |
Maincode = KC_MC_SEL_INVALID Im Selektionsbereich wurden ungültige Daten angegeben. Subcode: |
KC_SC_NO_INFO |
number_ret
Nach einem Aufruf mit subopcode1=KC_NAME, KC_NAME_NEXT, KC_ATTRIBUTES oder KC_ATTRIBUTES_NEXT enthält number_ret die Anzahl der Objekte, zu denen UTM Informationen im Datenbereich zurückgeliefert hat.
Ist zu dem im Identifikationsbereich angegebenen String kein weiteres Objekt vorhanden, dann gibt UTM number_ret=0 und data_lth_ret=0 zurück und setzt einen entsprechenden Returncode.
Nach einem Aufruf mit subopcode1=KC_APPLICATION_PAR liefert UTM immer number_ret=0 zurück.
data_lth_ret
In data_lth_ret liefert UTM die Länge der Daten zurück, die UTM im Datenbereich hinterlegt hat.
Die Länge der zurückgelieferten Daten ist:
- bei subopcode1=KC_NAME, KC_NAME_NEXT:
Anzahl der Objekte * Länge des zum Objekttyp gehörenden Namensfelds
- subopcode1=KC_ATTRIBUTES oder KC_ATTRIBUTES_NEXT:
Anzahl der Objekte * Länge der Datenstruktur des Objekttyps
- subopcode1=KC_APPLICATION_PAR:
Länge der Datenstruktur des Parametertyps
Ist zu dem im Identifikationsbereich angegebenen String kein Objekt und auch kein weiteres Objekt vorhanden, dann gibt UTM data_lth_ret=0 zurück und setzt einen entsprechenden Returncode.
Datenbereich
Im Datenbereich liefert UTM die angeforderten Informationen zurück.
- subopcode1=KC_NAME, KC_NAME_NEXT:
UTM liefert einen Vektor von Objektnamen zurück. In dem Vektor sind die Objektnamen alphabetisch aufsteigend (bei subopcode2=KC_ASCENDING) oder absteigend (bei subopcode2=KC_DESCENDING) geordnet.
Die Länge der einzelnen Namen entspricht der Länge des Namensfeldes in der Datenstruktur des Objekttyps.
Bei obj_type=KC_CON und KC_PTERM liefert UTM einen Vektor von Namensstrukturen des folgenden Formats zurück:
struct kc_long_triple_str |
|
Bei obj_type=KC_MUX liefert UTM einen Vektor von Namensstrukturen des folgenden Formats zurück:
struct kc_triple_str |
|
Für jedes Objekt werden die drei Felder der Datenstruktur versorgt mit:
p_name
Objektname, d.h. der Name der Verbindung, des Client, Druckers oder des Multiplexanschlusses
pronam
Name des Rechners, auf dem sich das Objekt befindet
bcamappl
Name der lokalen Anwendung, über den die Verbindung zu diesem Objekt aufgebaut wird.
Der Namensvektor beginnt bei subopcode1=KC_NAME_NEXT immer mit dem Objektnamen, der in Bezug auf den im Identifikationsbereich angegebenen String der alphabetisch nächstgrößere bzw. nächstkleinere ist, je nach Wert von subopcode2.
Bei subopcode1=KC_NAME sind zwei Fälle zu unterscheiden:
Existiert ein Objektname, der mit dem String, den Sie im Identifikationsbereich angegeben haben, übereinstimmt, dann beginnt der Namensvektor mit diesem Objektnamen. UTM liefert den Sub-Returncode KC_SC_SAME zurück.
Entspricht der im Identifikationsbereich angegebene String keinem Objektnamen, dann beginnt der Namensvektor wie bei subopcode1=KC_NAME_NEXT mit dem Objektnamen, der in Bezug auf den im Identifikationsbereich angegebenen String der alphabetisch nächstgrößere bzw. nächstkleinere ist. UTM liefert den Sub-Returncode KC_SC_NEXT zurück.
- subopcode1=KC_ATTRIBUTES oder KC_ATTRIBUTES_NEXT:
UTM legt einen Vektor von Datenstrukturen des Objekttyps über den Datenbereich. Jede Datenstruktur enthält die Eigenschaften eines Objektes. Die Datenstrukturen liegen hintereinander und sind nach den Objektnamen alphabetisch auf- oder absteigend geordnet, je nach Wert von subopcode2.
Die Datenstrukturen sind im Abschnitt „Datenstrukturen zur Beschreibung der Objekteigenschaften" beschrieben. Der Name jeder Datenstruktur ist wie folgt aufgebaut: Zum Objekttyp „TYP“ gehört die Datenstruktur „typ_ str “, also z.B. zu KC_LTERM gehört die Datenstruktur kc_lterm_str.
In den Datenstrukturen sind die Felder, die beim Eintragen des Objekts in die Konfiguration nicht angegeben wurden, mit den Standardwerten, Leerzeichen oder '0' besetzt. Felder, die nur in einem anderen Betriebssystem relevant sind, sind mit binär null versorgt.
Mit welchem Objekt der Vektor beginnt, ist abhängig von subopcode1 und von dem im Identifikationsbereich angegebenen Namen.
Bei subopcode1=KC_ATTRIBUTES_NEXT beginnt der Vektor mit dem Objekt, das in Bezug auf den im Identifikationsbereich angegebenen String das alphabetisch nächstgrößere bzw. nächstkleinere ist, je nach Wert von subopcode2.
Bei subopcode1=ATTRIBUTES sind zwei Fälle zu unterscheiden:
Existiert ein Objektname, der mit dem String, den Sie im Identifikationsbereich angegeben haben, übereinstimmt, dann beginnt der Vektor mit diesem Objekt. UTM liefert den Sub-Returncode KC_SC_SAME zurück.
Entspricht der String keinem Objektnamen, dann beginnt der Vektor wie bei subopcode1=KC_ATTRIBUTES_NEXT mit dem Objekt, das in Bezug auf den im Identifikationsbereich angegebenen String das alphabetisch nächstgrößere bzw. nächstkleinere ist. UTM liefert den Sub-Returncode KC_SC_NEXT zurück.
- subopcode1=KC_APPLICATION_PAR:
UTM legt die Datenstruktur des in obj_type angegebenen Parametertyps über den Datenbereich. In der Datenstruktur liefert UTM die angeforderten Anwendungsparameter zurück.
Die Datenstrukturen sind im Abschnitt „Datenstrukturen zur Beschreibung der Anwendungsparameter" beschrieben. Der Name jeder Datenstruktur ist wie folgt aufgebaut: Zum Parametertyp „TYP“ gehört die Datenstruktur „typ_ str“, also z.B. zu KC_MAX_PAR gehört die Datenstruktur kc_max_par_str.
Beispiel für eine sukzessive Abfrage mit KC_ATTRIBUTES_NEXT
Aufgabe
Es soll die gesamte Information zu Benutzerkennungen gelesen werden, deren Namen mit „S“ beginnen. Es wird hier vorausgesetzt, dass solche Benutzerkennungen existieren.
Lösung
Erster KC_GET_OBJECT-Aufruf:
(Es wird vorausgesetzt, dass bei diesem Aufruf n Objekte gefunden werden, d.h. n_ret=n ist) Rückgaben von UTM:
Angaben im Parameterbereich: |
version=KC_ADMI_VERSION_1 opcode=KC_GET_OBJECT |
Angaben im Identifikationsbereich: 'S bbbbbbb ' or 'S\0' (b = blank, \0 = Null-Byte in C) |
Angaben im Selektionsbereich: keine |
Angaben im Datenbereich: keine |
Rückgaben von UTM:
Rückgaben im Parameterbereich: |
retcode= KC_MC_OK with subcode KC_SC_SAME or KC_SC_NEXT number_ret=n_ret data_lth_ret=n_ret*sizeof(struct kc_user_str) |
Rückgaben im Datenbereich: n_ret * Datenstruktur kc_user_str mit den Eigenschaften der Benutzerkennungen |
Beginnt die zuletzt ausgegebene Benutzerkennung noch mit „S“, dann muss ein weiterer Aufruf erfolgen.
Zweiter KC_GET_OBJECT-Aufruf:
(Angaben, die sich von denen beim ersten Aufruf unterscheiden, sind unterstrichen)
Angaben im Parameterbereich : |
version=KC_ADMI_VERSION_1 |
Angaben im Identifikationsbereich : Name der Benutzerkennung, die UTM beim ersten Aufruf als letzte zurückgeliefert hat |
Angaben im Selektionsbereich : keine |
Angaben im Datenbereich : keine |
Rückgaben von UTM:
Rückgaben im Parameterbereich: |
| retcode=KC_MC_OK with subcode KC_SC_NEXT 1 number_ret=n_ret (<= n) data_lth_ret=n_ret * sizeof(struct kc_user_str) |
Rückgaben im Datenbereich: n_ret * Datenstruktur kc_user_str mit den Daten der Benutzerkennungen |
1 | Es können auch die Returncodes KC_MC_LAST_ELT (falls weniger als n Objekte gefunden wurden) und KC_MC_NO_ELT (falls kein weiteres Objekt gefunden wurde) auftreten. |
Der zweite Aufruf wird dann solange wiederholt, bis alle Benutzerkennungen mit „S“ gelesen sind. Das erkennen Sie durch Auswertung der Rückgabedaten. D.h. beginnt der Name der Benutzerkennung, die UTM als letzte zurückliefert, mit „S“, dann muss der Aufruf nochmal wiederholt werden. Beginnt er nicht mit „S“ oder ist beim letzten Aufruf number_ret != obj_number, dann sind bereits alle Benutzerkennungen mit „S“ gelesen.