Empfangen (CPI-C)

Der Empfangsaufruf (Funktionsname cmrcv) empfängt alle daten, die derzeit vom Partnerprogramm zur Verfügung stehen. Führen Sie für Microsoft Windows einen Hintergrundthread für alle 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.

buffer
Zurückgegebener Parameter. Gibt die Adresse des Puffers an, die die vom lokalen Programm empfangenen Daten enthalten soll.

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

• Der parameter data_received wird auf einen anderen Wert als CM_NO_DATA_RECEIVED festgelegt.

• Der parameter return_code wird auf CM_OK oder auf CM_DEALLOCATED_NORMAL festgelegt.

  requested_length
  Angegebener Parameter. Gibt an, wie viele Byte das lokale Programm empfangen soll. Der Bereich liegt zwischen 0 und 32767.

  data_received
  Zurückgegebener Parameter. Gibt an, ob das Programm Daten empfangen hat. Mögliche Werte sind im Anschluss an den Abschnitt "Parameters" aufgeführt.

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

  status_received
  Zurückgegebener Parameter. Gibt Änderungen am Status der Unterhaltung an. Im Folgenden sind mögliche Werte aufgeführt. Diese Codes sind nur relevant , wenn return_code auf CM_OK festgelegt ist. Mögliche Werte sind im Anschluss an den Abschnitt "Parameters" aufgeführt.

  request_to_send_received
  Zurückgegebener Parameter. Gibt den Anforderungs-zu-Sende-Empfangen-Indikator an. Werte werden im Anschluss an den Abschnitt "Parameters" aufgeführt.

  return_code
  Der von diesem Aufruf zurückgegebene Code. Werte werden im Anschluss an den Abschnitt "Parameters" 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 Füllmerkmal für Unterhaltungen auf CM_FILL_BUFFER festgelegt ist und angibt, dass das Programm Daten erhält, die von seinem logischen Format unabhängig sind. Das lokale Programm hat Daten empfangen, bis requested_length oder das Ende der Daten erreicht wurde.

Das Ende der Daten wird entweder durch eine Änderung an einem anderen Unterhaltungszustand angezeigt, basierend auf dem return_code, status_received und data_received Parametern oder einer Fehlerbedingung. Wenn der Unterhaltungstyp 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 empfangen hat.

In einer einfachen Unterhaltung mit dem auf CM_FILL_LL festgelegten Füllmerkmal weist dieser Wert darauf hin, 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 empfangen 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 Empfangen ist, der den Datensatz liest). Die empfangene Datenmenge entspricht dem parameter requested_length .

In einer einfachen Unterhaltung mit dem Füllmerkmalsatz auf CM_FILL_LL 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.)

Beim Empfang dieses Werts fordert das lokale Programm normalerweise "Receive" wieder auf, um den nächsten Teil des Datensatzes zu erhalten.

CM_NO_DATA_RECEIVED
Das Programm hat keine Daten empfangen.

Beachten Sie, dass Statusinformationen über den status_received-Parameter verfügbar sein können, wenn der parameter return_code auf CM_OK festgelegt ist.

Im parameter status_received zurückgegebene Werte

CM_NO_STATUS_RECEIVED
Bei diesem Anruf wurde keine Änderung des Unterhaltungsstatus empfangen.

CM_SEND_RECEIVED
Gibt für das Partnerprogramm an, dass die Unterhaltung den STATUS RECEIVE eingegeben hat. Für das lokale Programm befindet sich die Unterhaltung jetzt im SEND-Zustand, wenn für diesen Anruf keine Daten empfangen wurden, oder SEND_PENDING Zustand, ob Daten für diesen Anruf 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.

Beim Empfang dieses Werts gibt das lokale Programm normalerweise den bestätigten Anruf aus.

CM_CONFIRM_RECEIVED
Gibt an, dass das Partnerprogramm den Bestätigungsanruf ausgestellt hat. Für das lokale Programm befindet sich die Unterhaltung im Bestätigungszustand.

Beim Empfang dieses Werts gibt das lokale Programm normalerweise den bestätigten Anruf aus.

CM_CONFIRM_SEND_RECEIVED
Gibt für das Partnerprogramm an, dass die Unterhaltung den STATUS RECEIVE eingegeben 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 er den bestätigten Anruf ausstellt. Bei erfolgreicher Ausführung des bestätigten Anrufs ändert sich die Unterhaltung in den SEND-Zustand 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 Anruf ausgegeben, der das lokale Programm anfordert, die Unterhaltung in den STATUS EMPFANGEN zu ändern.

CM_REQ_TO_SEND_NOT_RECEIVED
Das Partnerprogramm hat den Request_To_Send Anruf nicht ausstellen können. 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 nicht abgeschlossen (der Verarbeitungsmodus ist nur nicht blockiert) und wird noch ausgeführt. Das Programm kann Wait_For_Conversation ausgeben, um auf den Abschluss des Vorgangs zu warten, oder Cancel_Conversation , um den Vorgang und die Unterhaltung abzubrechen. Wenn Specify_Windows_Handle aufgerufen wurde, sollte die Anwendung auf die Benachrichtigung durch eine Windows-Nachricht® warten und nicht Wait_For_Conversation aufrufen.

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

CM_DEALLOCATED_NORMAL
Primärer Rückgabecode; die Unterhaltung wurde normal abgeglichen. Das Partnerprogramm hat Deallocate mit dem Typ "Deallocate" ausgegeben, der auf CM_DEALLOCATE_FLUSH oder CM_DEALLOCATE_SYNC_LEVEL mit der Synchronisierungsebene der unterhaltung festgelegt ist, die als CM_NONE angegeben wurde.

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

• Der durch 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; einer der folgenden Ereignisse:

• Der Empfangstyp ist auf CM_RECEIVE_AND_WAIT festgelegt, und der Unterhaltungszustand ist nicht EMPFANGEN, SENDEN 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 Fehlerprotokoll der Produkte protokolliert.

  CM_CONVERSATION_TYPE_MISMATCH
  Primärer Rückgabecode; die logische Partnereinheit (PARTNER Logical Unit, LU) oder das Programm unterstützt nicht den in der Zuordnungsanforderung angegebenen Unterhaltungstyp (einfach oder zugeordnet).

  CM_PIP_NOT_SPECIFIED_CORRECTLY
  Primärer Rückgabecode; die Zuordnungsanforderung wurde von einem Nicht-CPI-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 nicht die in der Zuordnungsanforderung angegebene Synchronisierungsebene.

  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 kann auf dem Remoteknoten protokolliert werden. 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 kann auf dem Remoteknoten protokolliert werden. Wiederholen Sie die Zuordnung.

  CM_PROGRAM_ERROR_NO_TRUNC
  Primärer Rückgabecode; im SEND-Zustand oder in SEND_PENDING Zustand, wobei die Fehlerrichtung auf CM_SEND_ERROR festgelegt ist, hat das Partnerprogramm Send_Error ausgestellt. Daten wurden nicht abgeschnitten.

  CM_PROGRAM_ERROR_PURGING
  Primärer Rückgabecode; einer der folgenden Ereignisse:

• Während des Status "EMPFANGEN" oder "BESTÄTIGEN" hat das Partnerprogramm Send_Error ausgestellt. Gesendete, aber noch nicht empfangene Daten werden gelöscht.

• Während in SEND_PENDING Zustand, 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; einer der folgenden Ereignisse:

• Die Unterhaltung wurde aufgrund einer dauerhaften Bedingung vorzeitig beendet. Wiederholen Sie den Vorgang erst, wenn der Fehler korrigiert wurde.

• Das Partnerprogramm hat die Unterhaltung vor dem normalen Beenden nicht behandelt.

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

  CM_DEALLOCATED_ABEND
  Primärer Rückgabecode; die Unterhaltung wurde aus einem der folgenden Gründe umgestellt:

• Das Remoteprogramm hat Deallocate mit dem Typparameteret für CM_DEALLOCATE_ABEND ausgestellt, oder die Remote-LU hat dies aufgrund eines ungewöhnlichen Zustands des Remoteprogramms ausgeführt. Wenn sich die Unterhaltung für das Remoteprogramm beim Senden des Anrufs im EMPFANGSzustand befand, werden informationen, die vom lokalen Programm gesendet und noch nicht vom Remoteprogramm empfangen wurden, gelöscht.

• Der Remote-TP wurde normal beendet, hat die Unterhaltung jedoch nicht vor dem Beenden behandelt. Knotendienste in der Remote-LU haben die Unterhaltung im Auftrag des Remote-TP abgeglichen.

  CM_DEALLOCATED_ABEND_SVC
  Primärer Rückgabecode; die Unterhaltung wurde aus einem der folgenden Gründe umgestellt:

• Das Partnerprogramm hat Deallocate ausgestellt, wobei der Typparameter auf ABEND_SVC festgelegt ist.

• Das Partnerprogramm hat die Unterhaltung vor dem Beenden nicht behandelt.

  Wenn sich die Unterhaltung im STATUS RECEIVE für das Partnerprogramm befindet, wenn dieser Anruf vom lokalen Programm ausgestellt wird, werden die vom lokalen Programm gesendeten Daten und noch nicht vom Partnerprogramm empfangen.

  CM_DEALLOCATED_ABEND_TIMER
  Primärer Rückgabecode; die Unterhaltung wurde abgeglichen, da das Partnerprogramm Deallocate mit dem Typparameter ausgegeben hat, der auf ABEND_TIMER festgelegt ist. Wenn sich die Unterhaltung im STATUS RECEIVE für das Partnerprogramm befindet, wenn dieser Anruf vom lokalen Programm ausgestellt wird, werden die vom lokalen Programm gesendeten Daten und noch nicht vom Partnerprogramm empfangen.

  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. Daten, die an das Partnerprogramm gesendet werden, 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. Daten, die an das Partnerprogramm gesendet werden, wurden möglicherweise gelöscht.

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

  CM_SVC_ERROR_TRUNC
  Primärer Rückgabecode; während der STATUS "RECEIVE" oder "CONFIRM" hat das Partnerprogramm oder die Partner-LU Send_Error ausgestellt, wobei der Typparameter auf SVC festgelegt ist, bevor er das Senden eines vollständigen logischen Datensatzes abgeschlossen hat. Das lokale Programm hat möglicherweise den ersten Teil des logischen Datensatzes erhalten.

  Statusänderungen

  Die Unterhaltung kann sich im Status "EMPFANGEN", "SENDEN" oder "SEND_PENDING" befinden.

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

  Wenn sich die Unterhaltung im SEND- oder SEND_PENDING-Zustand befindet, sendet die lokale LU die Informationen im Sendepuffer und eine Sendeanzeige an das Partnerprogramm. Basierend auf data_received und status_received kann die Unterhaltung in den EMPFANGSstatus für das lokale Programm geändert werden.

  Der neue Unterhaltungszustand wird durch Folgendes bestimmt:

• Der Zustand, in dem sich die Unterhaltung befindet, wenn das Programm den Anruf 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 lautet wie folgt:

• Das lokale Programm gibt einen Empfangsanruf aus, bis er den Empfang einer vollständigen Dateneinheit abgeschlossen hat. Das lokale Programm muss möglicherweise mehrmals Empfangen 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 möglich sein:

  • Ein Datensatz, der in einer zugeordneten Unterhaltung übertragen wird.

  • Ein logischer Datensatz, der in einer einfachen Unterhaltung mit den Auffüllungsmerkmalen für CM_FILL_LL übertragen wurde.

  • Ein Puffer von Daten, die unabhängig vom logischen Datensatzformat in einer einfachen Unterhaltung mit dem Füllmerkmal auf CM_FILL_BUFFER empfangen wurden.

    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 über status_received empfangenen Steuerelementinformationen. Das lokale Programm muss möglicherweise erneut empfangen , um die Steuerinformationen 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 "Empfangen" mit der Unterhaltung im EMPFANGSstatus ausgegeben wird und return_code CM_OK ist.

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.

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

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

In diesem Abschnitt

• Bestätigung

• Normale Deallocation

• ABEND

• Fehler