Mit dem Aufruf Extract_Secondary_Information (CMESI) erhält das Programm erweiterte Informationen (secondary information), die sich auf den Returncode des letzten CPI-C-Aufrufs beziehen.
CMESI (conversation_ID, call_ID, buffer, requested_length, data_received, received_length, return_code)
Parameter
--> conversation_ID | Identifikation der bereits initialisierten Conversation (wird vom Aufruf Initialize geliefert). |
--> call_ID | spezifiziert die Funktion, deren erweiterte Information ausgegeben werden soll. |
<-- buffer | Puffer, in dem die Daten empfangen werden. Falls der Rückgabewert von data_received CM_NO_DATA_RECEIVED ist oder received_length=0, ist der Inhalt von buffer undefiniert. |
--> requested_length | Maximale Länge der Daten, die empfangen werden können. |
<-- data_received | Gibt an, ob das Programm die erweiterte Information vollständig empfangen hat. Falls das Ergebnis (return_code) nicht den Wert CM_OK hat, ist der Wert von data_received undefiniert. data_received kann folgende Werte annehmen: CM_COMPLETE_DATA_RECEIVED Die erweiterte Information wurde vollständig empfangen. CM_INCOMPLETE_DATA_RECEIVED Die erweiterte Information ist nicht vollständig vom Programm empfangen worden. CM_NO_DATA_RECEIVED Es wurden keine Daten empfangen. |
<-- received_length | Länge der empfangenen Daten. Der Wert von received_length ist undefiniert, falls das Ergebnis (return_code) nicht den Wert CM_OK hat. |
<-- return_code | Ergebnis des Funktionsaufrufs. |
Ergebnis (return_code)
CM_OK
Aufruf OK
CM_NO_SECONDARY_INFORMATION
Für den Aufruf der angegebenen Conversation ist keine erweiterte Information vorhanden.
CM_PROGRAM_PARAMETER_CHECK
Der Wert der conversation_ID ist ungültig, die call_ID gibt CMESI oder einen ungültigen Wert an, oder der Wert für requested_length ist größer als 32767 oder kleiner 1.
CM_PRODUCT_SPECIFIC_ERROR
Die UPIC-Instanz konnte nicht gefunden werden.
Hinweis
Das Programm sollte unmittelbar nach Erhalt eines return_codes diesen Aufruf machen. Nachfolgende CPI-C Aufrufe überschreiben gegebenenfalls die erweiterte Information. Wenn keine Conversation existiert, d.h. die Bibliothek ist im "Reset" Status, wird die conversation_ID ignoriert.
Wenn sich der Extract_Secondary_Information- Aufruf erfolgreich beendet hat, wird die zurückgegebene erweiterte Information nicht länger gespeichert. Die gleiche Information ist im nachfolgenden Extract_Secondary_Information-Aufruf nicht mehr verfügbar.
Das Programm kann den Aufruf nicht dazu nutzen, um von einem vorangegangenen Extract_Secondary_Information-Aufruf erweiterte Information zu erhalten.
Diese Funktion wurde nicht in ihrer vollen Komplexität gemäß den CPI-C Spezifikationen implementiert. Die Vereinfachungen gegenüber CPI-C sind folgende:
- Der interne Puffer besitzt eine beschränkte Größe von 1024 Byte.
- Ist der Wert für requested_length kleiner als die Länge der intern gespeicherten erweiterten Information, wird der vom Anwendungsprogramm zur Verfügung gestellte Puffer vollständig gefüllt und data_received auf CM_INCOMPLETE_DATA_RECEIVED gesetzt. Es ist nicht möglich, die restlichen Daten mit weiteren CMESI-Aufrufen zu erhalten.
Verhalten im Fehlerfall
CM_PROGRAM_PARAMETER_CHECK
Programm ändern.
CM_PRODUCT_SPECIFIC_ERROR
Das Betriebssystem kann nicht genügend Speicherplatz für interne Puffer bereitstellen. Überprüfen Sie Ihr Programm auf zu hohe Speicherplatzanforderung und starten Sie ggf. Ihr System neu.
CM_ENTRY Extract_Secondary_Information (
unsigned char CM_PTR conversation_ID,
CM_INT32 CM_PTR call_ID,
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_RETURN_CODE CM_PTR return_code )