Mit dem Aufruf APRO (address program) adressieren Sie im Auftraggeber-Vorgang einen Auftragnehmer-Vorgang oder eine TAC-Queue. Der APRO-Aufruf ist nur bei verteilter Verarbeitung anwendbar. Die Daten an den Auftragnehmer-Vorgang werden mit MPUT bzw. FPUT/DPUT gesendet, wobei man bei diesen Aufrufen als Empfänger die im APRO-Aufruf definierte Vorgangs-Id angibt.
Versorgen des 1. Parameters (KDCS-Parameterbereich)
Die folgende Tabelle zeigt die verschiedenen Möglichkeiten und die dafür notwendigen Angaben im KDCS-Parameterbereich.
Funktion des Aufrufs | Einträge im KDCS-Parameterbereich | ||||||
|---|---|---|---|---|---|---|---|
KCOP | KCOM | KCLM | KCRN | KCPA | KCPI | KCOF | |
Adressieren eines Dialog-Vorgangs | "APRO" | "DM" | 0/19/58 | LTAC-Name | (OSI-)LPAP-Name/Master-LPAP-Name/Leerzeichen | Vorgangs-Id | erlaubte OSI-Funktion |
Adressieren eines Asynchron-Vorgangs oder einer TAC-Queue | "APRO" | "AM" | 0/19/58 | LTAC-Name | (OSI-)LPAP-Name/Master-LPAP-Name/Leerzeichen | Vorgangs-Id | erlaubte OSI-Funktion |
Die Angabe im Feld KCPA ist abhängig von der Art der Adressierung:
bei einstufiger Adressierung muss das Feld Leerzeichen enthalten,
bei zweistufiger Adressierung muss das Feld den Namen der Partner-Anwendung enthalten ((OSI-)LPAP-Name bzw. Master-LPAP-Name).
Näheres zur ein- bzw. zweistufigen Adressierung von Auftragnehmer-Vorgängen bei verteilter Verarbeitung finden Sie im openUTM-Handbuch „Konzepte und Funktionen“.
Versorgen des 2. Parameters (Auswahl spezieller OSI TP-Funktionskombinationen)
Der 2. Parameterbereich findet nur Verwendung bei der Kommunikation über das OSI TP-Protokoll. Er erlaubt es, andere Funktionskombinationen zu spezifizieren, als über die Standardauswahl mittels des KDCS-Parameters KCOF möglich sind. Außerdem kann ausgewählt werden, ob SIGNON-Daten an den Auftragnehmer-Vorgang übergeben werden sollen. Für den 2. Parameterbereich ist eine Sprach-spezifische Datenstruktur verfügbar; für COBOL im COPY-Element KCAPROC, für C/C++ in der Include-Datei kcapro.h.
Wenn der 2. Parameterbereich verwendet wird, dann muss im Feld KCLM der Wert 19 bzw. 58 als Länge der Datenstruktur angegeben werden, und das Feld KCOF muss den Wert "O" enthalten.
Versorgen der Parameter im KDCS-Parameterbereich | |
Feldname im KDCS-Parameterbereich | Inhalt |
"APRO" | |
"DM"/"AM" | |
0/19/58 | |
LTAC-Name | |
(OSI-)LPAP-Name/Master-LPAP-Name/Leerzeichen | |
Vorgangs-Id | |
OSI-Funktionen | |
Versorgen der Parameter im 2. Parameterbereich (nur bei KCOF=O) | |
Feldname im 2. Parameterbereich | Inhalt |
Versionsnummer der Datenstruktur | |
Polarized FU (Y) | |
Handshake FU (Y/N) | |
Commit FU (Y/N) | |
Chained FU (Y/Leerzeichen) | |
KCFUFILL | leer - für spätere Erweiterungen |
Security-Typ (N/S/P) | |
Datentyp der Benutzerkennung (P/T/O) | |
Länge der Benutzerkennung | |
Benutzerkennung | |
KCSECFIL | leer - für spätere Erweiterungen |
Datentyp des Passworts (P/T/O) | |
Länge des Passworts | |
Passwort | |
KDCS-Aufruf | |
KDCS-Parameterbereich | 2. Parameterbereich |
C/C++-Makroaufrufe | |
Parameter | |
KDCS_APRODM / KDCS_APROAM | (kcrn,kcpa,kcpi) |
KDCS_APRODM_OSI / KDCS_APROAM_OSI | (kcrn,kcpa,kcpi,kcof) |
KDCS_APRODM_OSI_O / KDCS_APROAM_OSI_O | (nb,kclm,kcrn,kcpa,kcpi) |
Im KDCS-Parameterbereich machen Sie für den APRO-Aufruf folgende Angaben:
KCOP
Im Feld KCOP geben Sie den Operationscode APRO an.
KCOM
Im Feld KCOM tragen Sie die Operationsmodifikation ein:
DM (Dialog Message) zur Adressierung eines Dialog-Vorgangs
AM (Asynchronous Message) zur Adressierung eines Asynchron-Vorgangs oder einer TAC-Queue.
KCLM
Im Feld KCLM geben Sie die Länge des 2. Parameterbereichs an:
falls kein 2. Parameterbereich, verwendet wird, die Länge 0.
falls ein 2. Parameterbereich verwendet wird und Security-Typ "N" oder "S" gewählt ist, die Länge 19.
falls ein 2. Parameterbereich verwendet wird und Security-Typ "P" gewählt ist, die Länge 58.
KCRN
Im Feld KCRN geben Sie den logischen Transaktionscode (LTAC-Namen) des Auftragnehmer-Vorgangs an.
KCPA
Ob Sie im Feld KCPA die Partner-Anwendung identifizieren müssen, hängt von der Art der Adressierung ab:
Bei zweistufiger Adressierung tragen Sie den logischen Namen der Partner-Anwendung ein, d.h. den LPAP-Namen, OSI-LPAP-Namen oder Master-LPAP-Namen eines OSI-LPAP- oder LU6.1-LPAP-Bündels.
Bei einstufiger Adressierung tragen Sie Leerzeichen ein (der Name der Partner-Anwendung wird dann aus der Generierungsanweisung LTAC genommen).
Die Angabe der Partner-Anwendung in KCPA hat Priorität vor der bei der Generierung in der LTAC-Anweisung spezifizierten Partner-Anwendung.
KCPI
Im Feld KCPI vergeben Sie die Vorgangs-Id, mit der der Auftragnehmer-Vorgang im Auftraggeber-Vorgang bei den Aufrufen MPUT, MCOM, FPUT, DPUT bzw. MGET angesprochen werden soll. Die Vorgangs-Id muss mit dem Zeichen ">" beginnen.
KCOF
Das Feld KCOF enthält die bei der Kommunikation mit einem OSI TP-Partner erlaubten Funktionen (bei Kommunikation über das LU6.1-Protokoll irrelevant).
Mögliche Werte:
B (basic functions)
BasisfunktionenH (handshake functions)
Basis- und Handshake-Funktionen (nur bei APRO DM möglich)C (chained transactions)
Basis- und Commit-Funktionen mit Chained TransactionsO (other combination)
Die Auswahl der Funktionen geschieht über den 2. Parameterbereich; d.h. wenn KCOF=O angegeben wird, dann muss bei dem KDCS-Aufruf ein 2. Parameterbereich übergeben werden.
Im 2. Parameterbereich geben Sie an:
KCVERS
Im Feld KCVERS geben Sie die Versionsnummer der Datenstruktur an: in dieser openUTM-Version ist dies 1.
KCFUPOL
in das Feld KCFUPOL tragen Sie ein, ob die Functional Unit "Polarized Control" ausgewählt werden soll. Da "Shared Control" in dieser Version nicht unterstützt wird, ist hier nur die Angabe "Y" zulässig.
KCFUHSH
In das Feld KCFUHSH tragen Sie ein, ob die Functional Unit "Handshake" ausgewählt werden soll (Y/N).
Wird ein Asynchron-Vorgang adressiert (APRO AM), muss für KCFUHSH "N" angegeben werden.
KCFUCOM
In das Feld KCFUCOM tragen Sie ein, ob die Functional Unit "Commit" ausgewählt werden soll (Y/N). Die Functional Unit "Commit" kann nur ausgewählt werden, wenn der adressierte OSI-LPAP-Partner im Application Context die abstrakte Syntax CCR enthält (Commitment, Concurrency and Recovery).
KCFUCHN
In das Feld KCFUCHN tragen Sie ein, ob die Functional Unit "Chained Transactions" ausgewählt werden soll. Dieses Feld ist nur von Bedeutung, wenn auch die Functional Unit "Commit" ausgewählt wurde, d.h. KCFUCOM=Y angegeben ist.
Da "Unchained Transactions" in dieser Version nicht unterstützt wird, ist hier - falls Functional Unit "Commit" ausgewählt wurde - nur die Angabe "Y" zulässig.
Falls die Functional Unit "Commit" nicht ausgewählt wurde, ist das Feld KCFUCHN bedeutungslos. In diesem Fall müssen Sie ein Leerzeichen eintragen.
KCSECTYP
Im Feld KCSECTYP wählen Sie den Security-Typ aus.
Der Security-Typ regelt, ob SIGNON-Daten (Benutzerkennung und Passwort) an den Auftragnehmer-Vorgang übergeben werden:
N (none)
Es werden keine SIGNON-Daten an den Auftragnehmer-Vorgang übergeben.S (same)
Es wird die Benutzerkennung an den Auftragnehmer-Vorgang übergeben, unter der der lokale Vorgang läuft.P (program)
Es werden die in den Feldern KCUSERID und KCPSWORD spezifizierten Werte als Benutzerkennung und Passwort an den Auftragnehmer-Vorgang übergeben.
Security-Typ "S" oder "P" können Sie nur dann auswählen, wenn der adressierte OSI-LPAP-Partner im Application Context die abstrakte Syntax UTMSEC enthält.
KCUIDTYP
Im Feld KCUIDTYP tragen Sie den Datentyp der im Feld KCUSERID angegebenen Benutzerkennung ein:
P: Der im Feld KCUSERID angegebene String ist vom Typ "Printable String".
T: Der im Feld KCUSERID angegebene String ist vom Typ "T61 String".
O: Der im Feld KCUSERID angegebene String ist vom Typ "Octet String".Octet String ist eine hexadezimale Zeichenfolge. Es erfolgt keine Code-Umsetzung.
Die Wertebereiche dieser Datentypen sind im openUTM-Handbuch „Anwendungen generieren“ bei der KDCDEF-Anweisung LTAC beschrieben.
KCUIDLTH
Im Feld KCUIDLTH tragen Sie die Länge der im Feld KCUSERID angegebenen Benutzerkennung ein (in Byte, maximal 16).
KCUSERID
Im Feld KCUSERID geben Sie die Benutzerkennung an, die - falls KCSECTYP=P gesetzt ist - an den Auftragnehmer-Vorgang übergeben wird.
KCPWDTYP
Im Feld KCPWDTYP tragen Sie den Datentyp des im Feld KCPSWORD angegebenen Passworts ein:
P: Der im Feld KCPSWORD angegebene String ist vom Typ "Printable String".
T: Der im Feld KCPSWORD angegebene String ist vom Typ "T61 String".
O: Der im Feld KCPSWORD angegebene String ist vom Typ "Octet String" (siehe auch Feld KCUIDTYP).
Die Wertebereiche dieser Datentypen sind im openUTM-Handbuch „Anwendungen generieren“ bei der KDCDEF-Anweisung LTAC beschrieben.
KCPWDLTH
Im Feld KCPWDLTH tragen Sie die Länge des im Feld KCPSWORD angegebenen Passworts ein (in Byte, maximal 16). Falls kein Passwort übergeben wird, muss null angegeben werden.
KCPSWORD
Im Feld KCPSWORD geben Sie das Passwort an, das - falls KCSECTYP=P gesetzt ist - an den Auftragnehmer-Vorgang übergeben wird.
Beim KDCS-Aufruf geben Sie an:
1. Parameter
Die Adresse des KDCS-Parameterbereichs.
2. Parameter
(wenn benötigt): Die Adresse des 2. Parameterbereichs (Auswahl spezieller OSI TP-Funktionskombinationen).
Makronamen
Wie Sie Makroaufrufe für C/C++ nutzen, ist in Abschnitt „C/C++-Makroschnittstelle" ausführlich beschrieben.
openUTM gibt zurück:
KCRCCC
im Feld KCRCCC den KDCS-Returncode, siehe unten.
KCRCDC
KDCS-Returncodes im Feld KCRCCC beim APRO-Aufruf
Im Programm sind auswertbar:
000 | Die Funktion wurde ausgeführt. |
40Z | openUTM kann die Funktion nicht durchführen. Es liegt ein Generierungs- oder ein Systemfehler vor, oder die Funktion APRO wurde aufgerufen und die Anwendung ohne verteilte Verarbeitung generiert, oder es ist zurzeit keine Verbindung zur Partner-Anwendung möglich (siehe Eintrag in KCRCDC). |
41Z | Unzulässiger APRO-Aufruf. Dies kann z.B. einen der folgenden Gründe haben:
|
42Z | Der Eintrag in KCOM ist ungültig. |
43Z | Der Eintrag in KCLM ist ungültig. |
44Z | Der Wert in KCRN bezeichnet keinen gültigen LTAC eines Auftragnehmer-Vorgangs.
|
46Z | Der Eintrag in KCPA ist ungültig, d.h. unter dem angegebenen Namen ist keine Partner-Anwendung generiert oder es wurden in KCPA Leerzeichen angegeben und in der LTAC-Generierungsanweisung kein Anwendungsname definiert. |
47Z | Es wurde KCOF=O angegeben, aber der 2. Parameterbereich fehlt oder ist ungültig. |
48Z | Ungültige Version der Datenstruktur. |
55Z | Der Eintrag in KCPI ist ungültig (beginnt nicht mit ">") oder die Vorgangs-Id wurde vom Auftraggeber-Vorgang bereits vergeben. |
58Z | Der Wert in KCOF ist ungültig. |
Weitere Returncodes sind dem DUMP zu entnehmen:
71Z | INIT-Aufruf fehlt oder im MSGTAC-Programm wurde die Ausprägung DM gegeben. |
89Z | Bei der Adressierung eines OSI TP-Auftragnehmers sind die nicht verwendeten Felder des KDCS-Parameterbereichs nicht mit binär null versorgt worden. |
Eigenschaften des APRO-Aufrufs
Ein Vorgang, der mit einer Partner-Anwendung über das OSI TP-Protokoll kommuniziert und dabei die Functional Unit "Commit" nutzt, kann nicht mit einer anderen Partner-Anwendung über LU6.1 kommunizieren.
Wird in einem Vorgang, der an einer verteilten Transaktion beteiligt ist, das OSI TP-Protokoll verwendet, dann müssen alle Auftragnehmer dem gleichen lokalen ACCESS-POINT zugeordnet sein und dieser muss ggf. identisch zu dem ACCESS-POINT sein, der für die Kommunikation mit einem AG-Vorgang verwendet wird.
Security-Typ P und S können Sie sowohl bei APRO DM als auch bei APRO AM wählen. Bei Dialog-Vorgängen wird der Auftraggeber beim Vorgangsstart unter der übergebenen Benutzerkennung angemeldet und bei Vorgangsende wieder abgemeldet. Bei Asynchron-Vorgängen ist die übergebene Benutzerkennung nur so lange aktiv, bis der Auftrag in die entsprechende Queue eingetragen ist.
Bei Dialog-Vorgängen wird die Anmeldung des Auftraggebers unter der übergebenen Benutzerkennung abgelehnt, wenn unter dieser Benutzerkennung schon ein OSI TP Dialog-Vorgang läuft oder ein Benutzer über einen LTERM-Partner angemeldet ist und das mehrfache Anmelden eines Benutzers an die Anwendung verboten ist (SIGNON-Anweisung MULTI-SIGNON=NO) oder die Benutzerkennung mit RESTART=YES konfiguriert ist und nicht die Functional Unit "Commit" ausgewählt wurde.
Um bei Asynchron-Vorgängen einen Auftrag in die entsprechende Queue einzuhängen, kann sich der Auftraggeber immer unter der übergebenen Benutzerkennung anmelden.Bei Auswahl von Security-Typ "S" übergibt openUTM die Benutzerkennung, unter der der lokale Vorgang läuft, an den Auftragnehmer-Vorgang. Als Datentyp wird T61 String angenommen.
Wird Security-Typ "P" ausgewählt, müssen Benutzerkennung und Passwort angegeben werden. Zusätzlich muss angegeben werden, von welchem Datentyp Benutzerkennung und Passwort sind. Mögliche Datentypen sind Printable String, T61 String und Octet String. Die Wertebereiche dieser Datentypen sind im openUTM-Handbuch „Anwendungen generieren“ bei der KDCDEF-Anweisung LTAC beschrieben.
Hinweis für BS2000-Systeme
Bei Angabe des Typs Octet String findet keine Code-Umsetzung statt. Der Typ Octet String ist bei Übertragung von Passwörtern notwendig, die als Hex-String (PASSWORD=X'aabbcc..') generiert wurden.
Ein erfolgreicher APRO-DM-Aufruf bedeutet, dass eine logische Verbindung zur Partner-Anwendung besteht.
Ein erfolgreicher APRO-Aufruf bedeutet aber noch nicht, dass ein Nachrichtenaustausch mit dem Auftragnehmer-Vorgang möglich ist. Eine Session bzw. Association wird erst am Ende desjenigen Teilprogrammlaufs belegt, in welchem die erste Nachricht an den Auftragnehmer-Vorgang ausgegeben wurde.Falls zum Zeitpunkt des APRO-Aufrufs noch keine Verbindung zur entfernten Anwendung besteht, dann leitet openUTM den Verbindungsaufbau ein.
Gibt openUTM nach einem APRO DM-Aufruf einen KDCS-Returncode
!=000 zurück, so sollte anschließend keine Nachricht mit MPUT an den Auftragnehmer ausgegeben werden, da dann der Vorgang mit KCRCCC=74Z abgebrochen würde.Einem mit APRO DM adressierten Auftragnehmer-Vorgang muss in der gleichen Transaktion eine Nachricht gesendet werden, sonst bricht openUTM den Vorgang beim PEND mit KCRCCC=87Z ab.
Einem mit APRO AM adressierten Asynchron-Vorgang muss vor dem nächsten PEND-Aufruf ein Asynchron-Auftrag zugeordnet werden, sonst bricht openUTM den Vorgang beim PEND mit 86Z ab.
Ein RSET-Aufruf setzt die Adressierung eines Dialog-Vorgangs nur dann zurück, wenn der APRO DM im selben Verarbeitungsschritt erfolgte, d.h. es wurde noch keine Dialog-Nachricht an den Auftragnehmer-Vorgang (MPUT mit nachfolgendem PEND/PGWT).
Existieren in einer Anwendung gleichzeitig mehrere Auftraggeber-Vorgänge, dann dürfen sie gleichnamige Vorgangs-Ids verwenden - auch zur Adressierung unterschiedlicher Auftragnehmer-Vorgänge.
Soll ein Auftrags-Komplex an die ferne Anwendung gesendet werden, dann muss der APRO AM-Aufruf vor dem MCOM BC-Aufruf stehen und die Vorgangs-Id muss beim MCOM BC-Aufruf im Feld KCRN angegeben werden.
Lebensdauer einer Vorgangs-Id
Eine mit APRO DM erzeugte Vorgangs-Id ist ein sicherungsrelevantes Objekt, d.h., sie wird in die Transaktionssicherung einbezogen. Sie bleibt so lange erhalten, bis der Auftragnehmer-Vorgang beendet ist und wird erst am Ende der Transaktion freigegeben, in der der Auftraggeber-Vorgang die letzte Nachricht vom Auftragnehmer gelesen hat.
Eine mit APRO AM erzeugte Vorgangs-Id wird freigegeben
nach erfolgreichem FPUT/DPUT NE-Aufruf,
beim nächsten RSET- oder PEND-Aufruf,
nach dem Returncode 40Z bei einem FPUT/DPUT-Aufruf, oder
bei Auftrags-Komplexen mit dieser Vorgangs-Id:
Beim MCOM EC-Aufruf oder nach einem Returncode 40Z beim MCOM BC- oder bei einem DPUT-Aufruf.
Wurde eine Vorgangs-Id freigegeben, dann kann sie für die nächste Auftraggeber/Auftragnehmer-Beziehung verwendet werden.
Adressierung eines Master-LPAP
Wenn mit dem APRO-Aufruf ein Master-LPAP adressiert wird, wird, falls es sich um den ersten APRO-Aufruf der aktuellen Transaktion für dieses Master-LPAP handelt, ein Slave-LPAP des LPAP-Bündel ausgewählt:
Bei einem APRO DM wird das erste Slave-LPAP ausgewählt, zu dem eine logische Verbindung aufgebaut ist. Ist zu keinem Slave-LPAP eine logische Verbindung aufgebaut, so ist der Rückgabewert 40Z/KD10.
Bei einem APRO AM wird das erste Slave-LPAP ausgewählt, zu dem eine logische Verbindung aufgebaut ist. Ist zu keinem Slave-LPAP eine logische Verbindung aufgebaut, so wird eines der Slave-LPAPs ausgewählt.
Für jedes Slave-LPAP, das bei der Auswahl geprüft wird und zu dem keine Association oder Session aufgebaut ist, wird ein Association- oder Session-Aufbau angestoßen.
Wenn ein Slave-LPAP ausgewählt wurde, wird bei jedem weiteren APRO-Aufruf in dieser Transaktion, der an das Master-LPAP gerichtet ist, dasselbe Slave-LPAP verwendet.
Ein nachfolgender APRO DM kann den Returncode 40Z/KD10 liefern, wenn der erste APRO-Aufruf ein APRO AM war und zu keinem der Slave-LPAPs eine aufgebaute Association oder Session existierte, oder wenn die logische Verbindung zwischenzeitlich wieder abgebaut wurde.