Receive (CPI-C)

Articolo
07/21/2023

La chiamata Di ricezione (nome funzione cmrcv) riceve tutti i dati attualmente disponibili dal programma partner. Per Microsoft Windows, eseguire un thread in background per tutte le comunicazioni CPI-C e mantenere il thread in primo piano solo per l'interfaccia utente.

Sintassi

  
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              
);

Parametri

conversation_ID
Parametro fornito. Specifica l'identificatore per la conversazione. Il valore di questo parametro è stato restituito da Initialize_Conversation o Accept_Conversation.

buffer
Parametro restituito. Specifica l'indirizzo del buffer in cui contenere i dati ricevuti dal programma locale.

Il buffer contiene dati se le condizioni seguenti sono vere:

Il parametro data_received è impostato su un valore diverso da CM_NO_DATA_RECEIVED.
Il parametro return_code è impostato su CM_OK o su CM_DEALLOCATED_NORMAL.

requested_length
Parametro fornito. Indica il numero massimo di byte di dati che il programma locale deve ricevere. L'intervallo è compreso tra 0 e 32767.

data_received
Parametro restituito. Indica se il programma ha ricevuto i dati. I valori possibili sono elencati seguendo la sezione Parametri.

received_length
Parametro restituito. Indica il numero di byte di dati ricevuti dal programma locale in questa chiamata di ricezione . Se return_code o data_received indica che il programma non ha ricevuto dati, questo numero non è rilevante.

status_received
Parametro restituito. Indica le modifiche dello stato della conversazione. Di seguito sono riportati i valori possibili. Questi codici non sono rilevanti a meno che non return_code sia impostato su CM_OK. I valori possibili sono elencati seguendo la sezione Parametri.

request_to_send_received
Parametro restituito. Specifica l'indicatore request-to-send-received. I valori sono elencati seguendo la sezione Parametri.

return_code
Codice restituito da questa chiamata. I valori sono elencati seguendo la sezione Parametri.

Valori restituiti nel parametro data_received

Questi codici non sono rilevanti a meno che non return_code sia impostato su CM_OK o CM_DEALLOCATED_NORMAL.

CM_DATA_RECEIVED
Può essere restituito per una conversazione di base se la caratteristica di riempimento delle conversazioni è impostata su CM_FILL_BUFFER, a indicare che il programma riceve dati indipendentemente dal formato logico. Il programma locale ha ricevuto i dati fino a quando non sono stati raggiunti requested_length o la fine dei dati.

La fine dei dati è indicata da una modifica a un altro stato della conversazione, in base ai parametri return_code, status_received e data_received o a una condizione di errore. Se il tipo di ricezione delle conversazioni è impostato su CM_RECEIVE_IMMEDIATE, i dati ricevuti possono essere inferiori a requested_length se dal programma partner è arrivata una quantità minore di dati.

CM_COMPLETE_DATA_RECEIVED
In una conversazione mappata indica che il programma locale ha ricevuto un record di dati completo o l'ultima parte di un record di dati.

In una conversazione di base con la caratteristica di riempimento impostata su CM_FILL_LL, questo valore indica che il programma locale ha ricevuto un record logico completo o la fine di un record logico.

CM_INCOMPLETE_DATA_RECEIVED
In una conversazione mappata indica che il programma locale ha ricevuto un record di dati incompleto. Il parametro requested_length ha specificato un valore minore della lunghezza del record di dati (o minore del resto del record di dati se non è il primo oggetto Receive per leggere il record). La quantità di dati ricevuti è uguale al parametro requested_length .

In una conversazione di base con la caratteristica di riempimento impostata su CM_FILL_LL, questo valore indica che il programma locale ha ricevuto un record logico incompleto. La quantità di dati ricevuti è uguale al parametro requested_length . Se i dati ricevuti sono stati troncati, la lunghezza dei dati sarà minore di requested_length.

Al momento della ricezione di questo valore, il programma locale in genere esegue nuovamente Receive per ricevere la parte successiva del record.

CM_NO_DATA_RECEIVED
Il programma non ha ricevuto i dati.

Si noti che se il parametro return_code è impostato su CM_OK, le informazioni sullo stato potrebbero essere disponibili tramite il parametro status_received .

Valori restituiti nel parametro status_received

CM_NO_STATUS_RECEIVED
Non è stata ricevuta alcuna modifica dello stato della conversazione in questa chiamata.

CM_SEND_RECEIVED
Indica, per il programma partner, che la conversazione ha immesso lo stato RECEIVE. Per il programma locale, la conversazione è ora in stato SEND se non sono stati ricevuti dati su questa chiamata o SEND_PENDING stato se i dati sono stati ricevuti su questa chiamata.

Al momento della ricezione di questo valore, il programma locale usa in genere Send_Data per iniziare a inviare dati.

CM_CONFIRM_DEALLOC_RECEIVED
Indica che il programma partner ha emesso Deallocate con la conferma richiesta. Per il programma locale, la conversazione è ora in CONFIRM_DEALLOCATE stato.

Al momento della ricezione di questo valore, il programma locale in genere emette la chiamata confermata .

CM_CONFIRM_RECEIVED
Indica che il programma partner ha emesso la chiamata Confirm . Per il programma locale, la conversazione è in stato CONFIRM.

Al momento della ricezione di questo valore, il programma locale in genere emette la chiamata confermata .

CM_CONFIRM_SEND_RECEIVED
Indica, per il programma partner, che la conversazione ha immesso lo stato RECEIVE e che è stata ricevuta una richiesta di conferma dal programma locale. Per il programma locale, la conversazione è ora in CONFIRM_SEND stato.

Il programma risponde normalmente eseguendo la chiamata confermata . Al termine dell'esecuzione della chiamata confermata , la conversazione passa allo stato SEND per il programma locale.

Valori restituiti nel parametro request_to_send_received

CM_REQ_TO_SEND_RECEIVED
Il programma partner ha emesso la chiamata Request_To_Send , che richiede al programma locale di modificare lo stato RECEIVE della conversazione.

CM_REQ_TO_SEND_NOT_RECEIVED
Il programma partner non ha eseguito la chiamata Request_To_Send . Questo valore non è rilevante se il parametro return_code è impostato su CM_PROGRAM_PARAMETER_CHECK o CM_PROGRAM_STATE_CHECK.

Valori restituiti nel parametro return_code

CM_OK
Codice restituito primario; la chiamata eseguita correttamente.

CM_OPERATION_NOT_ACCEPTED
Codice restituito primario; un'operazione precedente in questa conversazione è incompleta.

CM_OPERATION_INCOMPLETE
Codice restituito primario; l'operazione non è stata completata (la modalità di elaborazione è solo non bloccante) ed è ancora in corso. Il programma può emettere Wait_For_Conversation per attendere il completamento dell'operazione o Cancel_Conversation per annullare l'operazione e la conversazione. Se Specify_Windows_Handle è stato chiamato, l'applicazione deve attendere la notifica da un messaggio di Windows® e non chiamare Wait_For_Conversation.

CM_UNSUCCESSFUL
Codice restituito primario; il tipo di ricezione è impostato su CM_RECEIVE_IMMEDIATE e non sono immediatamente disponibili dati dal programma partner.

CM_DEALLOCATED_NORMAL
Codice restituito primario; la conversazione è stata deallocata normalmente. Il programma partner ha rilasciato Deallocate con il tipo di deallocazione delle conversazioni impostato su CM_DEALLOCATE_FLUSH o CM_DEALLOCATE_SYNC_LEVEL con il livello di sincronizzazione della conversazione specificata come CM_NONE.

CM_PROGRAM_PARAMETER_CHECK
Codice restituito primario; si è verificato uno dei seguenti:

Il valore specificato da conversation_ID non è valido.
Il valore specificato da requested_length non è compreso nell'intervallo (maggiore di 32767).

Se il programma riceve questo codice restituito, gli altri parametri restituiti non sono validi.

CM_PROGRAM_STATE_CHECK
Codice restituito primario; si è verificato uno dei seguenti:
Il tipo di ricezione è impostato su CM_RECEIVE_AND_WAIT e lo stato della conversazione non è RECEIVE, SEND o SEND_PENDING.
Il tipo di ricezione è impostato su CM_RECEIVE_IMMEDIATE e lo stato della conversazione non è RECEIVE.
In una conversazione di base, la conversazione è in stato SEND, il tipo di ricezione è impostato su CM_RECEIVE_AND_WAIT e il programma non ha completato l'invio di un record logico.

Se il programma riceve questo codice restituito, gli altri parametri restituiti non sono validi.

CM_PRODUCT_SPECIFIC_ERROR
Codice restituito primario; si è verificato un errore specifico del prodotto ed è stato registrato nel log degli errori dei prodotti.

CM_CONVERSATION_TYPE_MISMATCH
Codice restituito primario; l'unità logica partner (LU) o il programma non supporta il tipo di conversazione (di base o mappato) specificato nella richiesta di allocazione.

CM_PIP_NOT_SPECIFIED_CORRECTLY
Codice restituito primario; la richiesta di allocazione è stata rifiutata da un programma di transazione NON CPI-C LU 6.2 (TP). Il programma partner richiede una o più variabili di dati PIP, che non sono supportate da CPI-C.

CM_SECURITY_NOT_VALID
Codice restituito primario; l'identificatore utente o la password specificati nella richiesta di allocazione non sono stati accettati dal lu partner.

CM_SYNC_LEVEL_NOT_SUPPORTED_PGM
Codice restituito primario; il programma partner non supporta il livello di sincronizzazione specificato nella richiesta di allocazione.

CM_TPN_NOT_RECOGNIZED
Codice restituito primario; l'lu partner non riconosce il nome del programma specificato nella richiesta di allocazione.

CM_TP_NOT_AVAILABLE_NO_RETRY
Codice restituito primario; l'lu partner non può avviare il programma specificato nella richiesta di allocazione a causa di una condizione permanente. Il motivo dell'errore può essere connesso al nodo remoto. Non ripetere l'allocazione fino a quando l'errore non è stato corretto.

CM_TP_NOT_AVAILABLE_RETRY
Codice restituito primario; l'lu partner non può avviare il programma specificato nella richiesta di allocazione a causa di una condizione temporanea. Il motivo dell'errore può essere connesso al nodo remoto. Ripetere l'allocazione.

CM_PROGRAM_ERROR_NO_TRUNC
Codice restituito primario; durante lo stato SEND o in SEND_PENDING con la direzione di errore impostata su CM_SEND_ERROR, il programma partner ha emesso Send_Error. I dati non sono stati troncati.

CM_PROGRAM_ERROR_PURGING
Codice restituito primario; si è verificato uno dei seguenti:
Durante lo stato RECEIVE o CONFIRM, il programma partner ha emesso Send_Error. I dati inviati ma non ancora ricevuti vengono eliminati.
Mentre in SEND_PENDING stato con la direzione di errore impostata su CM_RECEIVE_ERROR, il programma partner ha emesso Send_Error. I dati non sono stati eliminati.

CM_RESOURCE_FAILURE_NO_RETRY
Codice restituito primario; si è verificato uno dei seguenti:
La conversazione è stata terminata prematuramente a causa di una condizione permanente. Non riprovare finché l'errore non è stato corretto.
Il programma partner non ha deallocato la conversazione prima di terminare normalmente.

CM_RESOURCE_FAILURE_RETRY
Codice restituito primario; la conversazione è stata terminata prematuramente a causa di una condizione temporanea, ad esempio un errore del modem. Ripetere la conversazione.

CM_DEALLOCATED_ABEND
Codice restituito primario; la conversazione è stata deallocata per uno dei motivi seguenti:
Il programma remoto ha emesso Deallocare con il parametroset di tipo per CM_DEALLOCATE_ABEND o l'lu remoto lo ha fatto a causa di una condizione di fine anomala del programma remoto. Se la conversazione per il programma remoto era in stato RECEIVE quando è stata eseguita la chiamata, le informazioni inviate dal programma locale e non ancora ricevute dal programma remoto vengono eliminate.
Il tp remoto termina normalmente ma non dealloca la conversazione prima di terminare. I servizi del nodo nel lu remoto deallocazione della conversazione per conto del tp remoto.

CM_DEALLOCATED_ABEND_SVC
Codice restituito primario; la conversazione è stata deallocata per uno dei motivi seguenti:
Il programma partner ha rilasciato Deallocate con il parametro di tipo impostato su ABEND_SVC.
Il programma partner non ha deallocato la conversazione prima di terminare.

Se la conversazione è in stato RECEIVE per il programma partner quando questa chiamata viene eseguita dal programma locale, i dati inviati dal programma locale e non ancora ricevuti dal programma partner vengono eliminati.

CM_DEALLOCATED_ABEND_TIMER
Codice restituito primario; la conversazione è stata deallocata perché il programma partner ha emesso Deallocate con il parametro di tipo impostato su ABEND_TIMER. Se la conversazione è in stato RECEIVE per il programma partner quando questa chiamata viene eseguita dal programma locale, i dati inviati dal programma locale e non ancora ricevuti dal programma partner vengono eliminati.

CM_SVC_ERROR_PURGING
Codice restituito primario; durante lo stato SEND, il programma partner o l'lu partner ha emesso Send_Error con il parametro di tipo impostato su SVC. I dati inviati al programma partner potrebbero essere stati eliminati.

CM_SVC_ERROR_NO_TRUNC
Codice restituito primario; durante lo stato SEND, il programma partner o l'lu partner ha emesso Send_Error con il parametro di tipo impostato su SVC. I dati inviati al programma partner potrebbero essere stati eliminati.

CM_PROGRAM_ERROR_TRUNC
Codice restituito primario; nello stato SEND, prima di completare l'invio di un record logico completo, il programma partner ha emesso Send_Error. Il programma locale potrebbe aver ricevuto la prima parte del record logico tramite una chiamata di ricezione .

CM_SVC_ERROR_TRUNC
Codice restituito primario; durante lo stato RECEIVE o CONFIRM, il programma partner o l'lu partner ha emesso Send_Error con il parametro di tipo impostato su SVC prima di terminare l'invio di un record logico completo. Il programma locale potrebbe aver ricevuto la prima parte del record logico.

Modifiche dello stato

La conversazione può essere in stato RECEIVE, SEND o SEND_PENDING.

Se receive_type è impostato su CM_RECEIVE_IMMEDIATE, la conversazione deve essere in stato RECEIVE.

L'invio della ricezione mentre la conversazione è in stato SEND o SEND_PENDING fa sì che l'lu locale invii le informazioni nel buffer di invio e un indicatore di invio al programma partner. In base a data_received e status_received la conversazione può passare allo stato RECEIVE per il programma locale.

Il nuovo stato della conversazione è determinato da:
Stato in cui la conversazione si trova quando il programma emette la chiamata.
Parametro return_code .
Parametri data_received e status_received.

Se non sono attualmente disponibili dati e il tipo di ricezione (impostato da Set_Receive_Type) è impostato su CM_RECEIVE_AND_WAIT, il programma locale attende l'arrivo dei dati. Se il tipo di ricezione è impostato su CM_RECEIVE_IMMEDIATE, il programma locale non attende.

Il processo di ricezione dei dati è il seguente:
Il programma locale invia una chiamata di ricezione fino al termine della ricezione di un'unità completa di dati. Il programma locale potrebbe dover eseguire La ricezione più volte per ricevere un'unità completa di dati. Il parametro data_received indica se la ricezione dei dati è stata completata.

I dati ricevuti possono essere:
- Un record di dati trasmesso in una conversazione mappata.
- Un record logico trasmesso in una conversazione di base con le caratteristiche di riempimento delle conversazioni impostate su CM_FILL_LL.
- Buffer di dati ricevuti indipendentemente dal formato di record logico in una conversazione di base con la caratteristica di riempimento impostata su CM_FILL_BUFFER.
  
  Quando è stata ricevuta un'unità completa di dati, il programma locale può modificarlo.
Il programma locale determina l'azione successiva da eseguire in base alle informazioni sul controllo ricevute tramite status_received. Il programma locale potrebbe dover eseguire nuovamente Receive per ricevere le informazioni sul controllo.

Il tipo di conversazione viene impostato da Set_Conversation_Type. La caratteristica di riempimento è impostata da Set_Fill.

La tabella seguente riepiloga le modifiche dello stato che possono verificarsi quando Viene emesso con la conversazione nello stato RECEIVE e return_code è CM_OK.

data_received	status_received	Nuovo stato
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	Nessuna modifica
CM_COMPLETE_DATA_ RICEVUTO	CM_NO_STATUS_RECEIVED	Nessuna modifica
CM_INCOMPLETE_DATA_ RICEVUTO	CM_SEND_RECEIVED	SEND_PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	SEND

Se return_code è impostato su CM_UNSUCCESSFUL, il che significa che il receive_type è impostato su CM_RECEIVE_IMMEDIATE e non sono disponibili dati, non esiste alcuna modifica dello stato.

Nella tabella seguente vengono riepilogate le modifiche dello stato che possono verificarsi quando viene eseguita la ricezione con la conversazione nello stato SEND e return_code è CM_OK.

data_received	status_received	Nuovo stato
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_COMPLETE_DATA_ RICEVUTO	CM_NO_STATUS_RECEIVED	RECEIVE
CM_INCOMPLETE_DATA_ RICEVUTO	CM_SEND_RECEIVED	SEND_PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	Nessuna modifica

Nella tabella seguente vengono riepilogate le modifiche dello stato che possono verificarsi quando Viene emesso con la conversazione in SEND_PENDING stato e return_code è CM_OK.

data_received	status_received	Nuovo stato
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_COMPLETE_DATA_ RICEVUTO	CM_NO_STATUS_RECEIVED	RECEIVE
CM_INCOMPLETE_DATA_ RICEVUTO	CM_SEND_RECEIVED	Nessuna modifica
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	SEND

Gli argomenti seguenti riepilogano le modifiche dello stato che possono verificarsi quando Viene emesso in qualsiasi stato consentito.