Nachricht empfangen, blockierender und nicht-blockierender Receive

Der UTM-Service übergibt seine Ergebnisse in Form einer Nachricht bzw. mehrerer Teilnachrichten an den Client. Dabei kann es sich auch um eine leere Nachricht handeln. Darüber hinaus überträgt die UTM-Anwendung entweder das Senderecht an den Client oder sie beendet die Conversation. Die Nachricht vom UTM-Service wird von UPIC empfangen und lokal in einem Empfangspuffer abgelegt. Der Client kann die Nachricht bei Bedarf aus dem Empfangspuffer übernehmen. Dazu stehen ihm folgende Receive-Aufrufe zur Verfügung:

Receive()
Receive_Mapped_Data()

Jede Teilnachricht vom UTM-Service (MPUT NT/NE) muss mit einem eigenen Receive-Aufruf empfangen werden. Das Senderecht erhält der Client, wenn beim Receive Aufruf im Feld status_received der Wert CM_SEND_RECEIVED steht.

Wenn der UTM-Service sich beendet (PEND FI), wird die Conversation von der UTM-Anwendung beendet. Dem Client wird beim Receive() der Returncode CM_DEALLOCATE_NORMAL zurückgeliefert und die Conversation geht in den Zustand "Reset" über.

Ein CPI-C-Programm muss immer mindestens einen Receive-Aufruf absetzen, d.h. Send-Aufrufe ohne nachfolgenden Receive-Aufruf sind nicht erlaubt.

Dem folgenden Bild können Sie die Abläufe beim Empfangen von Nachrichten im Client-Programm entnehmen.

Bild 8: Client empfängt eine Nachricht vom Service, die Conversation wird abgebaut

Erläuterungen zum Bild

1. Mit dem Aufruf Set_Receive_Type können Sie festlegen, ob der Empfang der Daten blockierend oder nicht-blockierend erfolgen soll.
   Ob ein Receive-Aufruf blockierend oder nicht-blockierend bearbeitet wird, ist abhängig vom Wert der Conversation Characteristic receive_type. Nach dem Initialisieren der Conversation Characteristics mit dem Aufruf Initialize_Conversation ist der blockierende Receive für die Conversation eingestellt. Mit Hilfe des Aufrufs Set_Receive_Type können Sie diese Voreinstellung ändern.

   Beim blockierenden Receive-Aufruf (receive_type=CM_RECEIVE_AND_WAIT) wartet das Client-Programm solange im Receive bzw. Receive_Mapped_Data, bis Daten von der UTM-Anwendung für die Conversation eingetroffen sind, oder der Aufruf durch einen Timer unterbrochen wird. Erst dann wird die Kontrolle an das Client-Programm zurückgegeben, der Programmlauf kann fortgesetzt werden.

   Wenn Sie mit dem blockierenden Receive arbeiten, dann sollten Sie sicherstellen, dass das Programm nicht „endlos“ wartet. Dazu sollten in der UTM-Anwendung entsprechende Timer gesetzt werden (siehe openUTM-Handbuch „Anwendungen administrieren“ und das openUTM-Handbuch „Anwendungen generieren“). Auf Seiten des Client kann mit Set_Receive_Timer() ein Timeout-Timer für den blockierenden Receive() gesetzt werden.

   Beim nicht-blockierenden Receive-Aufruf (receive_type=CM_RECEIVE_IMMEDIATE) erhält das Programm sofort die Kontrolle zurück. Liegen zum Zeitpunkt des Aufrufs Daten vom Service vor, dann werden sie an das Programm übergeben. Liegen zum Zeitpunkt des Aufrufs keine Daten vor, dann liefert der Aufruf den Returncode CM_UNSUCCESSFUL.

   Die Characteristic receive_type kann innerhalb der Conversation beliebig oft geändert werden. Bei jedem Receive() gilt die Einstellung, die durch den letzten Set_Receive_Type-Aufruf vor dem Receive() festgelegt wurde.
   

Upic-Local:
Bei der lokalen Anbindung über UPIC-Local werden der nicht-blockierende Receive() und der Aufruf Set_Receive_Type() nicht unterstützt.

2. Mit dem Receive- bzw. Receive_Mapped_Data-Aufruf liest der Client die Daten aus dem Empfangspuffer. Liegen Daten vor, dann übergibt der Receive-Aufruf die Daten direkt an das Client-Programm. Der weitere Verlauf des Client-Programms ist abhängig vom Ergebnis des Receive-Aufrufs (Felder data_received, status_received, return_code). Folgende Situationen können auftreten:

1. • Der Receive-Aufruf wurde durchgeführt und UTM hat die Conversation noch nicht beendet (return_code=CM_OK) und

     • die aktuelle Teilnachricht konnte nicht komplett gelesen werden (data_received=CM_INCOMPLETE_DATA_RECEIVED), da sie länger ist als der zur Verfügung gestellte Puffer.
       --> Weitere Teile dieser Teilnachricht müssen per Receive- bzw. Receive_Mapped_Data-Aufruf gelesen werden.

     • die aktuelle Teilnachricht konnte komplett gelesen werden (data_received=CM_COMPLETE_DATA_RECEIVED), der Client hat das Senderecht noch nicht erhalten (status_received=CM_NO_STATUS_RECEIVED).
       --> Weitere Teilnachrichten müssen per Receive- bzw. Receive_Mapped_Data-Aufruf gelesen werden.

     • die aktuelle Teilnachricht konnte komplett gelesen werden (data_received=CM_COMPLETE_DATA_RECEIVED), sie war die letzte (oder einzige) Teilnachricht des UTM-Teilprogrammlaufs, und der Client hat das Senderecht erhalten (status_received=CM_SEND_RECEIVED).
       --> Die Conversation muss mit mindestens einem Send- bzw. Send_Mapped_Data-Aufruf und erneuten Receive- bzw. Receive_Mapped_Data-Aufrufen vom Client fortgesetzt werden. Der UTM-Service ist in diesem Fall ein Mehrschritt-Vorgang (der Teilprogrammlauf hat sich mit PEND RE, PEND KP, PGWT KP oder PGWT CM beendet).

   • Der Receive-Aufruf wurde durchgeführt und UTM hat die Conversation beendet (return_code=CM_DEALLOCATE_NORMAL - der Teilprogrammlauf hat sich mit PEND FI beendet).
     --> Dann geht das Programm in den Status "Reset" über. Es kann jetzt eine neue Conversation aufbauen oder sich mit Disable_UTM_UPIC() bei UPIC abmelden.

3. Nachdem die letzte Conversation beendet ist, ruft das Client-Programm Disable_UTM_UPIC() auf, um sich bei UPIC abzumelden.