Initialize_Conversation - Conversation Characteristics initialisieren

Der Aufruf Initialize_Conversation (CMINIT) liest den durch den symbolic destination name spezifizierten Eintrag in der upicfile und initialisiert die Conversation Characteristics. Die Characteristics partner_LU_name, partner_LU_name_lth, TP_name und TP_name_length werden mit den entsprechenden Werten aus der upicfile besetzt. Alle anderen Conversation Characteristics werden mit den Standardwerten initialisiert.

Neben den Conversation Characteristics wird bei diesem Aufruf auch festgelegt, ob bei den nachfolgenden Send- bzw. Receive-Aufrufen eine automatische Konvertierung der Benutzerdaten von ASCII nach EBCDIC bzw. umgekehrt stattfinden soll. Die Konvertierung erfolgt:

• Auf Unix-, Linux- und Windows-Systemen, falls vor dem symbolic destination name das Kennzeichen HD steht.

• Auf BS2000-Systemen, falls vor dem symbolic destination name das Kennzeichen SD steht.

Näheres siehe auch Abschnitt „Side Information für stand-alone UTM-Anwendungen“.

Als Ergebnis liefert die Funktion eine achtstellige Conversation_ID zurück. Diese dient als eindeutige Identifikation der Conversation und muss in allen späteren CPI-C-Aufrufen verwendet werden, um die Conversation zu adressieren.

Es besteht die Möglichkeit, zu einem späteren Zeitpunkt die mit diesem Aufruf initialisierten Werte für die Conversation Characteristics TP_name, TP_name_length, receive_type und deallocate_type zu ändern. Dazu stehen die Aufrufe Set_TP_Name, Set_Receive_Type und Set_Deallocate_Type zur Verfügung. Ein mit einem Set-Aufruf geänderter Wert bleibt bis zum Ende der Conversation oder bis zu einem erneuten Set-Aufruf bestehen.

Die Set-Aufrufe sind kein Bestandteil des CPI-C-Starter-Sets, sondern gehören zu den Advanced Functions.

Syntax

CMINIT (conversation_ID, sym_dest_name, return_code)

Parameter

<-- conversation_ID	Identifikation, die der Conversation zugeordnet wurde und dem Programm als Ergebnisparameter zurückgeliefert wird.
--> sym_dest_name	Falls Sie ohne upicfile arbeiten, dann müssen Sie für sym_dest_name 8 Leerzeichen angeben („leerer sym_dest_name“). Falls Sie mit der upicfile arbeiten, geben Sie den Verweis auf die Side Information ein (8 Zeichen langer Name). Für sym_dest_name können Sie auch 8 Leerzeichen angeben („leerer sym_dest_name“). In diesem Fall wird in der Side Information der symbolic destination name .DEFAULT gesucht (siehe Abschnitt „Side Information für stand-alone UTM-Anwendungen“) und die entsprechenden Werte für partner_LU_name, partner_LU_name_lth, TP_name und TP_name_length gesetzt.
<-- return_code	Ergebnis des Funktionsaufrufs

Ergebnis (return_code)

CM_OK

Aufruf ok

CM_PROGRAM_PARAMETER_CHECK

• Der Wert für sym_dest_name bzw. local_name (beim Enable_UTM_UPIC) ist ungültig oder der spezifizierte Eintrag in der upicfile konnte nicht gelesen werden oder ist syntaktisch ungültig.

• Ein eventuelles An- oder Abmelden von der Transportschnittstelle war nicht erfolgreich.

• In sym_dest_name oder in local_name (beim Enable_UTM_UPIC) wurde ein leerer Name angegeben, aber in der upicfile fehlt ein entsprechender DEFAULT-Eintrag bzw. der DEFAULT-Eintrag ist ungültig.

• Fehler in der upicfile:
  Die CD- oder ND-Einträge für den angegebenen sym_dest_name folgen nicht unmittelbar aufeinander oder die CD-Einträge für den angegebenen
  sym_dest_name beinhalten unterschiedliche TACs.

CM_PRODUCT_SPECIFIC_ERROR

• Für dieses Programm ist bereits eine Conversation aktiv, bzw. es wurde noch kein Enable_UTM_UPIC-Aufruf gemacht.

• Eine unerwartete Reaktion der Transportschnittstelle ist aufgetreten.

Zustandsänderung

Falls das Ergebnis CM_OK ist, geht das Programm in den Zustand "Initialize" über und die Characteristics der Conversation sind initialisiert. Näheres siehe Abschnitt „Conversation Characteristics“ (CPI-C-Begriffe). In allen Fehlersituationen ändert das Programm seinen Zustand nicht.

Hinweis

• Der Initialize_Conversation-Aufruf muss vom Programm ausgeführt worden sein, bevor ein anderer Aufruf für diese Conversation erfolgt.

• Falls das Programm mit dem Initialize_Conversation-Aufruf oder daran anschließenden Set-Aufrufen ungültige Information für das Etablieren einer Conversation bereitstellt, wird dies bei syntaktischen Fehlern sofort, bei inhaltlichen Fehlern jedoch erst bei der Ausführung des Allocate-Aufrufs (CMALLC) erkannt.

• Mehrere Programme können sich unter dem gleichen Namen mit der UTM-Anwendung verbinden, wenn für die entsprechende TPOOL-Anweisung CONNECT-MODE=MULTI definiert ist.

• bei remote Anbindung:

  • Die Funktion führt eventuell ein Anmelden an das Transportsystem (z.B. TCP/IP, PCMX, BCAM) durch. Dazu wird der Name des vorangegangenen Enable_UTM_UPIC-Aufrufs verwendet. Falls das Programm bereits mit demselben Namen angemeldet ist, erfolgt kein Anmelden.

  • Besteht noch eine Verbindung zu einem Partner, der ungleich dem Partner aus der upicfile ist, dann wird diese Verbindung abgebaut.

• bei lokaler Anbindung (UPIC auf Unix-, Linux- und Windows-Systemen):

  • Die Funktion führt die Anmeldung an die openUTM-interne Prozesskommunikation durch (mit dem UTM-Anwendungsnamen aus der upicfile), wenn das Programm noch nicht mit demselben Namen angemeldet ist. Ist das Programm noch mit einem anderen Namen angemeldet, erfolgt zuerst eine Abmeldung von der openUTM-internen Prozesskommunikation. Eine bestehende Conversation zu dieser UTM-Anwendung wird dabei implizit abgebaut. Erst danach wird das Programm mit dem neuen Namen angemeldet.

  • Bei der Anmeldung an die UTM-Anwendung wird die applifile der UTM-Anwendung gelesen. Dazu wird die Shellvariable UTMPATH, die auf das entsprechende UTM-Verzeichnis utmpfad zeigt, ausgewertet. Diese Variable muss gesetzt sein.

Verhalten im Fehlerfall

CM_PROGRAM_PARAMETER_CHECK

• upicfile einrichten; die Umgebungsvariablen UPICPATH und UPICFILE bzw. die Jobvariablen mit den Linknamen UPICPAT und UPICFIL bestimmen den Speicherort und den Namen der upicfile. Überprüfen des BCMAP-Eintrags auf BS2000-Systemen.

• Den aktuellen sym_dest_name in die upicfile eintragen oder den Eintrag für sym_dest_name auf richtige Syntax prüfen.

• bei lokaler Anbindung auf Unix-, Linux- und Windows-Systemen: Umgebungsvariable UTMPATH richtig setzen. Es ist auch möglich, dass kein Semaphor mehr zur Verfügung steht.

• upicfile ändern: CD- bzw. ND-Einträge überprüfen und anpassen.

CM_PRODUCT_SPECIFIC_ERROR

Programm ändern oder Systemdienst informieren und Diagnoseunterlagen erstellen.

Funktionsdeklaration: Initialize_Conversation

CM_ENTRY Initialize_Conversation ( unsigned char  CM_PTR  conversation_ID,
                                   unsigned char  CM_PTR  sym_dest_name,
                                   CM_RETURN_CODE CM_PTR  return_code)