Condividi tramite

RUI_READ

  • Articolo

Il verbo RUI_READ riceve risposte, comandi SNA e dati in un buffer di applicazioni luA (Logical Unit Application) di Microsoft® Windows®.

Nella struttura seguente viene descritto il membro LUA_COMMON del blocco di controllo verbo (VCB) utilizzato da RUI_READ.

Sintassi

  
struct LUA_COMMON {  
    unsigned short lua_verb;  
    unsigned short lua_verb_length;  
    unsigned short lua_prim_rc;  
    unsigned long  lua_sec_rc;  
    unsigned short lua_opcode;  
    unsigned long  lua_correlator;  
    unsigned char  lua_luname[8];  
    unsigned short lua_extension_list_offset;  
    unsigned short lua_cobol_offset;  
    unsigned long  lua_sid;  
    unsigned short lua_max_length;  
    unsigned short lua_data_length;  
    char FAR *     lua_data_ptr;  
    unsigned long  lua_post_handle;  
    struct LUA_TH  lua_th;  
    struct LUA_RH  lua_rh;  
    struct LUA_FLAG1 lua_flag1;  
    unsigned char  lua_message_type;  
    struct LUA_FLAG2 lua_flag2;   
    unsigned char  lua_resv56[7];  
    unsigned char  lua_encr_decr_option;  
};

Members

lua_verb
Parametro fornito. Contiene il codice verbo LUA_VERB_RUI per i verbi URI (Request Unit Interface).

lua_verb_length
Parametro fornito. Specifica la lunghezza in byte del VCB LUA. Deve contenere la lunghezza del record verbo da emettere.

lua_prim_rc
Codice restituito primario impostato da LUA al completamento del verbo. I codici restituiti validi variano a seconda del verbo LUA emesso.

lua_sec_rc
Codice restituito secondario impostato da LUA al completamento del verbo. I codici restituiti validi variano a seconda del verbo LUA emesso.

lua_opcode
Parametro fornito. Contiene il codice del comando LUA (codice dell'operazione verbo) per il verbo da emettere, LUA_OPCODE_RUI_READ.

lua_correlator
Parametro fornito. Contiene un valore fornito dall'utente che collega il verbo con altre informazioni fornite dall'utente. LUA non usa o modifica queste informazioni. Questo parametro è facoltativo e,

lua_luname
Parametro fornito. Specifica il nome ASCII dell'lu locale utilizzato dalla sessione LUA di Windows.

RUI_READ richiede questo parametro solo se lua_sid è zero.

Questo parametro è lungo otto byte, riempito a destra con spazi (0x20) se il nome è più breve di otto caratteri.

lua_extension_list_offset
Non usato dalla URI in Host Integration Server e deve essere impostato su zero.

lua_cobol_offset
Non usato da LUA in Microsoft® Host Integration Server e deve essere zero.

lua_sid
Parametro fornito e restituito. Specifica l'identificatore di sessione e viene restituito da SLI_OPEN e RUI_INIT. Altri verbi usano questo parametro per identificare la sessione usata per il comando . Se altri verbi usano il parametro lua_luname per identificare le sessioni, impostare il parametro lua_sid su zero.

lua_max_length
Specifica la lunghezza del buffer ricevuto per RUI_READ e SLI_RECEIVE. Non usato da altri verbi URI e SLI e deve essere impostato su zero.

lua_data_length
Parametro restituito. Specifica la lunghezza dei dati restituiti in lua_peek_data per il verbo RUI_BID .

lua_data_ptr
Puntatore al buffer fornito dall'applicazione che deve ricevere i dati da un verbo RUI_READ . Entrambi i comandi e i dati SNA vengono inseriti in questo buffer e possono essere in formato EBCDIC.

Quando viene eseguita RUI_READ , questo parametro punta alla posizione in cui ricevere i dati dall'host.

lua_post_handle
Parametro fornito. Utilizzato in Microsoft Windows Server se la notifica asincrona deve essere eseguita dagli eventi. Questa variabile contiene l'handle dell'evento da segnalare o un handle di finestra.

lua_th
Parametro restituito. Contiene l'intestazione di trasmissione SNA (TH) del messaggio inviato o ricevuto. Vari sottoparametri sono impostati per le funzioni di scrittura e restituite per le funzioni di lettura e offerta. I relativi sottoparametri sono i seguenti:

lua_th.flags_fid

Tipo di identificazione del formato 2, quattro bit.

lua_th.flags_mpf

Campo di mapping segmentazione, due bit. Definisce il tipo di segmento di dati. I valori seguenti sono validi:

0x00 Segmento intermedio0x04 Segmento ultimo0x08 Segmento primo0x0C Solo segmento

lua_th.flags_odai

Indicatore dell'assegnatore OAF-DAF (Address Field-DAF) di origine, un bit.

lua_th.flags_efi

Indicatore di flusso accelerato, un bit.

lua_th.daf

Campo indirizzo di destinazione (DAF), un carattere senza segno.

lua_th.oaf

Campo indirizzo di origine (OAF), un carattere senza segno.

lua_th.snf

Campo numero di sequenza, un carattere senza segno[2].

lua_rh
Parametro restituito. Contiene l'intestazione richiesta/risposta SNA del messaggio inviato o ricevuto. Viene impostata per la funzione di scrittura e restituita dalle funzioni di lettura e offerta. I relativi sottoparametri sono i seguenti:

lua_rh.rri

Indicatore di risposta della richiesta, un bit.

lua_rh.ruc

Categoria UR, due bit. I valori seguenti sono validi:

LUA_RH_FMD (0x00) controllo di reteLUA_RH_NC (0x20) Controllo di reteLUA_RH_DFC (0x40) Controllo flusso di datiLUA_RH_SC (0x60) Controllo sessione

lua_rh.fi

Indicatore di formato, un bit.

lua_rh.sdi

Indicatore di rilevamento dei dati inclusi, un bit.

lua_rh.bci

Indicatore della catena di inizio, un bit.

lua_rh.eci

Indicatore catena finale, un bit.

lua_rh.dr1i

Indicatore di risposta definito 1, un bit.

lua_rh.dr2i

Indicatore di risposta definita 2, un bit.

lua_rh.ri

Indicatore di risposta dell'eccezione (per una richiesta) o indicatore del tipo di risposta (per una risposta), un bit.

lua_rh.qri

Indicatore di risposta in coda, un bit.

lua_rh.pi

Indicatore di velocità, un bit.

lua_rh.bbi

Indicatore parentesi quadre iniziale, un bit.

lua_rh.ebi

Indicatore parentesi quadra finale, un bit.

lua_rh.cdi

Indicatore di direzione di modifica, un bit.

lua_rh.csi

Indicatore di selezione del codice, un bit.

lua_rh.edi

Indicatore di dati crittografati, un bit.

lua_rh.pdi

Indicatore dati riempito, un bit.

lua_flag1
Parametro fornito. Contiene una struttura di dati contenente flag per i messaggi forniti dall'applicazione. I relativi sottoparametri sono i seguenti:

lua_flag1.bid_enable

Indicatore di abilitazione dell'offerta, un bit.

lua_flag1.close_abend

Indicatore immediato di chiusura, un bit.

lua_flag1.nowait

Nessuna attesa per il flag di dati, un bit.

lua_flag1.sscp_exp

Flusso accelerato di SSCP, un bit.

lua_flag1.sscp_norm

Flusso normale SSCP, un bit.

lua_flag1.lu_exp

Flusso accelerato lu, un bit.

lua_flag1.lu_norm

Flusso normale LU, un bit.

Impostare lua_flag1.nowait su 1 per indicare che si desidera che RUI_READ restituire immediatamente se i dati sono disponibili o meno per la lettura o impostarli su zero se si vuole che il verbo attenda i dati prima della restituzione.

Impostare lua_flag1.bid_enable su 1 per riabilitare il RUI_BID più recente (equivalente all'emissione di RUI_BID con esattamente gli stessi parametri di prima) o impostarlo su zero se non si vuole riabilitare RUI_BID.

Riabilitare l'RUI_BID precedente riutilizza il vcb originariamente allocato, quindi il vcb non deve essere stato liberato o modificato.

Impostare uno o più dei flag seguenti su 1 per indicare da quale flusso di messaggi leggere i dati:

lua_flag1.sscp_exp

lua_flag1.lu_exp

lua_flag1.sscp_norm

lua_flag1.lu_norm

Se sono impostati più flag, vengono restituiti i dati con priorità più alta disponibili. L'ordine delle priorità (il primo più alto) è: SSCP accelerato, LU accelerato, normale SSCP, NORMALE LU. Il flag equivalente nel gruppo di lua_flag2 viene impostato per indicare da quale flusso sono stati letti i dati.

lua_message_type
Specifica il tipo di dati e comandi SNA in ingresso o in uscita. Parametro restituito. Specifica il tipo di messaggio SNA indicato per RUI_READ. I valori possibili sono:

LUA_MESSAGE_TYPE_LU_DATA

LUA_MESSAGE_TYPE_SSCP_DATA

LUA_MESSAGE_TYPE_RQR

LUA_MESSAGE_TYPE_BID

LUA_MESSAGE_TYPE_BIND

LUA_MESSAGE_TYPE_BIS

LUA_MESSAGE_TYPE_CANCEL

LUA_MESSAGE_TYPE_CHASE

LUA_MESSAGE_TYPE_CLEAR

LUA_MESSAGE_TYPE_CRV

LUA_MESSAGE_TYPE_LUSTAT_LU

LUA_MESSAGE_TYPE_LUSTAT_SSCP

LUA_MESSAGE_TYPE_QC

LUA_MESSAGE_TYPE_QEC

LUA_MESSAGE_TYPE_RELQ

LUA_MESSAGE_TYPE_RTR

LUA_MESSAGE_TYPE_SBI

LUA_MESSAGE_TYPE_SHUTD

LUA_MESSAGE_TYPE_SIGNAL

LUA_MESSAGE_TYPE_SDT

LUA_MESSAGE_TYPE_STSN

LUA_MESSAGE_TYPE_UNBIND

LU_DATA, LUSTAT_LU, LUSTAT_SSCP e SSCP_DATA non sono comandi SNA.

lua_flag2
Parametro restituito. Contiene i flag per i messaggi restituiti da LUA. I relativi sottoparametri sono i seguenti:

lua_flag2.bid_enable

Indica che RUI_BID è stato riabilitato se impostato su 1.

lua_flag2.async

Indica che il verbo dell'interfaccia LUA è stato completato in modo asincrono se impostato su 1.

lua_flag2.sscp_exp

Indica il flusso accelerato di SSCP se impostato su 1.

lua_flag2.sscp_norm

Indica il flusso normale di SSCP se impostato su 1.

lua_flag2.lu_exp

Indica il flusso accelerato lu se impostato su 1.

lua_flag2.lu_norm

Indica il flusso normale lu se impostato su 1.

lua_resv56
Riservato e deve essere impostato su zero.

lua_encr_decr_option
Riservato e deve essere impostato su zero.

Codici restituiti

LUA_OK
Codice restituito primario; il verbo eseguito correttamente.

LUA_DATA_INCOMPLETE

Codice restituito secondario; RUI_READ non è stato in grado di restituire tutti i dati ricevuti perché il buffer dei dati dell'applicazione (indicato da lua_max_length) non è abbastanza grande. Le richieste di RUI_READ successive possono essere inviate per recuperare i dati rimanenti delle URI.

Questo non è il comportamento predefinito per RUI_READ ed è abilitato solo quando lua_resv56[3] è impostato su un valore diverso da zero nel blocco di controllo verbo quando si chiama RUI_INIT durante la creazione della sessione. Per informazioni dettagliate, vedere Osservazioni.

LUA_CANCELED
Codice restituito primario; il verbo non è stato completato correttamente perché è stato annullato da un altro verbo o da un errore interno.

LUA_PURGED

Codice restituito secondario; RUI_READ è stato annullato da RUI_PURGE.

LUA_TERMINATED

Codice restituito secondario; RUI_TERM è stato emesso mentre RUI_READ era in sospeso.

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

LUA_BAD_DATA_PTR

Codice restituito secondario; il parametro lua_data_ptr contiene un valore non valido.

LUA_BAD_SESSION_ID

Codice restituito secondario; È stato specificato un valore non valido per lua_sid nel vcb.

LUA_BID_ALREADY_ENABLED

Codice restituito secondario; lua_flag1.bid_enable è stato impostato per riabilitare RUI_BID , ma il RUI_BID precedente era ancora in corso.

LUA_DUPLICATE_READ_FLOW

Codice restituito secondario; i flag di flusso nel gruppo di lua_flag1 specificato uno o più flussi di sessione per i quali RUI_READ era già in sospeso. È possibile attendere un solo RUI_READ alla volta in ogni flusso di sessione.

LUA_INVALID_FLOW

Codice restituito secondario; nessuno dei flag di flusso lua_flag1 è stato impostato. Almeno uno di questi flag deve essere impostato su 1 per indicare da quale flusso o flusso leggere.

LUA_INVALID_POST_HANDLE

Codice restituito secondario; per un sistema operativo Windows che usa eventi come metodo di registrazione asincrona, il VCB LUA di Windows non contiene un handle di evento valido.

LUA_NO_PREVIOUS_BID_ENABLED

Codice restituito secondario; lua_flag1.bid_enable è stato impostato per riabilitare RUI_BID, ma non è stato possibile abilitare RUI_BID precedenti. Per altre informazioni, vedere Note.

LUA_RESERVED_FIELD_NOT_ZERO

Codice restituito secondario; un campo riservato nel record verbo o un parametro non utilizzato da questo verbo è stato impostato su un valore diverso da zero.

LUA_VERB_LENGTH_INVALID

Codice restituito secondario; Un verbo LUA è stato emesso con il valore di lua_verb_length imprevisto da LUA.

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

LUA_NO_RUI_SESSION

Codice restituito secondario; RUI_INIT non è ancora stato completato correttamente per il nome lu specificato nel RUI_READ.

LUA_NEGATIVE_RSP
Codice restituito primario; indica uno dei due casi seguenti, che possono essere distinti dal codice restituito secondario:

  • LUA ha rilevato un errore nei dati ricevuti dall'host. Invece di passare il messaggio ricevuto all'applicazione in RUI_READ, LUA rimuove il messaggio (e il resto della catena se si trova in una catena) e invia una risposta negativa all'host. LUA informa l'applicazione su un RUI_READ o RUI_BID successivo che è stata inviata una risposta negativa.

  • L'applicazione LUA ha inviato in precedenza una risposta negativa a un messaggio al centro di una catena. LUA ha eliminato i messaggi successivi in questa catena e ora segnala all'applicazione che tutti i messaggi della catena sono stati ricevuti ed eliminati.

    LUA_SEC_RC

    Codice restituito secondario; questo parametro è un codice restituito secondario diverso da zero contenente il codice sense inviato all'host nella risposta negativa. Ciò indica che LUA ha rilevato un errore nei dati dell'host e ha inviato una risposta negativa all'host. Per informazioni sull'interpretazione dei valori di codice sense che possono essere restituiti, vedere Considerazioni su SNA con LUA.

    Un codice restituito secondario pari a zero indica che, dopo un RUI_WRITE precedente di una risposta negativa a un messaggio al centro di una catena, LUA ha ricevuto ed eliminato tutti i messaggi da questa catena.

    LUA_UNSUCCESSFUL
    Codice restituito primario; il record verbo specificato è valido, ma il verbo non è stato completato correttamente.

    LUA_DATA_TRUNCATED

    Codice restituito secondario; il parametro lua_data_length è minore della lunghezza effettiva dei dati ricevuti nel messaggio. Solo lua_data_length byte di dati sono stati restituiti al verbo; i dati rimanenti sono stati eliminati. Se si ottiene questo codice restituito secondario, vengono restituiti anche parametri aggiuntivi.

    LUA_NO_DATA

    Codice restituito secondario; lua_flag1.nowait è stato impostato per indicare la restituzione immediata senza attendere i dati e nessun dato è attualmente disponibile nel flusso o nei flussi di sessione specificati.

    LUA_INVALID_PROCESS

    Codice restituito secondario; il processo os/2 che ha emesso questo verbo non è lo stesso processo che ha emesso RUI_INIT per questa sessione. Solo il processo che ha avviato una sessione può emettere verbi in tale sessione.

    LUA_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 programma di transazione (TP) e il nodo unità fisica (PU) 2.1 è stato interrotto (errore LAN).

  • SnaBase nel computer TPS ha rilevato un ABEND.

    LUA_SESSION_FAILURE
    Codice restituito primario; è stato terminato un componente Host Integration Server necessario.

    LUA_LU_COMPONENT_DISCONNECTED

    Codice restituito secondario; indica che la sessione LUA non è riuscita a causa di un problema con il servizio di collegamento o con l'lu host.

    LUA_RUI_LOGIC_ERROR

    Codice restituito secondario; è stato rilevato un errore interno all'interno di LUA. Questo errore non deve verificarsi durante il normale funzionamento.

    LUA_INVALID_VERB
    Codice restituito primario; Il codice verbo o il codice dell'operazione o entrambi non sono validi. Il verbo non è stato eseguito.

    LUA_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.

    LUA_COMM_SUBSYSTEM_NOT_LOADED
    Codice restituito primario; Impossibile caricare o terminare un componente richiesto durante l'elaborazione del verbo. Pertanto, la comunicazione non poteva avvenire. Contattare l'amministratore di sistema per un'azione correttiva.

    LUA_UNEXPECTED_DOS_ERROR
    Codice restituito primario; dopo aver eseguito una chiamata al sistema operativo, è stato ricevuto un codice restituito imprevisto del sistema operativo e viene specificato nel codice restituito secondario.

Commenti

RUI_INIT deve essere stato completato correttamente prima di RUI_READ viene emesso.

Mentre un RUI_READ esistente è in sospeso, è possibile eseguire un altro RUI_READ solo se specifica un flusso di sessione o un flusso di sessione diverso da verbi RUI_READ in sospeso. Non è possibile avere più di un RUI_READ in sospeso per lo stesso flusso di sessione.

È possibile specificare un flusso di messaggi specifico (LU normal, LU expedited, SSCP normal o SSCP accelerato) da cui leggere i dati oppure è possibile specificare più di un flusso di messaggi. È possibile avere più verbi RUI_READ in sospeso, purché nessuna di esse specifichi lo stesso flusso.

I dati vengono ricevuti dall'applicazione in uno dei quattro flussi di sessione. I quattro flussi di sessione, dalla priorità più alta alla più bassa sono:

  • SSCP accelerato

  • LU accelerato

  • SSCP normale

  • NORMALE LU

    Il tipo di flusso di dati che RUI_READ deve elaborare viene specificato nel parametro lua_flag1 . L'applicazione può anche specificare se vuole esaminare più tipi di flusso di dati. Quando vengono impostati più bit di flusso, la priorità più alta viene ricevuta per prima. Quando RUI_READ completa l'elaborazione, lua_flag2 indica il tipo di flusso specifico per cui i dati sono stati ricevuti dall'applicazione LUA di Windows.

    Se RUI_BID viene completato correttamente prima dell'emissione di un RUI_READ , l'interfaccia LUA di Windows può essere incaricata di riutilizzare gli ultimi verbi RUI_BID VCB. A tale scopo, eseguire il RUI_READ con lua_flag1.bid_enable set.

    Il parametro lua_flag1.bid_enable può essere usato solo se il parametro seguente è true:

  • RUI_BID è già stato rilasciato correttamente e è stato completato.

  • L'archiviazione allocata per RUI_BID non è stata liberata o modificata.

  • Nessun altro RUI_BID in sospeso.

    Quando si usa lua_flag1.bid_enable, l'archiviazione RUI_BID non deve essere liberata perché viene usato l'ultimo verbo VCB RUI_BID. Inoltre, quando si usa lua_flag1.bid_enable, verrà pubblicato il completamento corretto di RUI_BID .

    Se RUI_READ viene rilasciato con lua_flag1.nowait quando non sono disponibili dati per la ricezione, LUA_NO_DATA sarà il codice restituito secondario impostato dall'interfaccia LUA di Windows.

    Se i dati ricevuti sono più lunghi di lua_max_length, viene troncato. Vengono restituiti solo lua_max_length byte di dati. Vengono restituiti anche il codice restituito primario LUA_UNSUCCESSFUL e il codice restituito secondario LUA_DATA_TRUNCATED. La libreria URI restituisce il maggior numero possibile di dati nel buffer dei dati dell'applicazione, ma i dati rimanenti nell'URI vengono eliminati e non possono essere estratti nelle richieste di RUI_READ successive. Ciò impone all'applicazione URI di allocare un buffer di dati RUI_READ abbastanza grande per gestire le dimensioni complete delle UR.

    Questo comportamento predefinito può essere modificato impostando il valore di lua_resv56[3] su un valore diverso da zero nel blocco di controllo verbo quando si chiama RUI_INIT durante l'impostazione della sessione. In questo caso, se i dati ricevuti sono più lunghi di lua_max_length, una richiesta di RUI_READ restituirà un codice restituito primario di LUA_OK e un codice restituito secondario di LUA_DATA_INCOMPLETE. Un'applicazione URI può quindi emettere nuove chiamate RUI_READ e ricevere il resto dei dati.

    Questo miglioramento non è stato adottato come parte dello standard DELL'API LUA di Microsoft Windows Open Services (WOSA) e differisce dall'implementazione di URI da IBM.

    Dopo che un messaggio è stato letto usando RUI_READ, viene rimosso dalla coda dei messaggi in ingresso e non è possibile accedere di nuovo. (RUI_BID può essere usato come lettura non strutturata. L'applicazione può usarla per controllare il tipo di dati disponibili, ma i dati rimangono nella coda in ingresso e non devono essere usati immediatamente.

    Il pacing può essere usato nella metà secondaria primaria (specificata nella configurazione host) per proteggere l'applicazione LUA da inondare con messaggi. Se l'applicazione LUA è lenta a leggere i messaggi, Host Integration Server ritarda l'invio di risposte di pacing all'host per rallentarlo.

Vedere anche

RUI_BID
RUI_INIT
RUI_TERM
RUI_WRITE
SLI_OPEN
SLI_PURGE
SLI_RECEIVE
SLI_SEND