Die Funktionen der Schnittstelle sind auf allen Plattformen in den Programmiersprachen C, C++ und COBOL nutzbar und stehen in Bibliotheken zur Verfügung.
Die folgende Beschreibung der CPI-C-Aufrufe ist aus diesem Grund so sprachunabhängig wie möglich gehalten. Sie benutzt jedoch die Notation der C-Schnittstelle. Im Abschnitt„COBOL-Schnittstelle“ sind Besonderheiten der COBOL-Schnittstelle beschrieben, die Sie beim Erstellen von CPI-C-Programmen in COBOL beachten müssen.
Die genaue Funktionsdeklaration wird für jeden Aufruf separat beschrieben.
Programmaufrufe
Ein Client kommuniziert mit einer UTM-Anwendung, indem er Funktionen aufruft. Diese Aufrufe dienen dazu, die Characteristics für die Conversation festzulegen und Daten und Kontrollinformationen auszutauschen. Die von UPIC unterstützten CPI-C-Aufrufe können in zwei Gruppen eingeteilt werden:
Starter-Set-Aufrufe
Die Starter-Set-Aufrufe ermöglichen eine einfache Kommunikation mit einem UTM-Anwendung. Sie dienen dem einfachen Austausch von Daten, z.B. übernehmen der initialisierten Werte für die Characteristic einer Conversation.Advanced Functions-Aufrufe
Die Advanced Functions-Aufrufe ermöglichen zusätzliche Funktionen. Zum Beispiel können mit Set-Aufrufen die Conversation Characteristics modifiziert werden.
Funktionen aus dem Starter-Set
Funktion | Beschreibung |
Initialize_Conversation | Conversation etablieren |
Allocate | Conversation starten |
Deallocate | Conversation abnormal beenden |
Send_Data | Daten senden |
Receive | Daten empfangen |
Tabelle 7: Funktionen aus dem Starter-Set
Es wird davon ausgegangen, dass das CPI-C-Programm (Client) in jedem Fall der aktive Teil ist. Deshalb wird die CPI-C-Funktion Accept_Conversation nicht unterstützt.
Auf Systemen, die das Multi-Threading unterstützen, können in einem CPI-C-Programm zu einem Zeitpunkt mehrere Conversations zu verschiedenen UTM-Anwendungen aktiv sein. Jede Conversation einschließlich zugehörigem Enable_UTM_UPIC- und Disable_UTM_UPIC-Aufruf muss in einem eigenen Thread ablaufen.
Auf allen anderen Systemen kann in einem CPI-C-Programmlauf zu einem Zeitpunkt nur eine Conversation aktiv sein.
Funktionen aus den Advanced Functions
Funktion | Beschreibung |
Convert_Incoming | Empfangene Daten in lokalen Code konvertieren |
Convert_Outgoing | Zu sendende Daten vom lokalem Code in den Code des Kommunikationspartners konvertieren |
Deferred_Deallocate | Conversation beenden, sobald die laufende Transaktion erfolgreich beendet wurde |
Extract_Conversation_State | Zustand der Conversation abfragen |
Extract_Secondary_Information | Erweiterte Informationen abfragen |
Extract_Partner_LU_Name | Wert der Conversation Characteristic partner_LU_name abfragen, bis zu einer maximalen Länge von 32 Bytes |
Extract_Partner_LU_Name_Ex | Wert der Conversation Characteristic partner_LU_name in voller Länge abfragen |
Prepare_To_Receive | Die im Sendepuffer zwischengespeicherten Daten sofort an den Kommunikationspartner senden und in den Status "Receive" wechseln |
Receive_Mapped_Data 1 | Daten zusammen mit Strukturierungsmerkmalen (Formatkennzeichen) empfangen |
Send_Mapped_Data 1 | Daten zusammen mit Strukturierungsmerkmalen (Formatkennzeichen) senden |
Set_Conversation_Security_Password | Passwort für eine UTM-Benutzerkennung setzen |
Set_Conversation_Security_Type | Security-Funktionen aktivieren oder deaktivieren |
Set_Conversation_Security_User_ID | UTM-Benutzerkennung setzen |
Set_Partner_LU_name | Wert für die Conversation Characteristics partner_LU_name setzen |
Set_Deallocate_Type | Wert für die Conversation Characteristic deallocate_type setzen |
Set_Receive_Type | Wert für die Conversation Characteristic receive_type setzen |
Set_Sync_Level | Wert für die Conversation Characteristic sync_level setzen |
Set_TP_Name | Namen für ein Partnerprogramm setzen (Transaktionscode) |
Tabelle 8: Advanced Functions
1Nicht Bestandteil von X/Open CPI-C Version 2
Zusätzliche Funktionen von UPIC
Funktion | Beschreibung |
Enable_UTM_UPIC | Beim UPIC-Trägersystem anmelden |
Extract_Client_Context | Client-Kontext ausgeben |
Extract_Conversation_Encryption_Level | Verschlüsselungsebene abfragen |
Extract_Convertion | ASCII-EBCDIC-Konvertierung abfragen |
Extract_Cursor_Offset | Offset der Cursor-Position abfragen |
Extract_Max_Partner_Index | Maximalen Index der Partner-Anwendungen abfragen |
Extract_Secondary_Return_Code | Erweiterte Returncodes abfragen |
Extract_Shutdown_State | Shutdown-Status des Servers abfragen |
Extract_Shutdown_Time | Shutdown-Time des Servers abfragen |
Extract_Transaction_State | Vorgangs- und Transaktionsstatus des Servers abfragen |
Disable_UTM_UPIC | Beim UPIC-Trägersystem abmelden |
Set_Allocate_Timer | Timer für Allocate setzen |
Set_Client_Context | Client-Kontext setzen |
Set_Convertion | ASCII-EBCDIC-Konvertierung setzen |
Set_Conversation_Encryption_Level | Verschlüsselungsebene setzen |
Set_Conversation_Security_New_Password | Neues Passwort für eine UTM-Benutzerkennung setzen |
Set_Function_Key | Wert der zu übertragenden Funktionstaste setzen |
Set_Receive_Timer | Timeout Timer für den blockierenden Empfang von Daten setzen |
Set_Partner_Host_Name | Hostname der Partner-Anwendung setzen |
Set_Partner_Index | Index der Partner-Anwendung setzen |
Set_Partner_IP_Address | IP-Adresse der Partner-Anwendung setzen |
Set_Partner_Port | TCP/IP-Port der Partner-Anwendung setzen |
Set_Partner_Tsel | TSEL der Partner-Anwendung setzen |
Set_Partner_Tsel_Format | TSEL-Format der Partner-Anwendung setzen |
Specify_Local_Tsel | TSEL der lokalen Anwendung setzen |
Specify_Local_Tsel_Format | TSEL-Format der lokalen Anwendung setzen |
Specify_Local_Port | TCP/IP-Port der lokalen Anwendung setzen |
Specify_Secondary_Return_Code | Eigenschaften des erweiterten Returncodes setzen |
Tabelle 9: Zusätzliche Funktionen von UPIC