Enable_UTM_UPIC - Beim Trägersystem UPIC anmelden

Dieser Aufruf muss gemacht werden, bevor andere CPI-C-Aufrufe verwendet werden. Mit dem Aufruf Enable_UTM_UPIC (CMENAB) meldet sich ein Client mit diesem Namen beim UPIC-Trägersystem an. Der Name dient dazu, dem Client einen Namen zu geben, der beim Verbindungsaufau zur UTM-Anwendung verwendet wird (siehe auch Abschnitt „Initialize_Conversation - Conversation Characteristics initialisieren“).

In der upicfile können Sie einen DEFAULT-Namen für die CPI-C-Anwendung definieren (LN.DEFAULT-Eintrag; siehe Abschnitt „Side Information für die lokale Anwendung“). Wenn sich das CPI-C-Programm mit diesem DEFAULT-Namen beim Trägersystem UPIC anmelden soll, dann kann es im Feld local_name einen „leeren lokalen Anwendungsnamen“ übergeben. UPIC sucht dann in der upicfile nach dem LN.DEFAULT-Eintrag und verwendet den zugehörigen lokalen Anwendungsnamen zum Verbindungsaufbau zur UTM-Anwendung. Es können sich gleichzeitig mehrere CPI-C-Programmläufe mit dem DEFAULT-Namen anmelden und auch Conversations zu selben UTM-Anwendung aufbauen, sofern diese entsprechend generiert ist (siehe Abschnitt Multiple Conversations (Unix-, Linux- und Windows- Systeme))

Nach erfolgreicher Ausführung des Enable_UTM_UPIC-Aufrufs ist eine UPIC-Ablaufumgebung für das Programm bereitgestellt. Nach diesem Aufruf bleiben Änderungen in der upicfile bis zum nächsten Enable_UTM_UPIC-Aufruf für das Programm unwirksam.

Diese Funktion gehört zu den zusätzlichen Funktionen des Trägersystems UPIC; sie ist nicht Bestandteil der CPI-C-Schnittstelle.

Syntax

CMENAB (local_name, local_name_length, return_code)

Parameter

--> local_name	Name des Programms. Folgende Angaben sind möglich (siehe auch Abschnitt „Side Information für die lokale Anwendung“): bei UPIC-Remote: lokaler Anwendungsname, der in der upicfile definiert ist. Name, mit dem das Programm bei CMX bekannt ist. beliebiger Name, dessen Eigenschaften mit nachfolgenden Specify-Aufrufen noch verändert werden können. leerer lokaler Anwendungsname (siehe unten). bei UPIC-Local auf Unix-, Linux- und Windows-Systemen: PTERM-Name, unter dem der Client in der Konfiguration der UTM-Anwendung bekannt ist. lokaler Anwendungsname, der in der upicfile definiert ist. leerer lokaler Anwendungsname (siehe unten). Existiert in der UTM-Partner-Anwendung ein LTERM-Pool für den Partnertyp UPIC-L (TPOOL mit PTYPE=UPIC-L), dann können Sie für local_name einen beliebigen, bis zu 8 Zeichen langen Namen angeben. Verwendung eines leeren lokaler Anwendungsname Voraussetzung ist, dass zum Zeitpunkt des Aufrufs in der upicfile ein LN.DEFAULT-Eintrag existiert. Einen leeren lokalen Anwendungsnamen übergeben Sie, indem: in local_name 8 Leerzeichen übergeben und local_name_length=8 setzen oder local_name_length=0 setzen. Übergeben Sie einen leeren lokalen Anwendungsnamen, dann übernimmt UPIC den Anwendungsnamen des LN.DEFAULT-Eintrags, um die Verbindung zur UTM-Partner-Anwendung aufzubauen. Voraussetzung ist, dass zum Zeitpunkt des Aufrufs in der upicfile ein LN.DEFAULT-Eintrag existiert.
--> local_name_length	Länge von local_name Minimum: 0, Maximum: 8 Wird in local_name ein lokaler Anwendungsname aus der upicfile eingetragen, dann muss local_name_length=8 angegeben werden. Geben Sie local_name_length=0 an, dann wird der Inhalt des Feldes local_name ignoriert, d.h. local_name wird als „leerer lokaler Anwendungsname“ behandelt. In der upicfile muss ein LN.DEFAULT- Eintrag existieren.
<-- return_code	Ergebnis des Funktionsaufrufs

Ergebnis ( return_code )

CM_OK

Aufruf ok

CM_PROGRAM_STATE_CHECK

Das Programm ist bereits an UPIC angemeldet.

CM_PROGRAM_PARAMETER_CHECK

mögliche Ursachen:

• Der Wert für local_name_length ist kleiner als 0 oder größer als 8.

• Es ist nicht genügend interner Speicher vorhanden oder

• ein Zugriff auf die upicfile ist fehlgeschlagen.

CM_PRODUCT_SPECIFIC_ERROR

mögliche Ursachen:

• Die UPIC-Instanz konnte nicht gefunden werden oder

• nur bei UPIC-Local auf Unix-, Linux- und Windows-Systemen: die Umgebungsvariable UTMPATH ist nicht gesetzt.

Zustandsänderung

Falls das Ergebnis CM_OK ist, geht das Programm in den Zustand "Reset" über. In allen anderen Fällen ändert das Programm seinen Zustand nicht.

Hinweis

• Es können sich gleichzeitig mehrere CPI-C-Programmläufe mit demselben Namen beim Trägersystem UPIC anmelden.

• Ein mehrfach gestartetes CPI-C-Programm kann sich auch mehrfach mit demselben Namen bei derselben UTM-Anwendung anschließen (z.B. der Anwendungsname, der dem DEFAULT-Namen zugeordnet ist). Dazu muss die UTM-Anwendung folgendermaßen konfiguriert sein:

  • Es darf kein LTERM-Partner explizit für diesen openUTM-Client generiert sein, d.h. es darf kein PTERM mit seinem Namen und PTYPE=UPIC-R für diesen Rechner in der Konfiguration der UTM-Anwendung existieren.

  • Für den Rechner, an dem der Client abläuft, ist ein LTERM-Pool (TPOOL) mit CONNECT-MODE=MULTI generiert. Das CPI-C-Programm kann sich unter demselben Namen dann maximal so oft an die UTM-Anwendung anschließen, wie LTERM-Partner im LTERM-Pool zur Verfügung stehen (die Anzahl wird durch die UTM-Administration eingestellt).

• bei UPIC-Local auf Unix-, Linux- und Windows-Systemen: Damit sich das CPI-C-Programm bei der lokalen UTM-Anwendung anmelden kann, muss die Umgebungsvariable UTMPATH gesetzt sein. In seltenen Fällen kann es bei lokaler Kommunikation geschehen, dass sich die Funktion mit CM_PROGRAM_STATE_CHECK beendet, obwohl kurz zuvor Disable_UTM_UPIC aufgerufen wurde und CM_OK zurücklieferte. Die Ursache ist ein unvollständiger openUTM-interner Verbindungsabbau.

Verhalten im Fehlerfall

CM_PRODUCT_SPECIFIC_ERROR

• Das Betriebssystem kann nicht genügend Speicherplatz für interne Puffer bereitstellen; prüfen Sie Ihr Programm auf zu hohe Speicherplatzanforderung und starten Sie ggf. Ihr System neu.

• Bei UPIC-Local auf Unix-, Linux- und Windows-Systemen: Die Umgebungsvariable UTMPATH setzen und das Programm neu starten.

CM_PROGRAM_STATE_CHECK

Programm ändern.

CM_PROGRAM_PARAMETER_CHECK

• Programm ändern.

• u.U. virtuellen Speicher vergrößern

Funktionsdeklaration: Enable_UTM_UPIC

CM_ENTRY Enable_UTM_UPIC ( unsigned char CM_PTR  local_name,
                          CM_INT32       CM_PTR  local_name_length,
                          CM_RETURN_CODE CM_PTR  return_code)