Die Programmierschnittstelle bietet Ihnen eine alternative Methode, auf Con-nect-Daten zuzugreifen. Ein derartiger Zugriff kann aus vielen verschiedenen Gründen erforderlich sein (z.B. Änderung der Firmenadresse, Telefonnummer oder Postleitzahl).
Um eine flexible und sichere Methode zu bieten, stellt Con-nect eine Reihe von parametergesteuerten API-Subprogrammen zur Verfügung. Jedes API-Subprogramm erfüllt eine bestimmte Aufgabe. Mit Hilfe der API-Subprogramme können Sie neue Objekte erstellen, existierende Objekte aktualisieren oder Informationen über existierende Objekte ausgeben.
Obwohl jedes der API-Subprogramme einem bestimmten Zweck dient, sind ihre Einsatzmöglichkeiten fast unbegrenzt. Dies bietet Ihnen ein hohes Maß an Kontrolle und Flexibilität beim Einsatz der API-Subprogramme, die je nach Bedarf in Ihre eigenen Programme eingebettet werden können.
Dieses Dokument behandelt die folgenden Themen:
Die API-Subprogramme werden in der Bibliothek SYSCNT2 ausgeliefert. Sie beginnen mit dem Präfix Z- (wie in Z-GET11C).
Die Nummer im Namen eines API-Subprogramms bezieht sich auf die Objektnummer. 10 ist zum Beispiel die Objektnummer für einen Verteiler. Demnach wird das Subprogramm Z-ADD10 zum EINGEBEN eines Verteiler benutzt. Siehe Objektnummern.
Anmerkung:
Es kann einem Benutzer verboten werden, TRS-Objekte mit Hilfe von
API-Subprogrammen aus einem Benutzerprogramm heraus zu bearbeiten. Siehe die
Beschreibung der Systemvorgaben in Con-nect
Administration, Abschnitt Con-nect Text
Retrieval.
Die Subprogramme, die von den API-Subprogrammen aufgerufen werden, werden ebenfalls in der Bibliothek SYSCNT2 ausgeliefert. Sie beginnen auch mit dem Präfix Z (wie in Z-120).
Jede Beschreibung eines API-Subprogramms enthält eine Liste der Subprogramme, die von dem API-Subprogramm aufgerufen werden (einschließlich aller Subprogramme, die wiederum von den Subprogrammen aufgerufen werden). Zum Beispiel:
Z-120
Z-122
Z-123
Z-1200&0
Die sprachabhängige Map Z-1200&0 muss sich in derselben Bibliothek oder Steplib befinden wie die API-Subprogramme. Diese Map wird aufgerufen, wenn ein Büro wegen zu vieler Zugriffsversuche mit einem falschen Passwort gesperrt wurde. Ein gesperrtes Büro kann nur von einem Büro- oder Systemadministrator wieder aufgesperrt werden. Natural ersetzt das Zeichen & in Z-1200&0 automatisch mit dem aktuellen Wert von *LANGUAGE. Der deutsche Name dieser Map ist also Z-120020.
Wenn Con-nect Text Retrieval und/oder der Transport Service installiert ist, werden von den meisten API-Subprogrammen zusätzliche Subprogramme aufgerufen.
Con-nect Text Retrieval
Die folgenden Subprogramme werden aufgerufen (zusätzlich zu denen, die
in der Beschreibung eines API-Subprogramms aufgelistet sind):
Z-283
Z-284
Transport Service
Die folgenden Subprogramme werden aufgerufen (zusätzlich zu denen, die
in der Beschreibung eines API-Subprogramms aufgelistet sind):
X-AMAIL
YA-CLOSE
YA-GETDA
YA-OPCR
YA-PUTDA
YA-PUTRE
YC-GET
YC-PUT
YCCORDAT
YCDMPSDE
YCLOG
YCSETUP
YCTCDAT
YFN5
YH-BCALL
YH-GETID
YH-GMT
YH-RMOBJ
YL-01
YL-02
Falls eine Anwendung nicht in der Bibliothek SYSCNT2 ausgeführt wird, sollten die API-Subprogramme und alle untergeordneten Subprogramme vor der Ausführung in die entsprechende Steplib kopiert werden.
Die wichtigsten Profildaten wie zum Beispiel der Büroname oder die aktuelle Zeitzone werden intern in einem API-Datenbereich gespeichert, der allen API-Subprogrammen zur Verfügung steht. Bei diesen Profildaten erfolgt nicht jedes Mal ein Zugriff auf die Datenbank, wenn ein API-Subprogramm aufgerufen wird. Der Zugriff erfolgt nur, wenn beim Aufruf verschiedener API-Subprogramme ein anderes Büro benutzt wird. Hierdurch wird die Performance deutlich erhöht.
Wenn die oben genannten Profildaten aus irgendeinem Grund nicht zur Verfügung stehen, werden Sie automatisch vom API-Subprogramm wiederhergestellt.
Con-form muss zur Verfügung stehen.
Die Bibliothek SYSCNT2 enthält lokale Datenbereiche (LDAs) für alle API-Subprogramme. Mit diesen LDAs können Sie sich Ihre Arbeit erleichtern.
Jeder LDA-Name beginnt mit dem Präfix "L-", gefolgt vom Namen eines API-Subprogramms. L-ADD05 ist also die LDA für das API-Subprogramm Z-ADD05.
Die LDA-Felder haben dieselben Namen wie die Parameter, die in der englischen Dokumentation verwendet werden.
Die Hierarchie ist in allen LDAs gleich. Somit können Sie mehrere LDAs gleichzeitig verwenden.
Beispiel:
1 LOCAL-ADD05 2 RETURN-CODE N 2 2 CABINET A 8 2 PASSWORD A 8 2 CABINET-NAME A 8 2 CABINET-TYPE N 1 2 LAST-NAME A 32 2 FIRST-NAME A 32 2 INITIAL A 1 2 DISALLOW-MAIL A 1 2 ISN P 8
Um eine LDA aufzurufen, müssen Sie in Ihrem API-Subprogramm nur den LDA-Namen im Statement DEFINE DATA LOCAL angeben. Beispiel:
DEFINE DATA LOCAL USING L-ADD05 END-DEFINE
Ausführliche Beispiele finden Sie bei den Beschreibungen von Z-ADD05 und Z-MODADR.
Wenn ein API-Subprogramm erfolgreich beendet wird, wird entweder der Wert 0 (Erfolg) oder 77 (Ende der Liste) im Parameter Return-Code ausgegeben.
Bei einem Fehler wird der entsprechende Wert im Parameter Return-Code ausgegeben. Jede Beschreibung eines API-Subprogramms enthält eine Liste der möglichen Return-Codes. Eine Liste aller Return-Codes finden Sie unter Return-Codes.
Anmerkung:
Mit dem Parameter Return-Code können Sie die Transaktionsverarbeitung
kontrollieren. Siehe Transaktionsverarbeitung.
Jedes API-Subprogramm enthält eine Liste aller erforderlichen Parameter. Zum Beispiel:
| Parameter | Format | Ein | Aus | Bemerkung |
|---|---|---|---|---|
| Return-Code | N2 | O | X | Eingabe -1: kein ET. |
| Buero | A8 | E | Das Büro, in dem sich das gewünschte Dokument befindet. | |
| Passwort | A8 | E | Das Passwort des o.g. Büros. | |
| Dokumentname | A32 | E* | Der Name des Dokuments, für das Sie die Beschreibung ausgeben möchten. Entweder Dokumentname oder ISN, nicht beides. | |
| ISN | P8 | E* | Die ISN des Dokuments, für das Sie die Beschreibung ausgeben möchten. | |
| Beschreibung | A60/1:4 | X | Die Beschreibung des Dokuments. |
Anmerkung:
Wenn der Name eines Parameters aus mehreren Worten besteht, enthält
er Bindestriche. Umlaute und der Buchstabe ß in einem Parameternamen führen zu
Natural-Problemen. Aus diesem Grund werden ae, oe, ue und ss in den
Parameternamen benutzt.
Die Parameter, die in der "Ein"-Spalte markiert sind, werden vom Benutzer eingegeben. Der Buchstabe E (erforderlich) bedeutet, dass Sie dem Parameter einen Wert zuordnen müssen. Der Buchstabe O (optional) bedeutet, dass Sie entscheiden können, ob Sie einen Wert zuordnen oder nicht.
Die Bezeichnung E* erscheint paarweise in der "Ein"-Spalte. In diesem Fall dürfen Sie nur einen der beiden mit E* gekennzeichneten Parameter angeben - Sie dürfen auf keinen Fall beide Parameter angeben.
Die Bezeichnung O* erscheint ebenfalls paarweise in der "Ein"-Spalte. In diesem Fall dürfen Sie nur einen der beiden mit O* gekennzeichneten Parameter angeben - Sie dürfen auf keinen Fall beide Parameter angeben.
Die Bezeichnung E/O bedeutet, dass Sie mindestens einen der mit E/O markierten Parameter angeben müssen. Wenn zum Beispiel drei Parameter mit E/O markiert sind, müssen Sie einen dieser Parameter mit einem Wert füllen; die beiden anderen Parameter sind optional.
Die Parameter, die in der "Aus"-Spalte mit X markiert sind, werden von dem API-Subprogramm ausgegeben.
Es ist nicht möglich, ein Objekt nicht über seine Beschreibung zu identifizieren. Die Beschreibung wird in der Regel in Klammern angezeigt. Um ein Objekt zu identifizieren, müssen Sie immer dessen Name (oder ISN) angeben.
Objekte in den Fächern Posteingang und Tageskopien haben keine Namen. Sie werden durch einen Betreff gekennzeichnet.
Ein Objektname wird in der Parameterliste folgendermaßen angegeben:
| Parameter | Format | Ein | Aus | Bemerkung |
|---|---|---|---|---|
| Dokumentname | A32 | E* | Der Name des Dokuments, für das Sie die Beschreibung ausgeben möchten. Entweder Dokumentname oder ISN, nicht beides. |
In einer Reihe von API-Subprogrammen wird der Parameter Anzahl benutzt. Dieser Parameter bestimmt die maximale Anzahl von Objekten, die mit jedem Aufruf ausgegeben werden. Der Vorgabewert ist 20. Sie können einen niedrigeren Wert angeben.
Der Parameter Anzahl wird in der Parameterliste folgendermaßen angegeben:
| Parameter | Format | Ein | Aus | Bemerkung |
|---|---|---|---|---|
| Anzahl | N2 | O | Die maximale Anzahl von Objekten, die mit jedem Aufruf ausgegeben werden. Wenn Sie keinen Wert definieren oder einen Wert, der größer ist als 20, wird der Vorgabewert 20 benutzt. |
Ein Subprogramm, mit dem eine Liste von Objekten ausgegeben wird, sollte solange iterativ aufgerufen werden, bis der Return-Code 77 das Ende der Liste kennzeichnet. Zum Beispiel:
REPEAT UNTIL RETURN-CODE = 77
CALLNAT 'Z-DIS23'
RETURN-CODE
BUERO
START-WERT
ANZAHL
PROFILLISTE (*)
WORK-PARAMETER
UNTIL RETURN-CODE NE 0
END-REPEAT
In einer Reihe von API-Subprogrammen wird der Work-Parameter benutzt. Dieser Parameter dient als Buffer, wenn ein API-Subprogramm iterativ aufgerufen wird.
Der Work-Parameter wird nur intern benutzt. Sie können ihn bei der Bearbeitung eines bestimmten Objekts nicht verändern. Da der Parameter bei jedem Aufruf gefüllt wird, müssen Sie ihn zurücksetzen, wenn ein anderes Objekt mit demselben API-Subprogramm bearbeitet werden soll.
Der Work-Parameter wird in der Parameterliste folgendermaßen angegeben:
| Parameter | Format | Ein | Aus | Bemerkung |
|---|---|---|---|---|
| Work-Parameter | A46 | Für den internen Gebrauch. |
In der Parameterliste werden in der Spalte "Bemerkung" immer die Personen aufgeführt, die das API-Subprogramm benutzen dürfen. Grundsätzlich darf jeder, der das Passwort eines Privatbüros kennt, in diesem Büro arbeiten.
| Parameter | Format | Ein | Aus | Bemerkung |
|---|---|---|---|---|
| Buero | A8 | E | Das Büro, in dem der Termin eingegeben werden soll. | |
| Passwort | A8 | E | Das Passwort des o.g. Büros. |
Wenn das Bürokennzeichen, das Sie hier angeben, und das Teilnehmerkennzeichen, mit dem Sie zur Zeit eingeloggt sind, gleich sind, ist ein Passwort nicht erforderlich. Wenn Sie ein Passwort angeben, wird es nicht geprüft.
Wenn das Bürokennzeichen mit dem Teilnehmerkennzeichen, mit dem Sie zur Zeit eingeloggt sind, nicht übereinstimmt (d.h. wenn Sie auf ein anderes als Ihr eigenes Büro zugreifen wollen), ist ein Passwort erforderlich. In diesem Fall wird das Passwort überprüft. Es wird nicht geprüft, ob Sie die Zugriffsberechtigung für dieses Büro besitzen.
Auf das Büro SYSCNT kann nur ein Systemadministrator oder Supervisor zugreifen.
Wenn Sie SYSCNT als Bürokennzeichen eingeben und Sie vom System als Systemadministrator oder Supervisor erkannt werden (anhand des Teilnehmerkennzeichens und des Passworts, mit dem Sie zur Zeit eingeloggt sind), ist ein Passwort nicht erforderlich. Wenn Sie ein Passwort angeben, wird es nicht überprüft.
Wenn ein API-Subprogramm nur von einem Administrator benutzt werden darf, wird dies in der Spalte "Bemerkung" folgendermaßen angegeben:
| Parameter | Format | Ein | Aus | Bemerkung |
|---|---|---|---|---|
| Buero | A8 | E | Das Bürokennzeichen eines Supervisors oder Systemadministrators. | |
| Passwort | A8 | E | Das Passwort des o.g. Büros. |
Wenn das Bürokennzeichen, das Sie hier angeben, und das Teilnehmerkennzeichen, mit dem Sie zur Zeit eingeloggt sind, gleich sind, und Sie vom System als Administrator erkannt werden, ist ein Passwort nicht erforderlich. Wenn Sie ein Passwort angeben, wird es nicht überprüft.
In diesem Fall wird mit Hilfe des Parameters Buero lediglich überprüft, ob der Teilnehmer, der das API-Subprogramm aufruft, den erforderlichen Administratorstatus hat.
Wenn ein Teilnehmer auf ein anderes Privatbüro als sein eigenes zugreift, werden alle Objekte, die in diesem Büro als persönliche Objekte definiert wurden, von den API-Subprogrammen ignoriert.
Bei einem Fach, das als persönliches Fach definiert wurde, müssen Sie jedoch Folgendes beachten: die Objekte, die in diesem Fach abgelegt sind, sind nicht automatisch auch persönliche Objekte. Ein persönliches Fach wird nicht in einer Liste aller Fächer angezeigt, wenn ein anderer Teilnehmer in Ihrem Büro arbeitet. Wenn der Teilnehmer jedoch zum Beispiel eine Liste aller Dokumente in Ihrem Büro anzeigt, so enthält die Liste auch die Dokumente, die in einem persönlichen Fach abgelegt wurden.
In einer Reihe von API-Subprogrammen wird der Parameter Berechtigungsstufen benutzt. Dieser Parameter bestimmt die Berechtigungsstufen, die ein anderer Teilnehmer haben muss, um ein Objekt in dem Büro, auf das er zugreift, zu lesen (zeigen), ändern, kopieren oder zu drucken.
| Parameter | Format | Ein | Aus | Bemerkung |
|---|---|---|---|---|
| Berechtigungsstufen | A1/1:4 | O | Die Berechtigungsstufen für Lesen, Ändern, Kopieren und Drucken. Werte 0 bis 9. |
Das erste Zeichen bestimmt die Berechtigungsstufe für das Lesen, das Zweite für das Ändern, das Dritte für das Kopieren und das Vierte für das Drucken. Die Berechtigungsstufen können zwischen 0 (niedrigste Stufe) und 9 (höchste Stufe) liegen.
Die erfolgreiche Ausführung eines API-Subprogramms wird immer mit einem END TRANSACTION abgeschlossen. In diesem Fall wird der Wert 0 im Parameter Return-Code ausgegeben.
Bei verschiedenen API-Subprogrammen können Sie die Transaktionsverarbeitung kontrollieren. Bevor Sie ein API-Subprogramm mit dem CALLNAT-Statement aufrufen, können Sie den Wert -1 (minus 1) an den Parameter Return-Code übergeben, damit kein END TRANSACTION erfolgt.
Wenn es bei einem API-Subprogramm erlaubt ist, den Wert -1 an den Parameter Return-Code zu übergeben, damit kein END TRANSACTION erfolgt, so wird dies in der Parameterliste in der Spalte "Bemerkung" folgendermaßen dargestellt:
| Parameter | Format | Ein | Aus | Bemerkung |
|---|---|---|---|---|
| Return-Code | N2 | O | X | Eingabe -1: kein ET. |
Das API-Subprogramm akzeptiert nur den Wert -1. Wenn Sie einen anderen Wert an den Parameter Return-Code übergeben, wird dieser Wert ignoriert und auf 0 gesetzt.
Weitere Informationen zum Statement END TRANSACTION finden Sie in der Natural-Dokumentation.
Ausnahme: Wenn Sie Post im Ordner Neu des Fachs Posteingang bearbeiten, wird die dazugehörende Empfängerliste aktualisiert (d.h. der Empfangsstatus des Objekts weist nun darauf hin, dass das Objekt gelesen wurde) und die Post wird in den Ordner Gelesen gestellt. In diesem Fall erfolgt automatisch ein END TRANSACTION (wenn Sie in diesem Fall vorher den Wert -1 an den Parameter Return-Code übergeben haben, so wird dies ignoriert).
Mit Con-nect Version 3 wurde das Format des Parameters ISN von P8 auf P10 geändert. Alle neuen API-Subprogramme benutzen von nun an das Format P10.
Die Parameter der API-Subprogramme, die bereits mit früheren Con-nect-Versionen ausgeliefert wurden, wurden nicht verändert. Um jedoch einen Natural-Fehler zu vermeiden, wenn die ISN zum Beispiel nicht in das 8 Stellen lange Ausgabefeld passt, wurden diese API-Subprogramme wie unten beschrieben überarbeitet.
Die unten aufgeführten API-Subprogramme werden zum Erstellen von Objekten benutzt. Die API-Subprogramme geben die ISN des neuen Objekts aus. Sie können die Transaktionsverarbeitung kontrollieren, indem Sie den Wert -1 an den Parameter Return-Code übergeben.
Z-ADD01
Z-ADD01A
Z-ADD01B
Z-ADD01T
Z-ADD10
Z-ADD11
Z-ADD11C
Z-ADD17
Z-ADD27
Z-ADD79
Z-ADDOBJ
Z-MAILA
Z-TRACNF
Z-TRADCA
Z-TRAINT
Wenn die ISN den Wert 99.999.999 übersteigt, gelten die folgenden Ausnahmen:
Wenn Sie den Wert -1 benutzen, wird das Objekt erstellt, die ISN wird nicht ausgegeben und END TRANSACTION wird nicht ausgeführt.
Wenn Sie den Wert -1 nicht benutzen, wird das Objekt nicht erstellt und BACKOUT TRANSACTION wird ausgeführt.
Wenn die ISN den Wert 99.999.999 übersteigt, wird immer der Return-Code 17 (ISN hat mehr als 8 Stellen) ausgegeben - auch wenn das Objekt erstellt wurde.
Die unten aufgeführten API-Subprogramme werden zum Erstellen von Objekten benutzt. Die API-Subprogramme geben die ISN des neuen Objekts aus. Die erfolgreiche Ausführung dieser API-Subprogramme wird immer mit einem END TRANSACTION abgeschlossen. Sie können die Transaktionsverarbeitung nicht kontrollieren.
Wenn die ISN den Wert 99.999.999 übersteigt, können Sie den Wert -1 an den Parameter Return-Code übergeben (Sie können die Transaktionsverarbeitung hierdurch jedoch nicht kontrollieren). Es gelten die folgenden Regeln:
Wenn Sie den Wert -1 benutzen, wird das Objekt erstellt, die ISN wird nicht ausgegeben und END TRANSACTION wird ausgeführt.
Wenn Sie den Wert -1 nicht benutzen, wird das Objekt nicht erstellt und BACKOUT TRANSACTION wird ausgeführt.
Wenn die ISN den Wert 99.999.999 übersteigt, wird immer der Return-Code 17 (ISN hat mehr als 8 Stellen) ausgegeben - auch wenn das Objekt erstellt wurde.
Die unten aufgeführten API-Subprogramme werden zum Ausgeben einer Objektliste benutzt. Für jedes Objekt in der Liste wird auch die ISN ausgegeben.
Z-DIS04A
Z-DIS05
Z-DIS11
Z-DIS13A
Z-SEARCH
Z-SRCH03
Wenn die ISN den Wert 99.999.999 übersteigt, gilt die folgende Ausnahme: im Parameter ISN wird der Wert 0 ausgegeben und der Return-Code ist 0 (Erfolg).
Die unten aufgeführten API-Subprogramme werden zum Ausgeben eines bestimmten Objekts benutzt. Sie können das auszugebende Objekt entweder über den Namen oder die ISN spezifizieren.
Z-FIL11
Z-FILOB
Z-GET01
Z-GET01T
Z-GETOBJ
Z-IN11G2
Z-IN11U1
Z-INOBG
Z-INOBU
Z-MOD01A
Z-MOD01T
Wenn die ISN den Wert 99.999.999 übersteigt, können Sie das Objekt nur über den Namen spezifizieren und es gilt die folgende Ausnahme: im Parameter ISN wird der Wert 0 ausgegeben und der Return-Code ist 0 (Erfolg).
Z-INBKT wird dazu benutzt, die Anzahl der Objekte in den verschiedenen Ordnern des Posteingangsfachs auszugeben. Wenn die Anzahl der Objekte in einem bestimmten Ordner den Wert 99.999.999 übersteigt, gilt die folgende Ausnahme: in dem entsprechenden Parameter wird der Wert 99.999.999 ausgegeben und der Return-Code ist 0 (Erfolg).
Ab Con-nect Version 3 tritt ein Fehler auf, wenn Sie die folgenden Zeitangaben benutzen:
| 24:mm | Entspricht 0:mm des folgenden Tages. |
| hh:60 | Entspricht hh:00 der folgenden Stunde. |
Sie müssen darauf achten, dass die oben aufgeführten Zeitangaben nicht in Ihren Benutzerprogrammen enthalten sind.