RUI_INIT
Il RUI_INIT verbo trasferisce il controllo dell'unità logica (LU) specificata all'applicazione luA (Logical Unit Application) di Microsoft® Windows®. RUI_INIT stabilisce una sessione tra il punto di controllo dei servizi di sistema (SSCP) e l'lu specificato.
Nota
Per gli utenti dell'emulatore 3270, è stata aggiunta un'estensione di Microsoft Host Integration Server che consente di usare 3270 UNITÀ di spostamento invece delle unità LOGICHE. Per altre informazioni, vedere La sezione Osservazioni in questo argomento.
Nella struttura seguente viene descritto il membro LUA_COMMON del blocco di controllo verbo (VCB) utilizzato da RUI_INIT.
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_INIT.
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_INIT richiede questo parametro.
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 Host Integration Server e deve essere zero.
lua_sid
Parametro restituito. Specifica l'identificatore di sessione.
lua_max_length
Non usato da RUI_INIT e deve essere impostato su zero.
lua_data_length
Non usato da RUI_INIT e deve essere impostato su zero.
lua_data_ptr
Non usato da RUI_INIT e deve essere impostato su zero.
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
Non usato da RUI_INIT e deve essere impostato su zero.
lua_rh
Non usato da RUI_INIT e deve essere impostato su zero.
lua_flag1
Non usato da RUI_INIT e deve essere impostato su zero.
lua_message_type
Specifica il tipo di dati e comandi SNA in ingresso o in uscita. Si tratta di un parametro restituito per RUI_INIT. I valori possibili sono:
LUA_MESSAGE_TYPE_LU_DATA
LUA_MESSAGE_TYPE_SSCP_DATA
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_RQR
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
L'interfaccia SLI (Session Level Interface) riceve e risponde alle richieste BIND, CRV e STSN tramite le routine di estensione dell'interfaccia LUA.
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.
lua_flag2.async
Indica che il verbo dell'interfaccia LUA è stato completato in modo asincrono se impostato su 1.
RUI_INIT viene sempre completato in modo asincrono, a meno che non restituisca un errore, ad esempio LUA_PARAMETER_CHECK).
lua_resv56
Parametro fornito. Campo riservato utilizzato da RUI_INIT e SLI_OPEN. Tutti gli altri campi riservati nella matrice devono essere lasciati vuoti. Per altre informazioni, vedere la discussione di queste estensioni di Host Integration Server nella sezione Osservazioni.
lua_resv56[1]
Parametro fornito. Indica se un'applicazione URI può accedere alle UNITÀ logiche configurate come 3270 UNITÀ di spostamento, oltre alle unità LOGICHE. Se questo parametro è diverso da zero, è possibile accedere a 3270 UNITÀ.
lua_resv56[2]
Parametro fornito. Indica se la libreria URI rilascerà l'lu quando la sessione o la connessione LU-SSCP non è più disponibile. Se questo parametro è diverso da zero, l'unità lu non verrà rilasciata.
lua_resv56[3]
Parametro fornito. Indica se sono supportate letture incomplete. Se questo parametro è impostato su un valore diverso da zero, sono supportate letture incomplete o troncate. Per altri dettagli, vedere le osservazioni per RUI_READ.
lua_resv56[4]
Parametro fornito. Indica se la libreria URI consentirà all'applicazione di mantenere il blocco dell'unità lu se viene riciclato nell'host. Se questo parametro è diverso da zero, l'applicazione può mantenere il valore lu.
lua_encr_decr_option
Campo per le opzioni di crittografia. In RUI_INIT sono supportati solo i seguenti elementi:
lua_encr_decr_option = 0
lua_encr_decr_option = 128
I valori compresi tra 1 e 127 non sono supportati.
Codici restituiti
LUA_OK
Codice restituito primario; il verbo eseguito correttamente.
LUA_CANCELED
Codice restituito primario; il verbo non è stato completato correttamente perché è stato annullato da un altro verbo.
LUA_TERMINATED
Codice restituito secondario; RUI_TERM è stato rilasciato prima del completamento dell'RUI_INIT .
LUA_PARAMETER_CHECK
Codice restituito primario; il verbo non è stato eseguito a causa di un errore di parametro.
LUA_INVALID_LUNAME
Codice restituito secondario; il parametro lua_luname non corrisponde ad alcun nome LU LU o nome del pool LUA nel file di configurazione.
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_RESERVED_FIELD_NOT_ZERO
Codice restituito secondario; Un campo riservato nel record verbo o un parametro non usato 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_DUPLICATE_RUI_INIT
Codice restituito secondario; il parametro lua_luname ha specificato un nome lu o un nome del pool LU già in uso da questa applicazione (o per cui l'applicazione ha già RUI_INIT in corso).
LUA_UNSUCCESSFUL
Codice restituito primario; il record verbo specificato è valido, ma il verbo non è stato completato correttamente.
LUA_COMMAND_COUNT_ERROR
Codice restituito secondario, che indica uno degli errori seguenti:
Impossibile eseguire il verbo perché l'applicazione aveva già raggiunto il numero massimo di sessioni attive. In Windows un'applicazione può avere un massimo di 15.000 sessioni attive in qualsiasi momento.
Il verbo ha specificato il nome di un pool di lu o il nome di un lu in un pool, ma tutte le unità di archiviazione nel pool sono in uso.
LUA_ENCR_DECR_LOAD_ERROR
Codice restituito secondario; il verbo ha specificato un valore per lua_encr_decr_option diverso da 0 o 128.
LUA_INVALID_PROCESS
Codice restituito secondario; l'lu specificato da lua_luname è in uso da un altro processo.
LUA_LINK_NOT_STARTED
Codice restituito secondario; la connessione all'host non è stata avviata; nessuno dei servizi di collegamento che potrebbe usare è attivo.
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_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
Questo verbo deve essere il primo verbo LUA emesso per la sessione. Fino al completamento di questo verbo, l'unico verbo LUA che può essere emesso per questa sessione è RUI_TERM (che termina un RUI_INIT in sospeso).
Tutti gli altri verbi rilasciati in questa sessione devono identificare la sessione usando uno dei parametri seguenti da questo verbo:
Identificatore di sessione, restituito all'applicazione in lua_sid.
Nome lu o pool LU, fornito dall'applicazione nel parametro lua_luname .
RUI_INIT viene completato dopo la ricezione di un messaggio ACTLU dall'host. Se necessario, il verbo attende per un tempo illimitato. Se un ACTLU è già stato ricevuto prima di RUI_INIT, LUA invia una notifica all'host per informarlo che l'lu è pronto per l'uso.
Né ACTLU né NOTIFY sono visibili all'applicazione LUA.
Al termine dell'RUI_INIT , questa sessione usa l'unità lu per cui è stata avviata la sessione. Nessun'altra sessione LUA (da questa o qualsiasi altra applicazione) può usare l'lu fino a quando non viene eseguita la RUI_TERM o fino a quando non viene ricevuto un codice restituito primario LUA_SESSION_FAILURE.
Uso di 3270 LU
Per fornire agli utenti dell'emulatore 3270 la possibilità di usare la chiamata di configurazione EIS (Emulator Interface Specification) con l'API RUI, è stata aggiunta un'estensione host Integration Server all'URI. Questa estensione consente di usare 3270 UNITÀ di spostamento invece di UNITÀ LOGICHE. Se un'applicazione imposta lua_resv56[1] su un valore diverso da zero nella chiamata RUI_INIT , è possibile usare 3270 UNITÀ di utilizzo.
Non rilasciare il lu
Se un'applicazione imposta lua_resv56[2] su un valore diverso da zero nella chiamata RUI_INIT , la libreria URI non rilascerà il lu quando la sessione o la connessione LU-SSCP non viene interrotta. Quando questa estensione host Integration Server è abilitata, l'applicazione non deve emettere un nuovo RUI_INIT dopo un errore di sessione o un errore di connessione. Quando viene eseguito il backup della sessione LU-SSCP (l'applicazione può usare WinRUIGetLastInitStatus per rilevarlo), l'applicazione può iniziare a usarla di nuovo.
Supporto della suddivisione in blocchi in questa sessione
Se un'applicazione imposta lua_resv56[3] su un valore diverso da zero nella definizione della sessione RUI_INIT , in questo modo viene abilitata un'estensione host integration server in grado di modificare il comportamento di RUI_READ. Il comportamento predefinito per una chiamata RUI_READ consiste nel troncare i dati (ignorando i dati rimanenti) se il buffer di dati dell'applicazione non è sufficientemente grande da ricevere tutti i dati nella UR, restituendo un codice di errore. Quando lua_resv56[3] è impostato su un valore diverso da zero nella chiamata RUI_INIT , un RUI_READ rilasciato in cui il buffer dei dati dell'applicazione non è abbastanza grande non comporterà l'eliminazione dei dati dell'UR. Il verbo RUI_READ restituirà l'esito positivo (LUA_OK) per il codice restituito primario e LUA_DATA_INCOMPLETE per il codice restituito secondario. Le richieste di RUI_READ successive possono quindi essere rilasciate per recuperare i dati che hanno superato il buffer dei dati dell'applicazione.
Ignorare DACTLUs
Se un'applicazione imposta lua_resv56[4] su un valore diverso da zero nell'istituzione di sessione RUI_INIT , in questo modo viene attivata un'estensione host integration server e la libreria URI consentirà all'applicazione di conservare l'lu se viene riciclata nell'host ,ovvero disattivata e riattivata.
Nota
Tutti gli altri campi riservati devono essere lasciati vuoti.
Per altre informazioni, vedere la descrizione della funzione sepdcrec nella sezione della Guida di Software Development Kit (SDK) sulla specifica dell'interfaccia dell'emulatore 3270.
Crittografia
La crittografia a livello di sessione viene implementata tramite le richieste CRV (Cryptography Verification). Le applicazioni URI devono eseguire tutte le operazioni necessarie per l'elaborazione di queste richieste. Per tutte le interfacce diverse da URI, le richieste CRV vengono rifiutate con una risposta negativa da Host Integration Server.
Per RUI_INIT, sono supportate le opzioni seguenti:
lua_encr_decr_option = 0
lua_encr_decr_option = 128
I valori da 1 a 127 (routine ACSRENCR e ACSROECR) non sono supportati.
L'applicazione di invio è responsabile della spaziatura dei dati in più di otto byte e dell'impostazione del bit dell'indicatore di dati in spaziatura interna e per la crittografia. L'applicazione ricevente è responsabile della rimozione della spaziatura interna dopo la decrittografia.