Receive (CPI-C)

Artikel
07/21/2023

Der Empfangsaufruf (Funktionsname cmrcv) empfängt alle daten, die derzeit aus dem Partnerprogramm verfügbar sind. Führen Sie für Microsoft Windows einen Hintergrundthread für die gesamte CPI-C-Kommunikation aus, und behalten Sie den Vordergrundthread nur für die Benutzeroberfläche bei.

Syntax

  
CM_ENTRY Receive(   
unsigned char FAR *conversation_ID,    
unsigned char FAR *buffer,             
CM_INT32 FAR *requested_length,        
CM_INT32 FAR *data_received,           
CM_INT32 FAR *received_length,         
CM_INT32 FAR *status_received,         
CM_INT32 FAR *request_to_send_received,    
CM_INT32 FAR *return_code              
);

Parameter

conversation_ID
Angegebener Parameter. Gibt den Bezeichner für die Unterhaltung an. Der Wert dieses Parameters wurde von Initialize_Conversation oder Accept_Conversation zurückgegeben.

Puffer
Zurückgegebener Parameter. Gibt die Adresse des Puffers an, der die vom lokalen Programm empfangenen Daten enthält.

Der Puffer enthält Daten, wenn die folgenden Bedingungen erfüllt sind:

Der data_received-Parameter ist auf einen anderen Wert als CM_NO_DATA_RECEIVED festgelegt.
Der parameter return_code ist auf CM_OK oder auf CM_DEALLOCATED_NORMAL festgelegt.

requested_length
Angegebener Parameter. Gibt die maximale Anzahl von Datenbytes an, die das lokale Programm empfangen soll. Der Bereich reicht von 0 bis 32767.

data_received
Zurückgegebener Parameter. Gibt an, ob das Programm Daten empfangen hat. Mögliche Werte werden im Abschnitt Parameter aufgeführt.

received_length
Zurückgegebener Parameter. Gibt die Anzahl der Datenbytes an, die das lokale Programm bei diesem Empfangsaufruf empfangen hat. Wenn return_code oder data_received angibt, dass das Programm keine Daten empfangen hat, ist diese Zahl nicht relevant.

status_received
Zurückgegebener Parameter. Gibt Änderungen im status der Unterhaltung an. Im Folgenden sind mögliche Werte aufgeführt. Diese Codes sind nur dann relevant , wenn return_code auf CM_OK festgelegt ist. Mögliche Werte werden im Abschnitt Parameter aufgeführt.

request_to_send_received
Zurückgegebener Parameter. Gibt den Request-to-Send-Received-Indikator an. Werte werden im Abschnitt Parameter aufgeführt.

return_code
Der von diesem Aufruf zurückgegebene Code. Werte werden im Abschnitt Parameter aufgeführt.

Im parameter data_received zurückgegebene Werte

Diese Codes sind nur relevant , wenn return_code auf CM_OK oder CM_DEALLOCATED_NORMAL festgelegt ist.

CM_DATA_RECEIVED
Kann für eine einfache Unterhaltung zurückgegeben werden, wenn das Unterhaltungsfüllmerkmal auf CM_FILL_BUFFER festgelegt ist, was angibt, dass das Programm Daten unabhängig von seinem logischen Format empfängt. Das lokale Programm hat Daten empfangen , bis requested_length oder Ende der Daten erreicht wurde.

Das Ende der Daten wird entweder durch eine Änderung an einem anderen Konversationszustand basierend auf den Parametern return_code, status_received und data_received oder durch eine Fehlerbedingung angezeigt. Wenn der Empfangstyp für Unterhaltungen auf CM_RECEIVE_IMMEDIATE festgelegt ist, können die empfangenen Daten kleiner als requested_length sein, wenn eine kleinere Datenmenge aus dem Partnerprogramm eingegangen ist.

CM_COMPLETE_DATA_RECEIVED
Gibt in einer zugeordneten Unterhaltung an, dass das lokale Programm einen vollständigen Datensatz oder den letzten Teil eines Datensatzes erhalten hat.

In einer einfachen Unterhaltung mit dem Füllmerkmal auf CM_FILL_LL festgelegt, gibt dieser Wert an, dass das lokale Programm einen vollständigen logischen Datensatz oder das Ende eines logischen Datensatzes erhalten hat.

CM_INCOMPLETE_DATA_RECEIVED
Gibt in einer zugeordneten Unterhaltung an, dass das lokale Programm einen unvollständigen Datensatz erhalten hat. Der requested_length-Parameter hat einen Wert angegeben, der kleiner als die Länge des Datensatzes ist (oder kleiner als der Rest des Datensatzes, wenn dies nicht der erste Empfang ist, der den Datensatz liest). Die empfangene Datenmenge entspricht dem parameter requested_length .

In einer einfachen Unterhaltung, bei der die Fülleigenschaft auf CM_FILL_LL festgelegt ist, gibt dieser Wert an, dass das lokale Programm einen unvollständigen logischen Datensatz erhalten hat. Die empfangene Datenmenge entspricht dem parameter requested_length . (Wenn die empfangenen Daten abgeschnitten wurden, ist die Länge der Daten kleiner als requested_length.)

Nach Dem Empfang dieses Werts wird Receive vom lokalen Programm normalerweise neu ausgegeben, um den nächsten Teil des Datensatzes zu erhalten.

CM_NO_DATA_RECEIVED
Das Programm hat keine Daten empfangen.

Beachten Sie, dass, wenn der parameter return_code auf CM_OK festgelegt ist, status Informationen möglicherweise über den parameter status_received verfügbar sind.

Im parameter status_received zurückgegebene Werte

CM_NO_STATUS_RECEIVED
Bei diesem Anruf wurde keine Konversation status Änderung empfangen.

CM_SEND_RECEIVED
Gibt für das Partnerprogramm an, dass die Unterhaltung den RECEIVE-Status erreicht hat. Für das lokale Programm befindet sich die Unterhaltung jetzt im SEND-Zustand, wenn bei diesem Aufruf keine Daten empfangen wurden, oder SEND_PENDING Zustand, wenn Daten bei diesem Aufruf empfangen wurden.

Beim Empfang dieses Werts verwendet das lokale Programm normalerweise Send_Data , um mit dem Senden von Daten zu beginnen.

CM_CONFIRM_DEALLOC_RECEIVED
Gibt an, dass das Partnerprogramm Deallocate mit der angeforderten Bestätigung ausgestellt hat. Für das lokale Programm befindet sich die Unterhaltung jetzt in CONFIRM_DEALLOCATE Zustand.

Nach Erhalt dieses Werts gibt das lokale Programm normalerweise den Bestätigten Aufruf aus .

CM_CONFIRM_RECEIVED
Gibt an, dass das Partnerprogramm den Bestätigungsaufruf ausgegeben hat. Für das lokale Programm befindet sich die Unterhaltung im CONFIRM-Zustand.

Nach Erhalt dieses Werts gibt das lokale Programm normalerweise den Bestätigten Aufruf aus .

CM_CONFIRM_SEND_RECEIVED
Gibt für das Partnerprogramm an, dass die Unterhaltung den RECEIVE-Status erreicht hat und eine Bestätigungsanforderung vom lokalen Programm empfangen wurde. Für das lokale Programm befindet sich die Unterhaltung jetzt in CONFIRM_SEND Zustand.

Das Programm antwortet normalerweise, indem es den bestätigten Anruf ausgibt. Nach erfolgreicher Ausführung des bestätigten Anrufs wechselt die Unterhaltung in den SEND-Status für das lokale Programm.

Im Parameter request_to_send_received zurückgegebene Werte

CM_REQ_TO_SEND_RECEIVED
Das Partnerprogramm hat den Request_To_Send-Aufruf ausgegeben, der das lokale Programm aufforderte, die Unterhaltung in den RECEIVE-Status zu ändern.

CM_REQ_TO_SEND_NOT_RECEIVED
Das Partnerprogramm hat den Request_To_Send Aufruf nicht ausstellen. Dieser Wert ist nicht relevant, wenn der parameter return_code auf CM_PROGRAM_PARAMETER_CHECK oder CM_PROGRAM_STATE_CHECK festgelegt ist.

Im parameter return_code zurückgegebene Werte

CM_OK
Primärer Rückgabecode; der Aufruf wurde erfolgreich ausgeführt.

CM_OPERATION_NOT_ACCEPTED
Primärer Rückgabecode; ein vorheriger Vorgang für diese Unterhaltung ist unvollständig.

CM_OPERATION_INCOMPLETE
Primärer Rückgabecode; Der Vorgang wurde noch nicht abgeschlossen (der Verarbeitungsmodus ist nur nicht blockiert) und wird noch ausgeführt. Das Programm kann Wait_For_Conversation ausgeben, um den Abschluss des Vorgangs abzuwarten, oder Cancel_Conversation , den Vorgang und die Unterhaltung abzubrechen. Wenn Specify_Windows_Handle aufgerufen wurde, sollte die Anwendung auf eine Benachrichtigung durch eine Windows-Nachricht® warten und nicht Wait_For_Conversation aufrufen.

CM_UNSUCCESSFUL
Primärer Rückgabecode; Der Empfangstyp ist auf CM_RECEIVE_IMMEDIATE festgelegt, und es sind keine Daten sofort aus dem Partnerprogramm verfügbar.

CM_DEALLOCATED_NORMAL
Primärer Rückgabecode; Die Zuordnung der Unterhaltung wurde normal aufgehoben. Das Partnerprogramm hat Deallocate mit dem Typ "Aufheben der Zuordnung von Unterhaltungen" ausgestellt, der auf CM_DEALLOCATE_FLUSH oder CM_DEALLOCATE_SYNC_LEVEL festgelegt ist, wobei die Synchronisierungsebene der Unterhaltung als CM_NONE angegeben ist.

CM_PROGRAM_PARAMETER_CHECK
Primärer Rückgabecode; eine der folgenden Ereignisse:

Der von conversation_ID angegebene Wert ist ungültig.
Der durch requested_length angegebene Wert liegt außerhalb des Bereichs (größer als 32767).

Wenn das Programm diesen Rückgabecode empfängt, sind die anderen zurückgegebenen Parameter ungültig.

CM_PROGRAM_STATE_CHECK
Primärer Rückgabecode; eine der folgenden Ereignisse:
Der Empfangstyp ist auf CM_RECEIVE_AND_WAIT festgelegt, und der Unterhaltungszustand lautet nicht RECEIVE, SEND oder SEND_PENDING.
Der Empfangstyp ist auf CM_RECEIVE_IMMEDIATE festgelegt, und der Unterhaltungszustand ist nicht EMPFANGEN.
In einer einfachen Unterhaltung befindet sich die Unterhaltung im SEND-Zustand, der Empfangstyp ist auf CM_RECEIVE_AND_WAIT festgelegt, und das Programm hat das Senden eines logischen Datensatzes nicht abgeschlossen.

Wenn das Programm diesen Rückgabecode empfängt, sind die anderen zurückgegebenen Parameter ungültig.

CM_PRODUCT_SPECIFIC_ERROR
Primärer Rückgabecode; Ein produktspezifischer Fehler ist aufgetreten und wurde im Produktfehlerprotokoll protokolliert.

CM_CONVERSATION_TYPE_MISMATCH
Primärer Rückgabecode; Die partner logical unit (LU) oder das Programm unterstützt den in der Zuordnungsanforderung angegebenen Konversationstyp (basic oder mapped) nicht.

CM_PIP_NOT_SPECIFIED_CORRECTLY
Primärer Rückgabecode; Die Zuordnungsanforderung wurde von einem Nicht-C LU 6.2-Transaktionsprogramm (TP) abgelehnt. Das Partnerprogramm erfordert eine oder mehrere PIP-Datenvariablen, die von CPI-C nicht unterstützt werden.

CM_SECURITY_NOT_VALID
Primärer Rückgabecode; Die in der Zuordnungsanforderung angegebene Benutzer-ID oder das Kennwort wurde von der Partner-LU nicht akzeptiert.

CM_SYNC_LEVEL_NOT_SUPPORTED_PGM
Primärer Rückgabecode; das Partnerprogramm unterstützt die in der Zuordnungsanforderung angegebene Synchronisierungsebene nicht.

CM_TPN_NOT_RECOGNIZED
Primärer Rückgabecode; Die Partner-LU erkennt den in der Zuordnungsanforderung angegebenen Programmnamen nicht.

CM_TP_NOT_AVAILABLE_NO_RETRY
Primärer Rückgabecode; Die Partner-LU kann das in der Zuordnungsanforderung angegebene Programm aufgrund einer dauerhaften Bedingung nicht starten. Der Grund für den Fehler wird möglicherweise auf dem Remoteknoten protokolliert. Wiederholen Sie die Zuordnung erst, wenn der Fehler behoben wurde.

CM_TP_NOT_AVAILABLE_RETRY
Primärer Rückgabecode; Die Partner-LU kann das in der Zuordnungsanforderung angegebene Programm aufgrund einer temporären Bedingung nicht starten. Der Grund für den Fehler wird möglicherweise auf dem Remoteknoten protokolliert. Wiederholen Sie die Zuordnung.

CM_PROGRAM_ERROR_NO_TRUNC
Primärer Rückgabecode; Während sich der Status SEND oder SEND_PENDING Zustand befindet, in dem die Fehlerrichtung auf CM_SEND_ERROR festgelegt ist, hat das Partnerprogramm Send_Error ausgestellt. Daten wurden nicht gekürzt.

CM_PROGRAM_ERROR_PURGING
Primärer Rückgabecode; eine der folgenden Ereignisse:
Im Status RECEIVE oder CONFIRM hat das Partnerprogramm Send_Error ausgestellt. Gesendete, aber noch nicht empfangene Daten werden gelöscht.
Während sich SEND_PENDING Zustand befindet, in dem die Fehlerrichtung auf CM_RECEIVE_ERROR festgelegt ist, hat das Partnerprogramm Send_Error ausgestellt. Daten wurden nicht gelöscht.

CM_RESOURCE_FAILURE_NO_RETRY
Primärer Rückgabecode; eine der folgenden Ereignisse:
Die Unterhaltung wurde aufgrund eines dauerhaften Zustands vorzeitig beendet. Wiederholen Sie den Vorgang erst, wenn der Fehler behoben wurde.
Das Partnerprogramm hat die Zuordnung der Unterhaltung vor dem normalen Beenden nicht aufgehoben.

CM_RESOURCE_FAILURE_RETRY
Primärer Rückgabecode; Die Konversation wurde aufgrund einer vorübergehenden Bedingung, z. B. eines Modemfehlers, vorzeitig beendet. Wiederholen Sie die Unterhaltung.

CM_DEALLOCATED_ABEND
Primärer Rückgabecode; Die Zuordnung der Unterhaltung wurde aus einem der folgenden Gründe aufgehoben:
Das Remoteprogramm hat Deallocate mit dem Typparameterset für CM_DEALLOCATE_ABEND ausgestellt, oder die Remote-LU hat dies aufgrund eines ungewöhnlichen Beendigungszustands des Remoteprogramms ausgeführt. Wenn sich die Unterhaltung für das Remoteprogramm im Empfangszustand befand, als der Anruf ausgegeben wurde, werden die vom lokalen Programm gesendeten und noch nicht vom Remoteprogramm empfangenen Informationen gelöscht.
Der Remote-TP wurde normal beendet, aber die Zuordnung der Konversation vor dem Beenden nicht aufgehoben. Knotendienste auf der Remote-LU haben die Zuordnung der Konversation im Namen des Remote-TP aufgehoben.

CM_DEALLOCATED_ABEND_SVC
Primärer Rückgabecode; Die Zuordnung der Unterhaltung wurde aus einem der folgenden Gründe aufgehoben:
Das Partnerprogramm hat Deallocate mit dem typparameter ausgestellt, der auf ABEND_SVC festgelegt ist.
Das Partnerprogramm hat die Zuordnung der Unterhaltung vor dem Beenden nicht aufgehoben.

Wenn sich die Unterhaltung für das Partnerprogramm im EMPFANGSzustand befindet, wenn dieser Aufruf vom lokalen Programm ausgegeben wird, werden die vom lokalen Programm gesendeten und noch nicht vom Partnerprogramm empfangenen Daten gelöscht.

CM_DEALLOCATED_ABEND_TIMER
Primärer Rückgabecode; Die Zuordnung der Unterhaltung wurde aufgehoben, weil das Partnerprogramm Deallocate mit dem typparameter auf ABEND_TIMER festgelegt hat. Wenn sich die Unterhaltung für das Partnerprogramm im EMPFANGSzustand befindet, wenn dieser Aufruf vom lokalen Programm ausgegeben wird, werden die vom lokalen Programm gesendeten und noch nicht vom Partnerprogramm empfangenen Daten gelöscht.

CM_SVC_ERROR_PURGING
Primärer Rückgabecode; Im SEND-Zustand hat das Partnerprogramm oder die Partner-LU Send_Error ausgestellt, wobei der Typparameter auf SVC festgelegt ist. An das Partnerprogramm gesendete Daten wurden möglicherweise gelöscht.

CM_SVC_ERROR_NO_TRUNC
Primärer Rückgabecode; Im SEND-Zustand hat das Partnerprogramm oder die Partner-LU Send_Error ausgestellt, wobei der Typparameter auf SVC festgelegt ist. An das Partnerprogramm gesendete Daten wurden möglicherweise gelöscht.

CM_PROGRAM_ERROR_TRUNC
Primärer Rückgabecode; im SEND-Zustand, bevor das Senden eines vollständigen logischen Datensatzes abgeschlossen ist, hat das Partnerprogramm Send_Error ausgestellt. Das lokale Programm hat möglicherweise den ersten Teil des logischen Datensatzes über einen Empfangsanruf empfangen.

CM_SVC_ERROR_TRUNC
Primärer Rückgabecode; Im Status RECEIVE oder CONFIRM hat das Partnerprogramm oder die Partner-LU Send_Error ausgestellt, wobei der Typparameter auf SVC festgelegt ist, bevor es den vollständigen logischen Datensatz gesendet hat. Das lokale Programm hat möglicherweise den ersten Teil des logischen Datensatzes erhalten.

Zustandsänderungen

Die Unterhaltung kann sich im Status "RECEIVE", "SEND" oder "SEND_PENDING" befinden.

Wenn receive_type auf CM_RECEIVE_IMMEDIATE festgelegt ist, muss sich die Unterhaltung im Empfangszustand befinden.

Die Ausgabe von Receive , während sich die Unterhaltung im SEND- oder SEND_PENDING Zustand befindet, bewirkt, dass die lokale LU die Informationen in ihrem Sendepuffer und einen Sendeindikator an das Partnerprogramm sendet. Basierend auf data_received und status_received kann sich die Unterhaltung für das lokale Programm in den EMPFANGSzustand ändern.

Der neue Unterhaltungszustand wird durch Folgendes bestimmt:
Der Zustand, in dem sich die Konversation befindet, wenn das Programm den Aufruf ausgibt.
Der parameter return_code .
Die Parameter data_received und status_received.

Wenn derzeit keine Daten verfügbar sind und der Empfangstyp (durch Set_Receive_Type festgelegt) auf CM_RECEIVE_AND_WAIT festgelegt ist, wartet das lokale Programm auf das Eintreffen von Daten. Wenn der Empfangstyp auf CM_RECEIVE_IMMEDIATE festgelegt ist, wartet das lokale Programm nicht.

Der Prozess zum Empfangen von Daten sieht wie folgt aus:
Das lokale Programm gibt einen Empfangsaufruf aus, bis es eine vollständige Dateneinheit erhält. Das lokale Programm muss möglicherweise mehrmals Receive ausgeben, um eine vollständige Dateneinheit zu erhalten. Der parameter data_received gibt an, ob der Empfang der Daten abgeschlossen ist.

Die empfangenen Daten können wie folgt sein:
- Ein Datensatz, der in einer zugeordneten Unterhaltung übertragen wird.
- Ein logischer Datensatz, der in einer einfachen Unterhaltung übertragen wird, wobei das Füllmerkmal für Unterhaltungen auf CM_FILL_LL festgelegt ist.
- Ein Puffer von Daten, der unabhängig vom Format des logischen Datensatzes in einer einfachen Konversation empfangen wird, wobei das Füllmerkmal auf CM_FILL_BUFFER festgelegt ist.
  
  Wenn eine vollständige Dateneinheit empfangen wurde, kann das lokale Programm sie bearbeiten.
Das lokale Programm bestimmt die nächste Auszuführende Aktion basierend auf den Kontrollinformationen , die über status_received empfangen wurden. Das lokale Programm muss möglicherweise erneut Receive abrufen, um die Steuerungsinformationen zu erhalten.

Der Unterhaltungstyp wird durch Set_Conversation_Type festgelegt. Das Füllmerkmal wird durch Set_Fill festgelegt.

In der folgenden Tabelle sind die Zustandsänderungen zusammengefasst, die auftreten können, wenn Receive für die Unterhaltung im RECEIVE-Zustand ausgegeben wird und return_code CM_OK ist.

data_received	status_received	Neuer Zustand
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	Keine Änderung
CM_COMPLETE_DATA_ ERHALTEN	CM_NO_STATUS_RECEIVED	Keine Änderung
CM_INCOMPLETE_DATA_ EMPFANGEN	CM_SEND_RECEIVED	SEND_PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	SEND

Wenn return_code auf CM_UNSUCCESSFUL festgelegt ist, was bedeutet, dass die receive_type auf CM_RECEIVE_IMMEDIATE festgelegt ist und keine Daten verfügbar sind, gibt es keine Zustandsänderung.

In der folgenden Tabelle sind die Zustandsänderungen zusammengefasst, die auftreten können, wenn Empfangen mit der Unterhaltung im SEND-Zustand ausgegeben wird und return_code CM_OK ist.

data_received	status_received	Neuer Zustand
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_COMPLETE_DATA_ ERHALTEN	CM_NO_STATUS_RECEIVED	RECEIVE
CM_INCOMPLETE_DATA_ EMPFANGEN	CM_SEND_RECEIVED	SEND_PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	Keine Änderung

In der folgenden Tabelle sind die Zustandsänderungen zusammengefasst, die auftreten können, wenn empfangen für die Unterhaltung in SEND_PENDING Zustand ausgegeben wird und return_code CM_OK ist.

data_received	status_received	Neuer Zustand
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_COMPLETE_DATA_ ERHALTEN	CM_NO_STATUS_RECEIVED	RECEIVE
CM_INCOMPLETE_DATA_ EMPFANGEN	CM_SEND_RECEIVED	Keine Änderung
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	SEND

In den folgenden Themen werden Zustandsänderungen zusammengefasst, die auftreten können, wenn Der Empfang in einem beliebigen zulässigen Zustand ausgegeben wird.

Freigeben über