Receive (CPI-C)

La chiamata Receive (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 Initialize_Conversation o Accept_Conversation.

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

Il buffer contiene dati se si verificano le condizioni seguenti:

  • Il data_received è impostato su un valore diverso da CM_NO_DATA_RECEIVED.

  • Il 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 dati. I valori possibili sono elencati dopo la sezione Parametri.

    received_length
    Parametro restituito. Indica il numero di byte di dati ricevuti dal programma locale in questa chiamata Receive . 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 nello stato della conversazione. Di seguito sono riportati i valori possibili. Questi codici non sono rilevanti a meno return_code non sia impostato su CM_OK. I valori possibili sono elencati dopo la sezione Parametri.

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

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

Valori restituiti nel parametro data_received

Questi codici non sono rilevanti a meno return_code non 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 indipendenti dal formato logico. Il programma locale ha ricevuto i dati fino requested_length non è stata raggiunta la fine 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 da 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 una quantità inferiore di dati è stata ricevuta dal programma partner.

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 requested_length specificato un valore minore della lunghezza del record di dati (o minore del resto del record di dati se non è la prima ricezione a leggere il record). La quantità di dati ricevuti è uguale al requested_length specificato.

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 requested_length specificato. Se i dati ricevuti sono stati troncati, la lunghezza dei dati sarà inferiore requested_length.

Alla ricezione di questo valore, il programma locale in genere emette di nuovo Receive per ricevere la parte successiva del record.

CM_NO_DATA_RECEIVED
Il programma non ha ricevuto dati.

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

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 è nello stato RECEIVE. Per il programma locale, la conversazione è ora nello stato SEND se non sono stati ricevuti dati in questa chiamata o SEND_PENDING se i dati sono stati ricevuti in questa chiamata.

Alla 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 Dealloca con la conferma richiesta. Per il programma locale, la conversazione è ora in CONFIRM_DEALLOCATE stato.

Alla ricezione di questo valore, il programma locale in genere esezione della chiamata Confirmed .

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

Alla ricezione di questo valore, il programma locale in genere esezione della chiamata Confirmed .

CM_CONFIRM_SEND_RECEIVED
Indica, per il programma partner, che la conversazione è entrata nello stato RECEIVE e che il programma locale ha ricevuto una richiesta di conferma. Per il programma locale, la conversazione è ora in CONFIRM_SEND stato.

Il programma in genere risponde emettendo la chiamata Confirmed . Al termine dell'esecuzione della chiamata Confirmed , la conversazione cambia in stato SEND per il programma locale.

Valori restituiti nel parametro request_to_send_received

CM_REQ_TO_SEND_RECEIVED
Il programma partner ha emesso Request_To_Send chiamata, che richiede al programma locale di impostare la conversazione sullo stato RECEIVE.

CM_REQ_TO_SEND_NOT_RECEIVED
Il programma partner non ha emettere la Request_To_Send chiamata. 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 è stata eseguita correttamente.

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

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

CM_UNSUCCESSFUL
Codice restituito primario; Il tipo di ricezione è impostato su CM_RECEIVE_IMMEDIATE e nessun dato è immediatamente disponibile dal programma partner.

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

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

  • 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 eventi:

  • 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 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 LU 6.2 non CPI-C. 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 specificata nella richiesta di allocazione non è stata accettata dal lun del 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'unità di ricerca partner non riconosce il nome del programma specificato nella richiesta di allocazione.

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

    CM_TP_NOT_AVAILABLE_RETRY
    Codice restituito primario; L'unità di ricerca partner non può avviare il programma specificato nella richiesta di allocazione a causa di una condizione temporanea. Il motivo dell'errore può essere registrato nel nodo remoto. Ripetere l'allocazione.

    CM_PROGRAM_ERROR_NO_TRUNC
    Codice restituito primario; mentre è in stato SEND o in SEND_PENDING con la direzione dell'errore impostata su CM_SEND_ERROR, il programma partner ha rilasciato Send_Error. I dati non sono stati troncati.

    CM_PROGRAM_ERROR_PURGING
    Codice restituito primario; si è verificato uno dei seguenti eventi:

  • Nello stato RECEIVE o CONFIRM, il programma partner ha rilasciato Send_Error. I dati inviati ma non ancora ricevuti vengono eliminati.

  • Mentre è SEND_PENDING stato con la direzione dell'errore impostata su CM_RECEIVE_ERROR, il programma partner ha rilasciato Send_Error. I dati non sono stati eliminati.

    CM_RESOURCE_FAILURE_NO_RETRY
    Codice restituito primario; si è verificato uno dei seguenti eventi:

  • 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 Dealloca con il parametro di tipo impostato su CM_DEALLOCATE_ABEND oppure la LU remota ha eseguito questa operazione a causa di una condizione di terminazione anomala del programma remoto. Se la conversazione per il programma remoto era in stato RECEIVE quando è stata emessa la chiamata, le informazioni inviate dal programma locale e non ancora ricevute dal programma remoto vengono eliminate.

  • Il TP remoto è terminato normalmente, ma non ha deallocato la conversazione prima di terminare. I servizi Node nella LU remota hanno deallocato la 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 Dealloca 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 emessa 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 Dealloca con il parametro di tipo impostato su ABEND_TIMER. Se la conversazione è in stato RECEIVE per il programma partner quando questa chiamata viene emessa 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; Mentre è in stato SEND, il programma partner o l'Send_Error partner ha emesso 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; Mentre è in stato SEND, il programma partner o l'Send_Error partner ha emesso 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 Receive .

    CM_SVC_ERROR_TRUNC
    Codice restituito primario; nello stato RECEIVE o CONFIRM, il programma partner o l'unità logica partner ha emesso Send_Error con il parametro di tipo impostato su SVC prima di inviare un record logico completo. È possibile che il programma locale abbia ricevuto la prima parte del record logico.

    Modifiche di stato

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

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

    L'emissione di Receive mentre la conversazione è in stato SEND o SEND_PENDING fa sì che l'unità di elaborazione locale invii le informazioni nel buffer di invio e un indicatore di invio al programma partner. In base 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 si trova la conversazione quando il programma esegue la chiamata.

  • Parametro return_code .

  • Parametri data_received e status_received specificati.

    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 per la ricezione dei dati è il seguente:

  • Il programma locale elava una chiamata Receive fino al termine della ricezione di un'unità completa di dati. Per ricevere un'unità completa di dati, il programma locale potrebbe dover eseguire più volte l'operazione Di ricezione. Il data_received parametro indica se la ricezione dei dati è terminata.

    I dati ricevuti possono essere:

    • Un record di dati trasmesso in una conversazione mappata.

    • Un record logico trasmesso in una conversazione di base con la caratteristica di riempimento delle conversazioni impostata 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 viene ricevuta un'unità completa di dati, il programma locale può modificarli.

  • Il programma locale determina l'azione successiva da eseguire in base alle informazioni di controllo ricevute tramite status_received. Per ricevere le informazioni di controllo, potrebbe essere necessario eseguire nuovamente il programma locale Receive.

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

    Nella tabella seguente vengono riepilogate le modifiche di stato che possono verificarsi quando receive viene emesso con la conversazione in stato RECEIVE e return_code viene CM_OK .

data_received status_received Nuovo stato
CM_DATA_RECEIVED CM_NO_STATUS_RECEIVED Nessuna modifica
CM_COMPLETE_DATA_ RICEVUTI 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, ovvero il receive_type è impostato su CM_RECEIVE_IMMEDIATE e non sono disponibili dati, non viene apportata alcuna modifica allo stato.

Nella tabella seguente vengono riepilogate le modifiche di stato che possono verificarsi quando receive viene emesso con la conversazione nello stato SEND e return_code viene CM_OK .

data_received status_received Nuovo stato
CM_DATA_RECEIVED CM_NO_STATUS_RECEIVED RECEIVE
CM_COMPLETE_DATA_ RICEVUTI 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 di stato che possono verificarsi quando viene eseguita la ricezione con la conversazione nello stato SEND_PENDING e return_code viene CM_OK .

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

Negli argomenti seguenti vengono riepilogate le modifiche di stato che possono verificarsi quando receive viene emesso in qualsiasi stato consentito.

Contenuto della sezione