DEALLOCATE

Il verbo DEALLOCATE dealloca una conversazione tra due programmi di transazione (TP).

La struttura seguente descrive il blocco di controllo dei verbi (VCB) usato dal verbo DEALLOCATE .

Sintassi

  
struct deallocate {  
    unsigned short       opcode;  
    unsigned char        opext;  
    unsigned char        reserv2;  
    unsigned short       primary_rc;  
    unsigned long        secondary_rc;  
    unsigned char        tp_id[8];  
    unsigned long        conv_id;  
    unsigned char        reserv3;  
    unsigned char        dealloc_type;  
    unsigned short       log_dlen;  
    unsigned char FAR *  log_dptr;  
    void                 (WINAPI *callback)();  
    void                 *correlator;  
    unsigned char        reserv6[4];  
};  

Members

Opcode
Parametro fornito. Specifica il codice dell'operazione del verbo, AP_B_DEALLOCATE.

opext
Parametro fornito. Specifica l'estensione dell'operazione verbo, AP_BASIC_CONVERSATION.

reserv2
Campo riservato.

Primary_rc
Parametro restituito. Specifica il codice restituito primario impostato da APPC al completamento del verbo. I codici restituiti validi variano a seconda del verbo APPC emesso. Per i codici di errore validi per questo verbo, vedere Codici restituiti.

Secondary_rc
Parametro restituito. Specifica il codice restituito secondario impostato da APPC al completamento del verbo. I codici restituiti validi variano a seconda del verbo APPC emesso. Per i codici di errore validi per questo verbo, vedere Codici restituiti.

Tp_id
Parametro fornito. Identifica il TP locale. Il valore di questo parametro è stato restituito TP_STARTED nel TP richiamato o da RECEIVE_ALLOCATE nel TP richiamato.

Conv_id
Parametro fornito. Identifica la conversazione stabilita tra i due TP. Il valore di questo parametro viene restituito da ALLOCATE nel TP richiamato o RECEIVE_ALLOCATE nel TP richiamato.

reserv3
Campo riservato.

dealloc_type
Parametro fornito. Specifica come eseguire la deallocazione.

L'uso di uno dei valori seguenti dealloca la conversazione in modo anomalo:

  • AP_ABEND_PROG

  • AP_ABEND_SVC

  • AP_ABEND_TIMER

    Se la conversazione è in stato SEND quando il TP locale invia DEALLOCATE, APPC invia il contenuto del buffer di invio dell'unità logica locale (LU) al partner TP prima di deallocare la conversazione. Se la conversazione è nello stato RECEIVE o PENDING_POST, APPC elimina tutti i dati in ingresso prima di deallocare la conversazione.

    Un TP dell'applicazione o del servizio deve AP_ABEND_PROG quando si verifica un errore che impedisce il completamento corretto di una transazione.

    Un TP del servizio deve specificare AP_ABEND_SVC quando rileva un errore causato dal TP del servizio partner(ad esempio, un errore di formato nelle informazioni di controllo inviate dal TP del servizio partner). Un TP del servizio deve specificare AP_ABEND_TIMER quando si verifica un errore che richiede la deallocazione immediata(ad esempio, un operatore che termina il programma in modo prematuro).

    AP_FLUSH invia il contenuto del buffer di invio della LU locale al partner TP prima di deallocare la conversazione. Questo valore è consentito solo se lo stato della conversazione è SEND.

    AP_SYNC_LEVEL usa il livello di sincronizzazione della conversazione (stabilito da ALLOCATE) per determinare come deallocare la conversazione. Questo valore è consentito solo se lo stato della conversazione è SEND.

    Se il livello di sincronizzazione della conversazione è AP_NONE, APPC invia il contenuto del buffer di invio della LU locale al partner TP prima di deallocare la conversazione.

    Se il livello di sincronizzazione AP_CONFIRM_SYNC_LEVEL, APPC invia il contenuto del buffer di invio della LU locale e una richiesta di conferma al partner TP. Quando si riceve la conferma dal partner TP, APPC dealloca la conversazione. Se, tuttavia, il partner TP segnala un errore, la conversazione rimane allocata.

    log_dlen
    Parametro fornito. Specifica il numero di byte di dati da inviare al file di log degli errori. L'intervallo è compreso tra 0 e 32767.

    È possibile impostare questo parametro su un numero maggiore di zero se dealloc_type è impostato su AP_ABEND_PGM, AP_ABEND_SVC o AP_ABEND_TIMER. In caso contrario, questo parametro deve essere zero.

    log_dptr
    Parametro fornito. Fornisce l'indirizzo del buffer di dati contenente le informazioni sull'errore. I dati vengono inviati al log degli errori locale e alla LU partner.

    Questo parametro viene usato da DEALLOCATE se log_dlen è maggiore di zero.

    Per Microsoft Windows, il buffer di dati può risiedere in un'area dati statica o in un'area allocata a livello globale. Il buffer di dati deve essere contenuto interamente in questa area.

    Per OS/2, il buffer dei dati di log deve risiedere in un segmento condiviso senza nome, allocato dalla funzione DosAllocSeg con Flag uguale a 1. Il buffer dei dati di log deve essere interamente contenuto nel segmento.

    Il provider di servizi di configurazione deve formattare i dati degli errori come variabile del log degli errori GDS. Per altre informazioni, vedere i manuali di IBM SNA.

    callback
    Parametro fornito. Presente solo se il AP_EXTD_VCB bit è impostato nel membro opext , che indica il supporto per il punto di sincronizzazione. Questo parametro è l'indirizzo di una funzione di callback fornita dall'utente. Se questo campo è NULL, non verrà fornita alcuna notifica.

    Il prototipo della routine di callback è il seguente:

void WINAPI callback_proc(  
    struct appc_hdr *vcb,  
    unsigned char tp_id[8],  
    unsigned long conv_id,  
    unsigned short type,  
    void *correlator  
   );  

La routine di callback può assumere qualsiasi nome, poiché l'indirizzo della procedura viene passato alla DLL APPC. I parametri passati alla funzione sono i seguenti:

Vcb

Puntatore al blocco di controllo del verbo DEALLOCATE che ha causato la deallocazione della conversazione.

Tp_id

Identificatore TP del TP proprietario della conversazione deallocata.

Conv_id

Identificatore di conversazione della conversazione deallocata.

tipo

Tipo del flusso di messaggi che ha causato la chiamata del callback. I valori possibili sono:

AP_DATA_FLOW

Flusso di dati normale nella sessione.

AP_UNBIND

La sessione non è stata associata normalmente.

AP_FAILURE

La sessione è stata terminata a causa di un'interruzione.

Correlatore

Questo valore è il correlatore specificato nel verbo DEALLOCATE .

Correlatore
Parametro fornito. Presente solo se il bit AP_EXTD_VCB è impostato nel membro opext , che indica il supporto per l'API del punto di sincronizzazione. Questo campo correlatore consente al provider di transazioni di specificare un valore che può usare per correlare una chiamata alla funzione di callback con, ad esempio, le proprie strutture di dati interne. Questo valore viene restituito al provider di servizi come uno dei parametri della routine di callback quando viene richiamato.

reserv4
Campo riservato.

Codici restituiti

AP_OK
Codice restituito primario; Il verbo è stato eseguito correttamente.

AP_PARAMETER_CHECK
Codice restituito primario; Il verbo non è stato eseguito a causa di un errore di parametro.

AP_BAD_CONV_ID

Codice restituito secondario; il valore di conv_id non corrisponde a un identificatore di conversazione assegnato da APPC.

AP_BAD_TP_ID

Codice restituito secondario; il valore di tp_id non corrisponde a un identificatore TP assegnato da APPC.

AP_DEALLOC_BAD_TYPE

Codice restituito secondario; Il dealloc_type parametro non è stato impostato su un valore valido.

AP_DEALLOC_LOG_LL_WRONG

Codice restituito secondario; Il campo LL della variabile del log degli errori GDS non corrisponde alla lunghezza effettiva dei dati di log.

AP_INVALID_DATA_SEGMENT

Codice restituito secondario; I dati di errore per il file di log sono più lunghi del segmento allocato per contenere i dati dell'errore o l'indirizzo del buffer dei dati degli errori è errato.

AP_STATE_CHECK
Codice restituito primario; Il verbo non è stato eseguito perché è stato emesso in uno stato non valido.

AP_DEALLOC_CONFIRM_BAD_STATE

Codice restituito secondario; la conversazione non era nello stato SEND e il TP ha tentato di scaricare il buffer di invio e inviare una richiesta di conferma. Questo tentativo si è verificato perché il valore di dealloc_type è AP_SYNC_LEVEL e il livello di sincronizzazione della conversazione è stato AP_CONFIRM_SYNC_LEVEL.

AP_DEALLOC_FLUSH_BAD_STATE

Codice restituito secondario; la conversazione non era nello stato SEND e il TP ha tentato di scaricare il buffer di invio. Questo tentativo si è verificato perché il valore di dealloc_type era AP_FLUSH o perché il valore di dealloc_type era AP_SYNC_LEVEL e il livello di sincronizzazione della conversazione era AP_NONE. In entrambi i casi, la conversazione deve essere nello stato SEND.

AP_DEALLOC_NOT_LL_BDY

Codice restituito secondario; la conversazione era in stato SEND e il TP non ha completato l'invio di un record logico. Il dealloc_type è stato impostato su AP_SYNC_LEVEL o AP_FLUSH.

AP_ALLOCATION_ERROR
Codice restituito primario; APPC non è riuscito ad allocare una conversazione. Lo stato della conversazione è impostato su RESET.

Questo codice può essere restituito tramite un verbo emesso dopo ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Codice restituito secondario; La conversazione non può essere allocata a causa di una condizione permanente, ad esempio un errore di configurazione o un errore del protocollo di sessione. Per determinare l'errore, l'amministratore di sistema deve esaminare il file di log degli errori. Non ripetere l'allocazione fino a quando l'errore non è stato corretto.

AP_ALLOCATION_FAILURE_RETRY

Codice restituito secondario; Impossibile allocare la conversazione a causa di una condizione temporanea, ad esempio un errore di collegamento. Il motivo dell'errore viene registrato nel log degli errori di sistema. Ripetere l'allocazione.

AP_CONVERSATION_TYPE_MISMATCH

Codice restituito secondario; il partner LU o TP non supporta il tipo di conversazione (di base o mappato) specificato nella richiesta di allocazione.

AP_PIP_NOT_ALLOWED

Codice restituito secondario; La richiesta di allocazione ha specificato i dati PIP, ma il partner TP non richiede questi dati o il partner LU non li supporta.

AP_PIP_NOT_SPECIFIED_CORRECTLY

Codice restituito secondario; Il partner TP richiede dati PIP, ma la richiesta di allocazione non ha specificato dati PIP o un numero errato di parametri.

AP_SECURITY_NOT_VALID

Codice restituito secondario; L'identificatore utente o la password specificata nella richiesta di allocazione non è stata accettata dal lun del partner.

AP_SYNC_LEVEL_NOT_SUPPORTED

Codice restituito secondario; il partner partner non supporta l'sync_level (AP_NONE o AP_CONFIRM_SYNC_LEVEL) specificato nella richiesta di allocazione oppure il sync_level non è stato riconosciuto.

AP_TP_NAME_NOT_RECOGNIZED

Codice restituito secondario; L'unità di ricerca partner non riconosce il nome TP specificato nella richiesta di allocazione.

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

Codice restituito secondario; L'unità lu remota ha rifiutato la richiesta di allocazione perché non è stato in grado di avviare il partner TP richiesto. La condizione è permanente. Il motivo dell'errore può essere registrato nel nodo remoto. Non ripetere l'allocazione fino a quando l'errore non è stato corretto.

AP_TRANS_PGM_NOT_AVAIL_RETRY

Codice restituito secondario; L'unità lu remota ha rifiutato la richiesta di allocazione perché non è stato in grado di avviare il partner TP richiesto. La condizione può essere temporanea, ad esempio un timeout. Il motivo dell'errore può essere registrato nel nodo remoto. Ripetere l'allocazione.

AP_COMM_SUBSYSTEM_ABENDED
Codice restituito primario; indica una delle condizioni seguenti:

  • Il nodo usato da questa conversazione ha rilevato un ABEND.

  • La connessione tra il TP e il nodo PU 2.1 è stata interrotta (errore LAN).

  • SnaBase nel computer del provider di servizi di dominio ha rilevato un ABEND.

    L'amministratore di sistema deve esaminare il log degli errori per determinare il motivo dell'abend.

    AP_COMM_SUBSYSTEM_NOT_LOADED
    Codice restituito primario; Non è stato possibile caricare o terminare un componente richiesto durante l'elaborazione del verbo. Di conseguenza, la comunicazione non è stata possibile. Contattare l'amministratore di sistema per un'azione correttiva.

    AP_CONV_FAILURE_NO_RETRY
    Codice restituito primario; La conversazione è stata terminata a causa di una condizione permanente, ad esempio un errore del protocollo di sessione. L'amministratore di sistema deve esaminare il log degli errori di sistema per determinare la causa dell'errore. Non ripetere la conversazione fino a quando l'errore non è stato corretto.

    AP_CONV_FAILURE_RETRY
    Codice restituito primario; La conversazione è stata terminata a causa di un errore temporaneo. Riavviare il TP per verificare se il problema si verifica di nuovo. In caso contrario, l'amministratore di sistema deve esaminare il log degli errori per determinare la causa dell'errore.

    AP_CONVERSATION_TYPE_MIXED
    Codice restituito primario; il TP ha rilasciato verbi di conversazione sia di base che mappati. È possibile eseguire un solo tipo in una singola conversazione.

    AP_INVALID_VERB_SEGMENT
    Codice restituito primario; il VCB è stato esteso oltre la fine del segmento di dati.

    AP_PROG_ERROR_PURGING
    Codice restituito primario; in stato RECEIVE, PENDING, PENDING_POST, CONFIRM, CONFIRM_SEND o CONFIRM_DEALLOCATE, il partner TP ha emesso SEND_ERROR con err_type impostato su AP_PROG. I dati inviati ma non ancora ricevuti vengono eliminati.

    AP_STACK_TOO_SMALL
    Codice restituito primario; Le dimensioni dello stack dell'applicazione sono troppo piccole per eseguire il verbo. Aumentare le dimensioni dello stack dell'applicazione.

    AP_CONV_BUSY
    Codice restituito primario; in qualsiasi conversazione può essere presente un solo verbo di conversazione in sospeso alla volta. Ciò può verificarsi se il punto di distribuzione locale ha più thread e più thread emette chiamate APPC usando lo stesso conv_id.

    AP_THREAD_BLOCKING
    Codice restituito primario; Il thread chiamante è già in una chiamata di blocco.

    AP_UNEXPECTED_DOS_ERROR
    Codice restituito primario; il sistema operativo ha restituito un errore ad APPC durante l'elaborazione di una chiamata APPC dal punto di distribuzione locale. Il codice restituito dal sistema operativo viene restituito tramite il secondary_rc. Viene visualizzato in ordine di scambio di byte Intel. Se il problema persiste, rivolgersi all'amministratore di sistema.

    AP_DEALLOC_ABEND_PROG
    Codice restituito primario; la conversazione è stata deallocata per uno dei motivi seguenti:

  • Il partner TP ha rilasciato DEALLOCATEcon dealloc_type impostato su AP_ABEND_PROG.

  • Il partner TP ha rilevato un ABEND, causando l'invio di una richiesta DEALLOCATE da parte della LU partner.

    AP_DEALLOC_ABEND_SVC
    Codice restituito primario; la conversazione è stata deallocata perché il partner TP ha emesso DEALLOCATEcon dealloc_type impostato su AP_ABEND_SVC.

    AP_DEALLOC_ABEND_TIMER
    Codice restituito primario; la conversazione è stata deallocata perché il partner TP ha emesso DEALLOCATEcon dealloc_type impostato su AP_ABEND_TIMER.

    AP_SVC_ERROR_PURGING
    Codice restituito primario; il partner TP (o LU partner) ha rilasciato SEND_ERROR con err_type impostato su AP_SVC in stato RECEIVE, PENDING_POST, CONFIRM, CONFIRM_SEND o CONFIRM_DEALLOCATE. I dati inviati al partner TP potrebbero essere stati eliminati.

Commenti

A seconda del valore del parametro dealloc_type , la conversazione può essere in uno degli stati indicati nella tabella seguente quando il TP esegue DEALLOCATE.

dealloc_type Stato consentito
AP_FLUSH SEND
AP_SYNC_LEVEL SEND
AP_ABEND Qualsiasi tranne RESET
AP_ABEND_PROG Qualsiasi tranne RESET
AP_ABEND_SVC Qualsiasi tranne RESET
AP_ABEND_TIMER Qualsiasi tranne RESET

Le modifiche dello stato, riepilogate nella tabella seguente, si basano sul valore del primary_rc.

Primary_rc Nuovo stato
AP_OK RESET
AP_ALLOCATION_ERROR RESET
AP_CONV_FAILURE_RETRY RESET
AP_CONV_FAILURE_NO_RETRY RESET
AP_DEALLOC_ABEND RESET
AP_DEALLOC_ABEND_PROG RESET
AP_DEALLOC_ABEND_SVC RESET
AP_DEALLOC_ABEND_TIMER RESET
AP_PROG_ERROR_PURGING RECEIVE
AP_SVC_ERROR_PURGING RECEIVE

Prima di deallocare la conversazione, questo verbo esegue l'equivalente di uno degli elementi seguenti:

  • FLUSH, inviando il contenuto del buffer di invio dell'unità di gestione locale alla LU partner (e TP).

  • CONFIRM, inviando il contenuto del buffer di invio dell'unità di ricerca locale e una richiesta di conferma al partner TP.

    Al termine dell'esecuzione di questo verbo, l'identificatore di conversazione non è più valido.

    Il punto di sincronizzazione LU 6.2 può usare un'ottimizzazione dei flussi di messaggi nota come forget implicito. Quando il protocollo specifica che è necessaria un'intestazione FORGET PS, il flusso di dati successivo nella sessione implica che è stata ricevuta un'intestazione FORGET. Nella situazione normale, il TP è a conoscenza del flusso di dati successivo quando i dati vengono ricevuti o inviati in una delle conversazioni del punto di sincronizzazione.

    Tuttavia, è possibile che l'ultimo messaggio da inviare sia causato dalla deallocazione della conversazione. In questo caso, il provider di servizi non è a conoscenza del momento in cui si verifica il flusso di dati successivo nella sessione. Per fornire al punto di distribuzione questa notifica, il verbo DEALLOCATE viene modificato per consentire al TP di registrare una funzione di callback che verrà chiamata:

  • Alla prima trasmissione di flusso normale (richiesta o risposta) sulla sessione usata dalla conversazione.

  • Se la sessione non è associata prima di qualsiasi altro flusso di dati.

  • Se la sessione viene terminata in modo anomalo a causa di un'interruzione del DLC.

    Il verbo DEALLOCATE contiene anche un membro di campo correlatore che viene restituito come uno dei parametri quando viene richiamata la funzione di callback. L'applicazione può usare questo parametro in qualsiasi modo, ad esempio come puntatore a un blocco di controllo all'interno dell'applicazione.

    TP può usare il parametro di tipo passato alla funzione di callback per determinare se il flusso di messaggi indica che è stato ricevuto un forget implicito.

    Si noti che il verbo DEALLOCATE verrà probabilmente completato prima che venga chiamata la routine di callback. La conversazione è considerata in stato RESET e non è possibile emissione di altri verbi usando l'identificatore di conversazione. Se l'applicazione e TP_ENDED verbo precedente al flusso di dati successivo nella sessione, la routine di callback non verrà richiamata.

    Host Integration Server consente ai TP di deallocare le conversazioni immediatamente dopo l'invio dei dati specificando il parametro di tipo SEND_DATA come AP_SEND_DATA_DEALLOC_*. Tuttavia, i SEND_DATA verbi non contengono la funzione di callback forget implicita. I TP che vogliono ricevere la notifica di tipo forget implicito devono rilasciare DEALLOCATE in modo esplicito.