Receive_Mapped_Data - Daten und Formatkennzeichen von einem UTM-Service empfangen

Mit dem Receive_Mapped_Data (CMRCVM)-Aufruf empfängt ein Programm Informationen von einem UTM-Service. Die Informationen, die empfangen werden, können entweder Daten, ein Formatkennzeichen und/oder das Senderecht sein.

Das Programm muss den Receive_Mapped_Data-Aufruf so lange wiederholen bis der Rückgabewert von return_code ungleich CM_OK oder status_received=CM_SEND_RECEIVED ist.

Der Aufruf kann blockierend oder nicht-blockierend ausgeführt werden.

• Der Receive_Mapped_Data-Aufruf ist blockierend, wenn die Characteristic receive_type den Wert CM_RECEIVE_AND_WAIT hat.
  Liegen zum Zeitpunkt des Receive_Mapped_Data-Aufrufs keine Informationen (Daten oder Senderecht) vor, dann wartet der Programmlauf so lange im Receive_Mapped_Data, bis eine Information für diese Conversation eintrifft. Erst dann kehrt der Programmlauf aus dem Receive_Mapped_Data-Aufruf zurück und liefert die Informationen zurück. Falls zum Zeitpunkt des Aufrufs bereits eine Information vorliegt, empfängt sie das Programm ohne zu warten.

  Um die Wartezeit beim blockierenden Receive-Aufruf zu beschränken, sollten entsprechende Timer in der UTM-Partner-Anwendung gesetzt werden (siehe KDCDEF-Anweisung TAC und Set_Receive_Timer - Timer für den blockierenden Receive setzen).

• Der Receive_Mapped_Data-Aufruf ist nicht-blockierend, wenn die Characteristic receive_type den Wert CM_RECEIVE_IMMEDIATE hat.
  Liegen zum Zeitpunkt des Receive_Mapped_Data-Aufrufs keine Informationen vor, dann wartet der Programmlauf nicht, bis Informationen für diese Conversation eintreffen. Der Programmlauf kehrt sofort aus dem Receive_Mapped_Data-Aufruf zurück. Falls bereits eine Information vorliegt, wird sie an das Programm übergeben ,andernfalls wird return_code auf CM_UNSUCCESSFUL gesetzt.
  UPIC-Local auf Unix-, Linux- und Windows-Systemen: Der nicht-blockierende Receive-Aufruf wird bei der Anbindung über UPIC-Local nicht unterstützt.

Die Characteristic receive_type können Sie vor dem Aufruf von Receive_Mapped_Data mit dem Aufruf Set_Receive_Type setzen.

Syntax

CMRCVM (conversation_ID, map_name, map_name_length, buffer, requested_length, data_received, received_length, status_received, control_information_received, return_code)

Parameter

--> conversation_ID	Identifikation der Conversation
<-- map_name	Formatkennzeichen, das die UTM-Partner-Anwendung zusammen mit den Daten an das CPI-C-Programm gesendet hat. Das Formatkennzeichen spezifiziert die Strukturierungsmerkmale der empfangenen Daten.
<-- map_name_length	Länge des Formatkennzeichens in map_name.
<-- buffer	Puffer, in dem die Daten empfangen werden. Falls der Rückgabewert von data_received CM_NO_DATA_RECEIVED ist, ist der Inhalt von buffer undefiniert.
--> requested_length	Maximale Länge der Daten, die empfangen werden können.
<-- data_received	Gibt an, ob auf der Conversation Daten empfangen wurden. data_received kann folgende Werte annehmen: CM_NO_DATA_RECEIVED Es lagen keine Daten für das Programm vor. Eventuell wurde jedoch das Senderecht empfangen. CM_COMPLETE_DATA_RECEIVED Eine (Teil-)Nachricht, die für das Programm vorlag, wurde vollständig empfangen. CM_INCOMPLETE_DATA_RECEIVED Eine (Teil-)Nachricht ist nicht vollständig an das Programm übergeben worden. Falls data_received diesen Wert annimmt, muss das Programm anschließend so viele Receive- bzw. Receive_Mapped_Data-Aufrufe absetzen, bis die (Teil-)Nachricht vollständig gelesen wurde, d.h. bis data_received den Wert CM_COMPLETE_DATA_RECEIVED hat. Der Wert von data_received ist undefiniert, wenn das Ergebnis des Aufrufs ungleich CM_OK oder CM_DEALLOCATED_NORMAL ist.
<-- received_length	Länge der empfangenen Daten. Der Wert von received_length ist undefiniert, wenn das Programm keine Daten empfangen hat (data_received=CM_NO_DATA_RECEIVED) bzw. wenn das Ergebnis ungleich CM_OK oder CM_DEALLOCATE_NORMAL ist.
<-- status_received	Gibt an, ob das Programm das Senderecht empfangen hat. status_received kann einen der folgenden Werte annehmen: CM_NO_STATUS_RECEIVED Das Senderecht wurde nicht empfangen. CM_SEND_RECEIVED Der UTM-Vorgang hat das Senderecht an das Programm abgegeben. Das Programm muss anschließend einen Send_Data-Aufruf absetzen. Der Wert in status_received ist undefiniert, wenn das Ergebnis in return_code ungleich CM_OK ist.
<-- control_information_received	Wird nur syntaktisch unterstützt und kann nur den Wert CM_REQ_TO_SEND_NOT_RECEIVED annehmen. Der Wert in control_information_received ist undefiniert, wenn das Ergebnis in return_code ungleich CM_OK oder CM_DEALLOCATE_NORMAL ist.
<-- return_code	Ergebnis des Funktionsaufrufs

Ergebnis ( return_code )

CM_OK

Aufruf ok. Das Programm hat nach dem Aufruf einen der folgenden Zustände:

"Receive" falls status_received den Wert CM_NO_STATUS_RECEIVED hat.

"Send" falls status_received den Wert CM_SEND_RECEIVED hat.

CM_SECURITY_NOT_VALID

mögliche Ursachen:

• ungültige UTM-Benutzerkennung bei Set_Conversation_Security_User_ID

• ungültiges Passwort beim Aufruf Set_Conversation_Security_Password

• Die UTM-Anwendung ist ohne Benutzerkennungen (USER-Anweisungen) generiert.

• Der Benutzer kann sich bei der UTM-Anwendung wegen Betriebsmittelengpass nicht anmelden.

Die UPIC-Schnittstelle liefert einen erweiterten Returncode, der die Ursache detailliert beschreibt. Die Ergebnisse, die das Programm dann erhält, sind unter secondary_return_code aufgeführt.

Die erweiterten Returncodes können auch durch den Aufruf Extract_Secondary_Return_Code abgefragt werden, siehe "Extract_Secondary_Information - Erweiterte Information abfragen". Der secondary_returncode wird nur dann im receive()-Aufruf geliefert, wenn Specify_second_Return_Code() auf PRIMARY steht, ansonsten muss er explizit durch Extract_Secondary_Return_Code() gelesen werden.

CM_TPN_NOT_RECOGNIZED

mögliche Ursachen:

• Vorgangs-Wiederanlauf mit Hilfe von KDCDISP wurde abgewiesen, da keine mit RESTART=YES generierte UTM-Benutzerkennung angegeben wurde.

• ungültiger Transaktionscode (TAC) in der upicfile oder beim Set_TP_Name- Aufruf, z.B.:

• • • • • • TAC ist nicht generiert

• • • • • • Keine Berechtigung, um diesen TAC aufzurufen

          • TAC ist nur als Folge-TAC erlaubt

          • TAC ist kein Dialog-TAC

          • TAC ist mit Verschlüsselung generiert, aber es wurden unverschlüsselte Benutzerdaten gesendet oder auf der Verbindung wird keine Verschlüsselung
            unterstützt oder die verschlüsselten Daten entsprechen nicht der geforderten Verschlüsselungsstufe.

          • Vorgangs-Wiederanlauf mit Hilfe von KDCDISP wurde abgewiesen, da keine mit RESTART=YES generierte UTM-Benutzerkennung angegeben wurde.

CM_TP_NOT_AVAILABLE_NO_RETRY

Vorgangs-Wiederanlauf mit Hilfe von KDCDISP ist nicht möglich, da UTM-Anwendung neu generiert wurde.

CM_TP_NOT_AVAILABLE_RETRY

Vorgangsstart wurde abgewiesen, da UTM-Anwendung beendet wird.

CM_DEALLOCATED_ABEND

mögliche Ursachen:

• Abnormale Beendigung des UTM-Vorgangs

• UTM-Anwendungsende

• Verbindungsabbau durch UTM-Administration

• Verbindungsabbau durch das Transportsystem

• Verbindungsabbau durch openUTM wegen Überschreitung der maximal zulässigen Anzahl von Benutzern (MAX-Anweisung, CONN-USERS=). Die Ursache kann auch darin liegen, dass beim Aufruf Set_Conversation_Security_User_ID zwar eine Administrator-Benutzerkennung übergeben wurde, aber die per UTM-Generierung der Verbindung implizit zugeordnete Benutzerkennung oder die explizit (mit der Anweisung LTERM..., USER=) zugeordnete (Verbindungs-)Benutzerkennung keine Administrator-Benutzerkennung ist (CONN-USERS wirkt nur für Benutzer ohne Administrationsberechtigung).

Das Programm geht in den Zustand "Reset" über.

CM_DEALLOCATED_NORMAL

Im UTM-Vorgang wurde ein PEND-FI-Aufruf ausgeführt. Das Programm geht in den Zustand "Reset" über.

CM_OPERATION_INCOMPLETE

Der Aufruf Receive_Mapped_Data ist durch den Ablauf des Timers, der mit Set_Receive_Timer gesetzt wurde, unterbrochen worden. Es wurden keine Daten empfangen.

CM_UNSUCCESSFUL

Die Characteristic receive_type hat den Wert CM_RECEIVE_IMMEDIATE und es sind zur Zeit keine Daten für die Conversation vorhanden.

CM_RESOURCE_FAILURE_RETRY

Ein vorübergehender Betriebsmittelengpass führte zur Beendigung der Conversation. Möglicherweise können im UTM-Pagepool keine Daten mehr zwischengespeichert werden. Tritt der Fehler häufiger auf, sollte der Pagepool der UTM-Anwendung vergrössert werden (MAX-Anweisung, PGPOOL=).

CM_RESOURCE_FAILURE_NO_RETRY

Es ist ein Fehler aufgetreten, der zu einer vorzeitigen Beendigung der Conversation führte (z.B. ein Protokollfehler oder vorzeitiger Verlust der Netzverbindung).

CM_PROGRAM_STATE_CHECK

Der Aufruf ist im aktuellen Zustand nicht erlaubt. Der Inhalt aller anderen Variablen ist undefiniert.

CM_PROGRAM_PARAMETER_CHECK

Der Wert in conversation_ID ist ungültig, oder der Wert in requested_length ist größer als 32767 oder kleiner als 0. Der Inhalt aller anderen Variablen ist undefiniert.

CM_PRODUCT_SPECIFIC_ERROR

Anstatt eines Send_Data-Aufrufs erfolgte ein Receive-Aufruf (nur unmittelbar nach einem Allocate-Aufruf).

CM_MAP_ROUTINE_ERROR

In der UTM-Partner-Anwendung werden keine Formatkennzeichen im UPIC-Protokoll unterstützt.

Erweiterter Returncode ( secondary_return_code )

CM_SECURITY_USER_UNKNOWN

Die angegebene Benutzerkennung ist nicht generiert.

CM_SECURITY_STA_OFF

Die angegebene Benutzerkennung ist gesperrt.

CM_SECURITY_USER_IS_WORKING

Mit dieser Benutzerkennung hat sich bereits jemand angemeldet.

CM_SECURITY_OLD_PSWORD_WRONG

Das angegebene bisherige Passwort ist falsch.

CM_SECURITY_NEW_PSWORD_WRONG

Die Angaben zum neuen Passwort sind nicht verwendbar. Mögliche Ursache: minimale Gültigkeitsdauer noch nicht abgelaufen.

CM_SECURITY_NO_CARD_READER

Der Benutzer ist mit Magnetstreifenkarte generiert und kann sich nicht über UPIC anmelden.

CM_SECURITY_CARD_INFO_WRONG

Der Benutzer ist mit Chipkarte generiert und kann sich nicht über UPIC anmelden.

CM_SECURITY_NO_RESOURCES

Die Anmeldung ist zur Zeit nicht möglich. Ursache ist

• ein Betriebsmittelengpass oder

• die Maximalzahl gleichzeitig angemeldeter Benutzer ist erreicht (siehe KDCDEF-Anweisung MAX CONN-USERS=) oder

• ein inverser KDCDEF läuft gerade

Anmeldung später wieder versuchen.

CM_SECURITY_NO_KERBEROS_SUPPORT

Der Benutzer ist mit einem Kerberos-Prinzipal generiert und kann sich nicht über UPIC anmelden.

CM_SECURITY_TAC_KEY_MISSING

Das aktuelle LTERM hat nicht die Berechtigung, den Vorgang fortzusetzen.

CM_SECURITY_PWD_EXPIRED_NO_RETRY

Die Gültigkeitsdauer des Benutzer-Passwortes ist abgelaufen.

CM_SECURITY_COMPLEXITY_ERROR

Das neue Passwort erfüllt nicht die Anforderung an die Komplexität.

CM_SECURITY_PASSWORD_TOO_SHORT

Das neue Passwort ist zu kurz.

CM_SECURITY_UPD_PSWORD_WRONG

Das von KDCUPD übertragene Passwort erfüllt nicht die in der Anwendungsgenerierung definierte Komplexitätsstufe.

CM_SECURITY_TA_RECOVERY

Für die angegebene Benutzerkennung ist ein Transaktionswiederanlauf erforderlich.

CM_SECURITY_PROTOCOL_CHANGED

Der offene Vorgang kann nicht von diesem LTERM-Partner aus fortgesetzt werden.

CM_SECURITY_SHUT_WARN

Vom Administrator wurde SHUT WARN gegeben, normale Benutzer dürfen sich nicht mehr an die UTM-Anwendung anmelden, nur ein Administrator darf sich noch anmelden.

CM_SECURITY_ENC_LEVEL_TOO_HIGH

Auf der Verbindung ist der für die Fortsetzung des offenen Vorgangs nötige Verschlüsselungsmechanismus nicht verfügbar.

CM_SECURITY_PWD_EXPIRED_RETRY

Die Gültigkeitsdauer des Benutzer-Passworts ist abgelaufen.

Die folgenden sekundären Returncodes treten nur im Zusammenhang mit UTM-Cluster-Anwendungen auf:

CM_SECURITY_USER_GLOBALLY_UNKNOWN

Die angegebene Benutzerkennung ist in der Cluster-User-Datei nicht bekannt.

CM_SECURITY_USER_SIGNED_ON_OTHER_NODE

Mit dieser Benutzerkennung hat sich bereits ein Benutzer an einer anderen Knoten-Anwendung angemeldet.

CM_SECURITY_TRANSIENT_ERROR

Beim Anmelden trat ein temporärer Fehler auf. Auf die Cluster-User-Datei konnte innerhalb der in der Knoten-Anwendung konfigurierten Zeit nicht zugegriffen werden.

Anmeldung später noch einmal versuchen.

Zustandsänderung

• Falls das Ergebnis CM_OK ist, hat das Programm nach dem Aufruf einen der folgenden Zustände:

  "Receive"  falls der Wert von status_received CM_NO_STATUS_RECEIVED ist.
  "Send"    falls der Wert von status_received CM_SEND_RECEIVED ist.

• Das Programm geht bei folgenden Ergebnissen in den Zustand "Reset" über:
  CM_DEALLOCATED_NORMAL
  CM_DEALLOCATED_ABEND
  CM_SECURITY_NOT_VALID
  CM_TPN_NOT_RECOGNIZED
  CM_TP_NOT_AVAILABLE_RETRY/NO_RETRY
  CM_RESOURCE_FAILURE_RETRY/NO_RETRY

• Bei allen anderen Fehlersituationen ändert das Programm seinen Zustand nicht.

Hinweis

• Bei einem Receive_Mapped_Data-Aufruf kann ein Programm nur so viele Daten empfangen, wie im Parameter requested_length angegeben wurde. Es ist deshalb möglich, dass das Programm damit noch nicht die komplette (Teil-)Nachricht, die vom Partner gesendet wurde, gelesen hat. Dem Parameter data_received können Sie entnehmen, ob noch weitere Daten der (Teil-)Nachricht gelesen werden müssen.

• • Falls das Programm bereits die komplette (Teil-)Nachricht empfangen hat, hat der Parameter data_received den Wert CM_COMPLETE_DATA_RECEIVED.

  • Hat das Programm noch nicht alle Daten der (Teil-)Nachricht empfangen, hat der Parameter data_received den Wert CM_INCOMPLETE_DATA_RECEIVED. Um die restlichen Daten der (Teil-)Nachricht zu lesen, müssen solange Receive_Mapped_Data- bzw. Receive-Aufrufe abgesetzt werden, bis data_received den Wert CM_COMPLETE_DATA_RECEIVED hat.

• Wurde vor einem blockierenden Receive_Mapped_Data-Aufruf mit dem Aufruf Set_Receive_Timer eine maximale Wartezeit eingestellt, dann kehrt der Programmlauf spätestens nach Ablauf der Wartezeit aus dem Receive_Mapped_Data-Aufruf zurück und der Receive_Mapped_Data-Aufruf liefert dann in return_code CM_OPERATION_INCOMPLETE zurück.

• Mit einem einzigen Aufruf kann ein Programm sowohl Daten als auch das Senderecht empfangen. Die Parameter return_code, data_received und status_received geben Auskunft über die Art der Information, die ein Programm erhalten hat.

• Falls das Programm den Receive_Mapped_Data-Aufruf im Zustand "Send" absetzt, wird das Senderecht an den UTM-Vorgang abgegeben. Auf diese Weise wird die Senderichtung der Conversation geändert.

• Ein Receive-Aufruf mit requested_length=0 hat keine spezielle Bedeutung. Falls Daten vorliegen, werden diese in der Länge 0 empfangen mit data_received=CM_INCOMPLETE_DATA_RECEIVED.
  Falls keine Daten vorliegen, kann das Senderecht empfangen werden. D.h. in diesem Fall können entweder Daten oder das Senderecht empfangen werden, aber nicht beides.

• Falls eine (Teil-)Nachricht mit mehreren Receive_Mapped_Data-Aufrufen empfangen wird (data_received hat den Wert CM_INCOMPLETE_DATA_RECEIVED außer beim letzten Receive_Mapped_Data-Aufruf), so werden die Parameter map_name und map_name_length nur beim ersten Aufruf von Receive_Mapped_Data versorgt. Sie werden bei den folgenden Receive_Mapped_Data-Aufrufen aber nicht überschrieben.

• Übergibt die UTM-Partner-Anwendung ein leeres Formatkennzeichen (d.h. 8 Leerzeichen), dann wird map_name mit 8 Leerzeichen belegt und map_name_length=-1 gesetzt.

Verhalten im Fehlerfall

CM_RESOURCE_FAILURE_RETRY

Conversation neu einrichten.

CM_RESOURCE_FAILURE_NO_RETRY

Systemdienst informieren und Diagnoseunterlagen erstellen. Es kann auch eine Störung im Transportsystem die Ursache für diesen Fehlercode sein.

CM_PROGRAM_STATE_CHECK

Programm ändern.

CM_PROGRAM_PARAMETER_CHECK

Programm ändern.

CM_PRODUCT_SPECIFIC_ERROR

Programm ändern.

CM_MAP_ROUTINE_ERROR

Programm ändern.

CM_OPERATION_INCOMPLETE

Conversation und Kommunikationsverbindung müssen explizit mit dem Aufruf Disable_UTM_UPIC abgebaut werden.
Jeder andere Aufruf kann zu unvorhersehbaren Ergebnissen führen.

CM_SECURITY_USER_UNKNOWN

Die UTM-Benutzerkennung ist nicht generiert. Benutzerkennung verwenden, die generiert ist oder gewünschte Benutzerkennung generieren oder dynamisch konfigurieren.

CM_SECURITY_STA_OFF

Benutzerkennung mit STATUS=ON generieren oder per Administration entsperren.

CM_SECURITY_USER_IS_WORKING

Andere UTM-Benutzerkennung benutzen oder den Vorgang des bereits angemeldeten Benutzers beenden.

CM_SECURITY_OLD_PSWORD_WRONG

Passwort korrekt angegeben.

CM_SECURITY_NEW_PSWORD_WRONG

Altes Passwort bis Ablauf der Gültigkeitsdauer weiterverwenden.

CM_SECURITY_NO_CARD_READER

Der Benutzer ist mit Magnetstreifenkarte generiert und kann sich nicht über UPIC anmelden.

CM_SECURITY_CARD_INFO_WRONG

Der Benutzer ist mit Chipkarte generiert.

CM_SECURITY_NO_RESOURCES

Später wieder probieren.

CM_SECURITY_NO_KERBEROS_SUPPORT

Der Benutzer ist mit einem Kerberos-Prinzipal generiert und kann sich nicht über UPIC anmelden.

CM_SECURITY_TAC_KEY_MISSING

Generierung oder Programm ändern.

CM_SECURITY_PWD_EXPIRED_NO_RETRY

Die Gültigkeitsdauer des Passworts ist abgelaufen. Das Passwort muss per Administration geändert werden, bevor der Benutzer sich wieder anmelden kann.

CM_SECURITY_COMPLEXITY_ERROR

Das neue Passwort entsprechend den Anforderungen der generierten Komplexitätsstufe wählen, siehe KDCDEF-Anweisung USER PROTECT-PW=.

CM_SECURITY_PASSWORD_TOO_SHORT

Neues längeres Passwort verwenden oder Generierung ändern, siehe KDCDEF-Anweisung USER PROTECT-PW= length, ... (Wert für die minimale Länge).

CM_SECURITY_UPD_PSWORD_WRONG

Das Passwort entspricht nicht der geforderten Komplexitätsstufe oder hat nicht die erforderliche Länge, siehe KDCDEF-Anweisung USER PROTECT-PW=. Das Passwort muss per Administration geändert werden, bevor sich der Benutzer wieder anmelden kann.

CM_SECURITY_TA_RECOVERY

Für die angegebene Benutzerkennung ist ein Transaktionswiederanlauf erforderlich.

CM_SECURITY_PROTOCOL_CHANGED

Der Benutzer hat einen offenen Vorgang, der nicht von einem UPIC-Client aus fortgesetzt werden kann.

CM_SECURITY_SHUT_WARN

Die UTM-Anwendung wird beendet; es dürfen sich nur noch Benutzer mit Administrationsberechtigung anmelden. Abwarten, bis die Anwendung neu gestartet wurde.

CM_SECURITY_ENC_LEVEL_TOO_HIGH

Auf der Verbindung ist der für die Fortsetzung des offenen Vorgangs nötige Verschlüsselungsmechanismus nicht verfügbar.

CM_SECURITY_PWD_EXPIRED_RETRY

Den Aufbau der Conversation mit Angabe des alten und eines neuen Passworts wiederholen.

Die folgenden sekundären Returncodes treten nur im Zusammenhang mit UTM-Cluster-Anwendungen auf:

CM_SECURITY_USER_GLOBALLY_UNKNOWN

Die angegebene Benutzerkennung ist in der Cluster-User-Datei nicht bekannt.

CM_SECURITY_USER_SIGNED_ON_OTHER_NODE

Mit dieser Benutzerkennung hat sich bereits ein Benutzer an einer anderen Knoten-Anwendung angemeldet.

CM_SECURITY_TRANSIENT_ERROR

Beim Anmelden trat ein temporärer Fehler auf. Auf die Cluster-User-Datei konnte innerhalb der in der Knoten-Anwendung konfigurierten Zeit nicht zugegriffen werden.

Anmeldung später noch einmal versuchen.

Funktionsdeklaration: Receive_Mapped_Data

CM_ENTRY Receive_Mapped_Data (unsigned char CM_PTR  conversation_ID,
            unsigned char                   CM_PTR  map_name,
            CM_INT32                        CM_PTR  map_name_length,
            unsigned char                   CM_PTR  buffer,
            CM_INT32                        CM_PTR  requested_length,
            CM_DATA_RECEIVED_TYPE           CM_PTR  data_received,
            CM_INT32                        CM_PTR  received_length,
            CM_STATUS_RECEIVED              CM_PTR  status_received,
            CM_CONTROL_INFORMATION_RECEIVED CM_PTR  request_to_send_received,
            CM_RETURN_CODE                  CM_PTR  return_code )